Walkthrough: Working with Team Foundation Version Control from the Command Line

This walkthrough describes how to use the Visual Studio Team System Team Foundation Server command-line client, tf.exe, to perform version control operations.

During this walkthrough, you will accomplish the following tasks:

  • Create the workspace in which your personal copy of files in the version control server will reside, and then get a copy of source from the server.

  • Add a file to the server, and then check out the file from the server and edit it in your workspace.

  • Check in pending changes and create a changeset.

  • Return your workspace to a specific point in time by retrieving source from the server at the time when a particular changeset was created.

Prerequisites

If you can establish a connection to a Team Foundation Server and you have the appropriate permissions, you can perform version control commands at a command prompt, batch file, or script file. To do this, you must either use the Visual Studio 2008 Command Prompt utility, or set several environment variables in your current command prompt by using vsvars32 as described in the following example. For more information about joining a team project, see Walkthrough: Joining a Team Project.

To open the Visual Studio 2008 command prompt

  • Click Start, click All Programs, point to Microsoft Visual Studio 2008, point to Visual Studio Tools, and then click Visual Studio 2008 Command Prompt.

Alternatively, you can run vsvars32 in the Visual Studio installation path, which is usually DriveLetter:\Program Files\Microsoft Visual Studio 9.0\Common7\Tools.

Required Permissions

To complete this walkthrough, you must have the CreateWorkspace, CheckIn, and PendChange permissions.

Creating a Workspace

To start working with version control, you must establish a workspace. A workspace is a local copy of the files and folders on the server. When you add, edit, delete, move, rename, or otherwise change any version-controlled item, your changes are isolated in your workspace where you can safely build and test your changes. When you perform a check-in, these changes are committed to the server and available outside your workspace.

A workspace consists of a series of mappings. Each mapping associates a folder in the server together with a local folder on disk. To obtain a local copy of the files from the server, create a new workspace, and specify the mappings for the workspace. Then use the get command to populate your workspace with source files.

Before you can perform any Team Foundation version control commands on your computer, you must create a workspace. The workspace persists the output of your operations, and enables you to commit them to the server by checking them in.

To create a workspace to manage your version-controlled files

  1. Click Start, click All Programs, point to Microsoft Visual Studio 2008, point to Visual Studio Tools, and then click Visual Studio 2008 Command Prompt.

  2. Type mkdir c:\projects.

  3. Type cd c:\projects.

  4. Type tf workspace /new /s:servername, where servername is the name of your Team Foundation Server, for example, tf workspace /new /s:team1server, and then press ENTER.

    Note

    If this is the first time that you are connecting to the server, you must specify the full URL. For example, specify "http://team1server:8080".

  5. In the Create Workspace dialog box, type a name for the new workspace such as "cmdwalkthrough".

  6. Under the Source Control Folder column, select a team project from the server.

    You can click the ellipses (…) to browse the server folders.

    The folder you select will be mapped to the c:\projects folder listed under the Local Folder column.

  7. Click OK.

You can see all the workspaces that you have created on the current computer by typing tf workspaces at the command prompt. For more information, see Workspaces Command.

When you create a workspace, the system maintains a workspace definition for that workspace. Team Foundation Server stores the workspace definition, and it lists all files in the workspace, the version upon which each is based, and also its current status. Because the server stores the workspace definitions, any user who has the correct permissions can duplicate your exact working environment on his or her computer, minus any pending changes. For more information about how to do this, see Get Command.

Add and Edit a File

After you create a workspace, you can specify which files you want to add to version control. Then you can edit them before you check in your changes.

To prepare a file for addition to version control

  1. At the command prompt, type notepad 314.cs, and then press Enter.

  2. When Notepad prompts with Do you want to create a new file?, click Yes.

  3. In Notepad, type using System.IO;, save your changes, and then close Notepad.

  4. At the command prompt, type tf add 314.cs to add the file to the list of pending changes.

  5. Type tf status to confirm the pending addition of 314.cs.

    You can use this command to view all pending changes in the current workspace.

In Team Foundation, you cannot add an item to the version control server in a single step. First, you add a file to the set of pending changes in the workspace. Then you submit all the pending changes to the version control server as a single unit.

Team Foundation enforces this two-step file-addition process to make sure that you can test and compile your code in context before you check it into the server. It also means that if Team Foundation cannot commit any one of your changes to the server for any reason, none of your changes will be committed.

Check In Pending Changes

When you check in a set of pending changes, Team Foundation creates a changeset.

To check in all pending changes in the workspace

  1. At the command prompt, type tf checkin.

  2. In the Check In dialog box, type a comment describing the nature of your changes in the Comment box, and then click Check In.

A changeset is a logical container into which Team Foundation bundles everything related to a single check-in operation. Most check-ins are more complicated than the simple example provided here. Frequently, a check-in involves changes to multiple files and folders. Therefore, a changeset represents a complete package of work that you can bring into your workspace as a single unit.

A changeset consists of:

  • Source file and folder revisions such as additions, renamings, edits, deletions, and moves.

  • Related work items such as bugs.

  • System metadata such as changeset number, author, date/time, and more.

  • Check-in notes and comments.

Next, you will create a second version of the 314.cs file to examine how different versions of a file are stored on the version control server.

To create a new version of a file that is in version control

  1. At the command prompt, type tf checkout 314.cs.

  2. Type notepad 314.cs.

  3. In Notepad, add a new line after using System.IO;, and then type using System.Windows;.

    Note

    This step intentionally introduces an error. In a later step, you are shown how to roll back to the error-free version of the file.

  4. Save your changes and close Notepad.

  5. At the command prompt, type tf checkin.

  6. In the Check In dialog box, type a comment in the Comment box, and click Check In.

    The pending change in the file 314.cs is checked in to the server as a new changeset. This also creates version 2 of 314.cs on the version control server.

Return a File to a Previous Version

Software developers are frequently asked to return their working environments to the way they were two months ago, and make a targeted fix to a specific build. Changeset numbers help identify specific sets of changes checked in over time.

A changeset number is a unique identifier for a set of related file and folder revisions. The changeset number is also a version number for the whole version control server at a specific date and time.

Therefore, you can return your workspace to the exact state of the server when you checked in that problematic line of code, using System.Windows;.

To synchronize a workspace to a changeset

  • At the command prompt, type tf get /version:C<##>, where <##> is the number of the changeset that contains the original version of 314.cs.

    Note

    You can get the correct changeset using the history command against the 314.cs file. For example, from the command line, type tf history 314.cs.

The Get command retrieves a working copy of all mapped files and subfolders from the server to the local workspace. The files are retrieved as they were at the time when changeset <##> was created. If you now open 314.cs in Notepad, you see that only one line appears, "using System.IO;".

See Also

Tasks

Walkthrough: Exploring Team Foundation Version Control

Walkthrough: Shelving Version Control Items

How to: Shelve and Unshelve Pending Changes

Reference

Add Command

Workspace Command

Unshelve Command

Other Resources

Team Foundation Version Control Walkthroughs

Team Foundation Version Control Command-Line Reference