How to use shelving from the command line

Shelving is a really useful feature that was included for the first time with the Dec. CTP.  Shelving allows you to save your changes to a shelveset on the server.  The shelveset consists of the same kind of information that a checkin does, except that you aren’t checking in.  You don’t create a new changeset.  Rather, you create a space on the server that is your own that contains your pending changes, comment, etc.

You can choose to move your changes out of your workspace or you can keep your pending changes when you shelve.  Moving your changes is great when you need to stop working on your current changes, make a targeted fix, check in that fix, and then unshelve what you were working on before being interrupted.  Keeping your changes in your workspace is very useful when you want share a change (perhaps a fix for another developer prior to checkin) or have another person review your changes.

I’ll talk more about how works in upcoming posts.  For now, here are some commands you can use to explore shelving in the Dec. CTP.

Bring up a Visual Studio command prompt (Start -> All Program -> Microsoft Visual Studio 2005 Beta -> Visual Studio Tools -> Visual Studio Command Prompt), cd to a workspace directory with some pending changes, and try out some of the following.  If you need to create a workspace, you can create one with “h workspace /new MyWorkspace /s:yourtfsservername” and then pend some changes.

To shelve all of your changes in your current workspace, use
    h shelve MyShelvesetName [optional filespecs]

To unshelve an existing shelveset, use
    h unshelve MyShelvesetName [optional filespecs]

To shelve the changes and undo them in your workspace, use the /move option with /i (or uncheck “Preserve my changes” in the GUI).  The /move option also deletes pending adds since they get uploaded to the server — something a plain undo doesn’t (and can’t) do.
    h shelve /i /move shelvesetname [optional filespecs]

To delete a shelveset, use the shelve command.
    h shelve /delete shelvesetname

To see the changes in another user’s shelveset, use the status command (when the other user is in the same domain, you should be able to leave that off).
    h status /shelveset:shelvesetname;domainuser

To see the diffs for a shelveset, use the diff command (great for remote code reviews).
    h diff /shelveset:shelvesetname;domainuser

You can also see a list of all shelvesets with shelvesets command
    h shelvesets /owner:*


Comments (4)

  1. BillT says:

    Shelving sounds like a very useful feature.

    It’s utility (usefulness) is limited because it requires the user to know in advance what he/she intends to do (at least in the example usage scenarios you provide in the paragraph "You can choose …"). The user must predict the future: What will he/she do next: a targeted fix, or a shared change?

    Features with this kind of limitation can be frustrating, because often the user will realize after-the-fact that they should have used the feature, but didn’t. "Oh, man, I should have shelved it, before I did that!!"

    Yes, it would be nice if we could all predict the future (even a few moments) accurately and reliable, but the fact is: we don’t.


    Can you (Microsoft?) think of a feature that would provide all the benefits that shelving provides, without requiring the user to prognosticate about the future?

  2. Well, I think shelve has you covered whichever way you do it. If you shelve with /move but then want the changes back, you can just unshelve. If you shelve without /move (the default) but want the changes out of your workspace, you can undo safely, since your shelveset has the changes. So neither option makes the other one inaccessible.

    Unshelve with /move is pretty much a one-shot deal, since it deletes the shelveset if all of the changes were successfully unshelved. So, if you want the "safety factor", you’d unshelve without /move (and /move is NOT the default on either the command line or in the VS UI) – that way, you can wait until you’re sure you’re done with the shelved changes to delete the shelveset.

    Make sense?