Walkthrough: Working with Team Foundation Source Control from Command Line

This walkthrough describes how to perform source control operations using the Visual Studio 2005 command line client, tf.

During this walkthrough, you will accomplish the following tasks:

  • Create the workspace in which your personal copy of files in the source control server will reside.

  • Get a copy of source from the server.

  • Add a file to the server.

  • 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 have the appropriate permissions, you can perform source control commands at a command prompt, batch file, or script file. To do this, you must either use the Visual Studio 2005 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 enable Team Foundation commands at a command prompt

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

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

Required Permissions

To complete this walkthrough, you must have the CreateWorkspace, Checkin and PendChange permissions. For more information, see Source Control Security Rights and Permissions.

Creating a Workspace

To start working with source 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 source-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 that has a local folder on disk. To obtain a local copy of the files on the server, create a new workspace, specify the mappings for the workspace, and then use the get command to populate your workspace with source files.

Before you can perform any Team Foundation source control commands on your computer, you must create a workspace into which the output of your operations can be persisted and from which you can commit them to the server by checking them in.

To create a workspace to manage your source-controlled files

  1. Click Start, click All Programs, point to Microsoft Visual Studio 2005, point to Visual Studio Tools, and then click Visual Studio 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 the default workspace name already exists, you must type a different name, for example "cmdwalkthrough."

  5. In the Create Workspace dialog box, map to the desired team project, and then click OK. For more information, see Working with Source Control Workspaces.

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

A workspace definition that lists all files in the workspace, the version upon which each is based and also its current status, is stored on the Team Foundation Server. Because workspace definitions are stored on the server, any user who has the correct permissions can duplicate your exact working environment on their computer, minus any pending changes. For more information about how to do this, see Get Command.

Note

You can retrieve pending changes from another workspace by shelving the changes in the source workspace and then unshelving them into the destination workspace. For more information, see Walkthrough: Shelving Source Control Items, How to: Shelve and Unshelve Pending Changes, and Unshelve Command.

Add and Edit a File

After you have created a workspace, you can start to specify which files you want to add to source control, and then edit them before checking in your changes.

To prepare a file for addition to source control

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

  2. 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 your 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 source control in a single step. Instead, you add a file to the set of pending changes in the workspace, make any desired modifications, and then submit all the pending changes to source control 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 checking it into the server. It also means that if any one of your changes cannot be committed to the server for some reason, no changes are 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 involve more revisions 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 retrieve 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.

For the purposes of this walkthrough, you must create a second version of the file 314.cs on the source control server.

To create a new version of a source-controlled file

  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, click Check In to commit your pending changes to the server as a new changeset, and at the same time create version 2 of 314.cs on the source control server.

Return to a Specific Point in Time

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. Sometimes, they do not know the exact point in time when they introduced an individual line of code but they do remember the task that they were performing when they did so.

To a developer, a changeset number is a unique identifier for a set of related file and folder revisions. To Team Foundation Server however, a changeset number is a version number for the whole source 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 containing version 1 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.

This command retrieves a working copy of all mapped files and subfolders from the server to the local workspace 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 Source Control

Reference

Add Command
Workspace Command

Other Resources

Team Foundation Source Control Walkthroughs
Team Foundation Source Control Command-Line Reference