Perforce Public Knowledge Base - Renaming a Perforce User
Downloads Blog Company Integrations Careers Contact Try Free
Menu Search
Reset Search



Renaming a Perforce User

« Go Back



How can I rename a Perforce user?


The 2014.1 server release added a 'p4 renameuser' command

#657309 (Bug #3270) **
    The new 'p4 renameuser' command renames an existing user to a
    new name, updating all the changes, specs, and other objects owned
    by that user. For more information, and some issues to consider
    prior to running the command, see 'p4 help renameuser'.

You simply identify the current and the new usernames, and the command will update accordingly: 

$ p4 renameuser --from=thomas --to=tom
User thomas renamed to tom.

The command will warn you if you try to rename to a username that already exists. 

$ p4 renameuser --from=thomas --to=tom
User tom already exists.

In this case, find out if 'tom' is in use, and decide if you wish to remove it or choose a different new username for 'thomas'. 

If the new username does not exist now but was in the system at some point previously, any objects they owned would prevent the user from being renamed: 

$ p4 renameuser --from=thomas --to=tom
User tom has already created changelists in this server.


$ p4 renameuser --from=thomas --to=tom
User tom has already created workspaces, labels, or other spec objects in this server.

To identify changes, client workspaces, labels and branches owned by the user in question, include '-u <username>' in the 'p4 changes', 'p4 labels', 'p4 branches' and 'p4 clients' command. For example, the items owned by user 'tom' can be found with the following commands: 

$ p4 changes -u tom
$ p4 labels -u tom
$ p4 branches -u tom
$ p4 clients -u tom

In the 2016.1 release, a '-f' flag was added, allowing you to bypass these checks and force the rename. 

#1214190 (Bug #72880) **
    'p4 renameuser' now supports a -f flag to bypass the checks
    against accidentally merging two unrelated users.

If there are objects in the database owned by your 'new' user, and you are using a version prior to 2016.1, you need to identify those changes, labels, branches or clients owned by the 'new' username and change the owner of each manually. It is possible to use a script to iterate through labels, changes, and so on if there are many of them. Once complete, the 'p4 renameuser' command would allow you to rename the use.

If users receive an "invalid credentials" error, you will have to ask the users reset their password.

Prior to 2014.1 and the introduction of 'p4 renameuser', you would create a new user-name and then migrate the client workspaces, labels, branches to this new user-name as the owner and update groups membership and protection table with this new user-name. However, all the changes history will remain associated to the old user-name.

Note: If you have reached your license quota, you will not be able to create the new user before deleting one of the existing users.  In this case, you have to delete the unwanted user before creating the new one (in short, skip step 1 and start with step 2 to the end of this process).  You will still be able to change the ownership of clients, changes, branches, and so on to the new user even if the new user does not yet exist.


To "rename" a user, follow these steps.

  1. Submit or revert all pending changes and/or shelves open with the old user-name.  You can use the following commands to find out what they are:

    p4 changes -s pending -u <olduser>
    p4 changes -s shelved -u <olduser>
  2. Create the new user-name.

    p4 user -f <newuser>
  3. Assign the new user a password (optional).

  4. For each workspace that the old user has, set the owner to the new user-name.  Use the following command to find out which clients belong to the user.

    p4 clients -u <olduser>

    Alternatively, you can delete the clients and let the user to re-create the workspaces as needed using the new user-name.

  5. Perform the same steps for any labels and branches belonging to the user.  Use the following commands to determine what specifications require updating:

    p4 labels -u <olduser>
    p4 branches -u <olduser>
  6. To rename <olduser(s)> to the new user-names in Perforce jobs (optional), use the following command to find jobs where old username is the owner:

    p4 jobs -e "<olduser>"
  7. Update group memberships with the new user-name in place of the old user-name. Use the following command to find out what the groups that the old_username is associated to:

     p4 groups -u <olduser>
  8. Update protections table entries with the new user-name in place of the old user-name. Use the following command to find out what the protection that the old_username is associated to:

     p4 protects -u <olduser>
  9. Inform the user of the default password and instruct him/her to change it and confirm everything is working as expected with the user.

    Note: If your security counter is set to 2 or higher, leaving the password unset will force the user to set the password when they next log into Perforce. However, in many installations this can be a security risk.

  10. Delete the old user-name:

    p4 user -df <olduser>

Alternative Approach to User Re-naming

It is also possible to rename user names where the new user name is not changed at a given time, but instead was already that name throughout the Perforce history.  This can be accomplished through a search-and-replace of a checkpoint, then a restore of this checkpoint.  Make sure the two at-marks (@) surrounding the name are included in the search-and-replace.  Also make sure that at least one super user is not changed so you can always log in.  Always take a checkpoint just before you make this change in the event there are unintended consequences.

Note: This will require all passwords of changed user-names to be reset.

For example, take this change of user-name "bsmith" to "Bruno.Smith" and "jdoe" to Jane.Doe in checkpoint.2404.

  1. Stop Perforce, and take a checkpoint.

    p4d -r . -jc

    This checkpoint is the fall-back (backup; reserve) if there are any problems with this procedure.

  2. Search-and-replace the checkpoint to create a new checkpoint.

    Search and replace @name@:

    cat checkpoint.2404 | sed -e "s/@bsmith@/@Bruno.Smith@/" -e "s/@jdoe@/@Jane.Doe@/" > newcheckpoint.2404

    Note:Avoid changing at least super user name to avoid being inadvertently locked out of the Perforce server.

  3. Move existing db.* files to a temporary directory.

    With Perforce stopped, move all db.*, server.locks, lbr, journal, and log files to a temporary directory for safekeeping.

  4. Restore the newly modified checkpoint.

    p4d -r . -jr newcheckpoint.24

    The new database will contain the user name changes.  Label names, branch specifications, client name, depot paths, and descriptions will not be changed.

  5. Reset the password of all users.

    Existing passwords and tickets will not work with any user changed user-names.  To change all users to a default password:

    1. Create a file, "input.txt" and enter the password on two lines.

    2. As a super user, run the "p4 passwd" command to read in the contents of input.txt:

      p4 passwd Bruno.Smith < input.txt
      Enter new password:                                                     
      Re-enter new password:                                                  
      Password updated.

    Users will need to log in again under their new name, and users will need to change their P4CONFIG variables to their new name.

Note: Changing a checkpoint directly known as "checkpoint surgery" as just described is dangerous.  Test your changes thoroughly on a duplicate server before implementing this. If you have any questions, please contact Perforce support.

Related Links



Was this article helpful?



Please tell us how we can make this article more useful.

Characters Remaining: 255