Question

I've noticed the Shelve command in TortoiseHg menus but discussion of it on this site (as yet) is nonexistant and documentation in the TortoiseHg is sparse as well.

What is Shelve, how does it fit into Kiln, and under what circumstances is it useful?

• Is this a means of saving some incomplete work without committing, such as when you are interrupted mid-task with a more pressing issue?
• Is this an "out" for those times in Subversion where you would commit only some your current changes (often with disastrous results)?
• Do commits and pushes with outstanding shelved items get communicated to Kiln in any way? (i.e. is it possible for Kiln to ever have tooling around this feature, or is it a phenomenon only for your local repository?)

Answer 1

Shelve is a way to put incomplete, uncommitted changes aside for the moment, freeing you to work with other repositories. The usual use case is this:

1. I'm working on a new feature.
2. I get blocked by a bug.
3. My colleague fixes said bug in her repo and pushes the fix.
4. I try to hg fetch (or hg merge) her fix, but Mercurial complains that I have uncommitted changes.
5. I use hgtk shelve to put those changes aside for the moment.
6. Run hg fetch.
7. Use hgtk shelve to unshelve my changes and continue on my way.

Shelve only stores the changes locally, they are not transmitted to any other repo when you push, or if someone pulls from your repo.

Be aware that it can get a bit messy if you try to shelve a file without unshelving it first. Likewise, you'll have to merge if you start working on a file you shelved without unshelving it first.

It's a useful little feature, and can help make the Mercurial workflow a little more flexible and forgiving.

Note:

You might notice that there is also a shelve extension for Mercurial, which gives you hg shelve. TortoiseHg's hgtk shelve is based on this extension (and is bundled with TortoiseHg), but is generally better maintained. If you want the command line version, add the following lines to your Mercurial.ini instead of using the extension:

[extensions]
...
tortoisehg.util.hgshelve=
...