Cause and effect

Recently, Keith Hill asked which version control commands require a checkin to complete. As Keith, Ed, and I delved into the topic, I realized this might be of broader general interest, too. Thanks to James for the assist on this one!

As many of you know, Team Foundation's Version Control system uses the pending changes model. Many operations require two steps to update the server state. First, you have to inform the server of your intent ("add a new file", "rename a folder", etc). Then, you tell the server to checkin the change (or, "commit", for those more familiar with the term). The list of commands which require this two-step process is:

  • Add: puts new files and folders on the server
  • Branch: creates a copy of a set of files and folders already on the server and stores information about the two trees to merge changes later
  • Checkout (or "Edit"): Change the contents of a file
  • Delete: Remove a file or folder from Version Control (note that this is not a permanent operation- it's somewhat akin to cloaking or hiding the file or folder for all users)
  • Merge: Used between two branches to port changes from one branch to the other
  • Rename: Change the name of a file or folder on the server
  • Undelete: Restore a deleted item

The other commands may affect the server, as well, but act immediately. Let's take a look at some of the more interesting examples:

Lock immediately sets the state of a file or folder. If you lock for checkout, other users cannot pend any of the changes listed above until you unlock the item or checkin a change on it. If you lock for checkin, other users can pend changes but won't be able to check them in to the server.

For more permanent access control, use the permission command. This operation is used to update the static access granted to users and groups for items on the server. It doesn't require a checkin to take effect and, unlike lock, doesn't go away when the user who set the permission checks in a change on the item.

Label and unlabel immediately update the contents of a label. When the command returns, the items and versions associated with the specified label are updated on the server, assuming the user has the right permission.

Shelve and unshelve, which Chris discusses in detail, store pending changes. Shelvesets are stored entirely on the server, and so shelving updates the server state. Unshelving updates the local workspace and thus updates the server data on the current workspace state.

This brings us to workfold and workspace, which also affect the workspace or its mappings though don't require a checkin to go into effect.

The get command also updates the server to let it know what versions of files the current workspace last downloaded. It also updates the local disk, of course. However, sometimes it generates conflicts, leading us to:

Resolve, scary operation as it is, doesn't require a checkin, either. Sometimes as part of resolving a conflict other changes will be pended locally, and these must then be checked in. For example, if you've overwritten a file with out checking out, trying to get a new version of that file will create a conflict telling you that the local file is writable. You can resolve this by selecting "Check out and auto merge". This them pends an edit on the file which will have to be checked in separately. However, the conflict itself has been resolved and server state updated.

The changeset command lets users update old changesets' comments and checkin notes. Such changes are immediate (and non-recoverable) and do not require a checkin.

Undo is sort of the evil twin of checkin. While it also makes pending changes go away, it does so without updating the items stored in the server.

"h diff /configure" (soon to be "tf diff /configure") doesn't affect the server state, though it does add information to the local registry. This command helps you set up particular tools for diff and merge functionality based on the file extension.

Many other commands are simply informational and don't affect the server or local system at all. These include:

  • Branches: shows the branch trees that the item is involved in, both ancestors and descendants
  • Difference: compares two versions of a file
  • Dir: lists files in the specified folder
  • History: shows a list of changes to the specified item or its children
  • Merges: lists what changes have previously been merged to an item
  • Properties: displays both local workspace and server state for an item
  • Shelvesets: shows information about shelvesets on the server
  • Status: lists pending changes
  • View: opens a file in its associated editor
  • Workspaces: shows information about workspaces on the server

I hope this helps clear things up a bit- it is rather long, but then there are a lot of commands. (Now you're playing with power?) If you want more specifics on how any command in particular works or how to use it, leave a comment and I'll be happy to oblige!