4.6. Shelve

Warning

The win32text extension can cause trouble with hunk selection. This has been resolved in Mercurial 1.3 and TortoiseHg 0.8, but requires proper configuration. See issue #82.

The purpose of this dialog is to allow the user to shelve selected changes from the working directory, store them in a special patch file within the repository, and then unshelve them back at a later time.

Shelve dialog

Shelve dialog

Walking across the toolbar buttons:

Shelve
Shelve selected diffs in checked files.
Unshelve
Replace the shelved changes back into the working directory.
Diff
Visual diff checked files
Revert
Revert checked files to last revisioned state. If merging, it allows you to select the revert parent.
Add
Add checked files that were in unknown ‘?’ or ignored ‘I’ state.
Move
Move checked files to specified target directory in versioned manner.
Remove
Delete checked unversioned files and/or remove (mark as deleted) any versioned files.
Forget
Forget checked versioned files
Refresh
Reload the state of the working directory. It tries to retain check and selection state across refresh.

The file list has four columns:

  1. A checkbox that indicates whether the file is selected for an operation. The toolbar buttons only operate on checked files. “Partially” selected files have a special check state. This column header is checkable, it will toggle the file selection states.
  2. The st column holds the status of the file, defined by Mercurial’s status command, one of ‘MARD?IC’.
  3. The ms column holds the merge state of the file, defined by Mercurial’s resolve command, one of ‘ RU’.
  4. The canonical path of the file (relative to the repository root)

Below the file list are checkboxes that toggle the display of the various classes of files {modified, added, removed, deleted, unknown, clean, ignored}. These check boxes will be disabled if the commit tool was given a specific set of files and/or directories.

4.6.1. Tabs

The shelve tool diff pane has four tabs
  1. Text Diff - shows diff of currently selected file
  2. Hunk Selection - allows diff hunks of current file to be skipped
  3. Shelf Preview - displays all selected changes. This previews the changes that will be removed from the working directory and stored in the shelf.
  4. Shelf Contents - the current contents of the shelf.

4.6.2. Shelving Changes

Just like the commit tool, this dialog uses TortoiseHg’s integrated hunk selection code to allow the user to select the files and change hunks to move to the shelf. When you press the shelve button, the selected changes are removed from the working directory and placed in a patch file. If the shelf already had changes in it, you will be asked whether to replace those changes or to merge these new changes into it. When the shelf has changes, the unshelve button will be active.

4.6.3. Unshelving Changes

When the unshelve button is pressed, the shelved changes are reapplied to the working directory.

Note

The unshelved changes will appear as working directory modifications when the shelve tool refreshes it’s view of the repository.

4.6.3.1. How is this different from record/commit?

Shelved changes are physically removed from the working directory until you unshelve them. This means you can build your project and run tests on it while the shelved changes are gone. This is safer than selecting changes at build time since you can test whether the change being committed is valid.

Shelving changes is also useful for removing partially completed work to make sure it doesn’t interfere with the debugging of other changes you are making.

Caveat: the shelved changes are stored in a patch that is based on the current working directory contents. There’s no guarantee that the patch can be cleanly reapplied later if the shelved changes conflict with changes made to your code after the shelving.

4.6.3.2. How is this different from MQ?

The shelf can be considered a single unnamed MQ patch that is never converted into a changeset.

The shelve tool can be useful when maintaining a patch queue. The shelf can take changes from one patch and re-apply them to another patch (or an entirely new patch).

For example:
  1. Push to a patch you would like to split up
  2. Open the shelve tool, the top patch changes will be selectable
  3. Unselect change hunks you want to leave in the patch, then press Shelve
  4. Refresh top patch using hg qrefresh, or use commit tool
  5. Push or pop to the patch you want to apply shelved patches
  6. Open the shelve tool and press Unshelve
  7. Refresh top patch (repeat step 4)

You cannot shelve added, removed, or renamed files, but MQ can handle this just fine.

4.6.3.3. How is this different from attic?

The attic extension is a super-set of the shelve feature. In particular, attic allows you to have several named shelves which can be saved and restored independently.

4.6.4. Keyboard navigation

Ctrl-C
in the diff panel will copy the currently highlighted (not selected, but highlighted) diff hunks to the clipboard. These can be pasted into a text buffer to generate any arbitrary patch based from the changes in your working directory.

The code which copies the hunks to the clipboard is intelligent about diff headers. The clipboard contents will always be a valid patch.

4.6.5. Configurables

  • TortoiseHg ‣ Bottom Diffs
  • TortoiseHg ‣ Tab Width
  • TortoiseHg ‣ Max Diff Size

4.6.6. From command line

The shelve tool can be started from command line:

hgtk shelve

aliases: unshelve

shelve/unshelve tool

use "hgtk -v help shelve" to show global options

To use TortoiseHg’s shelve functionality from the Mercurial command line, you must enable the extension with lines like these in your Mercurial.ini file:

[extensions]
tortoisehg.util.hgshelve=

This adds commands named shelve and unshelve to hg.