Shelve files

ShelvingClosed The process of temporarily storing files in the server without checking in a changelist. Shelves are often used for reviews. enables you to store copies of open files temporarily in the shared Helix Core Server repository without checking them in. Shelving is useful for a variety of purposes, including taking and restoring snapshots of in-progress work and reviewing other users' code before it’s checked in. When you shelve a file, a copy is placed in a pending changelistClosed A changelist that has not been submitted. from which other users can unshelve it. Pending changelists that contain shelved files are displayed with the following icon and badge: shelved changelist. When the changelist is expanded, shelved files are listed under the Shelved Files node, indicated with the following icon: shelved file

When you manage shelved files, note the following:

  • Basics: To be shelved, a file must be checked out. However, you cannot unshelve a checked-out file.
  • Submitting shelved files: You can submit a shelved file directly.
  • Managing changelists: You cannot move a shelved copy to another pending changelist. If you revert a file after shelving it, the copy remains shelved in the changelist until you delete it. Only the changelist owner can reshelve or delete files that are shelved in the changelist. You can submit shelved files directly, but your changelist must contain only shelved files.
  • File history: No file history is created when you shelve or unshelve files.
  • Diffing: You can diff shelved copies just as you diff any other file. For example, to display any changes you made after shelving a file, drag the shelved copy and drop it on the checked-out file.

Shelve checked-out files in a pending changelist

  1. Right-click the changelist and select Shelve.

    Alternately, you can shelve a checked-out file by dragging it from the pending changelist or depot pane to the Shelved Files node of the changelist where you want it shelved.

    P4V displays the Shelve dialog box. By default, all files in the changelist are selected.

  2. Clear the check boxes of any files that you do not want to shelve.

  3. Select any of the following options that apply:

    • Revert checked out files after they are shelved: Reverts the files in your workspace to the head revision in the depot. By default, when this option is selected, P4V also removes any files that are marked for add in the changelist from the file system when they are shelved. If you do not want P4V to remove these files from the file system when they are shelved, make sure to clear the Remove files that are opened for add check box.

    • Don't shelve unchanged files: Only shelves files that have changed.

    • Make shelf globally accessible: Promotes shelved files from an edge server to a commit server. This makes those shelved files accessible to other edge servers participating in the distributed configuration. Once a shelved change has been promoted, all subsequent local modifications to the shelf are also pushed to the commit server and remain until the shelf is deleted. See "Automatically promoting shelves" under Promoting shelved changelists in the Helix Core Server Administrator Guide.

  4. Click Shelve.

    P4V shelves the file in the selected changelist (or, if you are shelving files in the default changelist, creates a new changelist).

Unshelve files

After shelving a file, you or another user can unshelve it, which restores the shelved copy to your workspace and opens it in the changelist of your choice. Unshelving does not remove files from the shelf.

To unshelve a file that was shelved by another user, you must have permission to check out the file. When you unshelve a file that was shelved by another user, it is copied to one of your changelists, from which you can edit and submit the file.

To unshelve files in a pending changelist:

  1. Right-click the file changelist and select Unshelve.

    P4V displays the Unshelve dialog box. By default, all files in the changelist are selected.

  2. Clear the check boxes of any files that you do not want to unshelve.

  3. Add to pending changelist - you can chose which changelist.

  4. Select any options you want:
    • Map unshelved files - You might want the files that you unshelve to be available in a different branch. For example, you might have fixed a bug in a development branch (or stream) and now want to unshelve the files into the mainline branch (or stream).
    • Delete shelved files after they are unshelved - Shelved files are stored in the server. When you unshelve, those files are copied into your workspace. You can unshelve files from your shelf or another user's shelf. If there is no need for the Server to keep a copy of the unshelved files, this option is appropriate.
    • Revert checked out files before unshelving - If you already have files that are checked out in the changelist that you are unshelving, you can choose to revert these files before unshelving. If you don't need the current changes of the checked out files, reverting the checked out files is a way to avoid having to perform a resolve on those files.
    • Overwrite workspace files even if they are writable - You might have changed files in your workspace without checking them out. If you are unshelving work done by another user, this guarantees that your workspace will get a copy of that user's work.

  5. Preview - See what the result of unshelving would be.

  6. Click Unshelve.
    The shelved files are copied to your workspace and opened in the specified changelist.

To unshelve a file into a different branch than the one it was shelved in:

  1. In the Unshelve dialog box, select the Map unshelved files check box.

  2. Select the way you want to map the unshelved files to the target branch:

    • Using Branch Mapping: Enter the branch mapping you want to use, or browse for it.

      You can use any branch mapping that maps the branch the file was shelved in as either source or target. Your current workspace view must be mapped to the target.

    • Using Stream: Type or select the stream you want to use to unshelve.

      The stream must be the child in relation to the location of the files being unshelved. For example, if the files are shelved in a mainline and you want to unshelve into a development child, you must select the development child. Likewise, if the files are shelved in the development child and you want to unshelve into the mainline, you must select the development child. This still holds true if you reuse your workspace across streams. If you are working in the mainline and shelve some files, then move your workspace to the development child, you must still specify the development child stream to unshelve.

  3. Click Unshelve.

Submit shelved files

You can submit shelved files directly.

To submit shelved files in a pending changelist, right-click the changelist or shelved files folder and select Submit Shelved Files.

Restrictions:

  • If a pending changelist includes non-shelved files or a checked-out stream along with shelved files, you must first revert the non-shelved files or the checked-out stream or move them to another changelist.

  • You cannot submit shelved files from a task stream.

Delete shelved files

Shelved files remain shelved until you delete them from the pending changelist. To delete a shelved file from a pending changelist, right-click the file and choose Delete. Alternately, right-click the pending changelist and choose Delete Shelved Files​.

You can also selected multiple pending changelists and delete them in a single action. Any shelved files on these changelists are also deleted. However, pending changelists are preserved and not deleted if they are associated with checked out files, stream specs, or jobs.