Azure Repos PDF

Contents
Azure Repos Documentation

Start Using Azure Repos
Start using Azure Repos
What is Azure Repos?
Sign up and invite some teammates
Code with Git
Key concepts
Git
Git Repositories
Overview
Learn about Git
Learn about pull requests
Learn about branch policies
Learn about forks
Quickstarts
Create repo - Web
Create repo - CLI
Create repo - Visual Studio
Create repo - IntelliJ
Create repo - Xcode
Create repo - Eclipse
Import repo - Web
Tutorials
Commit, share, and sync your code
Create a new repo
Clone an existing repo
Save work with commits
Create work in branches
Share code with push
Update code with fetch and pull
Review code with pull requests
Apply changes with rebase
Copy changes with cherry-pick
Resolve merge conflicts
Undo changes
Ignore files
Review history
Samples
Azure DevOps Samples for .NET
Concepts
History in Git
Git log history simplification
Branch organization
Pull requests
Pull request templates
Squash merge pull requests
Extend pull request workflows with pull request status
Forks
Authentication
Understand dates in Git
Understand names in Git
Cross-Platform Compatibility
Git preferences and settings
Repository settings
Scale
Manage large files
How-to Guides
Authenticate with SSHAuthenticate with SSH
Authenticate with the Git Credential Manager
Pull request status
Create a pull request status server
Use Azure Functions to create custom branch policies
Configure branch policy for an external service
Define a CI build for your repo
Drive Git development from a work item
Go get using Azure Repos
Import a repo from TFVC
Manage repos
Manage your branches
Create a new branch
Delete a branch
Restore a deleted branch
Require branch folders
Lock a branch
Branch policies
Branch permissions (Security)
Map TFVC actions to Git
Set up continuous integration
Work item completion on commit
Work with tags
Reference
RPC failures & http.postBuffer
Command reference
Format comments with markdown
Frequently asked questions
History
Commit history
Commit details
Default Git permissions (Security)
Git limits
Resources
Pro Git
Team Foundation version control
Team Foundation version control
Learn about TFVC
Quickstarts
Visual Studio
Eclipse
Xcode
Tutorials
Walkthrough: Fix a bug and get your code reviewed
Visual Studio: Review Code
Concepts
Compare TFVC and Git
Use Git and TFVC
Map TFVC actions to Git
Manage feature isolation in TFVC
Test Impact for partially mapped TFVC repositories
Develop in branches
Manage branching strategies in TFVC for DevOps
Use branches to isolate risk
Branch folders and files
Branching strategies
More branch strategies
Merge folders and files
View changeset merges
View branch hierarchies
Associate files with merge tools
How-to guides
Set up TFVC
Create and work with workspaces
Optimize your workspace
Local and server workspaces
Add check-in policies
Work with files
Create and manage pending changes
Add files
Download files
Check out and edit
Check in your work
Rename or move
Delete or restore
Gated check-ins
Manage versions
Get the history of an item
View changes using annotate
Label versions
Find and view changesets
Roll back changesets
Suspend work with shelvesets
Compare code
Compare files
Compare folders
Folder comparison filters
Reconcile differences
Resolve conflicts
Lock files and folders
Understand lock types
Lock and unlock folders or files
Set TFVC permissions (Security)
Reference
TFVC command reference
Use Team Foundation version control commands
Git commands
Git permission
Git view
Add
Checkin
Checkout (or Edit)
Get
History
Status
Undo
Delete
Properties
Rename
Shelve
Unshelve
Branch
Branches
Changeset
Configure
Destroy
Difference
Dir
Folderdiff
Help
Label
Labels
LocalVersions
Lock
Merge
Merges
Msdn
Permission
Proxy
Resolve
Rollback
Shelvesets
Undelete
Unlabel
View
Workfold
Workspace
Workspaces
Resources
Administering TFVC
Integrations
Azure Repos with Slack
REST API Reference
Git
TFVC
IDE Client Resources
Visual Studio IDE
Visual Studio Code
Visual Studio for Mac
Eclipse
IntelliJ IDEA
Azure DevOps Learn
What is Git?
What is version control?
Learn Git
Git at Scale
How we use Git at Microsoft
Plan your migration to Git
Migrate from TFVC to Git
Migrate from Subversion (SVN) to Git
Resources
GitHub & Azure Boards
Manage projects
Default Git permissions (Security)
Default TFVC permissions (Security)
Set permissions (Security)
Marketplace extensions
Azure DevOps / Azure Repos
Azure Repos Documentation

Collaborate on code development using free Git public and private repositories, pull requests, and code review.

What is Azure Repos?
Sign up and invite some teammates
Code with Git
Git Repositories
Git and Azure Repos
Get feedback with pull requests
Set branch policies
Forks
Team Foundation version control (TFVC )

Use TFVC
Compare Git and TFVC
Share code using Visual Studio
Share code using Eclipse
Share code using Xcode
5/10/2019 • 2 minutes to read • Edit Online
Use this guide to sign up and start using Azure Repos. If you're new to Azure Repos, see What is Azure Repos?.
Azure DevOps Services includes free unlimited private Git repos, so Azure Repos is easy to try out. Git is the most
commonly used version control system today and is quickly becoming the standard for version control. Git is a
distributed version control system, meaning that your local copy of code is a complete version control repository.
These fully functional local repositories make it easy to work offline or remotely. You commit your work locally, and
then sync your copy of the repository with the copy on the server.
Git in Azure Repos is standard Git. You can use the clients and tools of your choice, such as Git for Windows, Mac,
partners' Git services, and tools such as Visual Studio and Visual Studio Code.
Start with Sign up and invite some teammates.
After you sign up, learn how to code with Git. Whether your code is in Azure Repos, in a GitHub repo, or on your
local computer, this guide shows you how to get started.
Other resources to get you up and running:
Web portal navigation
Security & identity
About projects and scaling your organization
Azure Repos is a set of version control tools that you can use to manage your code. Whether your software project is large or
small, using version control as soon as possible is a good idea.
Version control systems are software that help you track changes you make in your code over time. As you edit your code, you tell
the version control system to take a snapshot of your files. The version control system saves that snapshot permanently so you
can recall it later if you need it. Use version control to save your work and coordinate code changes across your team.
Even if you're just a single developer, version control helps you stay organized as you fix bugs and develop new features. Version
control keeps a history of your development so that you can review and even roll back to any version of your code with ease.
Azure Repos provides two types of version control:
Git: distributed version control
Team Foundation Version Control (TFVC ): centralized version control
Git
Git is the most commonly used version control system today and is quickly becoming the standard for version control. Git is a
distributed version control system, meaning that your local copy of code is a complete version control repository. These fully
functional local repositories make it is easy to work offline or remotely. You commit your work locally, and then sync your copy of
the repository with the copy on the server.
Git in Azure Repos is standard Git. You can use the clients and tools of your choice, such as Git for Windows, Mac, partners' Git
services, and tools such as Visual Studio and Visual Studio Code.
Connect your favorite development environment
Protect branches with policies
Isolate code with forks
Connect your favorite development environment

Connect your favorite development environment to Azure Repos to access your repos and manage your work.
Command-line
Visual Studio Code
Visual Studio
Xcode
Eclipse
IntelliJ

Review code with your team and make sure that changes build and pass tests before it's merged.
Create a pull request
Link work items to pull requests
Set up branch policies

Git branch and pull request workflows
Leave comments
Vote on the changes

There are a few critical branches in your repo that the team relies on to always be in good shape, such as your master branch.
Require pull requests to make any changes on these branches. Developers who push changes directly to the protected branches
will have their pushes rejected.
Add conditions to your pull requests to enforce a higher level of code quality in your key branches. A clean build of the merged
code and approval from multiple reviewers are extra requirements that you can set to help protect your key branches.
Branch policies overview
How to configure branch policies
Branch permissions
Pull requests and branch policies enable teams to enforce many best practices related to reviewing code and running automated
builds. But many teams have additional requirements and validations to perform on code. To cover these individual and custom
needs, Azure Repos offers pull request statuses.
Pull request statuses integrate into the PR workflow. They allow external services to programmatically sign off on a code change
by associating simple success/failure information with a pull request.
Pull request status overview
Create a PR status server with Node.js
Configure a branch policy for an external service

Isolate code with forks
Forks are a great way to isolate experimental, risky, or confidential changes from the original codebase. A fork is a complete copy
of a repository, including all files, commits, and (optionally) branches. The new fork acts as if someone cloned the original
repository and then pushed to a new, empty repository.
After a fork has been created, new files, folders, and branches are not shared between the repositories unless a pull request carries
them along. After you're ready to share those changes, it's easy to use pull requests to push the changes back to the original
repository.
Learn more about forks
TFVC
Azure Repos also supports Team Foundation Version Control (TFVC ). TFVC is a centralized version control system. Typically, team
members have only one version of each file on their dev machines. Historical data is maintained only on the server. Branches are
path-based and created on the server.
Get started by creating a project, configuring your workspace, and reviewing and sharing your code. You can use any one of these
clients or IDEs:
Visual Studio
Xcode
Eclipse
Learn more about TFVC

Sign up for free and invite others to collaborate on
your project
Sign up for Azure DevOps to upload and share code in free, unlimited private Git repositories.
Then, connect to your favorite development tool like Eclipse, Xcode, Visual Studio, IntelliJ, or Android Studio to
work on apps anytime, anywhere.
Sign up with a personal Microsoft account

1. Select the sign-up link for Azure DevOps.
2. Enter your email address, phone number, or Skype ID for your Microsoft account. If you're a Visual Studio
subscriber and you get Azure DevOps as a benefit, use the Microsoft account associated with your
subscription. Select Next.
If you don't have a Microsoft account, choose Create one. To learn more, see create a Microsoft account.
3. Enter your password and select Sign in.
4. To get started with Azure DevOps, select Continue.
An organization is created based on the account you used to sign in. Sign in to your organization at any time, (
https://dev.azure.com/{yourorganization} ).
You can rename and delete your organization, or change the organization location. To learn more, see the
following articles:
Rename an organization
Change the location of your organization
If you signed in with an existing Microsoft account, your next step is to Create a project. If you signed in with a
newly created Microsoft account, then your project is automatically created and named after your account name.
To learn more about managing projects, see Manage projects.
Sign up with a GitHub account

IMPORTANT
If your GitHub email address is associated with an Azure AD-backed organization in Azure DevOps, you can't sign in with
your GitHub account, rather you must sign in with your Azure AD account.
1. Select the sign-up link for Azure DevOps, Start free with GitHub. If you're already part of an Azure
DevOps organization, select Sign in to Azure DevOps.
2. Select Sign in with GitHub.
If you have an account in session already, select Use another account. You're taken to GitHub sign-in
where you can enter your GitHub user name or email address.
3. Enter your GitHub account credentials, and then select Sign in.
4. Select Authorize Microsoft corporation.
5. To get started with Azure DevOps, select Continue.
An organization is created based on the account you used to sign in. Sign in to your organization at any time, (
https://dev.azure.com/{yourorganization} ).
You can rename and delete your organization, or change the organization location. To learn more, see Manage
organizations.
Enable GitHub invitations
Creating a new Azure DevOps organization with your GitHub username turns on the Invite GitHub users policy
by default. For existing organizations, your administrator can turn on this capability via Organization settings >
Policies tab.
Once the setting is changed, sign out of Azure DevOps, and then from a fresh browser session, sign back in to the
organization dev.azure.com/{organizationName} or organizationName.visualstudio.com with your GitHub
credentials. You're now recognized as a GitHub user and the GitHub invitation experience is available to you.
For more information about GitHub authentication, see FAQs.

Invite team members
Give team members access to your organization by adding their email addresses or GitHub usernames to your
organization. For GitHub user invitations, ensure you've enabled the policy, Invite GitHub users in Organization
settings > Policies tab.
1. Sign in to your organization ( https://dev.azure.com/{yourorganization} ).
2. Select Organization settings.
3. Select Users > Add new users.
4. Enter the following information:

Users: Enter the email addresses (Microsoft accounts) or GitHub usernames for the users. You can add
several email addresses by separating them with a semicolon (;). An email address appears in red when
it's accepted.
Access level: Leave the access level as Basic for users who will contribute to the code base. To learn
more, see About access levels.
Add to project: Select the project you want to add them to.
DevOps Groups: Leave as Project Contributors, the default security group for users who will
contribute to your project. To learn more, see Default permissions and access assignments.
NOTE
Add email addresses for personal Microsoft accounts and IDs for GitHub accounts unless you plan to use Azure
Active Directory (Azure AD) to authenticate users and control organization access. If a user doesn't have a Microsoft
or GitHub account, ask the user to sign up for a Microsoft account or a GitHub account.
5. When you're done, select Add to complete your invitation.

Code with Git
After you create a new organization and team project in Azure DevOps Services, you can begin sharing your code
with others.
In this article, we'll show you how to start working with your code in Azure Repos with a simple walkthrough that
covers:
Installing Git command line tools
Cloning a Git repository
Working in a branch
Sharing your changes
Creating a pull request
Install Git command-line tools

Install one of the following Git command-line tools:
To install Git for Windows, including Git Credential Manager, see Install Git Credential Manager for Windows.
To install on macOS or Linux, check out the Installing Git chapter in the open-source Pro Git book. For macOS
and Linux, we recommend configuring SSH authentication
Get your code

To get a copy of the source code, you clone the Git repo that contains the code. Cloning creates both a local copy of
the source code so you can work with it, and all the version control information so Git can manage the source code.
If you're just getting started with Azure Repos, your code might be in one of several places:
I just created my organization in Azure DevOps, so I don't have any code
The code is in my (or my organization's) Azure Repos Git repo
The code is in another Git repo such as GitHub or another Azure Repos Git repo
The code is on my local computer and not yet in version control
I just created my organization in Azure DevOps, so I don't have any code
If you just signed up for Azure DevOps Services, by default you have a project named MyFirstProject and a Git
repo named MyFirstProject . If you want to work in that repo, you can clone it and then add your code to that repo.
If you want to make a new repo, follow the steps in Create a new Git repo in your project and then clone the new
repo and add your code there.
The code is in my (or my organization's) Azure Repos Git repo
If the code is in your (or your organization's) Azure Repo, you can clone the Git repo to your local computer and
start working with it by jumping down to Clone the repo.
The code is in another Git repo
If the code is in another Git repo, such as a GitHub repo or a different Azure Repo instance, you can import it into a
new or existing empty Git repo. Follow the steps in Import a Git repo, and then return to this article and jump
down to Clone the repo.
The code is on my local computer and not yet in version control
If your code is not yet in version control, you have a couple of options:
Create a new repository and add your code there. To do this, follow the steps in Create a new Git repo in your
project and then come back to this article and jump down to Clone the repo.
Add your code to an existing repository. To do this, jump down to Clone the repo.
After the repository is cloned, we'll show you how to add your existing code to the repo.
Clone the repo

To work with a Git repo, you clone it to your computer. Cloning a repo creates a complete local copy of the repo for
you to work with. Cloning also downloads all commits and branches in the repo and sets up a named relationship
with the repo on the server. Use this relationship to interact with the existing repo, pushing and pulling changes to
share code with your team.
1. From your web browser, open the team project for your organization and select Repos > Files. If you don't
have a team project, create one now.
2. Select Clone in the upper-right corner of the Files window and copy the clone URL.
3. Open the Git command window (Git Bash on Git for Windows) and browse to the folder where you want
the code from the repo stored on your computer. Run git clone followed by the path copied from the
Clone URL in the previous section, as shown in the following example.
git clone https://dev.azure.com/contoso-ltd/MyFirstProject/_git/contoso-demo
Git downloads a copy of the code, including all commits and branches from the repo, into a new folder for
you to work with.
4. Switch your directory to the repository that you just cloned.
cd fabrikam-web
Keep this command window open, because you'll use it in the following steps.
1. From your web browser, open the team project for your organization and select the Code page. If you don't
2. Select Clone in the upper-right corner of the Code page and copy the Clone URL.
git clone https://regius@dev.azure.com/regius/FabrikamFiber%20Web/_git/SmartHotel360
you to work with.
cd SmartHotel360
Work in a branch
Git branches isolate your changes from other work being done in the project. The recommended Git workflow
uses a new branch for every feature or fix that you work on.
Create branches by using the branch command. This command creates a reference in Git for the new branch and
a pointer back to the parent commit so Git can keep a history of changes as you add commits to the branch.
Git always adds new commits to the current local branch. Check what branch you're working on before you
commit so that you don't commit changes to the wrong branch.
Switch between local branches by using the checkout command. Git will change the files on your computer to
match the latest commit on the checked-out branch.
In this step, we'll create a working branch and make a change to the files on your computer in that branch.
Use the branch command to create the branch and checkout to switch to that branch. In the following example,
the new branch is named users/jamal/feature1 .
git branch users/jamal/feature1

git checkout users/jamal/feature1
When you create a branch from the command line, the branch is based on the currently checked-out branch. If you
just cloned the repository, the default branch (typically master ) is checked out. Because you just cloned, your local
copy of master has the latest changes.
If you're working with a previously cloned repository, ensure that you have checked out the right branch (
git checkout master ) and that it's up to date ( git pull origin master ) before you create your new branch.
git checkout master

git pull origin master
git branch users/jamal/feature1
git checkout users/jamal/feature1
You can replace the first three commands in the previous example with the following command, which creates a
new branch named users/jamal/feature1 based on the latest master branch.
git pull origin master:users/jamal/feature1
Switch back to the Git Bash window that you used in the previous section. Run the following commands to create
and check out a new branch based on the master branch.
git pull origin master:users/jamal/feature1

git checkout feature1
Browse to the location of the repository on your local computer, make an edit to one of the files, and save it. If
you're adding code from your local computer to the repository, you can add it here by copying it to the folder
where you cloned the repository.
Share your changes

When you're happy with the changes on your local computer, you can share them back to the remote repository.
1. Commit your changes by entering the following command in the Git command window:
git add .
git commit -m "My first commit"
The git add . command stages your files, and git commit -m "My first commit" commits the staged files
with the specified commit message.
2. Push your changes to the Git repo on the server by entering the following command in the Git command
window:
git push origin users/jamal/feature1
Your code is now shared to the remote repository, in a branch named users/jamal/feature1 . To merge the code
from your working branch into the master branch, use a pull request.
Review and merge your changes with a pull request

Pull requests combine the review and merge of your code into a single collaborative process. After you’re done
fixing a bug or new feature in a branch, create a new pull request. Add the members of the team to the pull request
so they can review and vote on your changes. Use pull requests to review works in progress and get early feedback
on changes. There’s no commitment to merge the changes because you can abandon the pull request at any time.
This example shows the basic steps of creating and completing a pull request.
1. From your web browser, open the team project for your organization and select Repos > Files. If you kept
your browser open after getting the clone URL, you can just switch back to it.
2. Select Create a pull request in the upper-right corner of the Files window. If you don't see a message like
You updated users/jamal/feature1 just now, refresh your browser.
3. New pull requests are configured to merge your branch into the default branch, which in this example is
master . The title and description are pre-populated with your commit message.
You can add reviewers and link work items to your pull request.
You can review the files included in the pull request at the bottom of the New Pull Request window.
Select Create to create the pull request.

4. You can view the details of your pull request from the Overview tab, and view the changed files, updates,
and commits in your pull request from the other tabs. Select Complete to begin the process of completing
the pull request.
5. Select Complete merge to complete the pull request and merge your code into the master branch.
NOTE
This example shows the basic steps of creating and completing a pull request. To learn more about pull requests, including
voting and reviewing, commenting, autocomplete, and more, see Pull requests overview.
1. From your web browser, open the team project for your organization and select the Code page. If you don't
2. Select Clone in the upper-right corner of the Code page and copy the Clone URL.
git clone https://dev.azure.com/contoso-ltd/MyFirstProject/_git/contoso-demo
you to work with.
cd fabrikam-web
Your changes are now merged into the master branch, and your users/jamal/feature1 branch is deleted on the
remote repository. To delete your local copy of the branch, switch back to your Git Bash command prompt and run
the following commands.
git checkout master

git branch -d users/jamal/feature1
The git checkout master command switches you to the master branch. The git pull origin master command
pulls down the latest version of the code in the master branch, including your changes and the fact that
users/jamal/feature1 was merged. The git branch -d users/jamal/feature1 command deletes your local copy of
that branch.
Now you're ready to create a new branch, write some code, and do it again.
Try this next

Set up continuous integration and delivery or learn more about working with a Git repo.
Key concepts
Here you'll find definitions of key concepts and artifacts used in Azure Repos.
Branch
Branches are lightweight references that keep a history of commits and provide a way to isolate changes for a
feature or a bug fix from your master branch and other work. Committing changes to a branch doesn't affect other
branches. You can push and share branches with other people on your team without having to merge the changes
into master.
Switching between branches is quick and easy. Git doesn't create multiple copies of your source code when you're
working with branches - it uses the history information stored in commits to re-create the files in a branch when
you start working on it.
Learn more: branches, branch organization, and how we use branches at Microsoft.
Branch policies
Branch policies are an important part of the Git workflow. You use them to help protect the important branches in
your development, like master . Branch policies enable you to:
Isolate work in progress from the completed work in your master branch.
Guarantee that changes build before they get to master.
Limit who can contribute to specific branches.
Enforce who can create branches and the naming guidelines for the branches.
Automatically include the right reviewers for every code change.
Enforce best practices with required code reviewers.
Learn more: branch policies.
Clone
Create a complete local copy of an existing Git repo by cloning it. Cloning a repo downloads all commits and
branches in the repo and sets up a named relationship with the existing repo that you cloned. Use this relationship
to interact with the existing repo, pushing and pulling changes to share code with your team.
Learn more: cloning.
Commit
A commit is a group of changes saved to your local repository. You can share these changes to the remote
repository by pushing.
Learn more: commits.
Fork
A fork is a complete copy of a repository, including all files, commits, and (optionally) branches. The new fork acts
as if someone cloned the original repository and then pushed to a new, empty repository. After a fork has been
created, new files, folders, and branches are not shared between the repositories unless a pull request carries them
along. When you're ready to share those changes, it's easy to use pull requests to push the changes back to the
original repository.
Learn more: forks
Git
Git is the most commonly used version control system today and is quickly becoming the standard for version
control. Git is a distributed version control system, so your local copy of code is a complete version control
repository. These fully functional local repositories make it is easy to work offline or remotely. You commit your
work locally, and then sync your copy of the repository with the copy on the server.
Git in Azure Repos is standard Git. You can use the clients and tools of your choice, such as Git for Windows, Mac,
partners' Git services, and tools such as Visual Studio and Visual Studio Code.
Learn more: Git and Azure Repos.
Git workflow
Version control has a general workflow that most developers use when writing code and sharing it with the team.
These steps are:
1. Get a local copy of code if they don't have one yet.
2. Make changes to code to fix bugs or add new features.
3. When the code is ready, make it available for your team to review.
4. After the code is reviewed, merge it into the team's shared codebase.
Git has a version of this workflow that uses terminology and commands such as repositories, branches, commits,
and pull requests. These terms might sound familiar if you've used a version control system like Team Foundation
Version Control (TFVC ) or Subversion, but they behave differently in Git.
1. Create a branch for the changes you plan to make and give it a name, such as users/jamal/fix-bug-3214 or
features/cool-feature .
2. Commit changes to your branch. People often have multiple commits for a bug fix or feature.
3. Push your branch to the remote repository.
4. Create a pull request so other people can review your changes. To incorporate feedback, you might need to
make more commits and push more changes. When the code is ready, complete the pull request and merge
your code into the target branch, such as master .
Use this workflow if you're new to Git. As your team gets more experienced and confident with Git, extend it to suit
your team's needs.
Learn more: how we use Git at Microsoft.
Notifications
With notifications, you receive an email when changes occur to work items, code reviews, pull requests, source
control files, and builds. For example, you can get notified whenever a bug that you opened is resolved, or when a
work item is assigned to you. You receive notifications based on rules or subscriptions made by you, for your
teams, or for the project. Learn more: About notifications.
Projects
A project, which was previously known as a team project, provides a repository for source code. A project provides
a place where a group of people can plan, track progress, and collaborate on building software solutions. A project
is defined for an Azure DevOps Services organization or within a TFS project collection. You can use it to focus on
those objects defined within the project. To learn more, see About projects and scaling your organization.
Public projects
A project created within an Azure DevOps Services organization that is visible to the whole world. Everyone in the
world can discover them and perform limited operations. Administrators can control who gets to fully contribute.
Administrators can switch a project from private to public, and vice-versa, as described in Change the project
visibility.
Pull request
Create pull requests to review and merge code in a Git project. Pull requests let your team review code and give
feedback on changes before you merge it into the master branch. Pull requests can come from either topic
branches within the same repository or a branch in a fork of the original repository. Reviewers can step through
the proposed changes, leave comments, and vote to approve or reject the code.
Learn more: pull requests.
Pull
A pull command updates the code in your local repository with the changes from other members of your team
that are in the remote repository.
Learn more: pull.
Push
Share changes made in commits and branches by using the push command.
When you push, Git uploads the saved commits in your checked branch to the remote repository. If the branch
exists on the remote repository, Git takes the commits and adds them to that branch on the remote repository. If
that branch doesn't exist, Git creates a new branch with the same commits as your local branch.
Learn more: push.
Repository
A repository is a location for your code managed by version control. Azure Repos supports both Git and TFVC.
Teams
A team corresponds to a selected set of project members. With teams, organizations can subcategorize work to
better focus on all the work they track within a project. Each team gets access to a suite of Agile tools. Teams can
use these tools to work autonomously and collaborate with other teams across the enterprise. Each team can
configure and customize each tool to meet their work requirements. To learn more, see About teams and Agile
tools.
Team Foundation Version Control (TFVC)

A centralized version control system. With TFVC, devs have only one version of each file on their dev machines.
Branches are path-based and created on the server. Historical data is maintained only on the server. Learn more:
Use Team Foundation Version Control.
Use Git repositories to host and collaborate on your code using Azure DevOps Services or Team Foundation Server (TFS ).
5-Minute Quickstarts
Get started by creating a repo, uploading your code, and inviting developers to work in the repo. You can use any one of these
clients or IDEs:
Web
Visual Studio
Command-line
Xcode
Eclipse
IntelliJ
Or, you can import an existing repo from GitHub, Bitbucket, GitLab, or other location to a new, empty repo.
Videos
https://channel9.msdn.com/Events/Connect/2017/T178/player https://channel9.msdn.com/Events/Connect/2017/T184/player
Step-by-Step Tutorials
Learn the basics of working in Git with these tutorials which show tasks performed using Visual Studio or the command line.
Clone an existing repo
Review history
Concepts
Authentication
History in Git
Branch organization
Pull requests
Forks
Branch policies
Customize and extend pull request workflows with pull request status
How we use Git at Microsoft
Reference
Format comments with markdown
Command reference
Resources
What is Git?
Plan your migration to Git
Git at Scale
Marketplace extensions
Azure Repos | Azure DevOps Server 2019 | TFS 2018 | TFS 2017 | TFS 2015 | VS 2017 | VS 2015
Host and manage your code in Git version control with Azure DevOps Services and Team Foundation Server. Use version control
to save your work and coordinate code changes across your team. Even if you're just a single developer, version control helps you
stay organized as you fix bugs and develop new features. Version control keeps a history of your development so that you can
review and even rollback to any version of your code with ease.
New to Git? Learn more about how Git and Azure Repos can help your team ship great code, and learn how we use Git at
Microsoft.
Get started
Connect your favorite development environment to Azure DevOps Services to access your repos and manage your work. Azure
DevOps Services IDE integrations are available for Visual Studio, Visual Studio Code, Eclipse, and IntelliJ.
New to Git? Learn how to share code with Git and Azure Repos with the following getting started guides:
Web
Visual Studio
Command-line
Xcode
Eclipse
IntelliJ
Git tutorial
Get up and running with Git and Azure Repos in just a few minutes with the Azure Repos Git quick start.
The Azure Repos Git tutorial walks you through Git tasks like creating repos, working in branches, saving your work, and sharing
your changes. Every task is presented step-by-step in Visual Studio or from the command line.
Authenticate with your repos

You can authenticate with your Azure Repos/TFS Git repo from any platform using cross-platform credential managers or SSH
public key authentication.
If you have code ready to share in Azure Repos, our getting started guides take you through the steps to connect your
development environment to a Git repo in Azure Repos and share your code with your team.
Get Started with Visual Studio
Get Started with Xcode
Get Started with Eclipse
Get Started with IntelliJ
Manage your repos

Manage your repos and customize your team's workflow. Set up permissions to control access to your code and set up branch
policies and continuous integration to prevent build breaks and catch bugs sooner.
Create, delete, and rename repos.
Set repo permissions and branch permissions
Set up branch policies to protect key branches
Set up continuous integration to catch bugs sooner.
Review code
Review code with your team and make sure that changes build and pass tests before it's merged.
Set up branch policies
Git branch and pull request workflows

Pull requests combine the review and merge of your code into a single collaborative process. Once you're done fixing a bug or
new feature in a branch, create a new pull request. Add the members of the team to the pull request so they can review and vote
on your changes.
Azure Repos has a rich pull request experience that's easy to use and scales to your needs. Use pull requests to review works in
progress and get early feedback on changes. There's no commitment to merge the changes as the owner can abandon the pull
request at any time.
Get your code reviewed

The code review done in a pull request isn't just to find obvious bugs. That's what your tests are for. A good code review catches
less obvious problems that could lead to costly issues later. Code reviews help protect your team from bad merges and broken
builds that sap your team's productivity. The review catches these problems before the merge, protecting your important
branches from unwanted changes.
Cross-pollinate expertise and spread problem solving strategies by using a wide range of reviewers in your code reviews.
Diffusing skills and knowledge makes your team stronger and more resilient.
Give great feedback

High quality reviews start with high quality feedback. The keys to great feedback in a pull request are:
Have the right people review the pull request
Make sure that reviewers know what the code does
Give actionable, constructive feedback
Reply to comments in a timely manner
When assigning reviewers to your pull request, make sure you select the right set of reviewers. You want reviewers that will
know how your code works, but try to also include developers working in other areas so they can share their ideas. Provide a
clear description of your changes and provide a build of your code that has your fix or feature running in it.
Reviewers should make an effort to provide feedback on changes they don't agree with. Identify the issue and give a specific
suggestions on what you would do differently. This feedback has clear intent and is easy for the owner of the pull request to
understand. The pull request owner should reply to the comments, accepting the suggestion or explaining why the suggested
change isn't ideal. Sometimes a suggestion is good, but the changes are outside the scope of the pull request. Take these
suggestions and create new work items and feature branches separate from the pull request to make those changes.
Provide reviewer guidance with pull request templates
Leave comments
Vote on the changes

There are a few critical branches in your repo that the team relies on always being in good shape, such as your master branch.
Require pull requests to make any changes on these branches. Developers pushing changes directly to the protected branches
Add additional conditions to your pull requests to enforce a higher level of code quality in your key branches. A clean build of the
merged code and approval from multiple reviewers are some extra requirements you can set to protect your key branches.
Branch policies overview
Branch permissions

Pull requests and branch policies enable teams to enforce many best practices related to reviewing code and running automated
builds, but many teams have additional requirements and validations to perform on code. To cover these individual and custom
needs, Azure Repos offers pull request statuses. Pull request statuses integrate into the PR workflow and allow external services
to programmatically sign off on a code change by associating simple success/failure type information with a pull request.
Pull request status overview
Create a PR status server with Node.js
Videos
https://www.youtube-nocookie.com/embed/J_DHkUKxI0E?start=0
Azure Repos | Azure DevOps Server 2019 | TFS 2018 | TFS 2017
Branch policies are an important part of the Git workflow and enable you to:
Isolate work in progress from the completed work in your master branch
Guarantee changes build before they get to master
Limit who can contribute to specific branches
Enforce who can create branches and the naming guidelines for the branches
Automatically include the right reviewers for every code change
Enforce best practices with required code reviewers
Adopt a Git branching strategy

There are a few critical branches in your repo that the team relies on always being in good shape, such as your master branch.
Require pull requests to make any changes on these branches. Developers pushing changes directly to the protected branches
Keep your branch strategy simple by building your strategy from these three concepts:
1. Use feature branches for all new features and bug fixes.
2. Merge feature branches into the master branch using pull requests.
3. Keep a high quality, up-to-date master branch.
A strategy that extends these concepts and avoids contradictions will result in a version control workflow for your team that is
consistent and easy to follow.
Adopt a branching strategy
Branch permissions
Require branch folders
Branching how to guides

Learn how to perform common tasks when working with branches.
Branches tutorial
How to create a branch

How to delete a branch
Restore a deleted branch
How to lock branches

Azure Repos | Azure DevOps Server 2019 | TFS 2018
Forks are a great way to isolate experimental, risky, or confidential changes from the original codebase. A fork is a complete copy
of a repository, including all files, commits, and (optionally) branches. The new fork acts as if someone cloned the original
repository, then pushed to a new, empty repository. After a fork has been created, new files, folders, and branches are not shared
between the repositories unless a pull request carries them along. Once you're ready to share those changes, it's easy to use pull
requests to push the changes back to the original repository.
The forking workflow

When working with forks, you typically use the following workflow:
1. Create a fork
2. Clone it locally
3. Make your changes locally and push them to a branch
4. Create and complete a PR to upstream
5. Sync your fork to the latest from upstream
Learn more
Learn more about forks

Create a new Git repo in your project
Azure Repos | Azure DevOps Server 2019 | TFS 2018 | TFS 2017 | TFS 2015
Azure DevOps Services and TFS projects contain Git repositories, work items, builds, and releases. You can use Git
repos in your projects to manage your source code as your project grows. This guide shows you how to create a
Git repo using the web portal for either Azure DevOps Services (hosted on Azure) or Team Foundation Server
(TFS - on-premises).
Prerequisites
An organization in Azure DevOps. If you don't have one, you can sign up for one for free. Each organization
includes free, unlimited private Git repositories.
Git command-line tools:
Install Git for Windows, which includes Git Credential Manager - Windows
Install Git for macOS and Linux.
For macOS and Linux, we recommend configuring SSH authentication
Create a repo using the web portal

1. Navigate to the Repos page in your project by browsing to https://<your account name>.visualstudio.com ,
hovering your mouse over the name of your project, and selecting the Repos icon. You can select it from
the All projects list, or from the Recent projects list if you have accessed it recently.
2. From the repo drop-down, select New repository.

3. In the Create a new repository dialog, verify that Git is the repo type and enter a name for your new repo.
You can also choose to add a README and create a .gitignore for the type of code you plan to manage in
the repo. A README contains information about the code in your repo, and a .gitignore file tells Git which
types of files to ignore, such as temporary build files from your development environment.
4. When you're happy with the repo name and choices, select Create.
A new empty Git repo is now created in your project.
If you created an empty repo (no README or .gitignore), you'll see instructions on how to clone the
repo to your computer or push code in an existing repo into the newly created one.
In this example you created a README and a .gitignore, so you'll see an overview of the files in your
repo, and you can clone the repo using the Clone link on the upper right of the page to get working
with a local copy of the repo immediately.
1. Navigate to your project by browsing to https://dev.azure.com/<your organization name> and selecting the
name of your project. You can select it from the All projects list, or from the Recent projects list at the top
if you have accessed it recently.
2. In the Project area in the web portal, select Code, then select the drop-down next to the current repo name
and choose New Repository.
3. In the Create a new repository dialog, verify that Git is the repo type and enter a name for your new repo.
You can also choose to add a README and create a .gitignore for the type of code you plan to manage in
the repo. A README contains information about the code in your repo, and a .gitignore file tells Git which
types of files to ignore, such as temporary build files from your development environment.
4. When you're happy with the repo name and choices, select Create.
A new empty Git repo is now created in your project.
If you created an empty repo (no README or .gitignore), you'll see instructions on how to clone the
repo to your computer or push code in an existing repo into the newly created one.
In this example you created a README and a .gitignore, so you'll see an overview of the files in your
repo, and you can clone the repo using the Clone link on the upper right of the page to get working
with a local copy of the repo immediately.
Clone the repo to your computer

To work with a Git repo, you clone it to your computer. Cloning a repo creates a complete local copy of the repo
for you to work with, and downloads all commits and branches in the repo and sets up a named relationship with
the repo on the server. Use this relationship to interact with the existing repo, pushing and pulling changes to
share code with your team.
1. From your web browser, open the team project for your organization in Azure DevOps and select Repos >
Files. If you don't have a team project, create one now.
2. Select Clone in the upper-right corner of the Files window and copy the clone URL.
git clone https://dev.azure.com/fabrikam-fiber/MyFirstProject/_git/
you to work with.
4. Switch your directory to the repository that you cloned.
cd fabrikam-fiber
1. Select Clone in the upper-right corner of the Code window and copy the Clone URL.
2. Open the Git command window (Git Bash on Git for Windows), navigate to the folder where you want the
code from the repo stored on your computer, and run git clone followed by the path copied from the
Clone URL in the previous step, as shown in the following example.
git clone https://fabrikam-fiber.visualstudio.com/DefaultCollection/MyFirstProject/_git/
After running the previous command, Git downloads a copy of the code, including all commits and
branches from the repo, into a new folder for you to work with.
Keep this command window open, as you'll use it in the following steps.
Work with the code

In this step, we'll make a change to the files on your computer, commit the changes locally, push the commit up to
the repo that is stored on the server, and view the changes there.
1. Browse to the folder on your computer where you cloned the repo and open the README.md file in your
editor of choice.
2. Make some changes, for example add This is my first edit. to the file, and save and close the file.
3. In the Git command window, navigate to the fabrikam-fiber directory by entering the following command:
cd fabrikam-fiber
4. Commit your changes by entering the following command in the Git command window:
git commit -a -m "My first commit"
When using git commit , -a means to commit all changed files, and -m specifies a commit message.
5. Push your changes up to the Git repo on the server by entering the following command into the Git
command window:
git push
6. Switch back to the web portal and select History from the Code view to view your new commit. The new
repo has two commits: the first commit where the README and .gitignore were added when the repo was
created, and the commit you just made.
7. Switch to the Files tab and click on the README file to view your changes.
Next steps
New to Git repos? Learn more
Learn more about using Git in the Git tutorial
Get started with Git from the command line
This guide shows you how to share your code in a Git repo in Azure Repos using the command line.
The instructions below use the default bash shell used on Linux and macOS, but the Git commands will work in
any shell, including Git Bash from Git for Windows.
Prerequisites
An organization in Azure DevOps. If you don't have an organization, you can sign up for one for free. Each
organization includes free, unlimited private Git repositories.
Download and install Azure CLI and add Azure DevOps extension
1. Install the Azure CLI. You must have at least v2.0.49 , which you can verify with az --version command.
2. Add the Azure DevOps Extension az extension add --name azure-devops
3. Run the az login command.

If the CLI can open your default browser, it will do so and load a sign-in page. Otherwise, you need to open
a browser page and follow the instructions on the command line to enter an authorization code after
navigating to https://aka.ms/devicelogin in your browser. For more information, see the Azure CLI login
page.
4. For seamless commanding, set the organization and project as defaults in configuration.
az devops configure --defaults organization=https://dev.azure.com/contoso project=contoso
Download and install Git

Windows
macOS
Linux and Unix
Windows
Download and install Git for Windows , which includes the Git Credential Manager to easily connect to Azure
Repos.
macOS
Use Homebrew to install and set up Git.
brew install git
Linux and Unix

Use your distribution's package management system to download and install Git. For example, on Ubuntu:
sudo apt-get install git

Refer to the list of install commands for the most up to date instructions for your Linux distribution.
Create your local repo

Create a local Git repo for your code. If your code is already in a local Git repo, you can skip this step.
1. Navigate to the folder where your code is on the command line:
cd /home/fabrikam/fiber
2. Create a Git repo on your machine to store your code. You will connect this repo to Azure Repos in the next
section.
git init .
3. Commit your code into the local Git repo.
git add --all

git commit -m "first commit of my code"
Create your Git repo in Azure Repos

1. Create a new Git repo in Azure Repos for your code.
az repos create --name FabrikamApp
2. Copy the clone URL from the remote URL attribute in the JSON output.
$ az repos create --name FabrikamApp
[
{
"defaultBranch": null,
"id": "fa3ee42f-519d-4633-8e31-4a84de343ca3",
"isFork": null,
"name": "FabrikamApp",
"parentRepository": null,
"project": {
"abbreviation": null,
"description": "This is the pipeline project for github repo",
"id": "fa3ee42f-519d-4633-8e31-4a84de343ca4",
"lastUpdateTime": "2019-04-09T08:32:15.977Z",
"name": "Fabrikam",
"revision": 255,
"state": "wellFormed",
"url": "https://dev.azure.com/fabrikops2/_apis/projects/fa3ee42f-519d-4633-8e31-4a84de343ca4",
"visibility": "public"
},
"remoteUrl": "https://dev.azure.com/fabrikops2/Fabrikam/_git/FabrikamApp",
"size": 0,
"sshUrl": "fabrikops2@vs-ssh.visualstudio.com:v3/fabrikops2/Fabrikam/FabrikamApp",
"url": "https://dev.azure.com/fabrikops2/fa3ee42f-519d-4633-8e31-
4a84de343ca4/_apis/git/repositories/fa3ee42f-519d-4633-8e31-4a84de343ca3",
"validRemoteUrls": null
}
]
3. Connect your local repo to the Git repo in Azure Repos using the copied clone URL in the git remote
command:
git remote add origin https://dev.azure.com/fabrikops2/Fabrikam/_git/FabrikamApp
Push your code

Before pushing your code, set up authentication with credential managers or SSH before continuing.
git push origin master
Next steps
Share your code with Visual Studio 2017 and Azure
Repos Git
Share your Visual Studio solution in a new Azure DevOps Services or Team Foundation Server Git repo.
This article walks you through the steps to get a Visual Studio solution on your PC into a Git repo you can share
with others.
If you want to work with a Visual Studio solution hosted in an existing repo, see the Git tutorial.
Prerequisites
Create a local Git repo for your project

Create a new local Git repo for your project by selecting on the status bar in the lower
right hand corner of Visual Studio. This will create a new repo in the folder the solution is in and commit your
code into that repo. You can also right-click your solution in Solution Explorer and choose Add Solution to
Source Control.
Once you have a local repo, select items in the status bar to quickly navigate between Git tasks in Team Explorer.
shows the number of unpublished commits in your local branch. Selecting this opens the
Synchronization view in Team Explorer.
shows the number of uncommitted file changes. Selecting this opens the Changes view in Team Explorer.
shows the current Git repo. Selecting this opens the Connect view in Team Explorer.
shows your current Git branch. Selecting this displays a branch picker to quickly switch between
Git branches or create new branches.
NOTE
If you don't see any icons such as or , ensure that you have a project open that is part of a Git repo. If your
project is brand new or not yet added to a repo, you can add it to one by selecting on the
status bar, or by right-clicking your solution in Solution Explorer and choosing Add Solution to Source Control.
Publish your code to Azure Repos

1. Navigate to the Push view in Team Explorer by choosing the icon in the status bar. You can also select
Sync from the Home view in Team Explorer.
2. In the Push view in Team Explorer, select the Publish Git Repo button under Push to Visual Studio
Team Services.
3. Verify your email and select your account in the Team Services Domain drop-down.
4. Enter your repository name and select Publish repository.
This creates a new project in your account with the same name as the repository. To create the repo in an
existing project, click Advanced next to Repository name and select a project.
5. Your code is now in a Git repo in Azure Repos. You can view your code on the web by selecting See it on
the web .
Commit and push updates

1. As you write your code, your changes are automatically tracked by Visual Studio. You can commit changes
to your local Git repository by selecting the pending changes icon from the status bar.
2. On the Changes view in Team Explorer, add a message describing your update and commit your changes.
3. Select the unpublished changes status bar icon (or select Sync from the Home view in Team
Explorer). Select Push to update your code in Azure DevOps Services/TFS.
Get changes from others
Sync your local repo with changes from your team as they make updates.
1. From the Synchronization view in Team Explorer, fetch the commits that your team has made. Double-
click a commit to view its file changes.
2. Select Sync to merge the fetched commits into your local repo and then push any unpublished changes to
Azure Repos.
3. The changes from your team are now in your local repo and visible in Visual Studio.

I don't see the Add to Source Control button in the status bar.
How can I see what changes are in a commit before I pull it into my local branch?
How do I associate my commits with work items?
Can I use the Git command prompt with Visual Studio?
I don't see the Add to Source Control button in the status bar.
The button in the status bar was added in Visual Studio 2017 (it was Publish in Visual
Studio 2015 Update 2 and later) and will only appear when you have Git as your source control provider. If your
code is already in a Git repo, you won't see the Add to Source Control button in the status bar, but the status of
the current branch in your local repo instead.
If you are in a previous version of Visual Studio, create a local Git repo for your project by selecting the Create
new Git repository option in the New Project window when you create a new project.
You can create a local Git repo for an existing solution by right-clicking your project in the Solution Explorer and
selecting Add Solution to Source Control.
How can I see what changes are in a commit before I pull it into my local branch?
To see what's changed in a commit, go to the Synchronization page in Team Explorer and right-click on the
commit. Select View Commit Details. You can then right-click on any file modified by the commit and select
Compare with Previous... to view the changes compared to the previous version of the file.
How do I associate my commits with work items?
You can include work items in your commits through Related Work Items in the Changes page in Team
Explorer.
Work items can be included in commits by adding #ID into the commit message. For example,
Fixing bug #23 in the reporting tools would link work item 23 to the commit. The work item is linked when the
commit is pushed to Azure Repos.
Can I use the Git command prompt with Visual Studio?
Visual Studio's Team Explorer and the Git command line work great together. Changes to your repos made in
either tool will be reflected in the other. Make sure to install the latest release of Git for Windows, which has tools
to help you connect to your Azure DevOps Services/TFS repos.
See the Azure Repos Git tutorial and the command reference for additional help using Git from the command line.
Next steps
Checkout more steps in the Git workflow
Azure Repos Plugin for IntelliJ IDEA and Android
Studio
IntelliJ IDEA is an IDE produced by JetBrains. You can find out more about it at https://www.jetbrains.com/idea/.
The Azure Repos Plugin for IntelliJ allows you to connect to your Git repositories on Azure DevOps Services and
Team Foundation Server (TFS ) in a seamless and intuitive way. You can also use this plugin to import projects into
Azure Repos or create pull requests in your Azure DevOps Services/TFS Git repository.
In this guide, we show you how to create a Git repo using the Azure DevOps Services web portal, add some
sample code, and then clone the repo and create pull requests all from within IntelliJ IDEA.
Prerequisites
To complete the steps in this guide you need:
IntelliJ IDEA installed on your machine. If you don't have it, get IntelliJ IDEA.
The Azure Repos plugin for IntelliJ. See IntelliJ Plugin download page for installation instructions. This plugin
is compatible with IntelliJ IDEA Ultimate and Community editions, Android Studio, RubyMine, WebStorm,
PhpStorm, PyCharm, AppCode, MPS, 0xDBE, and CLion.
Git command line tools.
To install Git for Windows, including Git Credential Manager, see Install the Git Credential Manager -
Windows.
To install Git for macOS and Linux, see Install the Git Credential Manager - macOS and Linux.
Create a repo
1. Navigate to your project in Azure DevOps by browsing to https://dev.azure.com/{your organization} and
selecting the name of your project. You can select it from the All projects list, or from the Recent projects
list if you have accessed it recently.
NOTE
Project URLs have changed with the release of Azure DevOps Services and now have the format
dev.azure.com/{your organization}/{your project} , but you can still use the existing visualstudio.com
format. For more information, see VSTS is now Azure DevOps Services.
2. In the Project area in the web portal, select Code, then select the drop-down next to the current repo name
and choose New Repository.
3. In the Create a new repository dialog, verify that Git is the repo type, enter DeepSpace for your new
repo name, and click Create.
Add sample code to your repo
1. Select Clone in the upper-right corner of the Code window and copy the Clone URL.
2. Open the Git command window (Git Bash on Git for Windows), navigate to the folder where you want the
code from the repo stored on your computer, and run git clone followed by the path copied from the
Clone URL in the previous step, as shown in the following example.
git clone https://dev.azure.com/contoso-ltd/MyFirstProject/_git/DeepSpace

3. Switch to the DeepSpace folder by running the following command.
cd DeepSpace
Keep this window open as you'll use it for subsequent steps.

4. Download the DeepSpace sample code and extract it to the local directory on your computer where you
cloned the DeepSpace repo.
5. Switch back to your Git command window and run the following command, which commits the sample
code files to your local repo.
git add --all
You may see some warnings stating the line feeds will be replaced with carriage return line feeds (i.e.
Warning: LF will be replaced by CRLF ). These warnings can be ignored.
6. Commit the files to the local repo by running the following command.
git commit -m "Committing DeepSpace sample files"
7. Run the following command to push the commit of DeepSpace sample files up to your Azure Repos
DeepSpace repo.
git push
8. Switch back to the Azure DevOps Services web portal and refresh, and you can see the files that were
added.
Clone your repo in IntelliJ

Now that we've got a Git repo with some sample code, let's take a look at how we can work with the code from
IntelliJ IDEA. To clone your VSTS repo in IntelliJ is extremely simple. You don't even need to know the URL for the
repo.
1. Open IntelliJ IDEA and select Check out from Version Control and then choose VSTS Git.
2. Next just sign in to Azure DevOps Services...
3. When you click Sign in, you will be presented with the standard Azure DevOps Services sign in UI. Once
signed in, you should see the list of all repositories you have access to on Azure DevOps Services. Choose
the correct repo, DeepSpace, and click the Clone button. (You may also want to choose where on your
hard drive the repo is cloned to by changing the Parent Directory.)
4. After the clone finishes, IntelliJ will ask you if you want to open the project. Click Yes and you should end
up with the DeepSpace project opened in IntelliJ IDEA.
Make some changes in IntelliJ

1. Start by making sure the project builds using Build > Make project. If you are prompted to add an SDK
for the project, simply add the latest Java JDK installed on your machine.
If you want to run the project now to see what it does, you can do the following:
a. From the DeepSpace root folder in your git repo, run the command mvn jetty:run (this requires maven
to be installed)
b. From a browser, go to http://localhost:3030/
You should see stars and planets flying by! If you look closely, you may notice that Earth does not fly by.
2. In our DeepSpace example, there are some code sections that have been commented out. If you open the
src/main/java/com.microsoft.tfs.demo/ImageService.java file in IntelliJ, you can see one of the sections.
Let's fix this section of code locally. Typically, when working in a Git repo, you should create a branch for
your work and commit to that branch. Create a branch through IntelliJ using the built-in VCS > Git >
Branches window. When prompted, use the branch name fixBugs. Once we have a branch to make our
changes in, we can uncomment the code and rebuild the project. If you follow the instructions above to run
the program again, you should see the Earth fly by.
3. Now that our changes are built and tested, we can commit them locally using the VCS > Commit
Changes menu. In the commit dialog, you will see a VSTS button above the commit message text box.
Click on that button to view your list of work items assigned to you. Select the Add Missing Earth work
item and click OK. You will see the commit message text box populate with the work item's type, number,
and title. This will associate the work item to this commit for traceability in the future.
Note that this change is only done locally; it hasn't been changed in our Azure DevOps Services repo yet.

You can push your local branch to the server and create a pull request for your team to review. Our plugin helps
you create the pull request based on your current context within IntelliJ. This saves you several steps and
eliminates the need for you to switch to your browser to create the pull request.
To accomplish this, simply select VCS > Git > Create Pull Request. This opens up the Create Pull Request
dialog. This dialog provides a lot of information including the files that have changed and the commits that will be
pushed. You can give the pull request a title and a description.
After you click Create Pull Request, you should receive a notification that the pull request was created. It also
contains a link to the pull request in case you want to add specific reviewers or comments. Once the code reviews
are done, you can merge the pull request into master.
Check build status

After you have merged your changes into master, you can check if your CI build has succeeded from within
IntelliJ. In the bottom right corner, there is an icon that displays your build status to you. If you see a green
checkmark, that means your build has succeeded. If you see a red X, then your build failed. If you see a gray
question mark, your build was not found or your credentials may have expired.
You can click on the icon for more options such as viewing build details, queuing a new build, and updating the
status manually.
View Pull Requests and Work Items
Under the Version Control menu, a Pull Request tab and Work Items tab exist to allow you to easily view the
information you need without leaving the IDE. The Pull Request tab shows you the current pull requests created
by you and assigned to you along with their status. The tab also gives you the ability to create and/or abandon pull
requests.
Under the Work Items tab, you can view the work items based on queries that you have created or use the
default query to see work items that are assigned to you. You can also create a branch based off of a work item so
that you can associate a work item with branch for future traceability purposes.
Next Steps
Check out the entire DeepSpace IntelliJ tutorial
View the IntelliJ plugin FAQ
Share your code in Git using Xcode
This guide shows you how to share your Xcode projects using Azure Repos.
Prerequisites
Create a local Git repo for your Xcode project

Create a local Git repo for your code to manage your project in version control.
New projects
Existing projects
If your project is already in a local Git repo, you can skip ahead to Create a new Git repo in Azure Repos.
New projects
Create a local Git repo when you create a new project. Choose Create Git repository on My Mac when creating
a new project.
Existing projects
Create a local Git repo for your existing projects not in version control by going to Source Control, Create
Working Copy... . Select the projects to add to the local Git repo and select Create. Xcode creates a Git repo for
your code and adds a commit with your project files.
Create a new Git repo in Azure Repos

Create a new Git repo in Azure Repos for your Xcode project.
If you have already created a repo for your Xcode project in Azure DevOps Services, you can skip ahead to Push
your project.
1. Browse to your Project in your Azure DevOps organization and select the drop-down next to the name
of the current Git repo. Select New Repository..
2. Enter a name for your new Git repo and select Create. Your browser will navigate to your new empty Git
repo for your Xcode project. Copy the clone URL to the clipboard so that you can use it in Xcode to connect
to VSTS.
NOTE
If you want to use SSH to connect to your Azure Repos/TFS Git repo, Set up SSH credentials and use the SSH clone
URL when adding the remote for your local Git repo.
Push your project

1. Go to Source Control in Xcode and select Projectname -- master, then Configure...
2. Select Remotes, then select the icon and choose Add Remote...
3. In the Address field, paste the Git clone URL for your repo copied in the previous step. Select Add
Remote, then select Done to finish creating the origin remote for your local Git repo.
4. Go to Source Control, Push..., enter the branchname on origin to push to, and select Push.
5. If prompted, enter your Azure DevOps Services credentials. For Username, enter your Azure DevOps
Services username. For Password, enter a Personal Access Token created for your user in VSTS. Select OK.
Xcode will push your project to your Azure Repos/TFS Git repo so you can share it with your team.
Next steps
Share your code in Git using Eclipse
Share your Eclipse project with your team in an Azure DevOps Services/TFS Git repo.
Prerequisites
An Azure DevOps organization. If you don't have one, you can sign up for one for free. Each organization
A local Eclipse project. If your code is already in version control in Azure Repos or TFS and you want to clone it,
see Clone an Azure DevOps Services Git repo using Eclipse.
Use Team Explorer Everywhere

Team Explorer Everywhere is an open-source Eclipse plug-in to connect Eclipse to Azure DevOps Services or
Team Foundation Server. If you're working with Azure DevOps Services/TFS and Eclipse, use this plugin to
connect to your repos, builds, and work items.
NOTE
The Team Explorer Everywhere plug-in works with Eclipse versions 4.2 (Juno) - 4.6 (Neon).
1. Install the Team Explorer Everywhere plug-in.

2. Add the Team Explorer Everywhere view in Eclipse. Go to Window, Show View and select Other... Search
for Team Explorer, select the Team Explorer view, and select OK.
Connect to Azure DevOps Services

1. In the Team Explorer Everywhere view, select Connect to VSTS or a Team Foundation Server .
2. If you know your Azure DevOps Services or Team Foundation Server account URL, select the Servers...
button under Connect to a Team Foundation Server or Azure DevOps organization to add your TFS
server or account to the drop-down list. If you don't know your account information for Azure DevOps
Services, select Browse Visual Studio Services and select Next.
Either choice will prompt for your credentials before continuing further.
3. Select the project where you will share your code from the Project Selection dialog and select Finish.
Create a local Git repo for your Eclipse project

Before you can push your project to Azure Repos, you need to add it to a local Git repo.
NOTE
If your code is already in a local Git repo, you can skip this step.
1. With your project open in Eclipse, right-click the project name in Project Explorer and select Team, Share
Project... Select Git and select Next.
2. Select Create... from the Configure Git Repository window and choose a folder for your local Git repo.
Select Finish.
3. Right-click your project in Project Explorer and select Team, Commit.... Stage your changes by dragging
your files to the Staged Changes field, enter a commit message, then select Commit.
Push your project to your Azure DevOps Services/TFS repo

1. In Team Explorer Everywhere, select Git Repositories, then right-click the empty repo you want to push
your Eclipse project to and select Copy Clone URL. If you don't have an empty Git repo created in Azure
DevOps Services/TFS yet, you can create one using these instructions.
2. In Package Explorer, right-click your project and Select Team, Push Branch ... . Paste the clone URL from
the clipboard into the URI field and select Next. Make sure Configure upstream for push and pull is
selected in the next window and select Next.
3. Review the changes and select Finish in the Push Branch window.
Your project code is now in your Git repo.
Troubleshooting
What if the Git views for commit and push don't show up?
You can download EGit to use Git with Eclipse.
Next steps
Import a Git repo
Azure Repos | Azure DevOps Server 2019 | TFS 2018 | TFS 2017 | TFS 2015 | TFS 2013
This guide shows you how to import an existing Git repo from GitHub, Bitbucket, GitLab, or other location into a
new or empty existing repo in your project in Azure DevOps.
IMPORTANT
The Import repository feature is currently not working if you are importing a GitHub repo using TFS 2017.1 to TFS 2018.1.
For more information about this issue, see Weak cryptographic standards removal notice and Unable to connect to GitHub
due to TLS 1.2 only change
There are several workarounds to this issue:

You can import a GitHub repo into TFS using the steps in Manually import a repo.
You can set a machine-wide .NET registry key on your Application Tier servers to enable them to use all
available TLS protocol versions. After setting these registry keys, you will need to recycle the TFS
application pools (or restart the servers) for the settings to be activated. Open an elevated command
prompt and run the following commands to set the registry keys.
reg add HKLM\SOFTWARE\Microsoft\.NETFramework\v4.0.30319 /v SystemDefaultTlsVersions /t REG_DWORD /d 1

/f /reg:64
reg add HKLM\SOFTWARE\Microsoft\.NETFramework\v4.0.30319 /v SystemDefaultTlsVersions /t REG_DWORD /d 1
/f /reg:32
On your Application Tier servers, you can modify the web.config file to change the targetFramework from
<httpRuntime targetFramework="4.5" to <httpRuntime targetFramework="4.6" .
This issue is resolved starting with Team Foundation Server 2018 Update 2 RC1 and higher.
Prerequisites
An organization in Azure DevOps. If you don't have one, you can sign up for one for free. Each organization
To use the Import repository feature in TFS, you must have TFS 2017 Update 1 or higher.
To import a repository using TFS 2017 RTM or earlier, see Manually import a repo.
Import into a new repo

1. Select Repos, Files.
2. From the repo drop-down, select Import repository.
3. If the source repo is publicly available, just enter the clone URL of the source repository and a name for
your new Git repository.
If the source repository is private but can be accessed using basic authentication (username-password,
personal access token, etc.), select Requires authorization and enter the your credentials. SSH
authentication is not supported, but you can manually import a repository that uses SSH authentication by
following the steps in Manually import a repo.
From the repo drop-down, select Import repository.
If the source repo is publicly available, just enter the clone URL of the source repository and a name for your new
Git repository.
If the source repository is private but can be accessed using basic authentication (username-password, personal
access token, etc.), select Requires authorization and enter the your credentials. SSH authentication is not
supported, but you can manually import a repository that uses SSH authentication by following the steps in
Manually import a repo.
Import into an existing empty repo

On the Files page of the empty Git repository, select Import and enter the clone URL. You will need to provide
credentials if the source repository requires authentication.
NOTE
The import feature disables automated linking for work items mentioned in a commit comment since the work item IDs in
the destination project might not be the same as ones in the source project. Automatic linking for work items mentioned in
a commit can be re-enabled by navigating to Settings, Version Control, selecting your repository, and choosing Options.
For more information on linking commits with work items, see How do I associate my commits with work items?
Manually import a repo

The import repo feature was introduced in TFS 2017 Update 1. If you are using TFS 2017 RTM or earlier, you can
use the following steps to manually import a repo into TFS. You can also follow these steps to manually import a
repo into an Azure DevOps Services repo by replacing TFS with Azure Repos in the following steps.
1. Clone the source repo to a temporary folder on your computer using the bare option, as shown in the
following command line example, and then navigate to the repo's folder. Note that when cloning using the
bare option, the folder name includes the .git suffix. In this example,
https://github.com/contoso/old-contoso-repo.git is the source repo to be manually imported.
git clone --bare https://github.com/contoso/old-contoso-repo.git

cd old-contoso-repo.git
2. Create a target repo using TFS 2017 RTM, and make a note of the clone URL. In this example,
https://dev.azure.com/contoso-ltd/MyFirstProject/_git/new-contoso-repo is the URL for the new target
repo.
3. Run the following command to copy the source repo to the target repo.
git push --mirror https://dev.azure.com/contoso-ltd/MyFirstProject/_git/new-contoso-repo
4. If the source repository has LFS objects then fetch them, and copy them from the source repo to the target
repo.
git lfs fetch origin --all
git lfs push --all https://dev.azure.com/contoso-ltd/MyFirstProject/_git/new-contoso-repo
5. Delete the temporary folder by running the following commands.
cd ..
rm -rf old-contoso-repo.git

Although most of the time the import is successful, the following conditions can cause problems.
What if my Source repository is behind two-factor authentication?
What if my source repository does not support multi_ack?
Can I import from previous versions of Team Foundation Server?
Can I use MSA based credentials?
Can I import from TFVC?
What if my source repository contains Git LFS objects?
What if my source repository is behind two -factor authentication?
The import service uses REST APIs to validate and trigger import and cannot work directly with repositories that
require two-factor authentication. Most Git hosting providers like GitHub and Azure DevOps Services support
personal tokens which can be supplied to the import service.
What if my source repository does not support multi_ack?
The import service uses the multi_ack capability of the Git protocol during the import. If the source repository
does not provide this capability, the import service can fail to import from the given source. This failure can
happen when creating import request or while import is in progress.
Can I import from previous versions of Team Foundation Server?
If the source Git repository is in a TFS version earlier than TFS 2017 RTM, then import will fail. This happens
because of a contract mismatch between the latest Azure DevOps Services/TFS and pre-2017 RTM versions of
TFS.
Can I use MSA based credentials?
Unfortunately, MSA (Microsoft Account, formerly Live ID ) based credentials will not work. Import service relies
on basic authentication to communicate with the source repository. If the username / password you are using are
not basic auth then authentication will fail and import will fail. One way to check if the username / password you
are using are basic auth or not is to try using Git to clone your repository using the below format
git clone https://<<username>>:<<password>>@<<remaining clone Url>>
Can I import from TFVC?

You can migrate code from an existing TFVC repository to a new Git repository within the same account. While
migrating to Git has many benefits, it is an involved process for large TFVC repositories and teams. Centralized
version control systems, like TFVC, behave different than Git in fundamental ways. The switch involves a lot more
than learning new commands. It is a disruptive change that requires careful planning. For more information, see
Import from TFVC to Git.
What if my source repository contains Git LFS objects?
Git import will not import Git LFS objects.
LFS objects can be moved using the following steps:
Import the repository using import repository feature into Azure DevOps. This will copy over all the Git
objects from source to Azure DevOps (this will also import the LFS pointers which are Git objects but not the
LFS files)
To move over the LFS files (you will need both Git.exe and LFS client in the same box and access to both source
repository and destination repository)
Clone the imported repository from Azure DevOps to local system, clone will work but it will fail while
performing checkout of LFS files
Add the source repository as remote (say ‘source’)
Perform “git lfs fetch source –all” (this will bring over all LFS files from source to your local repository)
Assuming the destination VSTS repository is your ‘target’ remote
Perform “git lfs push target –all”
Next steps
Learn more about Git in the Git tutorial
Azure Repos Git tutorial
Use version control to save your work and coordinate code changes across your team. Even if you're just a single
developer, version control helps you stay organized as you fix bugs and develop new features. Version control
keeps a history of your development so that you can review and even rollback to any version of your code with
ease.
The steps in the following tutorials show how to perform common version controls tasks using the following
version control workflow.
Version control workflow

Version control has a general workflow that most developers use when writing code and sharing it with the
team.
These steps are:
1. Get a local copy of code if they don't have one yet.

2. Make changes to code to fix bugs or add new features.
3. Once the code is ready, make it available for review by your team.
4. Once the code is reviewed, merge it into the team's shared codebase.
Git has a version of this workflow using terminology and commands unique to Git. Throughout this tutorial
you'll learn about repositories, branches, commits, and pull requests. These terms might sound familiar if you've
used a version control system like Team Foundation Version Control or Subversion, but they behave differently
in Git.
Git workflow
1. Create a branch for the changes you plan to make and give it a name, such as users/jamal/fix-bug-3214 or
cool-feature-x . For more branching guidance, see Adopt a Git branching strategy
2. Commit changes to your branch. People often have multiple commits for a bug fix or feature.
3. Push your branch to the remote repository.
4. Create a pull request so other people can review your changes. To incorporate feedback, you might need to
make more commits and push more changes.
5. Complete your pull request and resolve any merge conflicts from changes other people made after you
created your branch.
Use this workflow if you're new to Git. As your team gets more experienced and confident with Git, extend it to
suit your team's needs.
Next steps
Create a new Git repository
Clone an existing Git repository
Get Started with Azure Repos and Visual Studio
Azure Repos | Azure DevOps Server 2019 | TFS 2018 | TFS 2017 | TFS 2015 | VS 2017
This guide covers the basics so you can get up and running using Git with code already in Azure DevOps Services
or Team Foundation Server (TFS ). Explore our full tutorial for more information on how to use Git from Visual
Studio or the command line.
If you don't have your code in an Azure DevOps Services or TFS Git repo, visit our Visual Studio or command line
getting started articles to learn how to create a local repo for your code and push it to Azure Repos.
Get your code

To get a copy of the source code, you clone a Git repository. Cloning creates both a copy of the source code for
you to work with and all the version control information so Git can manage the source code.
If you don't have a Git repository yet, you can create one using your own code and continue with the steps in this
article to commit and share your work.
Visual Studio
Command Line
1. In Team Explorer, open up the Connect page by selecting the Connect icon, and then choose Manage
Connections, Connect to Project.
2. On the Connect to a Project dialog, select the repo you want to clone from the list and select Clone. If
you don't see your repo listed, you can filter the list to find it or add a Team Foundation Server where the
repo is hosted by selecting the Add TFS Server link.
NOTE
3. Verify the location of the cloned repo on your PC and select Clone.
Commit your work

Git branches isolate your changes from other work being done in the project. The recommended Git workflow
uses a new branch for every feature or fix you work on. You make commits in your local Git repository to save
your changes on that branch.
Visual Studio
Command Line
1. In Team Explorer, select the Home icon and choose Branches.
2. Right click the master branch and choose New Local Branch From...
3. Choose a descriptive branch name for your work to remind you and others what kind of work is in the
branch, and select Create Branch.
4. Make changes to your files in the cloned repo. From the Team Explorer Home view, you can open up
Visual Studio solutions in the repo or browse the repo contents using the Show Folder View link. Git
keeps track of changes made to your code both inside and outside of Visual Studio.
5. When you are satisfied with the changes, save them in Git using a commit. Open up the Changes view
from Team Explorer by selecting the Home icon and choosing Changes.
6. Enter a message describing the commit, and select Commit All.

NOTE
If you have multiple files and you don't want to commit them all, you can right-click each desired file and choose
Stage. When you have staged all the files you would like to commit, click Commit Staged. (The Commit All button
is replaced by Commit Staged when you manually stage your changes before the commit.)
Share your changes

When you are ready to share your changes with the team, you can push those changes so that others can reach
them. You can only push changes after you add commits to a branch.
Once you push the changes, you can create a pull request to let others know you'd like to have the changes
reviewed and added to the master branch of the code.
Visual Studio
Command Line
1. Open up the Synchronization view in Team Explorer by selecting the Home icon and choosing Sync.
You can also navigate to the Synchronization view from the Changes view by choosing Sync
immediately after making a commit.
2. Select Push to share your commit with the remote repository.
If this is your first push to the repository you'll see the following message in place of the outgoing commits
list:
The current branch does not track a remote branch. Push your changes to a new branch on the origin
remote and set the upstream branch.
Select Push to push your changes to a new branch on the remote repository and set the upstream branch.
The next time you push changes you'll see the list of commits.
3. Create a pull request so that others can review your changes. Open Pull Requests in Team Explorer by
selecting the Home icon and choosing Pull Requests.
4. From the Pull Requests view you can view pull requests opened by you, assigned to you, and you can
create new pull requests. Select New Pull Request to open up a web browser where you can create the
new pull request in the Azure DevOps Services web portal.
5. Verify your branches (in this example we want to merge the commits from the ReadMeFix branch into the
master branch), enter a title and optional description, specify any reviewers, optionally associate any work
items, and select Create.
For more information on pull requests, see the pull request tutorial.
Sync with others

To get changes from others and keep your code up to date, you can pull commits made by others and merge them
into your branch. Git is very good about merging multiple changes even in the same file, but sometimes you
might have to resolve a merge conflict. It's a good idea to pull your branches regularly to keep them up to date
with the changes from others. This makes sure that your feature branches from your main branch are using the
latest version of the code.
Visual Studio
Command Line
2. You can download the latest changes to the branch you are on using the Pull link. (There are two Pull
links, one near the top and one in the Incoming Commits section. You can use either one as they both do
the same thing.)
Create a new Git repo
Azure Repos | Azure DevOps Server 2019 | TFS 2018 | TFS 2017 | TFS 2015 | VS 2017 | VS 2015 Update 2
A Git repository, or repo, is a folder that you've told Git to help you track file changes in. You can have any number
of repos on your computer, each stored in their own folder. Each Git repo on your system is independent, so
changes saved in one Git repo don't affect the contents of another.
A Git repo contains every version of every file saved in the repo. Git saves these files very efficiently, so having a
large number of versions doesn't mean that it uses a lot of disk space. Storing each version of your files helps Git
merge code better and makes working with multiple versions of your code quick and easy.
In this tutorial you learn how to:
Create a new Git repo
Video tutorial
The following video explains what Git repos are, and shows you how to create them on your computer using
Visual Studio 2015 Update 2.
https://channel9.msdn.com/series/Team-Services-Git-Tutorial/Git-Tutorial-Create-a-Git-repo-in-Visual-Studio-
2015/player
TIP
Working from the command line? You can view our video overview using command line steps on Channel9.
Create a new repo

Manage any folder with source code or Visual Studio solution in Git by creating a repo for them. Later you can
connect this Git repo to a remote Git repo to share your work with others.
Visual Studio
Command Line
Create a repo
Create a repo from a new solution
Create a repo from an existing solution
Create a repo in an empty folder
Connect a local repo to a remote
From a new solution
Create a new Git repo for your new Visual Studio solution by selecting Create new Git repository when creating
the solution:
From an existing solution
To create a repo from an existing solution not in version control, select the Publish button in the bottom-right of
the lower status bar . This creates a new Git repo in the same directory as your solution and opens up the
Publish view in Team Explorer so you can push your code to Azure Repos or another remote Git repository.
In an empty folder
1. Open the Connect view in Team Explorer by choosing Projects then Manage Connections from the
context menu.
2. Under Local Git Repositories, select New and enter a folder where the repo will be created. This directory
must be empty.
3. Select Create to create the repo.
### Connect a local repo to a remote

To connect a local repository to a hosted remote Git repository to share your work, go the Settings page in Team
Explorer. Select Repository Settings. Under Remotes, select Add.
Enter origin in the Name field and enter the clone URL for your repo in the Fetch field. Make sure that Push
matches fetch is checked and select Save.
Next steps
Clone an existing Git repo
Create a complete local copy of an existing Git repo by cloning it. Cloning a repo downloads all commits and
branches in the repo and sets up a named relationship with the existing repo you cloned. Use this relationship to
interact with the existing repo, pushing and pulling changes to share code with your team.
NOTE
By default, Git will assign the origin to the remote repo you clone from. Most users don't need more than one remote,
so the tutorial uses origin in its steps. Learn more about setting up remotes to your Git repo.

Get the clone URL to your repo
Clone a repo
Video tutorial
https://channel9.msdn.com/series/Team-Services-Git-Tutorial/Git-Tutorial-Create-a-Git-repo-in-Visual-Studio-
2015/player
TIP
Working from the command line? You can view our video overview using command line steps on Channel9.
Get the clone URL to your repo

Before you can clone an existing repo, you'll need a URL that points to the existing repo. This URL represents
the source of the repo you're going to copy during the clone.
If you're using Azure DevOps Services or Team Foundation Server 2017, you can find this clone URL in the web
portal.
1. From your web browser, open the team project for your Azure DevOps organization and choose Repos,
Files.
2. Select Clone in the upper right.
If you need to clone a GitHub repo, you'll need to get the clone URL from the Clone or download button while
viewing the repo on the web in GitHub.
Other Git providers have similar buttons in their user interface to get the clone URL.
Copy this URL into the clipboard or store it in a place where you can find it easily. You can't clone a repo without
a clone URL.
Clone a repo
Visual Studio
Command Line
Clone from Azure DevOps Services / Team Foundation Server
Clone from another Git provider
Open a solution in Visual Studio from a cloned repo
Clone from Azure DevOps Services / Team Foundation Server
1. In Team Explorer, open up the Connect page by selecting the Connect icon, and then choose Manage
Connections, Connect to Project.
2. On the Connect to a Project dialog, select the repo you want to clone from the list and select Clone. If
you don't see your repo listed, you can filter the list to find it or add a Team Foundation Server where the
repo is hosted by selecting the Add TFS Server link.
NOTE
3. Verify the location of the cloned repo on your PC and select Clone.
Clone from another Git provider
If you are not using Azure Repos, you can still clone your repo in Team Explorer and work with your code in
Visual Studio.
1. In Team Explorer, open the Connect view.
2. Select Clone under Local Git Repositories and enter the URL for your Git repo—this will be provided
by your team or Git hosting provider.
3. Select a folder where you want your cloned repo to be kept.
4. Select Clone to clone the repo.
Open a solution in Visual Studio from a cloned repo

1. Open a solution in a cloned repo in Visual Studio by right-clicking on the repository in the Team Explorer
Connect view and selecting Open.
2. You'll be taken to the Home view in Team Explorer. Double-click your project solution file in the
Solutions area to open the solution in Solution Explorer.
Next steps
Git does not automatically snapshot your code as you make edits to files in your repo. You must tell Git
exactly which changes you want to add to the next snapshot by staging those changes. After staging your
changes, create a commit to save the snapshot to your repo.
In this tutorial you learn:
How Git tracks changes
What's in a commit
How to stage your changes
How to create a commit
How to update your last commit
How Git tracks changes

Git tracks file changes in your repo as you work, and separates the files in your repo into three categories:
Unmodified files - These files haven't changed since your last commit.
Modified files - These files have changes since your last commit, but you haven't yet staged for the next
commit.
Staged files - These files have changes that will be added to the next commit.
When you create a commit, only the staged changes and unchanged files are used for the snapshot.
Changes to unstaged but modified files are kept, but the commit uses the unmodified version from the
previous commit in its snapshot.
Commits are created in your local Git repository, so you don't have to worry about your changes being
perfect. Continue to create commits as you work, pushing your changes to the team when they are ready to
share.
Video overview
https://channel9.msdn.com/series/Team-Services-Git-Tutorial/Git-Tutorial-Commits/player
What's in a commit
Commits include the following information:
A snapshot of the files saved in the commit. Git snapshots the contents of all files in your repo at the time
of the commit—this makes switching versions very fast and helps Git merge changes.
A reference to the parent commit(s). Commits with multiple parents occur when branches are merged
together.
A short and to the point message describing the changes in the commit. You enter this message when
you create the commit.
Git uses the references between commits along with the file snapshots to maintain a complete record of
development in your repo.
Learn more about Git history and how to review history to investigate changes made to your code.
Stage your changes

Git does not automatically add changed files to the snapshot when you create a commit. You must first stage
your changes to let Git know which updates you want to add to the next commit. Staging lets you to
selectively add files to a commit while excluding changes made in other files.
Ignore temp files, logs, and other files that might change on your local machine but you don't want to add to
version control.
Visual Studio
Command Line
Visual Studio 2015 (Update 2) and 2017
Visual Studio keeps track of file changes to your project as you do your work. When you are ready to stage
changes, open up the Changes view in Team Explorer.
Stage individual file changes by right-clicking a file in the Change view and selecting Stage. Staging a
change creates a Staged Changes section in Team Explorer. Only changes in the Staged Changes section
are added to the next commit.
NOTE
The Team Explorer Changes view had Included Files and Excluded Files sections before Visual Studio 2015 Update
2. The Changes view was updated in Visual Studio 2015 Update 2 for better compatibility with other Git tools.
Stage multiple files or folders by selecting them then right-clicking and choosing Stage or by dragging and
dropping files from the Changes list into the Staged Changes list.
Ignore files by right-clicking and selecting Ignore this local item or Ignore this extension. This adds an
entry to the .gitignore file in your local repo. If the ignored file was added to your repo in an earlier commit,
ignoring the file will not remove it from the Changes list. See excluding and ignoring files section for more
information on how to ignore files already tracked by Git.
Create a commit
Visual Studio
Command Line
Open the Changes view in Team Explorer.
Enter a commit message describing your changes and select Commit Staged to create a new commit that
includes the changes listed in the Staged Changes section.
Skip staging files if you just want to commit all changes listed by entering a commit message and selecting
Commit All when you have no staged changes.
When you commit in Visual Studio you can push the commit and sync the branch with a remote repository.
These options are available in the drop-down on the Commit button.
Update your last commit

Amend your last commit to correct small errors without making a new commit.
WARNING
Do not amend pushed commits. If you need to update pushed code, undo the changes with revert or create and
push another commit.
Visual Studio
Command Line
1. Open the Changes view in Team Explorer and stage your updated changes. You can amend just the
commit message by leaving the staged changes empty.
2. Enter the updated commit message and select Amend Previous Commit from the Actions drop-
down.
Next steps
Create work in branches.
Git branches aren't much more than a small reference that keeps an exact history of commits, so they are
very cheap to create. Committing changes to a branch will not affect other branches, and you can share
branches with others without having to merge the changes into the main project. Create new branches to
isolate changes for a feature or a bug fix from your master branch and other work.
Since the branches are lightweight, switching between branches is quick and easy. Git does not create
multiple copies of your source when working with branches—it uses the history information stored in
commits to recreate the files on a branch when you start working on it. Your Git workflow should create and
use branches for managing features and bugfixes. The rest of the Git workflow, such as sharing code and
reviewing code with pull requests all work through branches. Isolating work in branches makes it very simple
to change what you are working on by simply changing your current branch.
In this tutorial you learn:
How are Git branches created?
How to create a branch
How to delete a branch
How to use branches
Video Overview
https://channel9.msdn.com/series/Team-Services-Git-Tutorial/Git-Tutorial-Branches/player
How are Git branches created?

Create branches using the branch command. Branch creates a reference in Git for the new branch and a
pointer back to the parent commit so Git can keep a history of changes as you add commits to the branch.
When you are working with a branch that someone else shared, Git keeps an upstream tracking relationship
to associate the branch on the local repo with the corresponding branch on the remote repo. This makes it
very simple to sync changes with others using push and pull.
In this image, a new branch is created from the main branch. Work continues on both branches and commits
are added to both branches.
Git always adds new commits to the current local branch. Check what branch you are working on before you
commit so that you don't commit changes to the wrong branch. Swap between local branches using the
checkout command. Git will change the files on your computer to match the latest commit on the checked
out branch. When your work in the branch is ready to share with the rest of the team, you push the changes
to update the remote branch.
A common mistake is to make some changes and commit them, realize you are on an incorrect branch, then
checkout to the correct branch. Your most recent changes will no longer be on the filesystem since each
branch has its own version of code. Git will bring the state of the files back to the last commit on the branch
you swapped into, not the previous branch where you made your changes. You'll need to either cherry-pick
the commits from the branch or merge the changes into the correct branch.
Create a branch
Visual Studio
Command Line
Visual Studio 2015 & 2017
1. Open up Team Explorer and go to the Branches view.
2. Right-click the parent branch (usually master ) to base your changes and choose New Local Branch
From....
3. Supply a branch name in the required field and click Create Branch. Visual Studio automatically
performs a checkout to the newly created branch.
Delete a branch
NOTE
Deleting a branch in your local repo doesn't remove the branch on the remote.
Visual Studio
Command Line
1. Open up Team Explorer and go to the Branches view.
2. Locate the branch you want to delete. Make sure that you aren't checked out to that branch, as you
can't delete the branch you are currently working in.
3. Right-click the branch name and select Delete. If you have unpublished changes, Visual Studio will
ask and make sure you want to delete the branch so you don't possibly lose work.
You can delete a remote branch using the same method - locate the tree for the remote in Team Explorer's
Branches view (such as remotes/origin ), right-click and select Delete.
Use branches to manage development

Git keeps track of which branch you are working on and makes sure that when you checkout a branch your
files match the most recent commit on the branch. Branches let you work with multiple versions of the source
code in the same local Git repository at the same time. Tell Git which branch you want to work on with
checkout , and Git takes care of setting the right file versions for that branch.
You shouldn't need more than one repo on your system when you use branches to isolate your work. Set up
your development environment one time after you clone, and then use Git branches to swap between feature
work and bug fixing.
Next steps
Share changes made in commits and branches using the push command. Push your branches to the remote
repository, where Git takes the commits and adds them to an existing branch on the remote or creates a new
branch with the same commits as your local branch.
Git makes sure that pushed changes are consistent with the remote branch so others can pull your commits
and merge them into their own local copy of the branch. Pushed branches that have finished work are
reviewed and merged into the main branch of the your repo through a pull request.
Share your code with push
Video overview
https://channel9.msdn.com/series/Team-Services-Git-Tutorial/Git-Tutorial-Push/player
Share your code with push

Visual Studio
Command Line
1. Open up the Synchronization view in Team Explorer by selecting the Home icon and choosing
Sync.
You can also navigate to the Synchronization view from the Changes view by choosing Sync
immediately after making a commit.
2. Select Push to share your commit with the remote repository.
If this is your first push to the repository you'll see the following message in place of the outgoing
commits list:
The current branch does not track a remote branch. Push your changes to a new branch on the origin
remote and set the upstream branch.
Select Push to push your changes to a new branch on the remote repository and set the upstream
branch. The next time you push changes you'll see the list of commits.
NOTE
To adjust your Git setup, go to Team Explorer > Settings > Repository Settings and make sure the correct
User, Email, Remotes URLs, etc. are being used.
Resolve merge conflicts before pushing

If there are conflicts between your local commits on the commits on the remote branch, you must first
resolve these conflicts before you can push your changes. You should pull the changes from others first,
resolve the conflicts and commit the changes, then re-attempt the push .
Next steps
Review code with pull requests or update code with fetch and pull
Update the code in your local repo with the changes from other members of your team using the following
commands:
fetch , which downloads the changes from your remote repo but does not apply them to your code.
merge , which applies changes taken from fetch to a branch on your local repo.
pull , which is a combined command that does a fetch and then a merge .

Download changes with fetch
Update branches with merge
Fetch and merge with pull
Update your local branch with the latest changes from master
Video Overview
https://channel9.msdn.com/series/Team-Services-Git-Tutorial/Git-Tutorial-Pull/player
If there is a merge conflict between a commit you haven't pushed yet and a commit you are merging or pulling,
you'll need to resolve those conflicts before you finish updating your code.
Download changes with fetch

You download changes to your local branch from the remote through fetch . Fetch asks the remote repo for
all commits and new branches that others have pushed but you don't have and downloads them into your repo,
creating local branches as needed.
Fetch does not merge any changes into your local branches, it only downloads the new commits for your
review.
TIP
To help keep your branches list clean and up to date, configure Git to prune remote branches during fetch. You can
configure this setting from the command line or from within Visual Studio.
Visual Studio
Command Line
Visual Studio uses the Sync view in Team Explorer to fetch changes. Changes downloaded by fetch are not
applied until you Pull or Sync the changes.
2. Choose Fetch to update the incoming commits list. (There are two Fetch links, one near the top and one
in the Incoming Commits section. You can use either one as they both do the same thing.)
3. You can review the results of the fetch operation in the incoming commits section.
Update branches with merge
Apply changes downloaded through fetch using the merge command. Merge takes the commits retrieved
from fetch and tries to add them to your local branch. The merge will keep the commit history of your local
changes so that when you share your branch with push Git will know how others should merge your changes.
The challenge with merge is when a commit taken from fetch conflicts with an existing unpushed commit on
your branch. Git is generally very smart about resolving merge conflicts automatically, but sometimes you must
resolve merge conflicts manually and complete the merge with a new merge commit.
Visual Studio
Command Line
Team Explorer merges when you do a Pull or a Sync from the Changes view. Sync is a combined operation of
pulling remote changes and then pushing local ones, synchronizing the commits on the local and remote
branch.
2. Choose Sync.
3. A confirmation message is displayed when the sync operation completes.

Fetch and merge with pull
Pull does a fetch and then a merge to download the commits and update your local branch in one command
instead of two. Use pull to quickly bring your branch up to date with the remote when you aren't worried
about reviewing the changes before merging them into your own branch.
Visual Studio
Command Line
Open the Team Explorer and open the Sync view. Then click the Pull link under Incoming Commits to pull
remote changes and merge them into your local branch. Pulling updates files in your open project, so make sure
to commit your changes before pulling.
2. Choose Pull to fetch remote changes and merge them into your local branch. (There are two Pull links,
one near the top and one in the Incoming Commits section. You can use either one as they both do the
same thing.)
3. A confirmation message is displayed when the pull operation completes.
Update your branch with the latest changes from master

When working in a branch, you may want to incorporate the latest changes from the master branch into your
branch. There are two different approaches you can use to perform this: rebase or merge.
Rebase takes the changes made in the commits in your current branch and replays them on the history of
another branch. The commit history of your current branch will be rewritten so that it starts from the most
recent commit in the target branch of the rebase.
Merge merges the changes from the source branch to the target branch using a merge commit, which
becomes part of the commit history.
NOTE
This article demonstrates the merge approach. For more information on rebase and guidance on which method is
right for your scenario, see Apply changes with Rebase - When to rebase vs. merge and Rebase vs merge from the Pro Git
book.
Visual Studio
Command Line
To merge the latest changes from the master branch to your branch:
1. Open the Branches view in Team Explorer. Ensure your desired target branch is checked out, right-click
the target branch, and choose Merge From.
2. Specify the desired Merge from branch, which is master in this example, and choose Merge.)
If there are any merge conflicts you'll be notified at this stage. Resolve the merge commits before
proceeding to the next step.
3. Enter a commit message and select Commit Staged.
4. When you are ready to push your local commits, including your new merge commit, to the remote server,
choose Push from the Synchronization view.
Next steps
Git's workflow uses branches to isolate work until you're ready to merge the changes into your default branch,
such as master . The pull request is the collaborative process that lets the rest of the team discuss changes in a
branch and agree to merge them once everyone approves. Use pull requests to get early feedback from others
on work in progress, even if you're not ready to merge the changes into another branch.
In this image, the purple branch is merged into the blue branch through a pull request. The changes are
discussed by reviewers in the pull request before the code is merged. When you complete the pull request,
there is a merge commit (seen here as the filled blue commit) where the changes in the purple branch are now
merged in the blue branch.
Complete a pull request

To create a pull request in Azure Repos:
1. Push your local branch.
2. Create a pull request for the branch. You can do this in the Code view on the web from either the Pull
Requests tab or the Files tab.
You can also initiate a pull request from Visual Studio. Select the Pull Requests view when connected to
your Project.
From the Pull Requests view you can view pull requests opened by you, assigned to you, and you can
new pull request in the Azure DevOps Services web portal for your current branch.
3. Create the pull request. You should give a clear title for the pull request that describes the changes in the
branch. In the description field give a clear explanation of how the changes are implemented along with
any resources that might help reviewers understand the changes. You can include VSTS work items and
hyperlinks to allow others to have as much context as possible when reviewing your changes. Add any
team member who you would like to review the changes.
Who reviews the pull request?

When you create the pull request, you can add others who need to review your changes. You can add users and
groups to the pull request after it is created if the scope of the review needs to expand. You can also associate
the pull request with a task in Azure Boards to let others working with the task know changes are ready for
review.
How does the code review work?
Pull request reviewers will see the proposed updates to the branch in the form of file differences between the
two branches. Reviewers can add comments on any of the changes and include notifications for other team
members to answer a question or give other feedback. You can make changes and push commits to resolve
issues brought up in the feedback and these changes are immediately reflected in the pull request.
If the changes need much more development to complete, you can abandon the pull request. You can later open
up a new pull request to revisit the changes and link to the conversations that took place in the abandoned pull
request.
You can also open up a pull request on a very early version of your code to ask for feedback from others, even if
the code isn't ready to merge yet. Once you get the team's feedback, you can keep the pull request open to
continue the conversation or abandon the pull request until your code is ready to be shared again.
Complete a pull request

Complete your pull request after the reviewers approve of the changes by selecting Complete in the upper
right of the pull request view.
Complete: Complete the pull request now and merge the changes to the target branch.
Set auto-complete: If you have branch policies, you can choose Set auto-complete to configure the pull
request to close once all branch policies are met. For more information on auto-complete (and reasons why
you might not see this option), see Complete automatically.
Abandon: Choose Abandon to close the pull request without merging the changes.
Enter the message used for the merge commit and update the pull request description as needed in the dialog
that follows.
Check Complete linked work items after merging to complete any linked work items.
Check Delete <branch name> after merging to delete the source branch from the pull request. Git retains
the commit history in the master branch after the pull request is complete, so unless you plan on doing
more work in the branch, it is safe to remove.
Check Squash changes when merging to squash merge your pull request.
Check Override branch policies and enable merge to force merge even if all branch policies haven't been
satisfied. This option is only available if you have Exempt from policy enforcement permissions.
What happens when a pull request is merged?
You must resolve any merge conflicts between the pull request branch and the target branch. Git adds a new
commit (the merge commit) to the end of the master branch. This merge commit links the earlier history of
both the master branch and the commits for the branch that was merged as part of the pull request.
Next steps
Apply changes with rebase
One of the tradeoffs from the Git feature branch workflow is that you do not actively manage your version control
history. Git creates this history as you save your code in your commits and merges changes back into the master
branch with pull requests.
This generated history can get complicated when you need to update a feature branch with changes from the
main branch to catch up on work committed by others. Your commit history will diverge from the master branch
at multiple points, making it hard to follow.
Use rebase to address the problem of updating your branch with the latest changes from the main branch.
Rebase takes the changes made in the commits in your current branch and replays them on the history of another
branch. The commit history of your current branch will be rewritten so that it starts from the most recent commit
in the target branch of the rebase. Rebasing your changes in your feature branch off the latest changes in the main
branch lets you test your changes on the most recent version in the main branch while keeping a clean Git history.
Force push to update your remote branch
Squash local commits
Video overview
https://channel9.msdn.com/series/Team-Services-Git-Tutorial/Git-Tutorial-Rebase/player
Use caution
Rebasing is a powerful tool for catching up changes a main branch but you must be careful about its use. Some
things to keep in mind before you rebase:
1. Never rebase commits that have been pushed and shared with others. The only exception to this rule is when
you are certain no one on your team is using the commits or the branch you pushed.
2. Use rebase to catch up with the commits on another branch as you work with a local feature branch. This is
especially useful when working in long-running feature branches to check how your changes work with the
latest updates on the master branch.
3. You can't update a published branch with a push after you've rebased the local branch. You'll need to force
push the branch to rewrite the history of the remote branch to match the local history. Never force push
branches in use by others.
During a rebase, Git attempts to reconcile the changes recorded in the commits on your branch and the changes in
the commits in the target branch. Resolve any conflicts between the commits in the same way that you resolve
merge conflicts.
When to rebase vs. merge
Using rebase instead of merging branches results in an easier to follow but less exact history of commits. Your
team should agree under what circumstances you should rebase a branch. You should still always merge
branches into the main branch through a pull request. A suggested approach is to allow rebasing local changes
that you have made but haven't shared with others, but to merge once you are sharing changes with others. This
avoids trouble with rewriting history while still letting you easily catch up with changes as you develop your code
locally.
Visual Studio
Command Line
In Team Explorer, go to the Branches view. Click Rebase. You'll see a prompt to rebase the changes from your
current branch, and then a drop-down to specify which branch the changes in the current branch should be
replayed on top of. If there is a conflict, resolve it just like you resolve merge conflicts in Visual Studio.
Force push to update your remote branch

WARNING
Never force push a branch that others are working on. Only force push branches that you alone work with.
After a successful rebase, your local branch will have a different history than your remote branch. You must force
push your local branch to update your remote branch.
> git push -f users/frank/myfixes
Squash local commits

Interactive rebase is not currently supported in Visual Studio, but you can use the following command line
steps to consolidate your commits.
A special use of rebase is available to condense the changes made in a set of commits down to one single
commit. This is useful to clean up commit histories before they are pushed to a remote branch. The benefits to the
readability are significant, and since you never rebase shared code, you can summarize the changes easily.
To consolidate commits, first decide about how many commits you'd like to squash into one. You don't have be
exact as you'll get to pick out exactly which commits to squash when you run the command. If you had five
commits to squash, then you'd make sure there are no unstaged changes and run:
> git rebase -i HEAD~5

This will open up an editor where you will see something like:
pick 7b43f3f Updated router.js

pick 00859d9 Updated README.md
pick 9d247f7 initial commits
pick 7068b09 Updated README.md with build instructions
You'll keep the first of the changes (leave it pick ), and then change pick to squash for the rest of the changes.
Save and close the editor. Git will now attempt to condense the commits into a single commit. After the rebase
completes, you will have a new editor window open up where Git asks you to give a commit message for the
commit with the combined changes. You'll want to condense this down to one line of text (just like you would have
for a normal commit) and save and quit the editor.
Azure DevOps Services and TFS users can squash merge their pull requests to consolidate commits added to
the master branch.
Next steps
Copy commits from one branch to another using cherry-pick. Unlike a merge or rebase, cherry-pick only brings
the changes from the commits you select, instead of all the changes in a branch.
Cherry-pick is a great way to tackle these common problems:
Accidentally committing on the wrong branch. Cherry-pick the change(s) over to the correct branch and then
reset the original branch to the previous commit.
Pulling out a set of commits made in a feature branch so you merge them back to your master branch sooner.
Porting in specific commits from the master branch without rebasing your branch.
Cherry-pick a commit
Cherry-pick a commit
Visual Studio
Command Line
1. Open up Team Explorer and checkout to the branch you want to cherry-pick changes into using the
Branches view.
2. Right-click the branch containing the changes you want and select View History....
3. Right-click the commit you want to cherry-pick and select Cherry-pick.
Visual Studio copies the changes made in that commit into a new one on your current branch.
Repeat this process for each commit you need to bring over to your current branch.
Next steps
Azure Repos | Azure DevOps Server 2019 | TFS 2018 | TFS 2017 | TFS 2015 | VS 2017 | VS 2015 | VS 2013
When you merge one branch into another, file changes from commits in one branch can conflict with the
changes the other. Git attempts to resolve these changes by using the history in your repo to determine what
the merged files should look like. When it isn't clear how to merge changes, Git halts the merge and tells you
which files conflict.
Understand merge conflicts
Understand merge conflicts

The following image shows a very basic example of how changes conflict in Git. Both the master and bugfix
branch make updates to the same lines of source code.
If you try to merge the bugfix branch into master, Git can't determine which changes to use in the merged
version. You may want to keep the changes in the master branch, the bugfix branch, or some combination of
the two. Resolve this conflict with a merge commit on the master branch that reconciles the conflicting
changes between the two branches.
The most common merge conflict situation is when you pull updates from a remote branch to your local
branch, for example from origin/bugfix into your local bugfix branch. Resolve these conflicts in the same
way - create a merge commit on your local branch reconciling the changes and complete the merge.
What does Git do to prevent merge conflicts?
Git keeps an entire history of all changes made in your repo. Git uses this history as well as the relationships
between commits to see if it can order the changes and resolve the merge automatically. Conflicts only occur
when it's not clear from your history how changes to the same lines in the same files should merge.
Preventing merge conflicts
Git is very good at automatically merging file changes in most circumstances, provided that the file contents
don't change dramatically between commits. Consider rebasing branches before you open up a pull request if
your branch is far behind your main branch. Rebased branches will merge into your main branch without
conflicts.

Visual Studio
Command Line
1. You'll be informed of the merge conflict(s) when you pull changes or attempt to merge two branches.
2. The conflict notification appears. Click the Conflicts link to start resolve file conflicts.
3. This will bring up a list of files with conflicts. Selecting a file lets you accept the changes in the source
branch you are merging from with the Take Source button or accept the changes in the branch you are
merging into using Keep Target. You can manually merge changes by selecting Merge, then entering
the changes directly into the merge tool specified in your Git settings.
4. Use the checkboxes next to the lines modified to select between remote and local changes entirely, or
edit the results directly in the Result editor under the Source and Target editor in the diff view.
5. When done making changes, click Accept Merge . Repeat this for all conflicting files.
6. Open the Changes view in Team Explorer and commit the changes to create the merge commit and
resolve the conflict.
Compare the conflicting commits as well as the differences between the common history with the
options in Visual Studio's merge tool.
Next steps
Undo changes
Undo changes
When undoing changes in Git, first decide what type of changes you are looking to undo. These changes fall into
three categories:
Discard uncommitted changes to a file, bringing the file back to the version in the last commit.
Reset your local branch to a previous commit.
Revert changes pushed to a remote branch and shared with others.
If you just need to make small updates such as to fix a typo or small problem introduced in your last commit,
consider amending your previous commit or fixing the change in a new commit instead of any of these other
steps.
Discard uncommitted changes to a single file
Revert changes in shared commits
Reset a branch to a previous state
Discard uncommitted changes to a single file

Restore file contents back to a known good version, removing unwanted changes.
WARNING
These commands will overwrite your existing file changes. If you think you might want these changes later, consider stashing
them instead.
Visual Studio
Command Line
1. Open up the Changes view in Team Explorer.
2. Under the Changes section, find the file that you want to restore to the previous version. If your change is
staged, remove it from the Staged Changes section by right-clicking and selecting Unstage.
3. Right-click that file and select Undo Changes.
Revert changes in shared commits
Use revert to undo the changes made in your commits pushed to shared branches. The revert command
creates a new commit that undoes the changes on a previous commit. No history is rewritten in a revert , making
it safe to use when working with others.
Visual Studio
Command Line
Open up the Changes view in Team Explorer. Select Actions and choose View History from the drop-down. In
the history window that appears, right-click the commit to undo and select Revert from the context menu.
Reset a branch to a previous state

Use reset to bring a branch in your local repository back to the contents of a previous commit. The most
common use of the reset command is to simply discard all changed files since the last commit and return the
files to the state they were in at the most recent commit.
WARNING
Don't use reset on branches shared with others. Use revert instead.
Visual Studio
Command Line
1. Open up the Changes view in Team Explorer.
2. Select Actions and choose View History from the drop-down.
3. In the history window that appears, right-click the commit to reset the repo to and select Reset from the
context menu.
4. Choose Reset and delete changes....
A reset affects all files in the current branch on the repository, not just those in your current directory. Reset
only discards changes that haven't been committed yet.
Next steps
Ignore files
Ignore file changes with Git
Not every file created or updated in your code should be committed to Git. Temporary files from your
development environment, test outputs and logs are all examples of files that you create but are not part of your
codebase. Customize which files Git tracks through the gitignore feature.
Use gitignore to prevent tracking of files
Ignore files only on your system
Ignore files across all repos on your system
Ignore changes to committed files
Use gitignore to prevent tracking of files

Create a .gitignore file in your Git repo to prevent Git from staging unwanted files. Share the .gitignore in the
default branch in your repo, so you and your team can update it to change which files to ignore.
Create a .gitignore
Visual Studio
Command Line
Visual Studio automatically creates a .gitignore file in your repo when you create new repo for your project.
Git applies a .gitignore to the folder and any child folders where it's located. We strongly recommended to place
your .gitignore in the root folder of your repo to prevent confusion.
Customize your .gitignore
Modify your .gitignore to include files types, paths, and file patterns in your repo. Git starts ignoring these files as
soon as the .gitignore is updated, but be sure to commit the changes if others on your team need the same set of
ignored files.
Visual Studio
Command Line
You can edit your .gitignore file for your repo by going to the Settings view in Team Explorer, then selecting
Repository Settings. Select the Edit link under next to your .gitignore.
Each line in the .gitignore excludes a file or set of files matching a pattern. The full gitignore syntax is very flexible.
Here are some examples of the most common entries:
# ignore a single file

mycode.class
# ignore an entire directory

/mydebugdir/
# ignore a file type

*.json
# add an exception (using !) to the preceding rule to track a specific file

!package.json
NOTE
Windows users: All file paths in the .gitignore file use a forward slash separator and not a backslash.
Ignore files only on your system

Your .gitignore is shared across team members as a file committed and pushed to the Git repo. To exclude files
only on your system without pushing the changes to the rest of your team, edit the .git/info/exclude file in your
local repo. Changes to this file will not be shared with others and only apply to the files in that repo. The syntax
for this file is the same as the one used in .gitignore.
Ignore files across all repos on your system

Set up a global .gitignore for use across all repos on your system using the command line git config tool:
> git config core.excludesfile C:\Users\frank\.gitignore_global
This is particularly useful for ignoring entire file types you don't want to ever commit, such as compiled binaries.
Ignore changes to committed files

Temporarily ignore changes
During development it's convenient to stop tracking file changes to a file committed into your git repo. This is
very convenient when customizing settings or configuration files that are part of your project source for your
own work environment.
> git update-index --assume-unchanged <file>
Resume tracking files with:
> git update-index --no-assume-unchanged <file>
Permanently ignore changes to a file

If a file is already tracked by Git, adding that file to your .gitignore is not enough to ignore changes to the file. You
also need to remove the information about the file from Git's index:
These steps will not delete the file from your system. They just tell Git to ignore future updates to the file.
1. Add the file in your .gitignore.

2. Run the following:
> git rm --cached <file>
3. Commit the removal of the file and the updated .gitignore to your repo.
Next steps
Review history
Review history
Git uses the parent reference information stored in each commit to manage a full history of your development.
Review this commit history to find out when file changes were made and determine differences between versions
of your code.
Git's use of feature branches and merges through pull requests mean that the commit history of your
development doesn't form a straight, chronological line. When you use history to compare versions, think in
terms of file changes between two commits instead of file changes between two points in time. A recent change
to a file in the master branch may have come from a commit created two weeks ago in a feature branch but was
only merged yesterday.
Compare files
Retrieve files
Compare branches
Compare files
Compare the changes between two versions of a file in your Git repo.
Visual Studio
Command Line
1. Right-click the file in Solution Explorer and choose View History.... The history window will appear
showing the commit ID, author, date, and description of all changes to the file in your local repo across all
branches.
2. Find the latest commit for a branch by looking for its name on an arrow to the right of a commit.
3. View changes from the previous version of the file by right-clicking and choosing Compare with
previous.... View the changes between any two versions by selecting both commits, then right-clicking and
select Compare...
4. The diff view shows lines removed from the older commit and added in the new one.
Retrieve files
Retrieve a specific version of a file from your history, even if the file was deleted or renamed in the latest version
of your code. Retrieving an older version of the file doesn't make any changes to your current branch. Create a
new commit to bring the older version of the file into your branch.
Visual Studio
Command Line
To retrieve a previous version of a file that exists in your Visual Studio project:
1. Right-click the file in Solution Explorer and select View History. The Visual Studio History view will
appear, showing the commits in your repo that updated the file. You can filter the commits to find the exact
commit with the file version you want to restore. Double click on the version to open it in Visual Studio.
To retrieve a previous version of a file that was deleted in a previous commit:

1. Open the Changes view in Team Explorer and select View History from the Actions drop-down.
2. Right-click the commit containing the version of the file you want to restore and select View Commit
Details.
3. Right click the file to restore in the Commit Details in Team Explorer and select Open.
NOTE
The retrieved version of a file is not automatically saved to your project. To save the retrieved version to your project, select
Save As... from the File menu. If you save the file in your current project, either as a new file or overwriting an existing one,
you'll need to commit your changes to add the previous version to your local branch.
Compare branches
Review potential changes from a merge or rebase by comparing branches directly. You can compare both local
and remote branches, which is useful when checking for potential merge conflicts or to see how the changes
others have made will affect your work.
Visual Studio
Command Line
Comparing branches can be done in the web portal, which you can access from the Team Explorer Home view in
Visual Studio by choosing Web Portal.
Select Branches from the menu under Code. Locate your branch and select the ... icon to view the branch
options. Select Compare branches.
Select the branch to compare to from the drop-downs at the top. The view will display all changes between the
branches.
Understand Git history
Git stores history as a graph of snapshots — called commits — of the entire repository. Each commit also contains
a pointer to one or more previous commits. Commits can have multiple parents, creating a history that looks like a
graph instead of a straight line. This difference in history is incredibly important and is the main reason users find
Git confusing.
NOTE
If you can't find a change in your Git history that you know you made, learn more about how Git history simplification works
at Git lost my changes: Taking a look at Git's history simplification.
Commit history basics

Start with a simple history example: a repo with 3 linear commits.
Commit A is the parent of commit B, and commit B is the parent of commit C. This history looks very similar to a
CVCS. The arrow pointing to commit C is a branch. It's named master because that's the default name for the
mainline branch in a Git repo. Branches are pointers to specific commits, which is why branching is so lightweight
and easy in Git.
A key difference in Git compared to CVCS is that I have my own full copy of the repo. I need to keep my local
repository in sync with the remote repository by getting the latest commits from the remote repository. To do this,
I'll pull the master branch with the following command:
This copies ("pulls") all commits from the master branch of the remote repo (called origin by default) to the
master branch of the local repo. The pull operation copied one new commit, and the master branch in the local
repo is now pointing to this new commit.
Understand branch history

Now I want to make a change to my code. It's common to have multiple active branches where you're working on
different features in parallel. This is in stark contrast to CVCS where new branches are heavy and rarely created.
The first step is to checkout to a new branch using the following command:
git checkout -b cool-new-feature
This is a shortcut combining two commands: git branch cool-new-feature to create the branch followed by
git checkout cool-new-feature to begin working in the branch.
Two branches now point to the same commit. I'll make a few changes on the cool-new-feature branch in two new
commits, E and F.
My commits are reachable by the cool-new-feature branch since I made them in that branch. I'm done with my
feature and want to merge it into master . To do that I'll use the following command:
git merge cool-feature master
The graph structure of history becomes visible when there's a merge. Git creates a new commit when I merged my
branch into another branch. This is a merge commit. There aren't any changes included in this merge commit since
I didn't have conflicts. If I had conflicts, the merge commit would include the changes needed to resolve those
conflicts.
History in the real world

Here is an example of Git history that more closely resembles code in active development on a team. There are
three people who merge commits from their own branches into the master branch around the same time.
Now that you understand how branches and merges create the shape of the graph, this shouldn't be too scary!
Git lost my changes: Taking a look at Git's history
simplification
How Git Log History Simplification Works

Git history simplification can be a confusing beast. 99% of the time you won't even know it exists, but every once in
a while it will jump out of the dark corners of Git and bite you. In this article we'll explore what history
simplification is and how it can cause confusion when looking at file history.
Let's start with a common scenario:
1. You push a change to a file and then merge the change into master.
2. Some of your colleagues also merge their branches to master.
3. You come back some time later and notice your changes are missing.
4. Looking for the culprit, you go look at the file history and notice... your changes aren't even listed!?
What is happening here is that Git commit history is a tree, and sometimes the chronological history is not the
same as the actual file tree history. This is particularly true in cases where a merge commit reverts a file back to its
original state. In that case, the default history view won't actually show you all changes, because technically the file
didn't change.
In the above scenario, Git realizes it can simplify the history and the "changes" you are most likely looking for are
removed from the log.
Unless you have run into it before, the result is often a lot of hair pulling and wondering Where the heck did my
changes go?
History Simplification: On by Default

By default, running the log command on a file: git log file.txt will automatically simplify history, possibly hiding
some commits from its output. You can read more details over at the git log man page.
What makes this a tad more confusing is that history simplification does not occur if you just run git log
(because you are looking at all changes there is nothing to simplify).
In order to turn off history simplification, we need to use the command line switch --full-history .
An Example of History Simplification
This is all nice and theoretical, but let's create our own example of history simplification so we can see how it works.
First, let's look at a diagram of the history we are going to create:
As you can see, we are going to:
1. Create a file.
2. Add a line to that file in a branch (animals).
3. Add a different line to that file in another branch (fruit).
4. Merge branch animals back into master.
5. Merge branch fruit back into master, and choose the entire copy of the file from the fruit branch.
6. Check the history of the file.
As you will see, Git is going to simplify the history for us. The key here is step 5 -- we ignored all changes from the
animal branch. Git will notice that our file essentially did not change between step 1 and step 5, and so it will only
show us two history entries.
First we create the file and add it to our repo:
> cd sample
> git init
> echo "some content" > test.txt
> git add test.txt
> git commit -m "Initial commit"
Now we decide to append the text "donkeys" to the file in an animal branch:
> git checkout -b animals

> echo "donkeys" >> test.txt
> git commit -am "We have added an animal"
While we are experimenting, we decide maybe we want to go with fruit in our file instead, so we create a different
branch and append the text "bananas" at the end of the file instead:
> git checkout master -b fruit
> echo "bananas" >> test.txt
> git commit -am "We have added a fruit"
Feeling satisfied with our changes, we decide to merge our animal branch back into master:
> git checkout master

> git merge animals
Now let's look at the log for our test.txt file:
> git log test.txt
commit 6b33d99b996c430a60c9552b79245d1aa8320339
Author: hross <robrodbe@microsoft.com>
Date: Mon Feb 15 10:45:33 2016 -0500
We have added an animal
commit 206613ccd9a54b055b184c7b6c16f2ece8067e51
Date: Mon Feb 15 10:44:18 2016 -0500
Initial commit
So far so good, right? Nothing looks out of the ordinary in our log output. Now let's say we changed our minds
and decided to merge our fruit branch:
> git merge fruit
Auto-merging test.txt
CONFLICT (content): Merge conflict in test.txt
Automatic merge failed; fix conflicts and then commit the result.
Uh-oh, a merge conflict. After some consideration, we decide to use the entire test.txt file from our fruit branch.
Typically you would use some kind of text editor or merge tool, but we'll just recreate the entire file, since it's only
two lines:
> echo "some content" > test.txt

> echo "bananas" >> test.txt
> git commit -am "Fixed merge conflict"
Now let's take a look at the history for our test.txt file:
> git log test.txt
commit fdd4dfd816c4efebc5bdb240f49e934e299db581
Date: Mon Feb 15 10:51:06 2016 -0500
We have added a fruit
Date: Mon Feb 15 10:44:18 2016 -0500
Initial commit
Sure enough, we don't see any changes from our first experiment in the log, nor do we see our merge! Are they
still there? Did Git eliminate the changes entirely?
> git log --full-history test.txt
As you can see, although it simplified the log without the full-history flag, Git has kept all of our changes:
commit 5d0bb77a24e265dc154654fb3b5be331b53bf977
Merge: 6b33d99 fdd4dfd
Date: Mon Feb 15 10:59:34 2016 -0500
Fixed merge conflict
commit fdd4dfd816c4efebc5bdb240f49e934e299db581
Date: Mon Feb 15 10:51:06 2016 -0500
We have added a fruit
commit 6b33d99b996c430a60c9552b79245d1aa8320339
Date: Mon Feb 15 10:45:33 2016 -0500
We have added an animal
Date: Mon Feb 15 10:44:18 2016 -0500
Initial commit
Git History Simplification in a Nutshell

The thing about history simplification is that most of the time you will never notice it. But when a merge conflict
goes wrong and you want to know what happened -- you may find yourself looking at the git log history and
wondering where your changes went.
Now, instead of panicking, you know that:
History simplification for files is turned on by default
The --full-history flag will give you a more comprehensive file history
Update: Since I wrote this article, Azure DevOps Services has introduced a number of awesome history viewing
options on the web. What this means is that if you don't want to go slogging through the command line, you can
simply pull up the file you wish to view history for in our explorer and you will be presented with the below history
filter where you can specify simple or non-simple history views:
(c) 2016 Microsoft Corporation. All rights reserved. This document is provided "as-is." Information and views
expressed in this document, including URL and other Internet Web site references, may change without notice. You
bear the risk of using it.
This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You
may copy and use this document for your internal, reference purposes.
Adopt a Git branching strategy
Distributed version control systems like Git give individuals wide flexibility in how they use version control to
share and manage code. Your team should find a balance between this flexibility and the need to collaborate and
share code in a consistent manner.
Team members publish, share, review, and iterate on code changes through Git branches shared with others.
Adopt a branching strategy for your team so that you collaborate better and spend less time managing version
control and more time developing code.
The following branching strategies are based on the way we use Git here at Microsoft. For more information, see
How we use Git at Microsoft.
Keep your branch strategy simple

Keep your branch strategy simple by building your strategy from these three concepts:
1. Use feature branches for all new features and bug fixes.
2. Merge feature branches into the master branch using pull requests.
3. Keep a high quality, up-to-date master branch.
A strategy that extends these concepts and avoids contradictions will result in a version control workflow for your
team that is consistent and easy to follow.
Use feature branches for your work
Develop your features and fix bugs in feature branches (also known as topic branches) based off your master
branch. Feature branches isolate work in progress from the completed work in the master branch. Git branches
are inexpensive to create and maintain, so even small fixes and changes should have their own feature branch.
Creating feature branches for all your changes makes reviewing history very simple. Look at the commits made
in the branch and look at the pull request that merged the branch.
Name your feature branches by convention
Use a consistent naming convention for your feature branches to identify the work done in the branch. You can
also include other information in the branch name, such as who created the branch.
Some suggestions for naming your feature branches:
users/username/description
users/username/workitem
bugfix/description
features/feature-name
features/feature-area/feature-name
hotfix/description
NOTE
For information on setting policies to enforce a branch naming strategy, see Require branch folders.
Use feature flags to manage long-running branches

Long-lived feature branches present problems when you need to build code on top of the branch before the
work in the branch is finished. Merge unfinished features into the master branch so others can build off their
work, but keep them hidden from your users and testers behind feature flags. Enable the flag in development to
use the feature without the changes affecting anyone else. Once the feature is finished, you can remove the flags
or use them to roll out the feature to select users and testers.
Learn more about using feature flags in your code.
Review and merge code with pull requests
The review that takes place in a pull request is critical for improving code quality. Only merge branches through
pull requests that pass your review process. Avoid merging branches to the master branch without a pull request.
Reviews in pull requests take time to complete, so your team should agree on what's expected from pull request
creators and reviewers. Distribute reviewer responsibilities to share ideas across your team and spread out
knowledge of your codebase.
Some suggestions for successful pull requests:
Two reviewers is an optimal number based on research.
If your team already has a code review process, bring pull requests into what you're already doing.
Take care assigning the same reviewer(s) to a large number of pull requests. Pull requests work better when
reviewer responsibilities are shared across the team.
Provide enough detail in the description to quickly bring reviewers up to speed with your changes.
Include a build or linked version of your changes running in a staged environment with your pull request so
others can easily test the changes.
Keep a high quality, up-to -date master branch
The code in your master branch should pass tests, build cleanly, and always be up to date. Your master branch
needs these qualities so that feature branches created by your team start from a known good version of code.
Set up a branch policy for your master branch that:
1. Requires a pull request to merge code. This prevents direct pushes to the master branch and ensures
discussion of proposed changes.
2. Automatically adds reviewers when a pull request is created. The added team members review the code and
comment on the changes in the pull request.
3. Requires a successful build to complete a pull request. Code merged into the master branch should build
cleanly.
TIP
The build pipeline for your pull requests should be quick to complete, so it doesn't interfere with the review process.
Manage releases
Use release branches to coordinate and stabilize changes in a release of your code. This branch is long-lived and
isn't merged back into the master branch in a pull request, unlike the feature branches. Create as many release
branches as you need, but keep in mind that each active release branch represents another version of the code
you'll need to support. Lock release branches when you're ready to stop supporting a particular release.
Use release branches
Create a release branch from the master branch as you get close to your release or other milestone, such as the
end of a sprint. Give this branch a clear name associating it with the release, for example release/20 .
Create branches to fix bugs from the release branch and merge them back into the release branch in a pull
request.
Port changes back to the master branch

Bring over changes made in your release branch into your master branch to prevent regression in your code.
Port your changes from your release branch into a new feature branch to bring them back into the master
branch. Use cherry-picking instead of merging so that you have exact control over which commits are ported
back to the master branch. Merging the feature branch into the master branch can bring over release-specific
changes you don't want in the master branch.
Update the master branch with a change made in the release branch with these steps:
1. Create a new feature branch off the master branch to port the changes.
2. Cherry-pick the changes from the release branch to your new feature branch.
3. Merge the feature branch back into the master branch in a second pull request.
This release branch workflow keeps the pillars of the basic workflow intact: feature branches, pull requests, and a
strong master branch that always has the latest version of the code.
Why not use tags for releases?
Other branching workflows use Git tags to mark a specific commits as a release. Tags are useful for marking
points in your history as important, but tags introduce extra steps in your workflow that aren't necessary if you
are using branches for your releases.
Tags are maintained and pushed separately from your commits. Team members can easily miss tagging a
commit and then have to go back through the history afterwards to fix the tag. You can also forget the extra step
to push the tag, leaving the next developer working from an older version of the code when supporting the
release.
The release branch strategy extends the basic feature branch workflow to handle releases. Your team doesn't
have to adopt any new version control process other than the cherry-pick to port changes.
Manage deployments
You can handle multiple deployments of your code in the same way you handle multiple releases. Create a clear
naming convention (such as deploy/performance-test ) and treat the environment branches like release branches.
Your team should agree on a process to update deployment branches with the code from your master branch.
Cherry-pick bugfixes in the deployment branch back to the master branch using the same steps as porting
changes from a release branch.
An exception to this recommendation is if you are using a form of continuous deployment. Use Azure Pipelines
or Build & Release in TFS when working with continuous deployment to promote builds from your master
branch to your deployment targets.
Videos
Create pull requests to review and merge code in a Git project. Pull requests let your team review code and give
feedback on changes before merging it into the master branch. Pull requests can come from either topic branches
within the same repository or from a branch in a fork of the original repository. Reviewers can step through the
proposed changes, leave comments, and vote to approve or reject the code.
New to pull requests? Learn more about how to get feedback with Git pull requests.
View and manage your pull requests

1. To view pull requests in a specific repository in a project, navigate to that project in the web portal and
select Repos, Pull requests.
2. Verify that the correct repository is selected.
3. Select Active to show all active pull requests for the current repository. Select Completed or
Abandoned to bring up a history of closed pull requests.
You can view all of your pull requests across different projects in your organization by choosing Pull requests in
the My Work view.
Manage to pull requests you own or are assigned to with the Pull Requests tab in the Code page on the web.
Select Active to show all active pull requests for the current repo.
Select Completed or Abandoned to bring up a history of closed pull requests.
You can view all of your pull requests in your organization, across all projects, by choosing My pull requests
from the Projects page.
Create a new pull request

Create a new pull request from:
Pushed feature branches to your Git repo
The Development section in a linked work item
From the Pull requests page on the web
Team Explorer in Visual Studio
Using the Azure DevOps Services CLI
After pushing a branch
When you publish or update a feature branch in Azure Repos, you get a prompt asking if you would like to create
a pull request. This prompt is displayed on the Pull Requests page and the Files page.
Select the Create a pull request link to go to a page where you can enter your pull request details and create the
pull request.
When you publish or update a feature branch in Azure Repos, you get a prompt asking if you would like to create
a pull request in the Code view on the web. This prompt is displayed on the Pull Requests tab and the Files tab.
Select the Create a pull request link to go to a page where you can enter your pull request details and create the
pull request.
From a linked work item
Create a pull request directly from a work item linked to the branch.
1. From the Backlogs or Queries tab in the Work view , open the work item with the linked branch.
2. In the Development area of the work item, there's a link to create a pull request under the branch name.
Select the link to go to a page where you can enter your pull request details and create the pull request.
From the Pull requests page on the web
Create pull requests from any branch from the Pull Request page on the web.
Select New pull request in the upper right to go to a page where you can enter your pull request details and
create the pull request. Pick the branch you wish to have reviewed and the branch you want to merge the
changes into, such as the master branch.
From Visual Studio
Initiate pull requests directly from Visual Studio.
1. Connect to your Project from Visual Studio.
2. Open Team Explorer (select View, then Team Explorer or use the Ctrl+\ , Ctrl+M hotkey)
3. Open Pull Requests in Team Explorer by selecting the Home icon and choosing Pull Requests.
4. From the Pull Requests view you can view pull requests opened by you, assigned to you, and you can
new pull request in the Azure DevOps Services web portal.
You can also initiate pull requests from Visual Studio from the Branches view in Team Explorer by right-
clicking the branch name and selecting Create pull request while connected to your project.
From the Azure DevOps Services CLI

You can now manage pull requests and other resources in Azure DevOps Services and Team Foundation Server
2017 Update 2 or later from the command line with the Azure DevOps Services CLI.
For a list of commands to create and manage pull requests, see Manage pull requests.
For more information about working with the Azure DevOps Services CLI, see Get started with the Azure
DevOps Services CLI.
Draft pull requests

Sometimes you may want to create a pull request but you aren't ready to send it to the entire team for review.
Draft pull requests allow you to indicate that a pull request is a work in progress, without resorting to title
prefixes such as WIP or DO NOT MERGE. When the pull request is ready for review, you can publish it, and
begin (or resume) the full review process.
Draft pull request differences
Create a draft pull request
Publish a draft pull request
Mark as draft
Draft pull request differences
Draft pull requests have the following differences from published pull requests.
Build validation policies are enabled but not run automatically, but they can be manually queued by
selecting the ... menu beside the build in the pull request.
Voting is disabled while in draft mode.
Required reviewers are not automatically added.
Notifications are sent while in draft mode, but only to reviewers that you explicitly add to the draft pull
request.
Draft pull requests are displayed in the pull requests list with a special badge.
Create a draft pull request

To create a draft pull request, choose Create as draft when creating the pull request.
If you start your pull request title with WIP, Create as draft is selected as the default option.
Publish a draft pull request
When you're ready to have the pull request reviewed and completed, you can publish it.
When a pull request is published, required reviewers are assigned and notified, policies are evaluated, and voting
is enabled.
Mark as draft
To mark an active pull request as a draft, choose Mark as draft. Marking a pull request as draft resets all votes,
and if your pull request has any votes you'll be asked to confirm.
Add detail to your pull request
Link work items and describe the changes in the branch to make it easier for others to see what problem you are
trying to solve. Change the pull request title, add a detailed description, add reviewers, link work items, and make
comments to explain your changes. When you're ready to create the pull request and have your changes
reviewed, select Create.
Don't worry if you don't have all of the work items, reviewers, or details ready when you create your pull request
- you can add them now when you create the pull request, and you can also add or update all of these items later
after you create the pull request.
Help reviewers using pull request labels
Sometimes it's important to communicate extra information about a pull request to the reviewers. Maybe the pull
request is still a work in progress, or it's a hotfix for an upcoming release - so you append some extra text in the
title, perhaps a "[WIP ]" prefix or "DO NOT MERGE". Labels now provide a way to tag pull requests with extra
information that can be used to communicate important details and help organize pull requests.
To add a label when creating a pull request, choose Add label. After a pull request is created you can manage
labels in the Labels section.
In a future release, we'll make labels even more useful by making it easier to filter pull requests using labels.
Add and remove reviewers
Add reviewers to your pull request.
1. Select the Overview tab in the pull request.
2. Select the add icon in the Reviewers area.

3. Enter the name of the user or group to add to the reviewer list for the pull request. If the user isn't a
member of your Project, you'll need to add them.
4. As you enter a name or email address, a list of matching users or groups appears. Select the user or group
from the list to add them as a reviewer.
Add reviewers to your pull request.
2. Select the add icon in the Reviewers area.

3. Enter the name of the user or group to add to the reviewer list for the pull request. If the user isn't a
member of your Project, you'll need to add them.
4. As you enter a name or email address, a list of matching users or groups appears. Select the user or group
from the list to add them as a reviewer.
Link work items
Link work items to your pull request:
2. Select the add icon in the Work Items area.

3. Enter the ID of the work item or search for work items with titles that match your text. Select the work item
from the list that appears.
Remove work item links by selecting the that appears when you hover over the work item. This only removes
the link between a work item to a pull request; links created in the branch or from commits stay in the work item.
Link work items to your pull request:
2. Select the add icon in the Work Items area.

3. Enter the ID of the work item or search for work items with titles that match your text. Select the work item
from the list that appears.
Remove work item links by selecting the that appears when you hover over the work item. This only removes
the link between a work item to a pull request; links created in the branch or from commits stay in the work item.
Edit pull request title and description
Update the title of a pull request by clicking the current title and updating the text. Choose the save icon to save
changes or select undo to discard your changes.
Edit the pull request description by selecting the edit link that appears when you hover over the existing
description.
Keep these fields up to date so reviewers know what the changes in the pull request are trying to accomplish.
Review a pull request

The Overview tab shows the current state of the pull request at a glance. Review the title, description, and
discussion to get an understanding of the proposed changes and see issues brought up by other reviewers.
If you need to make a change to the code as part of your review, starting with Visual Studio 2017 Update 6 you
can checkout the source branch from a pull request directly from the Pull Requests view in Team Explorer.
Right-click the desired pull request and choose Checkout Source Branch.
Browse code changes

Select the Files tab to view the changes made to the source branch relative to the target branch of the pull
request.
NOTE
The size limit for files in the files view and the diff view is 5 MB. To view and diff files larger than 5 MB, you can download
the file and view it using a local diff tool on your machine.
Review previous versions of the code pushed to the source branch of the pull request from the All updates
drop-down. A new version is added to the list in the drop-down and on the Updates tab every time the branch is
updated in Azure Repos.
The diff view updates as you select different changes, showing the differences between the files in the currently
selected and previous version in the pull request. Catch up with a pull request after being away from it for awhile
by stepping through changes made since your last review.
Browse a list of changes by push from the author using the Updates tab.
You can select and view changes made in commits on the branch in the Commits tab.
Leave comments
Add comments to the pull request to make suggestions, reply to previous comments, and point out problems
with the proposed changes. Comment inline in the Files tab in your pull request by selecting the comment icon (
). Leave feedback not tied to a specific code change by commenting in the Overview tab. Reply directly to the
author or other reviewers by using @username and reference work items using #workitemID in your comments.
You can also reference other pull requests using !pullrequestID .
Update comment status to let reviewers know what you are doing to address the concerns brought up in their
review. New comments start in Active status and can be updated in the conversation using the Resolve and
Reply & resolve buttons.
Additional options are available in the comment resolution drop-down.
Active: Comment is still under review.

Pending: The issue in this comment will be addressed, but isn't fixed yet.
Resolved: The issue brought up in this comment has been fixed.
Won't Fix: The suggestion in the comment is noted, but won't make changes in this pull request to address it.
Closed: Discussion for this comment is closed.
Vote on the changes
Vote on the changes in a pull request by choosing an option from the button on the upper right. The default
option is Approve, but you can select other options from the drop-down:
Approve: Agree with the proposed changes in the pull request as-is.
Approve with suggestions: Agree with the pull request, but provide optional suggestions to improve the
code.
Wait for author: Do not approve the changes, and ask the author to review your comments. The author
should let you know when you should re-review the code after they have addressed your concerns.
Reject: The changes aren't acceptable. If you are voting this way, you should leave a comment in the pull
request detailing why the changes were rejected.
Reset feedback: Choose Reset feedback to remove your vote.
The number of required approvals in a pull request can be set from the branch policy for the branch. Pull
requests can be completed if the number of required approvals is met, even if other reviewers have rejected the
changes. Votes in a pull request can optionally be reset when new code is pushed to the branch by checking
Reset code reviewer votes when there are new changes when configuring the Require a minimum number
of reviewers branch policy.
Best practice: At least two reviewers should review and approve the changes in a significant pull request.
Update code in response to feedback

Update your code in response to comments by creating a new commit with the changes and pushing the updates
to the branch in your Git repo. You can make quick updates to your branch directly from the Files tab in the
Code view on the web.
Change the target branch of a pull request
For most teams, nearly all pull requests target the same branch, such as master or develop . However, in the
case where you do need to target a different branch, it's easy to forget to change the target branch from the
default. With the new feature to change the target branch of an active pull request, this is now a simple action. To
learn how, see Change the target branch of a pull request.
Complete the pull request

Complete your pull request after the reviewers approve of the changes by selecting Complete in the upper right
of the pull request view.
Complete: Complete the pull request now and merge the changes to the target branch.
Set auto-complete: If you have branch policies, you can choose Set auto-complete to configure the pull
request to close once all branch policies are met.
Abandon: Choose Abandon to close the pull request without merging the changes.
Enter the message used for the merge commit and update the pull request description as needed in the dialog
that follows.
Check Complete linked work items after merging to complete any linked work items.
Check Delete <branch name> after merging to delete the source branch from the pull request.
Check Squash changes when merging to squash merge your pull request.
Check Override branch policies and enable merge to force merge even if all branch policies haven't been
satisfied. This option is only available if you have Exempt from policy enforcement permissions.
Linked work items are also updated showing the pull request completion.
Complete automatically
Select Auto-complete from the Complete button drop-down to complete the pull request and merge the
changes as soon as all branch policies are met. Auto-completion lets you skip having to come back to the pull
request to complete it after the build finishes successfully and the reviewers approve the changes. When the
conditions are satisfied for auto-complete, the pull request is completed and you are notified via email. If there is
a conflict or an error completing the pull request, you will get an email notifying you of the issue so you can
resolve it.
Once auto-complete has been set, the pull request displays a banner confirming that the changes will be merged
as soon as the policies are satisfied. Select Cancel auto-complete to turn off auto-complete and return the pull
request to an active state. Starting with TFS 2018 Update 2, the banner displays the outstanding list of policy
criteria.
NOTE
The Auto-complete option is available in Azure Repos and TFS 2017 and higher, and is only present when you have
branch policies that must be satisfied before the pull request can be completed. If you don't see Auto-complete, it is
because you don't have any branch policies. For more information, see Branch policies.
Abandon your changes

Abandon pull requests when you decide the work in the feature branch should not be merged by selecting
Abandon from the drop-down on the Complete button. The abandoned pull request will still be viewable on the
web and stays linked to work items.
Reactivate an abandoned pull request at any time by selecting the pull request from the Abandoned tab in the
Pull Request view and selecting Reactivate.
Receiving notification of pull request updates

Subscribe to email alerts to get notified when changes are made to your pull requests.
NOTE
By default you are subscribed to several common pull request notifications. For a complete list of default notification
subscriptions, see Out-of-the-box (OOB) or default subscriptions
1. Navigate to your project and select Project settings, Notifications to view your notification settings
2. Choose New subscription to subscribe to additional notifications.
3. To edit a notification, select ... for the notification and choose View to edit the subscription.
4. To opt-out of a notification, set the State to Off.
1. Select the settings icon while you have your project open to bring up the project administration page.
2. Select the Notifications tab to view your notification settings, and choose New subscription to
subscribe to additional notifications.
3. To edit a notification, select ... for the notification and choose View to edit the subscription.
4. To opt-out of a notification, set the State to Off.

Revert a pull request
Undo the changes made in a pull request by opening the completed pull request and selecting Revert. When you
revert a pull request in this way, you create a new branch with changes that will undo the pull request for an
existing target branch in your repo.
In the dialog that appears, pick the branch where you want to undo the pull request changes in the Target
branch selector and the name of a new branch where the reverted changes will be created in the Topic branch
name field, then select Revert. Select Create pull request to merge the newly created branch in a second pull
request to complete the revert.
NOTE
The branch created during this revert has a single commit that reverts the file changes in the pull request. The branch does
not contain a reverted commit for each of the commits merged in the original pull request.
Cherry-pick a pull request

Copy changes made in a pull request to another branch in your repo by selecting Cherry-pick while viewing the
completed pull request or selecting Cherry-pick from the ... menu while viewing an active pull request. Cherry-
picking a pull request in this way creates a new branch with the copied changes that you then merge into a target
branch in a second pull request.
In the dialog that appears, enter the branch you want to merge the copied changes into in the Target branch
field and a new branch that will contain the copied changes in the Topic branch name field, then select Cherry-
pick. If there are no conflicts between the target branch and the newly created topic branch, you can then select
Create pull request to merge the topic branch into the target branch to complete the cherry-pick.
Set a new default branch

NOTE
This step requires Edit Policies permissions on your Git repo.
Configure your Git repo to use a different default branch to merge code into when your team creates new pull
requests. This is useful when you want to use a branch other than master for new changes or need to change
your main line of development in your repo.
1. Navigate to your project and select Project settings.
2. Scroll down and select Repositories from the Code section.
3. Select the desired repository and expand the branches.
4. Select the ... beside the desired branch and choose Set as default branch.
2. Select Version Control.

3. Select your Git repository. Your branches are displayed under your repo.
4. Select the ... next to the branch you want to set as default, then select Set as default branch.
Improve pull request descriptions using templates
Azure Repos
Writing good pull request descriptions is a great way to help reviewers know what to expect when reviewing code.
They're also a great way to help track things that should be done for every change, such as testing, adding unit
tests, and updating documentation. Pull request templates can help your developers create great pull request
descriptions that meet your organization's standards.
This article shows you how to get started with pull request templates.
NOTE
Pull request templates can provide guidance, but are advisory only. Use branch policies to enforce best practices such as
requiring pull requests for key branches like master, requiring a successful build, and enforcing required reviewers. For more
information, see branch policies.
What is a pull request template?

A pull request template is a file containing markdown text that is added to your pull request description when the
pull request is created.
Thank you for your contribution to the Fabrikam Fiber repo.

Before submitting this PR, please make sure:
- [ ] Your code builds clean without any errors or warnings

- [ ] You are using approved terminology
- [ ] You have added unit tests
Azure Repos allows you to create the following type of pull request templates:
A default pull request template that is automatically applied for all new pull requests in the repository, unless
overridden by a branch specific pull request template
Branch specific pull request templates that are automatically applied to pull requests targeting a specific
branch
Additional pull request templates that can be optionally added by the pull request creator
The type of pull request template is determined by its filename and folder location, as covered in the following
sections. The filenames and folder locations are not case sensitive, but they must be in the default branch of your
repository.
NOTE
All pull request template files must be located in the default branch (typically master) of your repository. Only pull request
template files from the default branch are used.
Default pull request templates

Default pull request templates are automatically applied to the description field when a new pull request is created.
To configure your repository with a default pull request template, create a file named pull_request_template.md or
pull_request_template.txt and save it in the default branch of your repository in one of the following folders.
A folder named .azuredevops that is contained in the root folder of the repository
A folder named .vsts that is contained in the root folder of the repository
A folder named docs that is contained in the root folder of the repository
The root folder of the repository
Multiple locations are provided to give you flexibility in where you store your pull request templates. When a pull
request is created, Azure Repos searches the designated folders in the order given, and uses the first default pull
request template it finds.
When a new pull request is created in the repository, unless a branch specific pull request template applies, the
contents of the default pull request template are used to pre-populate the description field in the pull request.
You can edit or add to this description and append additional pull request templates if desired by selecting them
from the Add a template drop-down.
NOTE
When a default or branch specific pull request template is automatically applied, it replaces the standard commit messages
that are usually used for the default description. You can add them back by selecting Add commit messages.
Branch specific pull request templates

Branch specific pull request templates can be configured for pull requests that target a specific branch. To configure
your repository with a branch specific pull request template, create a .txt or .md file named after your branch.
The name must match the first level of the branch name, such as master , dev , release , or feature . Each branch
specific pull request template is applied any time a pull request targets that branch or any branches contained
under it. For example the pull request template named feature.md would be applied if a pull request targeted the
feature branch or any feature/* branches.
Branch specific pull request templates must be saved in the default branch of your repository using the following
folder hierarchy: pull_request_template/branches/ . These folders must be based in one of the following folders in
your repository.
A folder named .azuredevops that is contained in the root folder of the repository
A folder named .vsts that is contained in the root folder of the repository
A folder named docs that is contained in the root folder of the repository
The root folder of the repository
For example, a branch specific pull request template that should apply to all pull requests into the dev branch
would be named dev.md or dev.txt and located in one of the following locations.
<repository root>/.azuredevops/pull_request_template/branches/
<repository root>/.vsts/pull_request_template/branches/
<repository root>/docs/pull_request_template/branches/
<repository root>/pull_request_template/branches/
Just like default pull request templates, multiple locations are provided to give you flexibility in where you store
branch specific pull request templates. When a pull request is created, Azure Repos searches the designated folders
in the order given for a branch specific pull request template, and uses the first one it finds that matches the branch
name. If no branch specific pull request template is found, Azure Repos then searches for a default pull request
template as described in the previous Default pull request templates section.
Additional pull request templates

In addition to the default and branch specific pull request templates, you can configure additional pull request
templates. These can be .md or .txt files, located in one of the following folders in your default branch.
<repository root>/.azuredevops/pull_request_template/
<repository root>/.vsts/pull_request_template/
<repository root>/docs/pull_request_template/
<repository root>/pull_request_template/
When a pull request is created, you can append any of the available pull request templates by choosing them from
the Add a template drop-down. The names in the drop-down are based on the file names of the templates.
In the following example three templates are listed.
dev.md - This is the branch specific template that was applied by default to this pull request into the dev
branch, as indicated by the default message listed after the filename.
additional.md - This is an additional template.
pull_request_template.md - This is normally the default template but it was overridden by the dev.md branch
specific template in this pull request. Even though it was not added by default, it can still be applied by selecting
it from the list.
Select the name of the desired additional template to append its contents to the current pull request description.
NOTE
You can specify a pull request template to override any matching default or branch specific pull request by appending
?template=name.md to the querystring.
Pull requests and Git history

When you complete a pull request, you merge the topic branch into your default branch, usually master . This
merge adds the commits of the topic branch to your main branch and creates a merge commit to reconcile any
conflicts between the default and topic branch. The comments and discussion in the pull request give additional
context for the changes made in the topic branch.
The commit history on your master branch (or other default branch) does not follow a straight line because of
the related topic branch history. As the project grows larger, the number of topic branches worked on at the same
time increases, making the default branch history increasingly more difficult to follow.
This default branch is an accurate representation of the history of each topic branch, but it is difficult to use to
answer broader questions about your project's development.
What is a squash merge?

Squash merging is a merge option that allows you to condense the Git history of topic branches when you
complete a pull request. Instead of each commit on the topic branch being added to the history of the default
branch, a squash merge takes all the file changes and adds them to a single new commit on the default branch.
A simple way to think about this is that squash merge gives you just the file changes, and a regular merge gives
you the file changes and the commit history.
How is a squash merge helpful?

Squash merging keeps your default branch histories clean and easy to follow without demanding any workflow
changes on your team. Contributors to the topic branch work how they want in the topic branch, and the default
branches keep a linear history through the use of squash merges. The commit history of a master branch
updated with squash merges will have one commit for each merged branch. You can step through this history
commit by commit to find out exactly when work was done.
Considerations when squash merging

Squash merging condenses the history of changes in your default branch, so it is important to work with your
team to decide when you should squash merge and when you want to keep the full commit history of a topic
branch. When squash merging, it's a good practice to delete the source branch. This prevents confusion as the
topic branch itself does not have a commit merging it into the default branch.
Completing pull requests with squash merge

You can choose to squash merge when completing a pull request in Azure Repos. Choose Squash changes
when merging on the Complete pull request dialog to squash merge the topic branch.
Customize and extend pull request workflows with
pull request status
Azure Repos | Azure DevOps Server 2019 | TFS 2018 Update 2

Pull requests are a great tool for facilitating code reviews and managing code movement within a repository.
Branch policies enforce code quality during the pull request process by establishing requirements that must be
performed for every code change. These policies enable teams to enforce many best practices related to reviewing
code and running automated builds, but many teams have additional requirements and validations to perform on
code. To cover these individual and custom needs, Azure Repos offers pull request statuses. Pull request statuses
integrate into the PR workflow and allow external services to programmatically sign off on a code change by
associating simple success/failure type information with a pull request. Optionally, pull requests can be blocked
until the external service approves the change.
Integrating into the PR workflow involves a few different concepts:
Service hooks - this is how services that want to integrate with a pull request know when a pull request has
been created or updated.
Pull request status - provides a way for services to associate success/failure information with a pull request.
Status policy - provides a mechanism to block pull request completion until the pull request status indicates
success.
Custom actions - provides a way to extend the status menu using Azure DevOps Services extensions.
In this topic, you'll learn about pull request statuses and how they can be used to integrate in the PR workflow.
Service hooks
Any service that wants to integrate with pull requests will need to know when a new PR has been created or
updated, so that the contents of the PR may be evaluated. Service hooks enable external systems to be alerted
when events occur in Azure DevOps Services. There are two event triggers for pull requests: - pull request
created and pull request updated. Ensure that there are subscriptions for both of these events to receive
notifications any time the code in a PR changes.
Pull request status

Pull request status provides a way for services to associate simple success/failure type information with a pull
request, using the Status API. A status consists of four key pieces of data:
State. One of the following predefined states: succeeded , failed , pending , notSet , notApplicable , or error
.
Description. A string that describes the status to the end user.
Context. A name for the status - typically describing the entity posting the status.
URL. A link where users can get more information specific to the status.
Essentially, status is the way a user or service posts their evaluation about a pull request and provides the answer
to questions such as:
Did the changes meet the requirements?
Where can I learn more about what I need to do to meet the requirements?
Let's look at an example. Consider a CI service that is required to build all code changes in a project. When that
service evaluates the changes in a pull request, it needs to post back the results of the build and tests. For changes
that pass the build, a status like this might be posted on the PR:
{
"state": "succeeded",
"description": "CI build succeeded",
"context": {
"name": "my-ci-system",
"genre": "continuous-integration"
},
"targetUrl": "http://contoso.com/CI/builds/1"
}
This status would be displayed to the end user in the PR Details view:
The state is shown to the user using an icon (green check for succeeded , red X for failed , a clock for
pending , and a red ! for error ).
The description is displayed next to the icon, and the context is available in a tooltip.
When a targetUrl is applied, the description will be rendered as a link to the URL.
Updating status
A service may update a PR status for a single PR by posting additional statuses, only the latest of which is shown
for each unique context . Posting multiple statuses helps users manage expectations. For example, posting a
pending status is a good way to acknowledge to the user that a system has received an event and is starting work.
Using an informative description such as the following examples can further help the user understand how the
system is working:
"Build queued"
"Build in progress"
"Build succeeded"
Iteration status
When the source branch in a PR changes, a new "iteration" is created to track the latest changes. Services that
evaluate code changes will want to post new status on each iteration of a PR. Posting status to a specific iteration
of a PR guarantees that status applies only to the code that was evaluated and none of the future updates.
Conversely, if the status posted applies to the entire PR, independent of the code, posting to the iteration may be
unnecessary. For example, checking that the author (an immutable PR property) belongs to a specific group would
only need to be evaluated once, and iteration status would not be needed.
When configuring the status policy, if iteration status is being used, the Reset conditions should be set to Reset
status whenever there are new changes. This further guarantees that the PR will not be able to be merged
until the latest iteration has a status of succeeded .
See the REST API examples for posting status on an iteration and on a pull request.
Status policy
Using status alone, details from an external service can be provided to users within the PR experience. Sometimes,
sharing information about a PR is all that is necessary, but in other cases PRs should be blocked from merging
until requirements are met. Like the in-box policies, the Status policy provides a way for external services to
block PR completion until requirements are met. If the policy is required, it must pass in order to complete the pull
request. If the policy is optional, it is informational only, and a status of succeeded is not required in order to
complete the pull request.
Status policies are configured just like other branch policies. When adding a new status policy, the name and
genre of the status policy must be entered. If the status has been posted previously you can pick it from the list; if
it is a new policy you can type in the name of the policy in the format genre/name.
When a status policy is specified, it requires that a status of succeeded with the context matching the selected
name be present to in order for this policy to pass.
An Authorized account can also be selected to require that a specific account has the authority to post status
that will approve the policy.
Policy applicability
The Policy applicability options determine whether this policy applies as soon as a pull request is created, or
whether the policy applies only after the first status is posted to the pull request.
1. Apply by default - The policy applies as soon as the pull request is created. With this option, the policy
does not pass after pull request creation until a succeeded status is posted. A PR can be marked exempt
from the policy by posting a status of notApplicable , which will remove the policy requirement.
2. Conditional - The policy doesn't apply until the first status is posted to the pull request.
Together, these options can be used to create a suite of dynamic policies. A top-level "orchestration" policy could
be set to apply by default while the PR is being evaluated for applicable policies. Then, as additional conditional
policies are determined to apply (perhaps based on specific build output), status can be posted to make them
required. This orchestration policy could be marked succeeded when it is finished evaluating or could be marked
notApplicable to indicate to the PR that the policy doesn't apply.
Custom actions
In addition to predefined service hook events that can trigger the service to update PR status, it is possible to
extend the status menu by using Azure DevOps Services extensions to give trigger actions to the end user. For
example, if status corresponds to a test run that can be restarted by the end user, it is possible to have a Restart
menu item to the status menu that would trigger tests to run. To add a status menu, you'll need to use the
contribution model. Check out the Contributions guide sample on Github where you can see the parts of code that
add the following sample items to the status menu..
Next Steps
Learn more about the PR Status API and check out the how -to guides:
Create a pull request status server with Node.js
Forks

A fork is a complete copy of a repository, including all files, commits, and (optionally) branches. Forks are a great
way to support an Inner Source workflow: you can create a fork to suggest changes to a project when you don't
have permissions to write to the original project directly. Once you're ready to share those changes, it's easy to
contribute them back using pull requests.
What's in a fork
A fork starts with all the contents of its upstream (original) repository. When you create a fork, you can choose
whether to include all branches or limit to only the default branch. None of the permissions, policies, or build
pipelines are applied. The new fork acts as if someone cloned the original repository, then pushed to a new, empty
repository. After a fork has been created, new files, folders, and branches are not shared between the repositories
unless a PR carries them along.
Sharing code between forks
You can create PRs in either direction: from fork to upstream, or upstream to fork. The most common direction
will be from fork to upstream. The destination repository's permissions, policies, builds, and work items will apply
to the PR.
Choosing between branches and forks

For a very small team (2-5 developers), we recommend working in a single repo. Everyone should work in topic
branches, and master should be protected with branch policies. As your team grows larger, you may find yourself
outgrowing this arrangement and prefer to switch to a forking workflow.
If your repository has a large number of casual or infrequent committers (similar to an open source project), we
recommend the forking workflow. Typically only core contributors to your project have direct commit rights into
your repository. You should ask collaborators from outside this core set of people to work from a fork of the
repository. This will isolate their changes from yours until you've had a chance to vet the work.
The forking workflow

1. Create a fork
2. Clone it locally
3. Make your changes locally and push them to a branch
4. Create and complete a PR to upstream
5. Sync your fork to the latest from upstream
### Create the fork
1. Navigate to the repository to fork, and choose Fork.
2. Specify a name, and choose the project where you want the fork to be created. If the repository contains a
lot of topic branches, we recommend you fork only the default branch.
3. Choose Fork to create the fork.
NOTE
You must have the Create Repository permission in your chosen project to create a fork. We recommend you create a
dedicated project for forks where all contributors have the Create Repository permission. For an example of granting this
permission, see Set Git repository permissions.
### Clone your fork locally

Once your fork is ready, clone it using the command line or an IDE like Visual Studio. The fork will be your
origin remote.
For convenience, after cloning you'll want to add the upstream repository (where you forked from) as a remote
named upstream .
Visual Studio
Command Line
To add your upstream repository in Visual Studio, follow these steps:
1. Open the Settings page.
2. Choose Repository Settings.
3. Under Remotes, choose Add.
4. Add a new remote called upstream , using the Git clone URL of the repo you forked.
5. Select Save and the new remote is added and displayed in the repository settings.
### Make and push changes

It's possible to work directly in master - after all, this fork is your personal copy of the repo. We recommend you
still work in a topic branch, though. This allows you to maintain multiple, independent workstreams
simultaneously. Also, it reduces confusion later when you want to sync changes into your fork.
Make and commit your changes as you normally would. When you're done with the changes, push them to
origin (your fork).
### Create and complete a PR

Open a pull request from your fork to the upstream. All the policies, required reviewers, and builds will be applied
in the upstream repo. Once all policies are satisfied, the PR can be completed and the changes become a
permanent part of the upstream repo.
IMPORTANT
Anyone with the Read permission can open a PR to upstream. If a PR build pipeline is configured, the build will run against
the code introduced in the fork.
### Sync your fork to latest

When you've gotten your PR accepted into upstream, you'll want to make sure your fork reflects the latest state of
the repo. We recommend rebasing on upstream 's master branch (assuming master is the main development
branch).
Visual Studio
Command Line
In Visual Studio, you can use the Synchronization page to fetch and rebase.
1. Open the Synchronization page in Team Explorer.
2. Fetch from upstream .
3. Open the Branches page in Team Explorer. Make sure master is checked out.
4. Rebase master onto upstream/master .

Now you're all set to start your next feature on a new topic branch.
The forking workflow lets you isolate changes from the main repository until you're ready to integrate them.
When you're ready, integrating code is as easy as completing a pull request.
Authentication overview
Azure Repos | Azure DevOps Server 2019 | TFS 2018 | TFS 2017 | TFS 2015 Update 3
Choose a method to securely login and access the code in your Azure Repos/TFS Git repo. Use these credentials
with Git on the command line or from any Git client that supports HTTPS or SSH authentication. Limit the scope
of access and revoke these credentials from the web when they are no longer needed.
Using Visual Studio? Team Explorer handles authentication with Azure Repos for you.
Authentication comparison
ADDITIONAL TOOLING
AUTHENTICATION TYPE WHEN TO USE SECURE? EASE OF SETUP REQUIRED
Personal access When you need an Very secure (when Easy Optional (Git
tokens easy to configure using HTTPS) credential managers)
credential or need
configurable access
controls
SSH When you already Very secure Intermediate Windows users will
have SSH keys set up, need the SSH tools
or are on macOS or included with Git for
Linux Windows
Alternate credentials When you can't use Least secure Easy No

personal access
tokens or SSH
Personal access tokens

Personal access tokens let you create a password for use with the command line or other Git client without using
your Azure DevOps Services username and password directly. An expiration date is set on these tokens when they
are created and you can restrict the scope of the data they can access. Use personal access tokens to authenticate if
you don't already have SSH keys set up on your system or if you need to restrict the permissions granted by the
credential.
Learn more about personal access tokens and how to create one
Use credential managers to generate tokens
Git credential managers are an optional tool that makes it easy to create personal access tokens when working
with Azure Repos. Normally you'd need to log into the Azure DevOps Services web portal, generate a token, then
use the token as your password when connecting to Azure Repos.
Personal access tokens are generated on demand when you have the credential manager installed. The credential
manager creates the token in Azure DevOps Services and saves it locally for use with the Git command line or
other client.
NOTE
Current versions of Git for Windows include the Git credential manager as an optional feature during installation.
SSH key authentication

Key authentication with SSH works through a public and private key pair that you create on your computer. You
associate the public key with your username from the web. Azure DevOps Services will encrypt the data sent to
you with that key when you work with Git. You decrypt the data on your computer with the private key, which is
never shared or sent over the network.
SSH is a great option if you've already got it set up on your system—just add a public key to Azure DevOps
Services and clone your repos using SSH. If you don't have SSH set up on your computer, you should use personal
access tokens and HTTPS instead-it's secure and easier to set up.
Learn more about setting up SSH with Azure DevOps Services
Alternate credentials
IMPORTANT
Use of alternate credentials is not recommended.
Alternate credentials are not supported on TFS.
The username specified for the alternate credentials must be unique within that user's Azure DevOps organization, and
can't be reused more than once per organization.
Create an alternate user name and password to access your Git repository using alternate credentials. Unlike
personal access tokens, this login doesn't expire and can't be scoped to limit access to your Azure DevOps Services
data. Use alternate credentials as a last resort when you can't use personal access tokens or SSH keys.
How dates work in Git
Git tracks two dates in commits: author date and commit date. In addition, Azure DevOps Services and TFS track
when a commit was first pushed to the server.
Author date: when a commit was originally authored. Typically, when someone first ran git commit .
Commit date: when a commit was applied to the branch. In many cases it is the same as the author date.
Sometimes it differs: if a commit was amended, rebased, or applied by someone other than the author as part of
a patch. In those cases, the date will be when the rebase happened or the patch was applied.
Push date: when a commit was pushed to the remote repository in question. This date is specific to the remote
version control system you are using, and won't be available in your local repository.
When you run git log , by default you will see the author date. If you want to see commit date, you can use one of
the many command line options, such as --pretty=fuller .
Let's look at a brief example to see these concepts in practice. First we will create a normal commit:
git init
echo test > file.txt
git add *
git commit -m "A normal commit message"
Now let's amend our commit with a different message:
echo again > file.txt

git add *
git commit --amend -m "An amended commit"
If we look at our regular log history we would see something like the following:
git log
commit 17232459f0ae25adeff21c9e21742ba22b7f3499
Author: Ross Brodbeck <robrodbe@microsoft.com>
Date: Thu Feb 25 19:38:54 2016 -0500
An amended commit
Now let's view the same commit with the author date:
git log --pretty=fuller
commit 17232459f0ae25adeff21c9e21742ba22b7f3499
Author: Ross Brodbeck <robrodbe@microsoft.com>
AuthorDate: Thu Feb 25 19:38:54 2016 -0500
Commit: Ross Brodbeck <robrodbe@microsoft.com>
CommitDate: Thu Feb 25 19:39:36 2016 -0500
An amended commit
Note the (slight) difference between the author date and commit date above. The author date is my original,
unedited, commit time. The commit date is the time at which I ran the --amend command.
In fact, there are a lot of git log options to help you understand dates better. For example, passing the --date
flag will allow you to determine how dates are displayed. This can be useful for normalizing time zones (git displays
dates in their original time zone, by default) or changing the date display string.
To learn more about the various formatting options, see the git log man page.
Changing Git Dates

When you're getting ready to commit your code, note that you have the ability to set both the author and commit
dates. This isn't something you should do often.
You can change the author date of a given commit by passing the --date flag to git commit . There are various
articles regarding the formatting of this flag, but the gist is that it isn't well-documented. This StackOverflow
question does a great job of explaining the acceptable date formats.
You can also use the environment variables GIT_COMMITTER_DATE and GIT_AUTHOR_DATE to set the corresponding
dates, as documented in the man page. If you need to go this route, use this Stack Overflow question as a starting
point.
How names work in Git
When you commit to your local repo, Git includes your name and email address as part of the commit. This can
sometimes lead to confusion. The name and email on your commits may not match the identity you log in with on
a Git host like Azure Repos. Further, you may have commits under several different names and email addresses
even though you were the author for each of them.
Why are there multiple names for me in my repo?

Have you searched your name in the History page and been surprised to see multiple, slightly different entries for
yourself? You were probably left wondering how this happened and what you can do about it. The answer is
simple: in different commits, your name was recorded differently. Maybe you have two different computers, one
configured with your full name (e.g. Frances) and the other with the nickname you go by (e.g. Frank). Or maybe
you have a home computer connected to your Microsoft Account (e.g. frances@outlook.com) and a work computer
connected to your employer's Azure Active Directory (e.g. frances_t@fabrikam.com). It's even possible you
changed your settings over time, so older commits have one name and newer commits have another.
Where does Git get your name and email?

Git stores your name and email address in its config file. This file can be at the system level, global to your account
on your computer, or local to a repository. If a name and email aren't found in any of these places, Git will do its
best to get this information from your operating system. Your details are included in the commit, marking you as
the author of that commit.
When you set up Git for the first time on a new machine, you may create a commit using Git's "best effort"
information. Git will prompt you to set an explicit name and email address, and the new settings will be used for
subsequent commits. This is a frequent source of one author having multiple names.
Where does Azure DevOps Services get your name and email?
Your details in Azure DevOps Services come from your profile. Your profile was originally populated from details in
your Microsoft Account or Azure Active Directory account, but you may change these details yourself. When you
edit a file in the web or complete a PR, Azure Repos supplies your profile details as the author of the commit. This
is another opportunity for your name or email address to be specified differently.
How do I change my information in Git and Azure DevOps Services?

In Git, you can run two commands to change your name and email address:
git config --global user.name "Frances Totten"

git config --global user.email "frances_t@fabrikam.com"
In Azure DevOps Services, you can update your profile by clicking your picture in the upper right corner and
choosing My profile.
How do I change the author displayed for past commits?

If you've made a single change locally and it has the wrong author, you can amend that commit with new author
information. Be sure to format it like this: Name <email> .
git commit --amend --author="Frances L. Totten <frances_t@fabrikam.com>"
In most other cases, it's best to keep the existing author information. To change an author name or email, you must
create a new commit. When you change a commit, all subsequent commits descended from that commit also must
change.
Git Cross-Platform Compatibility
Azure Repos
The Windows, macOS, and Linux file systems each have limitations and behaviors that are not always supported
by one or more of the other platforms. Since Git is a cross-platform technology, it is possible for a developer on
one platform to make a commit containing files or folders that have incompatible names with another platform's
file system. Protecting your repo from this is important because developers on other platforms may unknowingly
checkout a commit that corrupts their working direction due to unsupported file or paths names.
Azure Repos offers three cross-platform compatibility settings that help protect your repo from people pushing
commits that are incompatible with one or more platforms. The three file system limitations these settings are
related to are:
Case Sensitivity
Restricted File and Folder Names
Path Length Restrictions
Case Sensitivity
The Windows and macOS file systems are case-insensitive (but case-preserving) by default. Most Linux
filesystems are case-sensitive. Git was built originally to be the Linux kernel's version control system, so
unsurprisingly, it's case-sensitive.
While many of the issues with a case-insensitive OS have been addressed in Git for Windows, a few quirks
remain.
File and folder names
On Linux, checking out a Git repo which contains both "File.txt" and "file.txt" is no problem. Those are distinct
filenames. On Windows and macOS, checking out both files will result in the second one overwriting the first one.
If two folders differ only by case, their contents will end up mixed together on case-insensitive filesystems.
Fixing case conflicts
One way to fix a repository with this problem is to check it out in a case-sensitive environment. Rename files and
folders so they no longer conflict, then push those changes to the repository. Windows Subsystem for Linux is one
such environment. Another approach is to use the command git mv -f <conflicting name> <non-conflicting name>
for each conflict, being careful to use exact capitalization on both file names.
Avoiding case conflicts
It's good to avoid creating this situation in the first place. Azure Repos offers a case-enforcement setting to
prevent pushes which would lead to this situation. For developers, adopting the habit of using tab-completion to
commit files will also help. Since both Windows and macOS are case-preserving, this will ensure that Git's
internals see the exact same casing that the filesystem uses.
Branch and tag names
You can create two branches or tags (known as 'refs') that differ only in casing. Git's internals, as well as Azure
DevOps Services/TFS, will treat them as two separate refs. On a user's machine, Git uses the filesystem to store
refs. Fetches and other operations begin to fail because of the ambiguity. Each ref is represented by a small file,
and if a ref name contains / characters, the parts before the final / are represented by folders.
One simple way to avoid issues is to always use all-lowercase branch and tag names. If you have already created
two branches or tags with this problem, you can fix it in the Azure Repos web UI.
Fixing branch names
From the branches page, navigate to the related commit. In the context menu, choose "New branch". Give the
branch a new name that doesn't have a case conflict. Return to the branches page and delete the conflicting
branch.
Fixing tag names
The steps for fixing a tag name are similar to branches. From the tags page, navigate to the tagged commit. In the
context menu, choose "Create tag". Give the tag a new name that doesn't have a case conflict. Return to the tags
page and delete the conflicting tag.
Path and File Name Restrictions

The Windows, Mac OS, and Linux operating systems each have various naming limitations and max path limits.
These restrict what you can name files or folders. This can create problem situations for teams using Git across
multiple platforms.
For example, let's say a developer on one platform commits a change to the shared repository that contains a file
name or path length that is invalid on another platform. Later, another developer attempts to checkout that
commit on a platform where the contents are invalid. This results in a corrupted working directory creating the
potential to damage your repo with corrupted data.
Azure Repos offers file name and max path repository settings that block pushes containing commits that violate
one or more of the below limitations.
File Name & Path Length Reference Table
WINDOWS MACOS LINUX
File Name Restrictions Reserved File Names: CON, Filenames ending in / Filenames ending in /
PRN, AUX, NUL, COM1 -
COM9, LPT1 - LPT9
Reserved File Names

followed by .
Reserved Characters:
\ / : * ? " < >
Filenames ending in . or
whitespace
Path Length Restrictions Paths in Windows have a File names are limited to File names are limited to 255
maximum length of 260 255 characters characters
characters (incl. a null
terminator). Path max in HFS+ are Path max is 4096
documented as unlimited,
For directories with .NET the though some macOS
fully qualified file name must versions cap it at 1016
be less than 260 characters, characters. Some file
and the directory name systems support 1016 as
must be less than 248 max path
characters.
Git preferences and settings in Visual Studio

Visual Studio allows you to configure and view common Git settings and preferences, such as your name and
email address, your preferred diff and merge tools, and more. These preferences and settings can be viewed and
configured in Team Explorer on either the Global Settings page (applies to all your repositories) or the
Repository Settings page (applies to the current repository).
Visual Studio allows you to configure two types of settings:
Git settings - The settings in this section correspond to Git settings that are saved in Git configuration files.
These settings can be viewed and modified in Visual Studio, but are managed by Git configuration files.
Visual Studio settings - The settings in this section configure Git-related settings and preferences that are
managed by Visual Studio.
This article shows you how to configure and view Git settings and preferences in Visual Studio, and where
applicable shows you the Git command line equivalents.
How to configure settings

1. To configure Git settings in Visual Studio, choose Settings from Team Explorer.
2. Choose Global Settings or Repository Settings to view and configure global-level or repository-level
settings.
3. Visual Studio allows you to configure several common Git settings, as described in the following sections of
this article. After configuring your desired settings, select Update to save the updated settings.
Git settings
Visual Studio allows you to configure and check some of the most common Git configuration settings. The
settings in this section can be viewed and modified in Visual Studio, but are managed by Git configuration files.
Name and email
Prune remote branches during fetch
Rebase local branch when pulling
Cryptographic network provider
Ignore & attributes files
Diff & merge Tools
Remotes
Other
NOTE
Git settings configured in Visual Studio's Global Settings correspond to settings in Git's user-specific configuration file, and
the settings in Repository Settings correspond to settings in the repository-specific configuration file. For more information
about Git configuration, see the Pro Git chapter on customizing Git, the git-config documentation, and the Pro Git reference
on configuration files. To configure Git settings not exposed in Visual Studio, use the git config command to write a value
to your configuration files: git config [--local|--global|--system] section.key value .
Name and email

The name and email that you provide will be used as the committer information for any commit you make. This
setting is available at both global and repository scopes, and corresponds to the git config user.email and
user.name settings.
Visual Studio
Command Line
1. In Team Explorer, go to Settings. To set your user name and email at the global level, go to Global
Settings; to set these at the repository level, go to Repository Settings.
2. Provide your user name and email, then choose Update to save.
Note that for Repository Settings, you'll first need to check Override global user name and email
settings.
Prune remote branches during fetch

Pruning removes remote-tracking branches that no longer exist on the remote and helps you keep your branches
list clean and up to date. This setting is available at both global and repository scopes, and corresponds to the
git config fetch.prune setting.
We recommend setting this option to True at the global level. Valid settings are:
True (recommended)
False
Unset (default)
Visual Studio
Command Line
Requires Visual Studio 2017 Update 5 and later.
1. In Team Explorer, go to Settings. Go to Global Settings and set Prune remote branches during fetch
to True (recommended). Select Update to save.
Rebase local branch when pulling

Rebasing sets aside the changes made by commits in the current branch that are not in the upstream branch,
resets the current branch to the upstream branch, then applies the changes that were set aside. This setting is
available at both global and repository scopes, and corresponds to the git config pull.rebase setting. Valid
settings are:
True: Rebase current branch on top of upstream branch after fetch.
False: Merge the current branch into the upstream branch.
Unset (default): Unless specified in other configuration files, merge the current branch into the upstream
branch.
Interactive: Rebase in interactive mode.
Preserve: Rebase without flattening locally created merge commits.
Visual Studio
Command Line
1. In Team Explorer, go to Settings. Go to Global Settings to configure this option at the global level; go to
Repository Settings to configure this option at the repo level.
2. Set Rebase local branch when pulling to the desired setting, and select Update to save.
Note that it is not possible to configure pull.rebase to Interactive in Visual Studio. Visual Studio does not have
interactive rebase support. To configure pull.rebase to use interactive mode, use the command line.
Cryptographic network provider
Cryptographic network provider is a Git configuration setting at global scope that configures which SSL backend
to use at runtime, and corresponds to the git config http.sslBackend setting. The values are:
OpenSSL: Use OpenSSL for TLS and SSL protocols.
Secure Channel: Use Secure Channel (schannel) for TLS and SSL protocols. Schannel is the native Windows
solution, accessing the Windows Credential Store, thereby allowing for enterprise-wide management of
certificates.
Unset (default): If this setting is unset, OpenSSL is the default.
Visual Studio
Command Line
1. In Team Explorer, go to Settings. Go to Global Settings to configure this setting.
2. Set Cryptographic network provider to the desired value, and select Update to save.
Ignore & attributes files

The Ignore & attributes files section is available at repository scope and allows you to view and edit the
gitignore and gitattributes files for your repository.
Diff & merge Tools

Git will show diffs and merge conflicts in your preferred tools. The settings in this section correspond to the
git config diff.tool and merge.tool settings. You can configure Git to use Visual Studio as your merge or diff tool
in Global Settings and Repository Settings by selecting Use Visual Studio. To configure other diff and merge
tools, use git config with the diff.tool or merge.tool switch.
Remotes
The Remotes section allows you to configure the remotes for this repository. This setting corresponds to the git
remote command and is available at the repository scope.
Other
The Other section allows you to view the Git configuration settings for this repository, with the exception of
settings that are displayed and managed in the Visual Studio Git settings pane.
To view all of your Git configuration settings, you can open and view the configuration files themselves, or you can
run git config --list to display the settings.
Visual Studio settings

The following settings manage Git-related preferences in Visual Studio, and are managed by Visual Studio instead
of Git configuration files. All of the settings in this section are configured on the Global Settings page.
Default repository location
Enable download of author images from 3rd party source
Commit changes after merge by default
Enable push --force
Default repository location
Default repository location configures the default folder in which repositories are cloned.
Enable download of author images from 3rd party source

Enable download of author images from 3rd party source is a Visual Studio specific setting at global scope. When
checked, author images are downloaded from the Gravatar image service, if available, and displayed in the commit
and history views.
IMPORTANT
In order to provide author images in the Commit and History views, the tool creates an MD5 hash for the author email
addresses stored in the active repository. This hash is then sent to Gravatar to find a matching hash value for users that
have previously signed up for the service. If a match is found, the user image will be retrieved from the service and displayed
in Visual Studio. Users that have not configured the service will return a randomly generated image. Note, email addresses
are not recorded by Microsoft, nor are they ever shared with Gravatar or any other third party.
Commit changes after merge by default

When Commit changes after merge by default is enabled, Git automatically creates a new commit when a
branch is merged with the current branch.
When checked, git merge commands issued by Visual Studio are run with the --commit option.
When unchecked, git merge commands issued by Visual Studio are run with the --no-commit --no-ff options.
For more information on these options, see --commit and --no-commit and --no-ff.
Enable push --force
Requires Visual Studio 2017 and later.
When enabled, this setting allows you to push --force from within Visual Studio. By default Enable push --force
is disabled.
WARNING
Use push --force with caution as it can overwrite changes that have been pushed to the branch since your last pull. For
more information, see push --force.
Repository settings
Azure Repos
Git repositories can be customized to a great extent on Azure DevOps Services and Team Foundation Server.
Global options for entire repositories are configured by repository settings. There are also user-specific and
branch-specific controls, covered by permissions and branch policies respectively.
This topic covers server-side repository settings. You may also want to learn about client-side Git preferences.
View and edit repository settings

1. From your web browser, open the project for your organization in Azure DevOps and choose Project
settings, Repositories, and select your repository.
2. Select options to view and configure your repository settings.

1. From your web browser, open the project for your organization in Azure DevOps and choose the gear icon,
Version Control, and select your repository.

1. From your web browser, open the project for your organization in Azure DevOps and choose the gear icon,
Version Control, and select your repository.

Forking
Controls whether users are able to create new server-side forks. Disabling this setting will not alter existing forks.
Work item management

There are two settings in this category.
Automatically create links for work items mentioned in a commit comment
When turned on, commit messages containing "#" followed by a valid work item ID will automatically link the
commit to the mentioned work item. You should turn this off when pushing a repository previously contained by a
different account or service. Those repositories may have #mentions that don't match the work item IDs in the
current account. If you import a repository, we automatically turn this option off.
Remember user preferences for completing work items with pull requests
By default, the option to complete linked work items during pull request completion will remember each user's
last choice. Some teams may have different approaches to closing work items, such as at a standup meeting, and
may want to discourage users from completing work items with their pull requests. By disabling this setting, users
must opt-in to completing work items for each pull request.
Cross-platform compatibility settings

NOTE
Our recommendation is to configure these settings either at the project level or each individual repo, but not both. If set at
both levels, we will compute whichever setting is the most restrictive and honor that. Configuring these settings at only one
level removes this complexity prevents slow downs in Git performance.
Case enforcement
Git is case-sensitive, meaning that a file called "Foo.txt" is different from a file called "foo.txt". Windows and
macOS default to case-insensitive file systems, meaning that "Foo.txt" and "foo.txt" are the same name. This can
cause problems for users if someone on a case-insensitive system pushes files, folders, branches, or tags that only
differ by letter case.
If most of your users are on Windows or macOS, we recommend turning on this setting. It will block the
introduction of new files, folders, branches, or tags that would cause such a conflict. The user will have to rewrite
their unpushed history to fix the problem, then try the push again.
This setting will not fix a repository which already contains objects that only differ by case. We recommend fixing
such issues before turning the policy on. You can rename files and folders or re-create branches and tags using
new, non-conflicting names.
Restrict File Names
Not all files names are allowed on the three major OS file systems (Windows, macOS, and Linux). Developers can
push commits to a shared repository that may contain files or folders with names that are invalid on one or more
platforms. If these files or folders are fetched and checked out on a platform where they are invalid then the
working directory can become corrupted.
This setting will block pushes to your repository that contain files or folders names that are invalid on any
platform. See what names are invalid
Restrict Path length
Not all path lengths are allowed on the three major OS file systems (Windows, macOS, and Linux). Developers
can push commits to a shared repository that may contain files or directories with path lengths that are invalid on
one or more platforms. If these files or directories are fetched and checked out on a platform where they are
invalid then the working directory can become corrupted.
This setting will block pushes to your repository that contain files or directories with path names that are invalid
on any platform. See what path lengths are invalid. When enabled, a default value of 248 is selected because
that is the highest max length that is 100% supported across all three major platforms.
The max path value can be modified. For example, if you only have macOS or Linux developers in your
organization, then you may optionally choose to set it to highest value that is 100% supported on both platforms (
1016 ). You may also optionally choose to set a lower max path value if you wish to enforce certain directory &
naming conventions for your organization.
Maximum file size

Large files checked into Git remain in the repository forever, dragging down clone times and increasing disk
usage. We have suggestions for helping you manage large files.
This setting gives administrators a way to block files over a certain size from entering the repository. If a push
contains a new or updated file larger than the limit configured in this setting, that push will be blocked. The user
will have to rewrite their unpushed history to remove the large file and try the push again.
Other ways to manage repositories

For branch-specific settings, you should look at branch policies. These include options like requiring a pull request,
a successful build, or a code review. For user-specific settings, you probably want permissions. Permissions allow
you to control who can read, write, contribute to pull requests, and other specific actions.
Manage and store large files in Git
Git is great at keeping the footprint of your source code small because the differences between versions are easily
picked out and code is easily compressed. Large files that don't compress well and change entirely between
versions (such as binaries) present problems when stored in your Git repos. Git's fast performance comes from its
ability to address and switch to all versions of a file from its local storage.
If you have large, undiffable files in your repo such as binaries, you will keep a full copy of that file in your repo
every time you commit a change to the file. If many versions of these files exist in your repo, they will dramatically
increase the time to checkout, branch, fetch, and clone your code.
What kind of files should you store in Git?

Source code -not dependencies
As your team works with editors and tools to create and update files, you should put these files into Git so your
team can enjoy the benefits of Git's workflow. Don't commit other types of files, such as DLLs, library files, and
other dependencies that aren't created by your team but your code depends on into your repo. Deliver these files
through package management to your systems.
Package management bundles your dependencies and installs the files on your system when you deploy the
package. Packages are versioned to ensure that code tested in one environment runs the same in another
environment as long as they have the same installed packages.
Don't commit outputs
Don't commit the binaries, logs, tracing output or diagnostic data from your builds and tests. These are outputs
from your code, not the source code itself. Share logs and trace information with your team through work item
tracking tools or through team file sharing.
Store small, infrequently updated binary sources in Git
Binary source files that are infrequently updated will have relatively few versions committed, and will not take up
very much space provided that their file size is small. Images for the web, icons, and other smaller art assets can
fall into this category. It's better to store these files in Git with the rest of your source so your team can use
consistent workflow.
IMPORTANT
Even small binaries can cause problems if updated often. One hundred changes to a 100KB binary file uses up as much
storage as 10 changes to a 1MB binary, and due to the frequency of updates to the smaller binary will take slow down
branching performance more often than the large binary.
Don't commit large, frequently updated binary assets

Git will manage one main version of a file and then store only the differences from that version in a process known
as deltification. Deltification and file compression allow Git to store your entire code history in your local repo.
Large binaries usually change entirely between versions and are often already compressed, making these files
difficult for Git to manage since the difference between versions is very large. Git must store the entire contents of
each version of the file and has difficulty saving space through deltification and compression. Storing the full file
versions of these files causes repo size to increase over time, reducing branching performance, increasing the clone
times, and expanding storage requirements.
Strategies for working with large binary source files
Don't commit compressed archives of data. It's better to uncompress the files and commit the diffable sources,
letting Git handle compressing the data in your repo.
Avoid committing compiled code and other binary dependencies. Commit the source and build the
dependencies, or use a package management solution to version and supply these files to your system.
Store configuration and other structured data in diffable plain text formats, such as JSON.
Use Git Large File Storage (LFS)

When you have source files with large differences between versions and frequent updates, you can use Git LFS to
manage these file types. Git LFS is an extension to Git which commits data describing the large files in a commit to
your repo, and stores the binary file contents into separate remote storage. When you clone and switch branches
in your repo, Git LFS downloads the correct version from that remote storage. Your local development tools will
transparently work with the files as if they were committed directly to your repo.
Benefits
The benefit of Git LFS is that your team can use the familiar end to end Git workflow no matter what files your
team creates. LFS files can be as big as you need them to be. Additionally, as of version 2.0, Git LFS supports file
locking to help your team work on large, undiffable assets like videos, sounds, and game maps.
Git LFS is is fully supported and free in Azure DevOps Services. To use LFS with Visual Studio, you need at least
Visual Studio 2015 Update 2. Just follow the instructions to install the client, set up LFS tracking for files on your
local repo, and then push your changes to Azure Repos.
Limitations
Git LFS has some drawbacks that you should consider before adopting:
1. Every Git client used by your team must install the Git LFS client and understand its tracking configuration.
2. If the Git LFS client is not installed and configured correctly, you will not see the binary files committed through
Git LFS when you clone your repo. Git will download the data describing the large file (which is what Git LFS
commits to the repo) and not the actual binary file itself. Committing large binaries without the Git LFS client
installed will push the binary to your repo.
3. Git cannot merge the changes from two different versions of a binary file even if both versions have a common
parent. If two people are working on the same file at the same time, they must work together to reconcile their
changes to avoid overwriting the other's work. Git LFS provides file locking to help. Users must still take care to
always pull the latest copy of a binary asset before beginning work.
4. Azure Repos currently does not support using SSH in repos with Git LFS tracked files.
5. If a user drags and drops a binary file via the web interface into a repo which is configured for Git LFS, the
binary will be committed to the repo and not the pointers that would be committed via the Git LFS client.
File format
The file written into your repo for a Git LFS tracked file will have a few lines with a key and value pair on each line:
version https://git-lfs.github.com/spec/v1
oid a747cfbbef63fc0a3f5ffca332ae486ee7bf77c1d1b9b2de02e261ef97d085fe
size 4923023
NOTE
The GitHub URL included for the version value only defines the LFS pointer file type, and is not a link to your binary file.
Known issues
If you use a version of LFS below 2.4.0 with TFS, there's an extra setup step required to authenticate using NTLM
instead of Kerberos. This step is no longer necessary as of LFS 2.4.0, and we highly recommend you upgrade.
Use SSH key authentication
Connect to your Git repos through SSH on macOS or Linux, or on Windows when you can't (or don't want to)
use the recommended Git Credential Managers or Personal Access Tokens to securely connect using HTTPS
authentication.
IMPORTANT
SSH URLs have changed, but old SSH URLs will continue to work. If you have already set up SSH, you should update your
remote URLs to the new format:
Verify which remotes are using SSH by running git remote -v in your Git client.
Visit your repository on the web and select the Clone button in the upper right.
Select SSH and copy the new SSH URL.
In your Git client, run: git remote set-url <remote name, e.g. origin> <new SSH URL> . Alternatively, in Visual
Studio, go to Repository Settings, and edit your remotes.
NOTE
As of Visual Studio 2017, SSH can be used to connect to Git repos.
How SSH key authentication works

SSH public key authentication works with a pair of generated encryption keys. The public key is shared and used
to encrypt messages. The private key is kept safe and secure on your system and is used to read messages
encrypted with the public key.
Set up SSH key authentication

The following steps cover configuration of SSH key authentication on the following platforms:
Linux
macOS running at least Leopard (10.5)
Windows systems running Git for Windows
Configure SSH using the command line. bash is the common shell on Linux and macOS and the Git for
Windows installation adds a shortcut to Git Bash in the Start menu. Other shell environments will work, but are
not covered in this article.
Step 1: Create your SSH keys
NOTE
If you have already created SSH keys on your system, skip this step and go to configuring SSH keys.
The commands here will let you create new default SSH keys, overwriting existing default keys. Before
continuing, check your ~/.ssh folder (for example, /home/jamal/.ssh or C:\Users\jamal\.ssh) and look for the
following files:
id_rsa
id_rsa.pub
If these files exist, then you have already created SSH keys. You can overwrite the keys with the following
commands, or skip this step and go to configuring SSH keys to reuse these keys.
Create your SSH keys with the ssh-keygen command from the bash prompt. This will create a 2048-bit RSA
key for use with SSH. You can give a passphrase for your private key when prompted—this provides another
layer of security for your private key. If you give a passphrase be sure to configure the SSH agent to cache your
passphrase so you don't have to enter it every time you connect.
$ ssh-keygen -C "jamal@fabrikam.com"
Generating public/private rsa key pair.
Enter file in which to save the key (/c/Users/jamal/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /c/Users/jamal/.ssh/id_rsa.
Your public key has been saved in /c/Users/jamal/.ssh/id_rsa.pub.
The key fingerprint is:
SHA256:******************************************* jamal@fabrikam.com
The key's randomart image is:
+---[RSA 2048]----+
|+. +yX*o . |
|... ..E+*=o |
| ..o.=E=.o |
| . * =.o . |
| . S o o.. |
| + .oo |
| S+. . |
| ..+.+ |
| o*.. |
+----[SHA256]-----+
This produces the two keys needed for SSH authentication: your private key ( id_rsa ) and the public key (
id_rsa.pub ). It is important to never share the contents of your private key. If the private key is compromised,
attackers can use it to trick servers into thinking the connection is coming from you.
Step 2: Add the public key to Azure DevOps Services/TFS
Associate the public key generated in the previous step with your user ID.
1. Open your security settings by browsing to the web portal and selecting your avatar in the upper right of
the user interface. Select Security in the menu that appears.
2. Select SSH Public Keys , then select Add.
3. Copy the contents of the public key (for example, id_rsa.pub) that you generated into the Key Data field.
IMPORTANT
Avoid adding whitespace or new lines into the Key Data field, as they can cause Azure DevOps Services to use an
invalid public key. When pasting in the key, a newline often is added at the end. Be sure to remove this newline if it
occurs.
4. Give the key a useful description (this will be displayed on the SSH public keys page for your profile) so
that you can remember it later. Select Save to store the public key. Once saved, you cannot change the key.
You can delete the key or create a new entry for another key. There are no restrictions on how many keys
you can add to your user profile.
Step 3: Clone the Git repository with SSH
NOTE
To connect with SSH from an existing cloned repo, see updating your remotes to SSH.
1. Copy the SSH clone URL from the web portal. In this example the SSL clone URL is for a repo in an
organization named fabrikam -fiber, as indicated by the first part of the URL after dev.azure.com .
NOTE
2. Run git clone from the command prompt.
git clone git@ssh.dev.azure.com:v3/fabrikam-fiber/FabrikamFiber/FabrikamFiber
SSH may display the server's SSH fingerprint and ask you to verify it.
For cloud-hosted Azure DevOps Services, where clone URLs contain either ssh.dev.azure.com or
vs-ssh.visualstudio.com , the fingerprint should match one of the following:
MD5: 97:70:33:82:fd:29:3a:73:39:af:6a:07:ad:f8:80:49 (RSA)

SHA256: SHA256:ohD8VZEXGWo6Ez8GSEJQ9WpafgLFsOfLOtGGQCQo6Og (RSA) These fingerprints are also listed in the
SSH public keys page.
For self-hosted instances of Azure DevOps Server, you should verify that the displayed fingerprint matches one
of the fingerprints in the SSH public keys page.
SSH displays this fingerprint when it connects to an unknown host to protect you from man-in-the-middle
attacks. Once you accept the host's fingerprint, SSH will not prompt you again unless the fingerprint changes.
$ git clone git@ssh.dev.azure.com:v3/fabrikam-fiber/FabrikamFiber/FabrikamFiber

Cloning into 'FabrikamFiber'...
The authenticity of host 'ssh.dev.azure.com (65.52.8.37)' can't be established.
RSA key fingerprint is SHA256:********************************************
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'ssh.dev.azure.com,65.52.8.37' (RSA) to the list of known hosts.
Enter passphrase for key '/c/Users/jamal/.ssh/id_rsa':
remote:
remote: vSTs
remote: vSTSVSTSv
remote: vSTSVSTSVST
remote: VSTS vSTSVSTSVSTSV
remote: VSTSVS vSTSVSTSV STSVS
remote: VSTSVSTSvsTSVSTSVS TSVST
remote: VS tSVSTSVSTSv STSVS
remote: VS tSVSTSVST SVSTS
remote: VS tSVSTSVSTSVSts VSTSV
remote: VSTSVST SVSTSVSTs VSTSV
remote: VSTSv STSVSTSVSTSVS
remote: VSTSVSTSVST
remote: VSTSVSTs
remote: VSTs (TM)
remote:
remote: Microsoft (R) Visual Studio (R) Team Services
remote:
remote: Found 127 objects to send. (50 ms)
Receiving objects: 100% (127/127), 56.67 KiB | 2.58 MiB/s, done.
Resolving deltas: 100% (15/15), done.
When you are asked if you want to continue connecting, type yes . Git will clone the repo and set up the origin
remote to connect with SSH for future Git commands.
TIP
Avoid trouble: Windows users will need to run a command to have Git reuse their SSH key passphrase.
Questions and Troubleshooting

How can I have Git remember the passphrase for my key on Windows?
Run the following command included in Git for Windows to start up the ssh-agent process in Powershell or the
Windows Command Prompt. ssh-agent will cache your passphrase so you don't have to provide it every time
you connect to your repo.
start-ssh-agent.cmd
If you are using the Bash shell (including Git Bash), start ssh-agent with:
eval `ssh-agent`
I use PuTTY as my SSH client and generated my keys with PuTTYgen. Can I use these keys with Azure DevOps
Services?
Yes. Load the private key with PuTTYgen, go to Conversions menu and select Export OpenSSH key. Save the
private key file and then follow the steps to set up non-default keys. Copy your public key directly from the
PuTTYgen window and paste into the Key Data field in your security settings.
How can I verify that the public key I uploaded is the same key as I have locally?
You can verify the fingerprint of the public key uploaded with the one displayed in your profile through the
following ssh-keygen command run against your public key using the bash command line. You will need to
change the path and the public key filename if you are not using the defaults.
ssh-keygen -l -E md5 -f ~/.ssh/id_rsa.pub
You can then compare the MD5 signature to the one in your profile. This is useful if you have connection
problems or have concerns about incorrectly pasting in the public key into the Key Data field when adding the
key to Azure DevOps Services.
How can I start using SSH in a repository where I am currently using HTTPS?
You'll need to update the origin remote in Git to change over from a HTTPS to SSH URL. Once you have the
SSH clone URL, run the following command:
git remote set-url origin git@ssh.dev.azure.com:v3/fabrikam-fiber/FabrikamFiber/FabrikamFiber
You can now run any Git command that connects to origin .
I'm using Git LFS with Azure DevOps Services and I get errors when pulling files tracked by Git LFS.
Azure DevOps Services currently doesn't support LFS over SSH. Use HTTPS to connect to repos with Git LFS
tracked files.
How can I use a non default key location, i.e. not ~/.ssh/id_rsa and ~/.ssh/id_rsa.pub?
To use keys created with ssh-keygen in a different place than the default, you do two things:
1. The keys must be in a folder that only you can read or edit. If the folder has wider permissions, SSH will not
use the keys.
2. You must let SSH know the location of the keys. You make SSH aware of keys through the ssh-add
command, providing the full path to the private key.
ssh-add /home/jamal/.ssh/id_jamal.rsa
On Windows, before running ssh-add , you will need to run the following command from included in Git for
Windows:
start-ssh-agent.cmd
This command runs in both Powershell and the Command Prompt. If you are using Git Bash, the command you
need to use is:
eval `ssh-agent`
You can find ssh-add as part of the Git for Windows distribution and also run it in any shell environment on
Windows.
On macOS and Linux you also must have ssh-agent running before running ssh-add , but the command
environment on these platforms usually takes care of starting ssh-agent for you.
I have multiple SSH keys. How do I use different SSH keys for different SSH servers or repos?
Generally, if you configure multiple keys for an SSH client and connect to an SSH server, the client can try the
keys one at a time until the server accepts one.
However, this doesn't work with Azure DevOps for technical reasons related to the SSH protocol and how our
Git SSH URLs are structured. Azure DevOps will blindly accept the first key that the client provides during
authentication. If that key is invalid for the requested repo, the request will fail with the following error:
remote: Public key authentication failed.

fatal: Could not read from remote repository.
For Azure DevOps, you'll need to configure SSH to explicitly use a specific key file. One way to do this to edit
your ~/.ssh/config file (for example, /home/jamal/.ssh or C:\Users\jamal\.ssh ) as follows:
# The settings in each Host section are applied to any Git SSH remote URL with a matching hostname.
# Generally:
# * SSH uses the first matching line for each parameter name, e.g. if there's multiple values for a
# parameter across multiple matching Host sections
# * "IdentitiesOnly yes" prevents keys cached in ssh-agent from being tried before the IdentityFile
# values we explicitly set.
# * On Windows, ~/.ssh/your_public_key maps to %USERPROFILE%\.ssh\your_public_key, e.g.
# C:\Users\<username>\.ssh\your_public_key.
# To use the same key across all hosted Azure DevOps organizations, where the SSH URL host is
# ssh.dev.azure.com (like git@ssh.dev.azure.com:v3/some_organization/some_project/some_repo), add
# the Host section below:
Host ssh.dev.azure.com
IdentityFile ~/.ssh/your_public_key
IdentitiesOnly yes
# Since all hosted Azure DevOps URLs have the same hostname (ssh.dev.azure.com), if you need
# different keys for different organizations (or just different repos within the same organization),
# you'll need to use host aliases to create separate Host sections.
#
# Imagine that we have the following two SSH URLs:
# * git@ssh.dev.azure.com:v3/org1/org1_project/org1_repo
# * For this, we want to use key1, so we'll use devops_key1 as the Host alias.
# * git@ssh.dev.azure.com:v3/org2/org2_project/org2_repo
# * For this, we want to use key2, so we'll use devops_key2 as the Host alias.
#
# You'll need to substitute ssh.dev.azure.com with the Host alias in the SSH URL you use with Git.
# The SSH URLs above become:
# * git@devops_key1:v3/org1/org1_project/org1_repo
# * git@devops_key2:v3/org2/org2_project/org2_repo
#
# To set explicit keys for the two host aliases and to tell SSH to use the correct actual hostname,
# add the next two Host sections:
Host devops_key1
HostName ssh.dev.azure.com
IdentityFile ~/.ssh/public_key_for_org1
IdentitiesOnly yes
Host devops_key2
HostName ssh.dev.azure.com
IdentityFile ~/.ssh/public_key_for_org2
IdentitiesOnly yes
# If you have an SSH URL where the hostname is vs-ssh.visualstudio.com, from when Azure DevOps was
# formerly called Visual Studio Team Services, add the following Host section.
# Alternately, you can just replace the hostname in your SSH URL with ssh.dev.azure.com. Both
# ssh.dev.azure.com and vs-ssh.visualstudio.com point to the same place.
Host vs-ssh.visualstudio.com
IdentitiesOnly yes
# If you have an on-premises Azure DevOps Server instance, where SSH URLs look like
# ssh://someHost:22/someCollection/some_project/_git/some_repo, add the following Host section:
Host someHost
IdentitiesOnly yes
# Put global defaults here. Note that "*" also matches any hosts that match the sections above, and
# remember that SSH uses the first matching line for each parameter name.
Host *
What notifications may I receive regarding my SSH keys?

Whenever you register a new SSH Key with Azure DevOps Services, you will receive an email notification
informing you that a new SSH key has been added to your account.
Q: What do I do if I believe that someone other than me is adding SSH keys on my account?
A: If you receive a notification of an SSH key being registered and you did not manually upload it to the service,
your credentials may have been compromised.
The next step would be to investigate whether or not your password has been compromised; changing your
password is always a good first step to defend against this attack vector. If you’re an Azure Active Directory user,
talk with your administrator to check if your account was used from an unknown source/location.
Use Git Credential Managers to Authenticate to
Azure Repos
Git Credential Managers simplify authentication with your Azure DevOps Services/TFS Git repos. Credential
Managers let you use the same credentials that you use for the Azure DevOps Services/TFS web portal and
support multi-factor authentication through Microsoft Account (MSA) or Azure Active Directory (Azure AD ). In
addition to supporting multi-factor authentication with Azure DevOps Services, the credential managers also
provide support two-factor authentication with GitHub repositories.
Azure DevOps Services provides IDE support for MSA and Azure AD authentication through Team Explorer in
Visual Studio, IntelliJ and Android Studio with the Azure Repos Plugin for IntelliJ, and Eclipse (with the Team
Explorer Everywhere plug-in). If your environment doesn't have an integration available, configure your IDE with
a Personal Access Token or SSH to connect with your to your repos.
Install the Git Credential Manager

Windows
Download and run the latest Git for Windows installer, which includes the Git Credential Manager for Windows.
Make sure to leave the Git Credential Manager installation option enabled when prompted.
macOS and Linux

We recomend using SSH keys to authenticate to Azure DevOps, not a credential manager.
Review the system and software requirements before installing the credential manager.
On macOS and Linux, there are several install options that use native package managers to install the credential
manager. After installing the package for your platform, run the following command to configure Git to use the
credential manager :
> git-credential-manager install

Using the Git Credential Manager
When you connect to a Git repo in Azure Repos from your Git client for the first time, the credential manager
prompts for your Microsoft Account or Azure Active Directory credentials. If your account has multi-factor
authentication enabled, you are prompted to go through that experience as well.
Once authenticated, the credential manager creates and caches a personal access token for future connections to
the repo. Git commands that connect to this account won't prompt for user credentials until the token expires or
is revoked through Azure DevOps Services/TFS.
Getting help
You can open up and report issues with the Git Credential Manager for Windows on the project GitHub.
Frequently Asked Questions for the Git Credential Manager for Windows are available in the online readme.
Manual installation steps for the Windows Git Credential Manager and the macOS and Linux Git Credential
Manager are available. Use these steps to install the credential manager if the recommended steps above are not
suitable for your environment.
Learn more
In addition to providing full source code, we've also documented how the credential manager integrates with Git.
Refer to the MSDN blog posts on the macOS and Linux Git Credential Manager and the Windows Credential
Manager. There is also an article on the project GitHub with information on the low -level internals of the Git
Credential Manager for Windows.
Create a pull request status server with Node.js

The pull request (PR ) workflow provides developers with an opportunity to get feedback on their code from peers
as well as from automated tools. 3rd party tools and services can participate in the PR workflow by using the PR
Status API. This article guides you through the process of creating a status server to validate PRs in an Azure
DevOps Services Git repository. For more information about PR status, see Customize and extend pull request
workflows with pull request status.
Prerequisites
An organization in Azure DevOps with a Git repo. If you don't have an organization, sign up to upload and
share code in free unlimited private Git repositories.
Install VS Code or other code editor of your choice. The instructions in this guide use VS Code but the steps in
other code editors are similar.
Install Node.js
To install Node.js, download the LTS release appropriate for your platform. The download contains an installer,
which you can run to install the Node.js runtime on your local machine. When installing Node.js, be sure to keep
the npm package manager portion of the install, which is selected by default.
Create a basic web server using Express

The steps in this section use Express, which is a lightweight web framework for Node.js that provides a number of
HTTP utility methods that simplify creating a web server. This framework provides you with the basic functions
needed to listen to PR events.
1. From the command line, create a new project folder for your web server.
mkdir pr-server
cd pr-server
2. Use the npm init command to create a new package.json file for the project.
npm init
Press Enter to accept the defaults for all of the options except the entry point. Change it to app.js
entry point: (index.js) app.js
3. Install Express in the pr-server directory using the following command. This installs Express and saves it to
the dependencies list.
npm install express
4. Create a simple Express app to build upon for the PR status server. The following steps are based on the
Express Hello world example. Open the project folder in VS Code by running the following command from
the pr-server folder.
code .
5. Create a new file (Ctrl + N) and paste in the following sample code.
const express = require('express')

const app = express()
app.get('/', function (req, res) {

res.send('Hello World!')
})
app.listen(3000, function () {
console.log('Example app listening on port 3000!')
})
6. Save the file as app.js .

7. Run the basic web server using the following command:
node app.js
Verify the server is running by browsing to http://localhost:3000/ .
Listen for HTTP POST requests

The web server is going to receive POST requests from Azure DevOps Services, so you need to handle those
requests in your server.
1. At the end of the app.js file, add the following code, and save the file.
app.post('/', function (req, res) {

res.send('Received the POST')
})
2. Re-run your web server using the following command:
node app.js
Configure a service hook for PR events

Service hooks are an Azure DevOps Services feature that can alert external services when certain events occur.
For this sample, you'll want to set up two service hooks for PR events, so the status server can be notified. The
first will be for the Pull request created event and the second will be for the Pull request updated event.
In order to receive the service hook notifications, you'll need to expose a port to the public internet. The ngrok
utility is very useful for doing this in a development environment.
1. Download and unzip the appropriate ngrok release for your platform.
2. Use ngrok to start listening on the same port as your sample server - port 3000. Run the following
command in a new command window.
ngrok http 3000
Ngrok will create a public URL that forwards to localhost:3000 . Note that URL as you will need it in the
next step. It will look something like this:
http://c3c1bffa.ngrok.io
3. Browse to your project in Azure DevOps, e.g. https://dev.azure.com/<your account>/<your project name>
4. From the navigation menu, hover over the gear and select Service Hooks.
5. If this is your first service hook, select + Create subscription.
If you already have other service hooks configured, select the green plus (+) to create a new service hook
subscription.
6. On the New Service Hooks Subscription dialog, select Web Hooks from the list of services, then select
Next.
7. Select Pull request created from the list of event triggers, then select Next.
8. In the Action page, enter the URL from ngrok in the URL box. Select Test to send a test event to your
server.
In the ngrok console window, you'll see an incoming POST that returned a 200 OK , indicating your server
received the service hook event.
HTTP Requests
-------------
POST / 200 OK
In the Test Notification window, select the Response tab to see the details of the response from your server.
You should see a content length of 17 that matches the length of the string from your POST handler (i.e.
"Received the POST").
9. Close the Test Notification window, and select Finish to create the service hook.
Go through steps 3-9 again but this time configure the Pull request updated event.
IMPORTANT
Be sure to go through the preceding steps twice and create service hooks for both the Pull request created and Pull
request updated events.
Post status to PRs

Now that your server can receive service hook events when new PRs are created, update it to post back status to
the PR.
1. Service hook requests include a JSON payload describing the event. To help parse the JSON returned by
the service hook, install the body-parser package.
npm install body-parser
2. Update app.js to use body-parser for parsing application/json .

var bodyParser = require('body-parser')
app.use(bodyParser.json());
3. To simplify making REST API calls to Azure Repos, install the azure-devops-node-api package.
npm install azure-devops-node-api
4. Update app.js to use the azure-devops-node-api package, set up the details for a connection to your
account, and get an instance of the Git API.
const vsts = require("azure-devops-node-api");
const collectionURL = process.env.COLLECTIONURL;

const token = process.env.TOKEN;
var authHandler = vsts.getPersonalAccessTokenHandler(token);

var connection = new vsts.WebApi(collectionURL, authHandler);
var vstsGit = connection.getGitApi().then( success => { console.log(success); }, error => {

console.log(error); } );
5. Create an environment variable for your collection URL, replacing <your account> with the name of your
Azure DevOps organization.
setx COLLECTIONURL "https://dev.azure.com/<your account>"
6. Create a personal auth token (PAT) for your app to use, following these instructions: Authenticating with
personal access tokens. You should create a new PAT for every service that you use to access your account,
naming it appropriately.
7. Create an environment variable for your PAT.
setx TOKEN "yourtokengoeshere"
8. Update the post() function to read the PR details from the service hook payload. You'll need these values
in order to post back status.
var repoId = req.body.resource.repository.id;

var pullRequestId = req.body.resource.pullRequestId;
var title = req.body.resource.title;
9. Build the status object to post on the PR.

State is an enum of type GitStatusState. Use succeeded to indicate that the PR has passed the status
check and is ready to merge.
The description is a string value that will be displayed to the user in the Status section and activity feed in
the PR details view.
The targetUrl is a URL that will be used to create a link for the description text in the Status section and
activity feed. This is the place where users can go to get more information about the status, for example, a
build report or test run. If no URL is specified, the description will appear as text with no link.
The context name and genre are used to categorize the status and distinguish it from other services
posting status.
var prStatus = {
"description": "Ready for review",
"targetUrl": "http://visualstudio.microsoft.com",
"context": {
"name": "wip-checker",
}
}
10. Instead of just blindly posting the succeeded status, inspect the PR title to see if the user has indicated if the
PR is a work in progress by adding WIP to the title. If so, change the status posted back to the PR.
if (title.includes("WIP")) {
prStatus.state = "pending";
prStatus.description = "Work in progress"
}
11. Finally, post the status using the createPullRequestStatus() method. It requires the status object, the repo
ID, and the pull request ID. Output the response to the node console so you can see the result of the post.
vstsGit.createPullRequestStatus(prStatus, repoId, pullRequestId).then( result => {

console.log(result);
});
12. The resulting method should look something like this:

app.post("/", function (req, res) {
// Get the details about the PR from the service hook payload
var repoId = req.body.resource.repository.id;
var pullRequestId = req.body.resource.pullRequestId;
var title = req.body.resource.title;
// Build the status object that we want to post.

// Assume that the PR is ready for review...
var prStatus = {
"description": "Ready for review",
"targetUrl": "http://visualstudio.microsoft.com",
"context": {
"name": "wip-checker",
}
}
// Check the title to see if there is "WIP" in the title.

if (title.includes("WIP")) {
// If so, change the status to pending and change the description.

prStatus.state = "pending";
prStatus.description = "Work in progress"
}
// Post the status to the PR

vstsGit.createPullRequestStatus(prStatus, repoId, pullRequestId).then( result => {
console.log(result);
});
res.send("Received the POST");

})
13. Save app.js and restart your node app.
node app.js
Create a new PR to test the status server

Now that your server is running and listening for service hook notifications, create a pull request to test it out.
1. Start in the files view. Edit the readme.md file in your repo (or any other file if you don't have a readme.md).
2. Make an edit and commit the changes to the repo.

3. Be sure to commit the changes to a new branch so you can create a PR in the next step.
4. Select the Create a pull request link.
5. Add WIP in the title to test the functionality of the app. Select Create to create the PR.
6. Once the PR has been created, you will see the status section, with the Work in progress entry which links
to the URL specified in the payload.
7. Update the PR title and remove the WIP text and note that the status changes from Work in progress to
Ready for review.
Next Steps
In this article, you learned the basics of how to create a service that listens for PR events via service hooks and
can post status messages using the status API. For more information about the pull request status API see the
REST API documentation.
Configure a branch policy for an external service.

The pull request (PR ) workflow provides developers with an opportunity to get feedback on their code from peers
as well as from automated tools. 3rd party tools and services can participate in the PR workflow by using the PR
Status API. This article guides you through the process of creating a custom branch policy using Azure Functions
to validate PRs in an Azure DevOps Services Git repository. With Azure Functions you don't have to worry about
provisioning and maintaining servers, especially when your workload grows. Azure Functions provide a fully
managed compute platform with high reliability and security.
For more information about PR status, see Customize and extend pull request workflows with pull request status.
Prerequisites
An organization in Azure DevOps with a Git repo. If you don't have an organization, sign up to upload and share
code in free unlimited private Git repositories.
Create a basic Azure function to listen to Azure Repos events

Follow the create your first Azure function documentation to create a simple function. Modify the code in the
sample to look like this:
using System;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using Newtonsoft.Json;
public static async Task<HttpResponseMessage> Run(HttpRequestMessage req, TraceWriter log)

{
try
{
log.Info("Service Hook Received.");
// Get request body

dynamic data = await req.Content.ReadAsAsync<object>();
log.Info("Data Received: " + data.ToString());
// Get the pull request object from the service hooks payload
dynamic jObject = JsonConvert.DeserializeObject(data.ToString());
// Get the pull request id

int pullRequestId;
if (!Int32.TryParse(jObject.resource.pullRequestId.ToString(), out pullRequestId))
{
log.Info("Failed to parse the pull request id from the service hooks payload.");
};
// Get the pull request title

string pullRequestTitle = jObject.resource.title;
log.Info("Service Hook Received for PR: " + pullRequestId + " " + pullRequestTitle);
return req.CreateResponse(HttpStatusCode.OK);
}
catch (Exception ex)
{
log.Info(ex.ToString());
return req.CreateResponse(HttpStatusCode.InternalServerError);
}
}
Configure a service hook for PR events

Service hooks are an Azure DevOps Services feature that can alert external services when certain events occur.
For this sample, you'll want to set up a service hook for PR events, your Azure function will be notified when a pull
request changes. In order to receive POST requests when pull requests change, you will need to provide the
service hook with the Azure function URL.
For this sample you will need to configure 2 service hooks. The first will be for the Pull request created event
and the second will be for the Pull request updated event.
1. Get the function URL from the Azure portal by clicking the Get function URL in your Azure function view
and copy the URL.
2. Browse to your project in Azure DevOps, e.g. https://dev.azure.com/<your account>/<your project name>
3. From the navigation menu, hover over the gear and select Service Hooks.
4. If this is your first service hook, select + Create subscription.

If you already have other service hooks configured, select the green plus (+) to create a new service hook
subscription.
5. On the New Service Hooks Subscription dialog, select Web Hooks from the list of services, then select
Next.
6. Select Pull request created from the list of event triggers, then select Next.
7. In the Action page, enter the URL that you copied in step 1 in the URL box. Select Test to send a test event
to your server.
In the Azure function log window, you'll see an incoming POST that returned a 200 OK , indicating your
function received the service hook event.
HTTP Requests
-------------
POST / 200 OK
In the Test Notification window, select the Response tab to see the details of the response from your server.
You should see the response from your server.
8. Close the Test Notification window, and select Finish to create the service hook.
Go through steps 2-8 again but this time configure the Pull request updated event.
IMPORTANT
Be sure to go through the preceding steps twice and create service hooks for both the Pull request created and Pull
request updated events.
Create a pull request to verify your Azure function is receiving notifications.
Post status to PRs

Now that your server can receive service hook events when new PRs are created, update it to post back status to
the PR. You can use the JSON payload posted by the service hook in order to determine what status to set on
your PR.
Update the code of your Azure function to look like the following example.
Make sure to update the code with your account name, project name, repository name and PAT token. In order to
have permission to change PR status, the PAT requires vso.code_status scope, which you can grant by selecting the
Code (status) scope on the Create a personal access token page.
IMPORTANT
This sample code stores the PAT in code to simplify the sample. It is recommended to store secrets in KeyVault and retrieve
them from there.
This sample inspects the PR title to see if the user has indicated if the PR is a work in progress by adding WIP to
the title. If so, the sample code changes the status posted back to the PR. Replace the code in your Azure function
with the following code to implement updating the status posted back to the PR.
using System;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using Newtonsoft.Json;
private static string accountName = "[Account Name]"; // Account name

private static string projectName = "[Project Name]"; // Project name
private static string repositoryName = "[Repo Name]"; // Repository name
/*
This is here just to simplify the sample, it is recommended to store
secrets in KeyVault and retrieve them from there.
*/
private static string pat = "[PAT TOKEN]";
public static async Task<HttpResponseMessage> Run(HttpRequestMessage req, TraceWriter log)

{
try
{
log.Info("Service Hook Received.");
// Get request body

dynamic data = await req.Content.ReadAsAsync<object>();
log.Info("Data Received: " + data.ToString());
// Get the pull request object from the service hooks payload
dynamic jObject = JsonConvert.DeserializeObject(data.ToString());
// Get the pull request id

int pullRequestId;
if (!Int32.TryParse(jObject.resource.pullRequestId.ToString(), out pullRequestId))
{
log.Info("Failed to parse the pull request id from the service hooks payload.");
};
// Get the pull request title

string pullRequestTitle = jObject.resource.title;
log.Info("Service Hook Received for PR: " + pullRequestId + " " + pullRequestTitle);
PostStatusOnPullRequest(pullRequestId, ComputeStatus(pullRequestTitle));
return req.CreateResponse(HttpStatusCode.OK);
}
catch (Exception ex)
{
log.Info(ex.ToString());
return req.CreateResponse(HttpStatusCode.InternalServerError);
}
}
private static void PostStatusOnPullRequest(int pullRequestId, string status)

{
string Url = string.Format(
@"https://dev.azure.com/{0}/{1}/_apis/git/repositories/{2}/pullrequests/{3}/statuses?api-version=4.1-
preview.1",
accountName,
projectName,
repositoryName,
pullRequestId);
using (HttpClient client = new HttpClient())

{
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic",
Convert.ToBase64String(
ASCIIEncoding.ASCII.GetBytes(
ASCIIEncoding.ASCII.GetBytes(
string.Format("{0}:{1}", "", pat))));
var method = new HttpMethod("POST");

var request = new HttpRequestMessage(method, Url)
{
Content = new StringContent(status, Encoding.UTF8, "application/json")
};
using (HttpResponseMessage response = client.SendAsync(request).Result)

{
response.EnsureSuccessStatusCode();
}
}
}
private static string ComputeStatus(string pullRequestTitle)

{
string state = "succeeded";
string description = "Ready for review";
if (pullRequestTitle.ToLower().Contains("wip"))
{
state = "pending";
description = "Work in progress";
}
return JsonConvert.SerializeObject(
new
{
State = state,
Description = description,
TargetUrl = "http://visualstudio.microsoft.com",
Context = new
{
Name = "PullRequest-WIT-App",
Genre = "pr-azure-function-ci"
}
});
}
Create a new PR to test the status server

Now that your server is running and listening for service hook notifications, create a pull request to test it out.
1. Start in the files view. Edit the readme.md file in your repo (or any other file if you don't have a readme.md).
2. Make an edit and commit the changes to the repo.

3. Be sure to commit the changes to a new branch so you can create a PR in the next step.
4. Select the Create a pull request link.
5. Add WIP in the title to test the functionality of the app. Select Create to create the PR.
6. Once the PR has been created, you will see the status section, with the Work in progress entry which links
to the URL specified in the payload.
7. Update the PR title and remove the WIP text and note that the status changes from Work in progress to
Ready for review.
Next Steps
In this article, you learned the basics of how to create a serverless Azure function that listens for PR events via
service hooks and can post status messages using the status API. For more information about the pull request
status API see the REST API documentation.
Configure a branch policy for an external service.

Branch policies are a powerful feature to ensure high quality code in your repo by establishing requirements for
all pull requests. External services can use the PR Status API to post detailed status to your PRs. The branch policy
for external services brings the ability for those 3rd party services to participate in the PR workflow and establish
policy requirements. This article guides you through the process of configuring a branch policy for a service that
is posting PR status. For more information about PR status, see Customize and extend pull request workflows
with pull request status.
Prerequisites
An organization in Azure DevOps with a Git repo. If you don't have an organization, sign up to upload and
share code in free unlimited private Git repositories.
A service that posts status to PRs. See Create a pull request status server.
Configure the branch policy

1. Navigate to Code > Branches and find the branch that you want to configure the policy on (typically
master or develop ). From the context menu, select the Branch policies option.
2. Scroll down to find the policy to Require approval from external services. Select Add status policy.
3. Select the service you want to create a policy for from the list. If the status has been posted previously you
can pick it from the list; if it is a new policy you can type in the name of the policy.
Policy requirement determines whether or not this policy is optional or required to complete pull
requests into the branch.
Authorized account is used to enforce that status from only the specified account will be counted
towards the policy fulfillment.
Reset conditions is used to determine when a posted status is no longer valid. If the status posted is
specific to the latest code (i.e. a build), check Reset status whenever there are new changes to reset
the status when the source branch changes.
Policy applicability determines whether this policy applies as soon as a pull request is created, or
whether the policy applies only after the first status is posted to the pull request.
Default display name allows you to specify an optional display name for your policy.
Create a new pull request

1. Create a new pull request into the branch where the policy is defined. For more information, see Create a
pull request.
2. After creating the PR, the new policy will appear in the Policies section of the PR details view. Initially, the
policy will appear as not set until the external service has posted status.
When the service has posted status, the policy will update accordingly. Completion will be blocked until the
policy approves the PR.
When the policy criteria are met, and the service posts a succeeded status, the PR will be approved and
completion will be unblocked.
Summary
In this article, you learned how to configure a branch policy for an external service.
Build multiple branches
Azure Pipelines | Azure DevOps Server 2019 | TFS 2018 | TFS 2017
NOTE
In Microsoft Team Foundation Server (TFS) 2018 and previous versions, build and release pipelines are called definitions,
service connections are called service endpoints, stages are called environments, and jobs are called phases.
You can build every commit and pull request to your Git repository using Azure Pipelines or TFS. In this tutorial,
we will discuss additional considerations when building multiple branches in your Git repository. You will learn
how to:
Set up a CI trigger for topic branches
Automatically build a change in topic branch
Exclude or include tasks for builds based on the branch being built
Keep code quality high by building pull requests
Use retention policies to clean up completed builds
Prerequisites
You need a Git repository in Azure Pipelines, TFS, or GitHub with your app. If you do not have one, we
recommend importing the sample .NET Core app into your Azure Pipelines or TFS project, or forking it into
your GitHub repository. Note that you must use Azure Pipelines to build a GitHub repository. You cannot
use TFS.
You also need a working build for your repository.
Set up a CI trigger for a topic branch

A common workflow with Git is to create temporary branches from your master branch. These branches are called
topic or feature branches and help you isolate your work. In this workflow, you create a branch for a particular
feature or bug fix. Eventually, you merge the code back to the master branch and delete the topic branch.
YAML
Classic
Unless you specify a trigger in your YAML file, a change in any of the branches will trigger a build. Add the
following snippet to your YAML file in the master branch. This will cause any changes to master and feature/*
branches to be automatically built.
trigger:
- master
- feature/*
YAML builds are not yet available on TFS.

You're now ready for CI for both the master branch and future feature branches that match the branch pattern.
Every code change for the branch will use an automated build pipeline to ensure the quality of your code remains
high.
Follow the steps below to edit a file and create a new topic branch.
1. Navigate to your code in Azure Repos, TFS, or GitHub.
2. Create a new branch for your code that starts with feature/ , e.g., feature/feature-123 .
3. Make a change to your code in the feature branch and commit the change.
4. Navigate to the Pipelines menu in Azure Pipelines or TFS and select Builds.
5. Select the build pipeline for this repo. You should now see a new build executing for the topic branch. This build
was initiated by the trigger you created earlier. Wait for the build to finish.
Your typical development process includes developing code locally and periodically pushing to your remote topic
branch. Each push you make results in a build pipeline executing in the background. The build pipeline helps you
catch errors earlier and helps you to maintain a quality topic branch that can be safely merged to master. Practicing
CI for your topic branches helps to minimize risk when merging back to master.
The master branch typically produces deployable artifacts such as binaries. You do not need to spend time creating
and storing those artifacts for short-lived feature branches. You implement custom conditions in Azure Pipelines or
TFS so that certain tasks only execute on your master branch during a build run. You can use a single build with
multiple branches and skip or perform certain tasks based on conditions.
YAML
Classic
Edit the azure-pipelines.yml file in your master branch, locate a task in your YAML file, and add a condition to it.
For example, the following snippet adds a condition to publish artifacts task.
- task: PublishBuildArtifacts@1
condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/master'))
Validate pull requests

Use policies to protect your branches by requiring successful builds before merging pull requests. You have options
to always require a new successful build before merging changes to important branches such as the master branch.
There are other branch policy settings to build less frequently. You can also require a certain number of code
reviewers to help ensure your pull requests are high quality and don't result in broken builds for your branches.
GitHub repository
YAML
Classic
Unless you specify pr triggers in your YAML file, pull request builds are automatically enabled for all branches.
You can specify the target branches for your pull request builds. For example, to run the build only for pull requests
that target: master and feature/* :
pr:
- master
- feature/*
For more details, see Triggers.

Azure Pipelines or TFS repository
1. Navigate to the Code hub in Azure Repos or TFS.
2. Choose your repository and Select Branches. Choose the master branch.
3. You will implement a branch policy to protect the master branch. Select the ellipsis to the right of your branch
name and Select Branch policies.
4. Choose the checkbox for Protect this branch. There are several options for protecting the branch.
5. Under the Build validation menu choose Add build policy.
6. Choose the appropriate build pipeline.
7. Ensure Trigger is set to automatic and the Policy requirement is set to required.
8. Enter a descriptive Display name to describe the policy.
9. Select Save to create and enable the policy. Select Save changes at the top left of your screen.
10. To test the policy navigate to the Pull request menu in Azure Pipelines or TFS.
11. Select New pull request. Ensure your topic branch is set to merge into your master branch. Select create.
12. Your screen displays the policy being executed.
13. Select the policy name to examine the build. If the build succeeds your code will be merged to master. If the
build fails the merge is blocked.
Once the work is completed in the topic branch and merged to master, you can delete your topic branch. You can
then create additional feature or bug fix branches as necessary.
Use retention policies to clean up your completed builds

Retention policies allow you to control and automate the cleanup of your various builds. For shorter-lived branches
like topic branches, you may want to retain less history to reduce clutter and storage costs. If you create CI builds
on multiple related branches, it will become less important to keep builds for all of your branches.
1. Navigate to the Pipelines menu in Azure Pipelines or TFS.
2. Locate the build pipeline that you set up for your repo.
3. Select Edit at the top right of your screen.
4. Under the build pipeline name, Select the Retention tab. Select Add to add a new retention policy.
5. Type feature/* in the Branch specification dropdown. This ensures any feature branches matching the
wildcard will use the policy.
6. Set Days to keep to 1 and Minimum to keep to 1.
7. Select the Save & queue menu and then Select Save.
Policies are evaluated in order, applying the first matching policy to each build. The default rule at the bottom
matches all builds. The retention policy will clean up build resources each day. You retain at least one build at all
times. You can also choose to keep any particular build for an indefinite amount of time.
Next steps
In this tutorial, you learned how to manage CI for multiple branches in your Git repositories using Azure Pipelines
or TFS.
You learned how to:
Set up a CI trigger for topic branches
Keep code quality high by building pull requests
Use retention policies to clean up completed builds
Drive Git development from a work item
Azure DevOps Services | Azure DevOps Server 2019 | TFS 2018 | TFS 2017
One of the ways your team can drive their development and stay in sync is to link your work items to the objects
created during development, such as branches, commits, pull requests, and builds. You can begin that linking by
creating a branch from one or more work items. Later, you can create pull requests, quickly open commits, and
maintain a record of development operations performed to complete specific work.
IMPORTANT
This article addresses creating new branches and adding links to commits and pull requests to a Git repository hosted on
Azure DevOps. To link to GitHub commits and pull requests, see Link GitHub commits and pull requests to work items.
The Development section records all Git development processes that support completion of the work item. This
section can show your team information needed to take the next development step and minimize navigational
steps to accomplish common development tasks. It also supports traceability, providing visibility into all the
branches, commits, pull requests, and builds related to the work item.
NOTE
The Development section within the work item form is not supported in TFS 2015 and earlier versions. Consider upgrading
to a later TFS version.
From it, you can quickly access branches, pull requests, and commits which are linked to the work item. Also, you
can initiate a pull request for a branch you've created or linked to from the work item.
Prerequisites
You must connect to a project. If you don't have a project yet, create one.
You must be added to a project as a member of the Contributors or Project Administrators security group.
To get added, Add users to a project or team.
To add or modify work items, you must be granted Stakeholder access or higher. For details, see About access
levels.
To view or modify work items, you must have your View work items in this node and Edit work items in
this node permissions set to Allow. By default, the Contributors group has this permission set. To learn more,
see Set permissions and access for work tracking.
To create new tags to add to work items, you must have Basic access or higher and have the project-level
Create new tag definition permissions set to Allow. By default, the Contributors group has this permission
set. Even if the permission is explicitly set for a Stakeholder, they won't have permission to add new tags, as
they are prohibited through their access level.
You must connect to a project. If you don't have a project yet, create one.
You must be added to a project as a member of the Contributors or Project Administrators security group.
To get added, Add users to a project or team.
To add or modify work items, you must be granted Stakeholder access or higher. For details, see About access
levels.
To view or modify work items, you must have your View work items in this node and Edit work items in
this node permissions set to Allow. By default, the Contributors group has this permission set. To learn more,
see Set permissions and access for work tracking.
To create new tags to add to work items, you must have Basic access or higher and have the project-level
Create new tag definition permissions set to Allow. By default, the Contributors group has this permission
set. Even if the permission is explicitly set for a Stakeholder, they won't have permission to add new tags, as
they are prohibited through their access level.
Workflow process to create a branch and pull request

Consider creating a new branch when there are no linked code artifacts. If there is a branch but no pull requests,
consider creating a pull request. Here's a typical workflow sequence when working with a Git repository.
1. Start work on the work item by creating a branch. You can add a new Git branch from within the
Development section...
... or, from the form's Actions menu.
Name the branch and select the repository on which it's based.
Branches you create are automatically linked to the work item.
NOTE
You can only create a branch once you've added files to the main branch, which is always named master . The
system automatically adds a README file to the initial repo created with each new project.
2. The system will open to the repository and branch that you just created.
You can edit a file within the web portal.
Or, if you have extensive file edits or need to add files, then you'll need to work from Visual Studio or other
supported IDE. You'll want to add a new local branch from the branch you just created. For details, see
Update code with fetch and pull, Download changes with fetch. (While any code editing and committing
process will work, we work best with an edition of Visual Studio.)
3. Add or modify files in the branch that you created.
From Visual Studio or other supported IDE, commit and push changes from your local branch to the
repository.
If this is the first time pushing changes from a new branch, you'll need to publish the branch before pushing
your changes. For more details, see Share code with push.
4. Create a pull request from the work item form.
You create a pull request to merge the changes you made to a master branch and get your changes
reviewed by other members of your team.
5. Your view will switch to Code, Pull Requests page. Complete creating the pull request as shown.
NOTE
Once you've created a pull request, you can't create a new pull request for the same branch until you complete the
previous pull request.
Check the box for Squash changes when merging and then complete the merge.
6. Upon completion, you should see a similar screen as follows.
7. Open the work item form or refresh the form, expand the Development section (click the icon), and
you'll see the links that have been added to support the operations you just completed.
Create a branch for several work items

You can also add a new branch from the work item listed on the backlog or Kanban board without having to open
the work item. Using multi-select, you can select several work items and create a new branch where they're all
linked to the branch.
For example, here we select the first five items to link to a new branch.
And, we specify the name of the branch.
Link to existing development and build objects
All items listed under the Development section also appear under the Links tab. All development actions
initiated from the Development section are also logged under the History tab.
To link a work item to an existing object, click the Add links icon and then choose the link type.
Linking, traceability, and managing dependencies.

Remove a link
If you want to remove a link, you can do so from the Development section by highlighting it first and then click the
delete icon.
Or, you can select it from the Links tab and click the remove link icon.
Related articles
Learn more about tracking work with work items and developing with Git from these resources:
Add work items
Git overview
Link GitHub commits and pull requests to work items
TFVC overview
Create your backlog
Add work items
Git overview
TFVC overview
Create your backlog
Keep in mind that the Development section only appears within the web portal work item form. The work item
tracking experience and forms that appear in Visual Studio or other supported clients will be missing several of the
features that the web portal makes available.
Associated work items in build
With Git commits, any work items that have been linked to a commit will be listed under the Associated work items
in the build summary page.
Link types showing in the Development section

Links shown in this section appear as a result of these actions:
Creating a branch, commit, or pull request from the work item
Specifying the work item ID during a commit, pull request, or other supported Git or TFVC operation
Specifically linking the work item from the Development section or Links tab to a source code branch, build,
or other supported Git or TFVC operation.
Hovering over any entry listed under the Development section activates the hyperlink to the associated object.
The link types you can add within the development section are Branch, Build, Changeset, Commit, Found in build,
Integrated in build, Pull Request, and Versioned Item.
The link types you can add within the development section are Branch, Build, Changeset, Commit, Pull Request,
and Versioned Item.
To learn more about the links control or to customize the Development links control, see LinksControlOptions
elements, Development links control.
Go get command support in Azure Repos Git
Azure Repos
Go is an open-source programming language, also referred to as Golang. In Go, you can use the get command to
download and install packages and dependencies. Azure Repos Git provides support for go get within an Azure
Repos Git repository. With go get , you will be able to download packages with their dependencies named by the
import paths. You can also use the import key word inside a go file to specify the import path, using the same
syntax described in the following sections.
Go get with public projects

If your Azure Repos Git repo is in a public project you can use go get using the web repo url in the following
format, and Azure Repos returns the appropriate meta tags so that go get knows the type and location of the repo
to retrieve it.
go get dev.azure.com/<organization>/_git/<repo>
You can also import/get a Go package in a subfolder of a repo by appending the subfolder names, as shown in the
following examples.
go get dev.azure.com/<organization>/_git/<repo>/subfolder1
go get dev.azure.com/<organization>/_git/<repo>/subfolder1/subfolder2
Go get with private projects

If your Azure Repos Git repo is in a private project, you need to create a Personal Access Token (PAT) as described
in Authenticate access with personal access tokens. This PAT requires only the Code (read) scope. After you create
the PAT, add an entry to your .gitconfig as shown in the following example.
[url "https://<user>:<token>@dev.azure.com/<organization>/_git/<repo>"]
insteadOf = https://dev.azure.com/<organization>/_git/<repo>
After this entry is made into your .gitconfig , you can use go get in the following format. Note the .git that
follows the repo name.
go get dev.azure.com/<organization>/_git/<repo>.git
You can also import/get a Go package in a subfolder of a repo by appending the subfolder names, as shown in the
following examples.
go get dev.azure.com/<organization>/_git/<repo>.git/subfolder1
go get dev.azure.com/<organization>/_git/<repo>.git/subfolder1/subfolder2
Import repositories from TFVC to Git
Azure Repos | Azure DevOps Server 2019 | TFS 2018 | TFS 2017 Update 2
You can migrate code from an existing TFVC repository to a new Git repository within the same organization.
While migrating to Git has many benefits, it is an involved process for large TFVC repositories and teams.
Centralized version control systems, like TFVC, behave different than Git in fundamental ways. The switch involves
a lot more than learning new commands. It is a disruptive change that requires careful planning. You need to think
about:
Revising tools and processes
Removing binaries and executables
Training your team
We strongly recommend reading our whitepapers - Centralized version control to Git and TFVC to Git before
starting the migration.
The import experience is great for small simple TFVC repositories. It's also good for repositories that have already
been "cleaned up" as outlined in the previous whitepapers. Those whitepapers also recommend other tools for
more advanced TFVC repository configurations.
Importing the repository

1. Select Repos, Files.

3. Select TFVC from the Source type dropdown
4. Type the path to the repository / branch / folder that you want to import to the Git repository. For example,
$/Fabrikam/FabrikamWebsite
5. If you want to migrate history from the TFVC repository, click Migrate history and select the number of
days. You can migrate up to 180 days of history starting from the most recent changeset. A link to the TFVC
repository is added in the commit message of the 1st changeset that is migrated to Git. This makes it easy to
find older history when needed.
6. Give a name to the new Git repository and click Import. Depending on the size of the import, your Git
repository would be ready in a few minutes.
IMPORTANT
Due to the differences in how TFVC and Git store version control history, we recommend that you don't migrate your history.
This is the approach that Microsoft took when it migrated Windows and other products from centralized version control to
Git.

1. Select TFVC from the Source type dropdown
2. Type the path to the repository / branch / folder that you want to import to the Git repository. For example,
$/Fabrikam/FabrikamWebsite
3. If you want to migrate history from the TFVC repository, click Migrate history and select the number of
days. You can migrate up to 180 days of history starting from the most recent changeset. A link to the TFVC
repository is added in the commit message of the 1st changeset that is migrated to Git. This makes it easy to
find older history when needed.
4. Give a name to the new Git repository and click Import. Depending on the size of the import, your Git
repository would be ready in a few minutes.
IMPORTANT
Due to the differences in how TFVC and Git store version control history, we recommend that you don't migrate your history.
This is the approach that Microsoft took when it migrated Windows and other products from centralized version control to
Git.
Troubleshooting
This experience is optimized for small, simple TFVC repositories or repositories that have been prepared for a
migration. This means it has a few limitations.
1. It only migrates the contents of root or a branch. For example, if you have a TFVC project at $/Fabrikam which
has 1 branch and 1 folder under it, a path to import $/Fabrikam would import the folder while
$/Fabrikam/<branch> would only import the branch.
2. The imported repository and associated history (if imported) cannot exceed 1GB in size.
3. You can import up to 180 days of history.
If any of the above is a blocker for your import, we recommend you try external tools like Git-TFS for importing
and reading our whitepapers - Centralized version control to Git and TFVC to Git
Manage branches
Manage the work in your team's Git repo from the Branches view on the web. Customize the view to track the
branches you care most about so you can stay on top of changes made by your team.
View your repo's branches by selecting Repos, Branches while viewing your repo on the web.
View your repo's branches by selecting Branches while viewing your repo on the web.
Organize your branches

The default Mine tab on the branches page shows branches you've created, pushed changes to, or set as a
favorite, along with the default branch for the repo, such as master . The All tab lists all branches in the repo, and
the Stale tab lists branches in the repo that haven't had any commits in three months or longer.
If you don't see the branch you're looking for and you think it might have been deleted, see Restore a deleted
branch.
Filter the listed branches in any of the branch views by entering a specific name or pattern in the Search all
branches box in the upper right.
If your team uses a forward slash separator in your branch names, you'll see a collapsible tree view for those
branches.
TIP
Using a naming convention for your branches is highly recommended. For suggestions on how to name your branches, see
Adopt a Git branching strategy.
Add favorite branches

Add branches from the All view to the Mine view by selecting the star icon to favorite the branch. Mark multiple
branches as favorites by selecting the star icon on the tree view next to a folder on the tree. Remove favorites by
toggling the star off or by selecting the ... to the right of the star to open the branch context menu, then selecting
Remove from my favorites.
Review updates to your branches
Each branch name has the name of the last contributor to the branch and a link to the latest commit on the branch.
Select the date or time of the last commit to review the updates to the branch. The branch view also shows the
number of commits the branch is ahead of and behind the branch labeled Compare. Use this information to
quickly check how far a branch has diverged from another.
If the branch has a pull request open, you can see its pull request ID. Select the pull request to open it up so you
can review the details.
Change the compare branch

The ahead and behind numbers listed for each branch are in comparison with the branch currently labeled
Compare on the Branches page. Update your compare branch to see how far ahead or behind your branches
shown on the page are to another branch in your repo:
1. Select the ... next to the branch you want to set as the baseline for comparison.
2. Select Set as compare branch.
The Compare label will move to this branch and the other branches on the page will have the number of commits
ahead/behind updated to reflect the new comparison.
View branch history

Review the files in a branch or history by selecting the ... icon next to the branch name and choosing View files or
View history. View files opens up the Files view on the web so you can browse the files based on the most
recent commit on the branch. View history shows each commit in the branch history. Select a commit from this
history to see the file changes made in that commit.
Change your default branch
NOTE
This step requires Edit Policies permissions on your Git repo.
Configure your Git repo to use a different default branch to merge code into when your team creates new pull
requests. This is useful when you want to use a branch other than master for new changes or need to change
your main line of development in your repo.
1. Navigate to your project and select Project settings.
2. Scroll down and select Repositories from the Code section.
3. Select the desired repository and expand the branches.
4. Select the ... beside the desired branch and choose Set as default branch.
2. Select Version Control.

3. Select your Git repository. Your branches are displayed under your repo.
4. Select the ... next to the branch you want to set as default, then select Set as default branch.
Create a new Git branch
TIP
Need help creating a new Git branch in your local repo from Visual Studio or the command line? Visit the Git tutorial.
IMPORTANT
Users of TFS 2015 and previous will not have the Branches tab in the Code view. When using those versions, you can create
a new branch in TFS from the Code view by selecting the drop-down next to the branch name and then selecting New
branch.
Create a new branch from the web

1. View your repo's branches by selecting Repos, Branches while viewing your repo on the web.
2. Select the New branch button in the upper right corner of the page.
3. In the Create a branch dialog, enter a name for your new branch, select a branch to base the work off of,
and associate any work items.
4. Select Create branch.
1. View your repo's branches by selecting Branches while viewing your repo on the web.
2. Select the New branch button in the upper right corner of the page.
3. In the Create a branch dialog, enter a name for your new branch, select a branch to base the work off of,
and associate any work items.
4. Select Create branch.
TIP
You will need to fetch the branch before you can see it and swap to it in your local repo.
Delete a Git branch from the web portal
IMPORTANT
This topic covers deleting a Git branch via the web in Azure DevOps Services and TFS. If you need to delete a Git branch in
your own repo from Visual Studio or the command line, follow these steps in the Azure Repos Git tutorial.
1. Open your repo on the web and select the Branches view.
2. Locate your branch on the branches page. If you don't see it, select All to view all branches and filter the
branches using the Search all branches box in the upper right.
3. Select the trashcan icon next to the branch you want to delete.
Restore a deleted Git branch from the web portal
IMPORTANT
This topic covers restoring a deleted Git branch via the web in Azure Repos and TFS 2018. If you need to restore a Git
branch in your own repo from Visual Studio or the command line, push your branch from your local repo to Azure Repos to
restore it.
2. Search for the exact branch name using the Search all branches box in the upper right.
3. Click the link to Search for exact match in deleted branches. If there is a deleted branch that matches
your search, you will be able to see which commit it pointed to when it was deleted, who deleted it, and
when it was deleted.
4. To restore the branch, select the ... icon next to the branch name and then select Restore branch from the
menu. The branch will be recreated at the last commit to which it pointed. Note that branch policies and
permissions will not be restored.
If you've re-used the same branch name for different commits, you may not see all the commits you're expecting
when you restore the deleted branch. In that case, navigate to the Pushes page of the restored branch to see the
entire history of the branch.
You can navigate to a specific commit, then select New branch from the ... icon. From there, you can use a pull
request, cherry-pick, or merge to get the commits back into the desired branch.
You can navigate to a specific commit, then select New branch from the ... icon. From there, you can use a pull
request, cherry-pick, or merge to get the commits back into the desired branch.
Require branches to be created in folders

When you have many people collaborating in a repository, the number and names of branches can quickly get out
of control. Hierarchical branch folders is an effective way to tame the chaos. Azure DevOps Services, TFS, and
Visual Studio treat / as a folder separator and will automatically collapse folders by default. This way, you don't
have to wade through every single branch to find the one you're looking for. You don't have to rely on everyone to
get it right, either. Azure Repos and TFS can enforce the correct use of branch folders.
Planning
Decide on the folder structure you want to allow. As an example, we'll set our repository to enforce the following
rules:
Only master can exist at the repository root.
All users will be allowed to create branches under the features/ and users/ folders.
Administrators will be able to create branches under the releases/ folder.
NOTE
For more examples and information about branch naming strategies, see Adopt a Git branching strategy.
Preparation
You will need the Team Foundation version control command ( tf.exe ) on your computer. Run a Visual Studio
Developer Command Prompt (in Windows, choose Start, choose Visual Studio, then choose the Developer
Command Prompt).
You will need the URL of your account or collection, the name of the project, and the name of the repository.
For this example, we'll use https://fabrikam-fiber.visualstudio.com , FabrikamProject , and FabrikamRepo .
Enforce permissions
Run the following commands in the Developer Command Prompt. Each command is preceded with an
explanation of what it's doing. If you don't have a personal access token cached (for example by signing in to the
Azure DevOps Services web portal) you'll be prompted to login.
First, block the Create Branch permission at the repository root for the project's contributors.
tf git permission /deny:CreateBranch /group:[FabrikamProject]\Contributors

/collection:https://dev.azure.com/fabrikam-fiber/ /teamproject:FabrikamProject /repository:FabrikamRepo
Then, allow contributors to create branches under features and users .

tf git permission /allow:CreateBranch /group:[FabrikamProject]\Contributors
/branch:features
tf git permission /allow:CreateBranch /group:[FabrikamProject]\Contributors

/branch:users
Allow administrators to create branches under releases .
tf git permission /allow:CreateBranch /group:"[FabrikamProject]\Project Administrators"

/branch:releases
Finally, allow administrators to create a branch called master (in case it ever gets deleted accidentally.
tf git permission /allow:CreateBranch /group:"[FabrikamProject]\Project Administrators"

/branch:master
NOTE
For more information, see tf git permission. You can also access help for these commands from the command line by running
tf git /? and tf git permission /? .
Rename old branches

Browser
Command Line
2. Locate your existing branch. If you don't see it, you may need to look on the All tab.
3. Choose its context menu (the ... button) and choose New branch.
4. Type the new name of the branch, for example users/frank/readme-fix. Choose Create branch.
5. Choose the red trashcan icon next to the old branch name to delete it.
NOTE
Any custom permissions or branch policies you had set up will not be migrated.
Lock a branch
Prevent updates to a Git branch by locking the branch. Locking a branch prevents other users from changing the
existing commit history. Locking also blocks any new commits from being added to the branch by others.
Locking limitations
Locking is ideal for preventing new changes that might conflict with an important merge or to place a branch into
a read-only state. Use branch policies and pull requests instead of locking if you just want to ensure that changes
in a branch are reviewed before they are merged.
Locking does not prevent cloning of a repo or fetching updates made in the branch into your local repo. Share with
your team the reason for the locking of the branch and make sure your team knows what to do to work with the
branch after it is unlocked.
Only the user who locked the branch or a user with Remove Others' Locks permissions for the branch can
remove the lock.
Lock a branch using the Branches view

2. Locate your branch on the Branches view. You can search for your branch using the Search all branches
box in the upper right.
3. Lock the branch by selecting the ... icon next to the branch name and then selecting Lock from the menu. A
lock icon will appear next to the branch name. Unlock a locked branch by selecting Unlock from the same
menu.
Improve code quality with branch policies
Branch policies help teams protect their important branches of development. Policies enforce your team's code
quality and change management standards.
Configure branch policies

1. Open the Branches page by navigating to your project in the web portal and selecting Repos,
Branches.
If you're not using the new navigation preview, select Code, Branches.
2. Locate your branch in the page. You can browse the list or you can search for your branch using the
Search all branches box in the upper right.
3. Open the context menu for the branch by selecting the ... icon. Select Branch policies from the context
menu.
4. Configure your desired policies in the Policies page. See the following sections in this article for
descriptions for each policy type. Once your policies are configured, select Save changes to apply your
new policy configuration.
Require a minimum number of reviewers
Code reviews are a best practice for most software development projects. To require teams to review their
changes before completing a pull request, check Require a minimum number of reviewers.
The basic policy requires that a certain number of reviewers approve the code with no rejections.
If Allow users to approve their own changes is not selected, the creator of the pull request can still vote
Approve on their pull request, but their vote won't count toward the Require a minimum number of
reviewers policy.
If any reviewer rejects the changes, the pull request cannot be completed unless the Allow completion
even if some reviewers vote "Waiting" or "Reject" is selected.
To reset code reviewer votes when new changes are pushed to the source branch, check Reset code
reviewer votes when there are new changes.
When the required number of reviewers approve the pull request, it can be completed.
NOTE
The Allow users to approve their own changes setting only applies to the Require a minimum number of
reviewers policy, and doesn't affect other policies such as Automatically include code reviewers. For example, Jamal
Hartnett creates a pull request with the following policies configured:
Require a minimum number of reviewers is configured with two required reviewers.
Allow users to approve their own changes is not set.
The Fabrikam Team group is a required reviewer, and Jamal is a member of that group.
In this example, since Jamal is part of the Fabrikam Team group, his Approve vote satisfies the required reviewer
policy, but the pull request still requires two additional Approve votes to satisfy the Require a minimum number of
reviewers policy, since his vote doesn't count toward that policy because Allow users to approve their own changes
is not set.
Check for linked work items

Require associations between pull requests and a work item to ensure that changes to your branch have work
item management tracking. Linking work items provides additional context for your changes and ensures that
updates go through your work item tracking process.
Check for comment resolution
Configure a comment resolution policy for your branch by selecting Check for comment resolution.
For more information on working with pull request comments, see Pull requests - leave comments.
Enforce a merge strategy

Maintain a consistent branch history by enforcing a merge strategy when a pull request is completed. Select
Enforce a merge strategy and pick an option to require that pull requests merge using that strategy.
No fast-forward merge - This merges the commit history of the source branch when the pull request
closes and creates a merge commit in the target branch.
Squash merge - Complete all pull requests with a squash merge, creating a single commit in the target
branch with the changes from the source branch. Learn more about squash merging and how it affects your
branch history.
Build validation
Set a policy requiring changes in a pull request to build successfully with the protected branch before the pull
request can be completed. Even if you're using continuous integration (CI) on your development branches to
catch problems early, build policies reduce build breaks and keep your tests results passing.
When a build validation policy is enabled, a new build is queued when a new pull request is created or when
changes are pushed to an existing pull request targeting this branch. The build policy then evaluates the results
of the build to determine whether the pull request can be completed.
IMPORTANT
Before specifying a build validation policy, you must have a build definition. If you don't have one, see Create a build
definition and choose the type of build that matches your project type.
Choose Add build policy and configure the desired options in the Add build policy window.
Select the build definition from the Build definition drop-down.

Choose the type of Trigger - either Automatic (whenever the source branch is updated) or Manual.
Configure the Policy requirement. If set to Required, builds must complete successfully in order to
complete pull requests. Choose Optional to provide a notification of the build failure but still allow pull
requests to complete.
Set a build expiration to make sure that updates to your protected branch don't break changes in open pull
requests.
Immediately when branch name is updated: This option sets the build policy status in a pull
request to failed when the protected branch is updated. You must requeue a build to refresh the build
status. This setting ensures that the changes in pull requests build successfully even as the protected
branch changes. This option is best for teams that have important branches with a lower volume of
changes. Teams working in busy development branches may find it disruptive to wait for a build to
complete every time the protected branch is updated.
After n hours if branch name has been updated: This option expires the current policy status
when the protected branch updates if the passing build is older than the threshold entered. This
option is a compromise between always requiring a build when the protected branch updates and
never requiring one. This choice is excellent for reducing the number of builds when your protected
branch has frequent updates.
Never: Updates to the protected branch do not change the policy status. This reduces the number of
builds for your branch, but can cause problems when closing pull requests that haven't been updated
recently.
Choose an optional Display name for this build policy which is used to identify the policy on the Branch
policies page. If you don't specify a display name, the build definition name is used.
When the owner pushes changes that build successfully, the policy status is updated. If you have an
Immediately when branch name is updated or After n hours if branch name has been updated build
policy chosen, the policy status updates when the protected branch is updated if the most recent build is no
longer valid.
Require approval from external services

External services can use the PR Status API to post detailed status to your PRs. The branch policy for external
services brings the ability for those 3rd party services to participate in the PR workflow and establish policy
requirements.
For instructions on configuring this policy, see Configure a branch policy for an external service.
Automatically include code reviewers

Designate reviewers for specific directories and files in your repo.
These reviewers are automatically added to pull requests that change files along those paths.
If you select Required next to a path entry, then the pull request cannot be completed until:
Every user added as a reviewer for the path approves the changes.
At least one person in every group added to the path approves the changes.
Select Optional if you want to add reviewers automatically, but not require their approval to complete the pull
request.
When the required reviewers approve the code, you can complete the pull request.
Bypass branch policies

NOTE
There are several permissions that allow users to bypass branch policy. In TFS 2015 through TFS 2018 Update 2, the
Exempt from policy enforcement permission allows users with this permission to perform the following actions:
When completing a pull request, opt-in to override policies and complete a pull request even if the current set of
branch policies is not satisfied.
Push directly to a branch even if that branch has branch policies set. Note that when a user with this permission
makes a push that would override branch policy, the push automatically bypasses branch policy with no opt-in step
or warning.
In Azure DevOps Services, the Exempt from policy enforcement permission is removed and its functionality divided
into the following two new permissions:
Bypass policies when completing pull requests
Bypass policies when pushing
Users that previously had Exempt from policy enforcement enabled now have the two new permissions enabled
instead.
In some cases, you need to bypass policy requirements so you can push changes to the branch directly or
complete a pull request even if branch policies are not satisfied. For these situations, grant the desired
permission from the previous list to a user or group. You can scope this permission to an entire project, a repo,
or a single branch. Manage this permission along the with other Git permissions.
IMPORTANT
Use caution when granting these permissions, especially at the repo and project level.
Q&A
Can I push changes directly to a branch after a branch policy is configured?
What is auto-complete?
When are the conditions set in branch policies checked?
Can I use XAML build definitions in branch policies?
What type of wildcard characters are supported when configuring required code reviewers?
Are the required code reviewer paths case-sensitive?
How can I configure multiple users as required reviewers, but only require that one of them approve?
I have the exempt from policy permission set, why am I still seeing policy failures in the pull request status?
Where can I get more information on advanced policy configurations?
Can I push changes directly to a branch after a branch policy is configured?
No. After you set up a required branch policy, you cannot directly push changes to the branch. Changes to the
branch are only made through pull requests.
NOTE
If you have permissions that allow you to bypass branch policies you can push directly to a branch after a required
branch policy is configured.
If you configured optional branch policies, but no required branch policies, you can push changes directly to a branch.
What is auto-complete?
When a pull request is made into a branch with branch policies configured, the Set auto-complete button is
enabled for the pull request. If you don't expect any problems with your changes and you want your pull
request to complete once all policies are met, you can set the pull request to automatically complete.
When are the conditions set in branch policies checked?
Branch policies are re-evaluated on the server as changes are pushed and reviewers vote. If there is a build
triggered by the policy, the build status is set to waiting until the build completes.
Can I use XAML build definitions in branch policies?
You cannot use XAML build definitions in branch policies.
What type of wildcard characters are supported when configuring required code reviewers?
Single asterisks ( * ) are supported, and will match any number of characters, including both forward-slashes (
/ ) and back-slashes ( \ ). Question marks ( ? ) will match any single character.
Examples:
*.sql will match all files with the .sql extension
/ConsoleApplication/* will match all files under the folder named ConsoleApplication
/.gitattributes will match the .gitattributes file in the root of the repo
*/.gitignore will match any .gitignore file in the repo
Are the required code reviewer paths case-sensitive?

No, branch policies are not case-sensitive at this time.
How can I configure multiple users as required reviewers, but only require that one of them approve?
You can add the users to a group, and then add the group as a reviewer. Any member of the group can then
approve on behalf of the group to meet the policy requirement.
I have the exempt from policy permission set, why am I still seeing policy failures in the pull request status?
Even for users that are exempt from policy enforcement, the configured policies are still evaluated when
changes are added to a pull request. For exempt users, policy status is advisory only and will not block
completion of the pull request.
Where can I get more information on advanced policy configurations?
Check out the REST API documentation for more details.
Set branch permissions
Overview
Set up permissions to control who can read and update the code in a branch on your Git repo. You can set
permissions for individual users and groups, and inherit and override permissions as needed from your repo
permissions.
Use the branches view to configure security

1. Open the Branches page by navigating to your project in the web portal and selecting Repos, Branches.
If you're not using the new navigation preview, select Code, Branches.
2. Locate your branch in the page. You can browse the list or you can search for your branch using the
Search all branches box in the upper right.
3. Open the context menu by selecting the ... icon next to the branch name. Select Branch security from the
menu.
Add users or groups

Avoid trouble: You can only add permissions for users and groups already in your Project. Add new users and
groups to your Project before setting branch permissions.
Add users or groups to your branch permissions by selecting Add Enter the sign-in address or group alias, then
select Save Changes.
Remove users or groups

Remove permissions for a user or group by selecting the user or Azure DevOps group, then selecting Remove.
The user or group will still exist in your Project and this change will not affect other permissions for the user or
group.
Set permissions
Control branch permission settings from the branch permission view. Users and groups with permissions set at
the repo level will inherit those permissions by default.
NOTE
These permissions have changed in TFS 2017 Update 1 and Azure DevOps Services. Ensure you are viewing the correct
version of this documentation for permissions by choosing your product version in the upper left corner of the window.
Permissions in TFS 2017 Update 1 through TFS 2018 Update 2

PERMISSION DESCRIPTION
Contribute Users with this permission can push new commits to the
branch and lock the branch.
Edit Policies Can edit branch policies.

Exempt from policy enforcement Users with this permission are exempt from the branch policy
set for the branch when completing pull requests and can
override the policies by checking Override branch policies
and enable merge when completing a PR. Users with this
permission can also push to a branch that has branch policies
enabled.
Force Push (Rewrite History and Delete Branches) Can force push to a branch, which can rewrite history. This
permission is also required to delete a branch.
Manage Permissions Can set permissions for the branch.
Remove Others' Locks Can remove locks set on branches by other users.
Permissions in TFS 2017 and lower

Administer Users with this permission can set branch permissions for
other users, delete the branch, and lock the branch.
branch. Users with this permission cannot rewrite the existing
commits on the branch. Users with this permission can lock
the branch.
Exempt from policy enforcement Users with this permission are exempt from the branch policy
set for the branch.
Rewrite and destroy history (force push) Can force push to a branch. This permission is also required
to delete a branch. Users with this permission can modify the
commit history of a branch.
Permissions in Azure DevOps Services
NOTE
In Azure DevOps Services, the Exempt from policy enforcement permission (which is still available in TFS 2015 through
TFS 2018 Update 2) was removed and its functionality divided into the following two new permissions:
Bypass policies when completing pull requests
Bypass policies when pushing
Users that previously had Exempt from policy enforcement enabled now have the two new permissions enabled instead.
See the following table for more details on these two new permissions.
branch and lock the branch.
Edit Policies Can edit branch policies.

Bypass policies when completing pull requests Users with this permission are exempt from the branch policy
set for the branch when completing pull requests and can
opt-in to override the policies by checking Override branch
policies and enable merge when completing a PR.
Bypass policies when pushing Users with this permission can push to a branch that has
branch policies enabled. Note that when a user with this
permission makes a push that would override branch policy,
the push automatically bypasses branch policy with no opt-in
step or warning.
Force Push (Rewrite History and Delete Branches) Can force push to a branch, which can rewrite history. This
permission is also required to delete a branch.
Manage Permissions Can set permissions for the branch.
Remove Others' Locks Can remove locks set on branches by other users.
Learn to map your familiar Team Foundation Version
Control (TFVC) commands and workflows to Git
Do you plan to adopt Git, are familiar with TFVC actions, and wondering how they map to Git? Both are powerful
and mature source control systems. However, mapping common actions you have grown accustomed to in the one
to the other can be a confusing experience.
This article will not delve deep into the Git commands, as they are well documented in the product documentation,
but show examples to help you make the right decisions, while moving through a typical create -> clone -> branch
-> change -> commit -> push workflow.
Start at the beginning by creating a new repo

Each Project can host TFVC and Git repositories in the same project, creating one TFVC, and one or more Git
repositories.
Once the repo is created, you are presented with step-by-step instructions to quickly get started.
Click on the `Create a ReadMe file' at the end of the instruction page, to give the repo context and to create some
history.
Create a workspace and get latest

When connecting to a TFVC repo for the first time, you typically create a workspace and get the latest code. so, how
do you get started in Git?
Similar to a workspace in TFVC you clone the Git repository to a folder on your machine. Cloning will download
all of the contents and history of the repository, to your local machine. Once you have the cloned repo, nearly all
operations are performed locally. You are able to work offline with a full backup of the centralized repository.
Command Line
Visual Studio
git clone https://dev.azure.com/demo-fabrikam/Fabrikam/_git/Mapping-TFVC-actions-to-Git
You only need to clone once per repo, but like TFVC workspaces, you can have multiple clones to isolate in-
progress work. However, branching is typically a better way to isolate changes.
Create a branch
With Git, you are always working in a branch and by default in the "master" branch. You are recommended to
create multiple local branches. It's a process that takes seconds and allows you to seamlessly context switch
between branches and work in isolation. Unlike TFVC branches, which are paths scoped, Git branches are
repository scoped. They are lightweight, can be local only, or shared with others when you are ready to share your
changes.
Consider branching if you need to work in isolation, need to suspend your work, focus on new features, or if you
are planning to conduct a Git pull request.
As a TFVC user, repeat a few times:
Branching is recommended!
Git branching is inexpensive, fast, and powerful!
Git encourages you to use local branches.
Publish local branches to your centralized repository as needed.
Always verify your branch context before making changes.
Name the branch using a common convention such as users/alias/branchname for example:
users/doris/newfeature
Create and switch to a local topic branch, named francis/demo -feature. It is good practice to run a git status first,
to verify that you are on the right branch to start with.
Command Line
Visual Studio
git checkout -b francis/demo-feature

Make a change by adding files
Similar to the TFVC experience, new files in the working folder are not automatically part of the repository. You
stage your new files with the git add command, which is synonymous to performing an add Items to Folder
operation in TFVC.
Here's a sample project to try adding files to your repo.
Command Line
Visual Studio
git add <file>
or
git add --all
Using the pre-baked sample, you will have 13 new files that have been included and staged in the local repository.
View pending changes

Wondering what changes are now sitting in your working environment? As before, the Git status command or the
Changes view in the Visual Studio IDE will show changes in your working tree.
Command Line
Visual Studio
git status
Checkin changes and commit locally
In TFVC, you share your changes with a Check In, which sends your pending changes to the server. The Git process
is a bit different. First, you commit to the local repository, creating a commit object (like a changeset), then you push
to send those changes with the server.
You commit the changes to your local repository using git commit , which feels like doing a
Checkin Pending Changes in TFVC. A key difference is that the git commit commits your changes to the local, not
the remote repository.
Command Line
Visual Studio
git commit
Check in changes with the server/remote repo

First you need to publish your local francis/demo-feature branch to the remote server, which includes all committed
changes.
Command Line
Visual Studio
git push --set-upstream origin francis/demo-feature
To synchronize further updates in your local with the remote repository, you need to push your changes using
git push . The recommended practice using the git command or the Visual Studio IDE is to:
fetch to download content and preview incoming changes from others.

pull to download and then merge changes from others.
push to share your local changes.
View history
To see the commit, you just created you can review the local history.
Command Line
Visual Studio
For a compact history, use:
git log --oneline
For a detailed, view, use:
git log
As shown above, git log lists the author, email, date written, and the commit SHA-1 checksum. As a TFVC user
you may want to use the --stat option to include more information, such as file name and change statistics.
You can also view the history of the centralized repository using the Azure DevOps Services web portal.
In the Azure DevOps Services web portal, choose CODE > History or CODE > Explorer > History
At this point, you have successfully explored the create -> clone -> branch -> change -> commit -> push workflow,
based on common TFVC actions.
You also have the option of issuing a pull request, to publish and stage your changes on the server/remote repo at
this point.
Other actions
Switch branches
When working with Git, you do not change branches by switching to separate folders and locations on your
machine. You change the context by doing a checkout , making the entire working directory match the selected
branch or commit. Fast and simple!
Command line
git checkout <branch>
If you forgot what branches you have in your local repository, use git branch to list the default and known
branches.
Keep in mind which branch you are working on! When you work with multiple branches in Git, you switch branches
in place in the same working directory. Switching between branches is a fast operation, and making sure you are on
the right branch at all times is good practice.
Get latest version
There are lots of reasons to want to get updates. For example, when you need to switch context to another project,
refresh your development machine with the latest version of the codebase.
Command line
git pull
or
git fetch
followed by
git merge FETCH_HEAD
Always get the latest version and resolve merge conflicts locally.
Undo local changes
There may be a valid reason to revert all revisions you made in your local repository and reset your working
environment to the latest version from the remote repository.
Command line
git reset --hard HEAD
followed by
git pull origin
followed by
git clean -xdf
The scenario is synonymous to doing a Get > Latest Version with the
Overwrite writable files that are not checked out and
Overwrite all files if the local version matches the specified version options in TFVC.
Alternatively you can manually delete your local repo - after making a validated copy off course - and then clone
the repository again.
There are a lot more actions and options available to Git users. Here are some useful reference sites for further
reading:
Git commands covered herein, refer to git documentation
Think like (a) Git, a Guide for the Perplexed.
How to undo (almost) anything with Git, by Joshua Wehner
Q&A
What about sync?
"Does the Visual Studio IDE Commit and Sync not magically do all this?", you may be asking yourself.
With magic comes responsibility! Many users dislike the sync as it can sometimes mess up your local history and
add a merge commit on top of your current commit. Once you are in a bad state, you have to revert to the
command line as there is currently no reset support in the IDE.
Authors: Jesse Houwing, Martin Hinshelwood, Mike Fourie, and Willy Schaub from the ALM | DevOps Rangers.
Connect with them here.
Build pipeline triggers
Azure Pipelines | Azure DevOps Server 2019 | TFS 2018 | TFS 2017 | TFS 2015
NOTE
In Microsoft Team Foundation Server (TFS) 2018 and previous versions, build and release pipelines are called definitions,
service connections are called service endpoints, stages are called environments, and jobs are called phases.
On the Triggers tab, you specify the events that trigger the build. You can use the same build pipeline for both CI
and scheduled builds.
CI triggers
Continuous integration (CI) triggers cause a build to run whenever a push is made to the specified branches or a
specified tag is pushed.
YAML
Classic
YAML builds are configured by default with a CI trigger on all branches.
YAML builds are configured by default with a CI trigger on all branches.
Branches
You can control which branches get CI triggers with a simple syntax:
trigger:
- master
- releases/*
You can specify the full name of the branch (for example, master ) or a wildcard (for example, releases/* ). See
Wildcards for information on the wildcard syntax. Note: you cannot use variables in triggers, as variables are
evaluated at runtime (after the trigger has fired).
You can specify branches to include and exclude. For example:
# specific branch build

trigger:
branches:
include:
- master
- releases/*
exclude:
- releases/old*
In addition to specifying branch names in the branches lists, you can also configure triggers based on tags by
using the following format:
trigger:
branches:
include:
refs/tags/{tagname}
exclude:
refs/tags/{othertagname}
If you don't specify any triggers, the default is as if you wrote:
trigger:
branches:
include:
- '*' # must quote since "*" is a YAML reserved character; we want a string
IMPORTANT
When you specify a trigger, it replaces the default implicit trigger, and only pushes to branches that are explicitly configured
to be included will trigger a pipeline. Includes are processed first, and then excludes are removed from that list. If you specify
an exclude but don't specify any includes, nothing will trigger.
Batching CI builds
If you have a lot of team members uploading changes often, you may want to reduce the number of builds you're
running. If you set batch to true , when a build is running, the system waits until the build is completed, then
queues another build of all changes that have not yet been built.
# specific branch build with batching

trigger:
batch: true
branches:
include:
- master
Paths
You can specify file paths to include or exclude. Note that the wildcard syntax is different between branches/tags
and file paths.
# specific path build

trigger:
branches:
include:
- master
- releases/*
paths:
include:
- docs/*
exclude:
- docs/README.md
When you specify paths, you also need to explicitly specify branches to trigger on.
Tags
In addition to specifying tags in the branches lists as covered in the previous section, you can directly specify tags
to include or exclude:
trigger:
tags:
include:
- v2.*
exclude:
- v2.0
If you don't specify any tag triggers, then by default, tags will not trigger pipelines.
NOTE
If you specify tags in combination with branch filters that include file paths, the trigger will fire if the branch filter is satisfied
and either the tag or the path filter is satisfied.
NOTE
Triggering on tags is not currently supported for Bitbucket Cloud repos.
Opting out of CI builds

Disabling the CI trigger
You can opt out of CI builds entirely by specifying trigger: none .
# A pipeline with no CI trigger

trigger: none
IMPORTANT
When you push a change to a branch, the YAML file in that branch is evaluated to determine if a CI build should be run.
For more information, see Triggers in the YAML schema.

Skipping CI for individual commits
You can also tell Azure Pipelines to skip running a pipeline that a commit would normally trigger. Just include
***NO_CI*** in the commit message of the HEAD commit and Azure Pipelines will skip running CI. This is
supported for commits to Azure Repos Git and GitHub.
You can also tell Azure Pipelines to skip running a pipeline that a commit would normally trigger. Just include
[skip ci] in the commit message or description of the HEAD commit and Azure Pipelines will skip running CI.
You can also use any of the variations below. This is supported for commits to Azure Repos Git, Bitbucket Cloud,
GitHub, and GitHub Enterprise Server.
[skip ci] or [ci skip]
skip-checks: true or skip-checks:true
[skip azurepipelines] or [azurepipelines skip]
[skip azpipelines] or [azpipelines skip]
[skip azp] or [azp skip]
***NO_CI***

PR triggers
Pull request (PR ) triggers cause a build to run whenever a pull request is opened with one of the specified target
branches, or when changes are pushed to such a pull request.
YAML
Classic
IMPORTANT
YAML PR triggers are only supported in GitHub and Bitbucket Cloud. If you are using Azure Repos Git, you can configure a
branch policy for build validation in order to trigger your build pipeline for validation.
NOTE
New pipelines automatically override YAML PR triggers with a setting in the UI. To opt into YAML-based control, you need
to disable this setting on the Triggers tab in the UI.
IMPORTANT
YAML PR triggers are only supported in GitHub. If you are using Azure Repos Git, you can configure a branch policy for
build validation in order to trigger your build pipeline for validation.
You can specify the target branches for your pull request builds. For example, to run pull request builds only for
source branches in a PR that target master and releases/* , you can use the following pr trigger. This
configuration triggers a build upon creation of any pull request where the target branch is set to the master or
releases/* branches. The pipeline also triggers once with any commit coming into the source branch when the
target branch is set to be master or releases/* , while the pull request is active.
pr:
- master
- releases/*
PR triggers will fire for these branches once the pipeline YAML file has reached that branch. For example, if you
add master in a topic branch, PRs to master will not start automatically building. When the changes from the
topic branch are merged into master , then the trigger will be fully configured.
If no pr triggers appear in your YAML file, pull request builds are automatically enabled for all branches, as if you
wrote the following pr trigger. This configuration triggers a build when any pull request is created, and when
commits come into the source branch of any active pull request.
pr:
branches:
include:
- '*' # must quote since "*" is a YAML reserved character; we want a string
IMPORTANT
When you specify a pr trigger, it replaces the default implicit pr trigger, and only pushes to branches that are explicitly
configured to be included will trigger a pipeline. Includes are processed first, and then excludes are removed from that list. If
you specify an exclude but don't specify any includes, nothing will trigger.
You can specify the full name of the branch (for example, master ) or a wildcard (for example, releases/* ). See
Wildcards for information on the wildcard syntax.
You can specify branches to include and exclude. For example:

pr:
branches:
include:
- master
- releases/*
exclude:
- releases/old*
You can specify file paths to include or exclude. For example:
# specific path build

pr:
branches:
include:
- master
- releases/*
paths:
include:
- docs/*
exclude:
- docs/README.md
Note that the wildcard syntax is different between branches/tags and file paths.
You can specify whether additional pushes to a PR should cancel in-progress runs for the same PR. The default is
true .
# auto cancel false

pr:
autoCancel: false
branches:
include:
- master
You can opt out of pull request builds entirely by specifying pr: none .
# no PR builds
pr: none
IMPORTANT
When you create a pull request, or push a change to the source branch of a PR, the YAML file in the source branch is
evaluated to determine if a PR build should be run.
For more information, see PR trigger in the YAML schema.

Trigger builds using GitHub pull request comments
If your team uses GitHub pull requests, you can manually trigger pipelines using pull request comments. See
details here.
Scheduled triggers
YAML
Classic
IMPORTANT
Scheduled triggers defined using the pipeline settings UI take precedence over YAML scheduled triggers.
If your YAML pipeline has both YAML scheduled triggers and UI defined scheduled triggers, only the UI defined scheduled
triggers are run. To run the YAML defined scheduled triggers in your YAML pipeline, you must remove the scheduled
triggers defined in the pipeline setting UI. Once all UI scheduled triggers are removed, a push must be made in order for the
YAML scheduled triggers to start running.
Scheduled triggers cause a build to run on a schedule defined using cron syntax.
schedules:
- cron: string # cron syntax defining a schedule
displayName: string # friendly name given to a specific schedule
branches:
include: [ string ] # which branches the schedule applies to
exclude: [ string ] # which branches to exclude from the schedule
always: boolean # whether to always run the pipeline or only if there have been source code changes since
the last run. The default is false.
In the following example, two schedules are defined.
schedules:
- cron: "0 0 * * *"
displayName: Daily midnight build
branches:
include:
- master
- releases/*
exclude:
- releases/ancient/*
- cron: "0 12 * * 0"
displayName: Weekly Sunday build
branches:
include:
- releases/*
always: true
The first schedule, Daily midnight build, runs a pipeline at midnight every day, but only if the code has changed
since the last run, for master and all releases/* branches, except those under releases/ancient/* .
The second schedule, Weekly Sunday build, runs a pipeline at noon on Sundays, whether the code has changed
or not since the last run, for all releases/* branches.
NOTE
The time zone for cron schedules is UTC, so in these examples, the midnight build and the noon build are at midnight and
noon in UTC.
The schedules are read and updated when the following events occur, and schedules get added to the scheduling
database for the current branch, if the branch criteria is satisfied.
The yaml file is created or updated
A pipeline is created or updated
A new branch is created
Supported cron syntax
Each cron expression is a space-delimited expression with five entries in the following order.
mm HH DD MM DW
\ \ \ \ \__ Days of week
\ \ \ \____ Months
\ \ \______ Days
\ \________ Hours
\__________ Minutes
FIELD ACCEPTED VALUES
Minutes 0 through 59
Hours 0 though 23
Days 1 through 31
Months 1 through 12, full English names, first three letters of English
names
Days of week 0 through 6 (starting with Sunday), full English names, first
three letters of English names
Values can be in the following formats.
FORMAT EXAMPLE DESCRIPTION
Wildcard * Matches all values for this field
Single value 5 Specifies a single value for this field
Comma delimited 3,5,6 Specifies multiple values for this field.

Multiple formats can be combined, like
1,3-6
Ranges 1-3 The inclusive range of values for this

field
Intervals */4 or 1-5/2 Intervals to match for this field, such as

every 4th value or the range 1-5 with a
step interval of 2
EXAMPLE CRON EXPRESSION
Build every Monday, Wednesday, and Friday at 6:00 PM 0 18 * * Mon,Wed,Fri , 0 18 * * 1,3,5 ,

0 18 * * Mon,Wed,Fri , or 0 18 * * 1-5/2
Build every 6 hours 0 0,6,12,18 * * * , 0 */6 * * * , or 0 0-18/6 * * *

EXAMPLE CRON EXPRESSION
Build every 6 hours starting at 9:00 AM 0 9,15,21 * * * or 0 9-21/6 * * *
For more information on supported formats, see Crontab Expression.
NOTE
Each cron schedule has a maximum of 100 pipeline runs per week. If you need more, you can split your cron schedule into
multiple cron schedules that each result in 100 or less pipeline runs per week.
Migrating from the classic editor

The following examples show you how to migrate your schedules from the classic editor to YAML.
Example: Nightly build of Git repo in multiple time zones
Example: Nightly build with different frequencies
Example: Nightly build of Git repo in multiple time zones
In this example, the classic editor scheduled trigger has two entries, producing the following builds.
Every Monday - Friday at 3:00 AM (UTC + 5:30 time zone), build branches that meet the features/india/*
branch filter criteria
Every Monday - Friday at 3:00 AM (UTC - 5:00 time zone), build branches that meet the features/nc/*
branch filter criteria
The equivalent YAML scheduled trigger is:
schedules:
- cron: "30 21 * * Sun-Thu"
displayName: M-F 3:00 AM (UTC + 5:30) India daily build
branches:
include:
- /features/india/*
- cron: "0 8 * * Mon-Fri"
displayName: M-F 3:00 AM (UTC - 5) NC daily build
branches:
include:
- /features/nc/*
In the first schedule, M -F 3:00 AM (UTC + 5:30) India daily build, the cron syntax ( mm HH DD MM DW ) is
30 21 * * Sun-Thu .
Minutes and Hours - 30 21 - This maps to 21:30 UTC , or 9:30 PM UTC . Since the specified time zone in the
classic editor is UTC + 5:30, we need to subtract 5 hours and 30 minutes from the desired build time of 3:00
AM to arrive at the desired UTC time to specify for the YAML trigger.
Days and Months are specified as wildcards since this schedule doesn't specify to run only on certain days of
the month, or on a specific month.
Days of the week - Sun-Thu - because of the timezone conversion, for our builds to run at 3:00 AM in the UTC
+ 5:30 India time zone, we need to specify starting them the previous day in UTC time. We could also specify
the days of the week as 0-4 or 0,1,2,3,4 .
In the second schedule, M -F 3:00 AM (UTC - 5) NC daily build, the cron syntax is 0 8 * * Mon-Fri .
Minutes and Hours - 0 8 - This maps to 8:00 AM UTC . Since the specified time zone in the classic editor is
UTC - 5:00, we need to add 5 hours from the desired build time of 3:00 AM to arrive at the desired UTC time
to specify for the YAML trigger.
Days of the week - Mon-Fri - Because our timezone conversions don't span multiple days of the week for our
desired schedule, we don't need to do any conversion here. We could also specify the days of the week as 1-5
or 1,2,3,4,5 .
IMPORTANT
The UTC time zones in YAML scheduled triggers don't account for daylight savings time.
Example: Nightly build with different frequencies

In this example, the classic editor scheduled trigger has two entries, producing the following builds.
Every Monday - Friday at 3:00 AM UTC, build branches that meet the master and releases/* branch filter
criteria
Every Sunday at 3:00 AM UTC, build the releases/lastversion branch, even if the source or pipeline hasn't
changed
The equivalent YAML scheduled trigger is:

schedules:
- cron: "0 3 * * Mon-Fri"
displayName: M-F 3:00 AM (UTC) daily build
branches:
include:
- master
- /releases/*
- cron: "0 3 * * Sun"
displayName: Sunday 3:00 AM (UTC) weekly latest version build
branches:
include:
- /releases/lastversion
always: true
In the first schedule, M -F 3:00 AM (UTC ) daily build, the cron syntax is 0 3 * * Mon-Fri .
UTC, we don't need to do any time zone conversions.
Days of the week - Mon-Fri - because there is no timezone conversion, the days of the week map directly from
the classic editor schedule. We could also specify the days of the week as 1,2,3,4,5 .
In the second schedule, Sunday 3:00 AM (UTC ) weekly latest version build, the cron syntax is 0 3 * * Sun .
UTC, we don't need to do any time zone conversions.
Days of the week - Sun - Because our timezone conversions don't span multiple days of the week for our
desired schedule, we don't need to do any conversion here. We could also specify the days of the week as 0 .
We also specify always: true since this build is scheduled to run whether or not the source code has been
updated.
Scheduled builds are not yet supported in YAML syntax. After you create your YAML build pipeline, you can use
pipeline settings to specify a scheduled trigger.
TFVC gated check-in

If your code is in a Team Foundation version control (TFVC ) repo, use gated check-in to protect against breaking
changes.
By default Use workspace mappings for filters is selected. Builds are triggered whenever a change is checked in
under a path specified in your mappings in the source repository settings.
Otherwise, you can clear this check box and specify the paths in the trigger.
How it affects your developers
When developers try to check-in, they are prompted to build their changes.
The system then creates a shelveset and builds it.
For details on the gated check-in experience, see Check in to a folder that is controlled by a gated check-in build
pipeline.
Option to run CI builds
By default, CI builds are not run after the gated check-in process is complete and the changes are checked in.
However, if you do want CI builds to run after a gated check-in, select the Run CI triggers for committed
changes check box. When you do this, the build pipeline does not add ***NO_CI*** to the changeset description.
As a result, CI builds that are affected by the check-in are run.
A few other things to know
Make sure the folders you include in your trigger are also included in your mappings on the Repository tab.
You can run gated builds on either a Microsoft-hosted agent or a self-hosted agent.
Build completion triggers

YAML
Classic
Build completion triggers are not yet supported in YAML syntax. After you create your YAML build pipeline, you
can use the classic editor to specify a build completion trigger.
Wildcards
When specifying a branch or tag, you may use an exact name or a wildcard. Wildcards patterns allow * to match
zero or more characters and ? to match a single character. For branches and tags, a wildcard may appear
anywhere in the pattern.
For paths, you may include * as the final character, but it doesn't do anything differently from specifying the
directory name by itself. You may not include * in the middle of a path filter, and you may not use ? .
trigger:
branches:
include:
- master
- releases/*
- feature/*
exclude:
- releases/old*
- feature/*-working
paths:
include:
- '*' # same as '/' for the repository root
exclude:
- 'docs/*' # same as 'docs/'
Q&A
How do I protect my Git codebase from build breaks?
If your code is in a Git repo on Azure Repos or Team Foundation Server, you can create a branch policy that runs
your build. See Improve code quality with branch policies. This option is not available for GitHub repos.
My build didn't run. What happened?
Someone must view a page in your organization regularly for CI and scheduled builds to run. It can be any page,
including, for example, Azure Pipelines.
Your organization goes dormant five minutes after the last user signed out of Azure DevOps. After that, each of
your build pipelines will run one more time. For example, while your organization is dormant:
A nightly build of code in your organization will run only one night until someone signs in again.
CI builds of an Other Git repo will stop running until someone signs in again.
The YAML file in my branch is different than the YAML file in my master branch, which one is used?
For CI triggers, the YAML file that is in the branch you are pushing is evaluated to see if a CI build should be
run.
For PR triggers, the YAML file that is in the source branch of the PR is evaluated to see if a PR build should be
run.
Do I need an agent?
You need at least one agent to run your build or release. Get an agent for Linux, macOS, or Windows.
I'm having problems. How can I troubleshoot them?
See Troubleshoot Build and Release.
I can't select a default agent pool and I can't queue my build or release. How do I fix this?
See Agent pools.
I use TFS on-premises and I don't see some of these features. Why not?
Some of these features are available only on Azure Pipelines and not yet available on-premises. Some features are
available on-premises if you have upgraded to the latest version of TFS.
Resolve work items on commit
Azure Repos
Close work items by mentioning keywords in commit messages. When you mention a work item in a commit that
makes it to the default branch via one of the supported workflows, we will attempt to resolve that work item.
Keywords
The three supported keywords to trigger a resolution mention are fix , fixes , and fixed (case insensitive).
Optionally, a colon can follow the keyword. Most forms of punctuation can precede or proceed the resolution
mention, excluding another pound sign (#).
Examples
Fixes #123
This fixed #123!
Change behavior to fix: #123
Fixes #123 and fixes #124
NOTE
Each work item to be closed must include both a supported keyword and the work item number. Comma separated lists such
as fixes #123,124,125 after a keyword will only resolve the first work item. This is done to mitigate the amount of
accidental resolution that could occur.
Close a work item

Use the keywords to mention a work item in the commit message then follow one of two workflows:
Push event - If a commit contains a resolution mention when it is pushed to the default branch of the
repository, it will attempt to resolve the work item.
Pull request post-completion event - When a user completes a pull request (excluding squash merge) to
the default branch and selects the option to Complete associated work items after merging, all commits
tied to the pull request will be processed for resolution mentions and will attempt to resolve the associated
work items. This is done by selecting the post-completion option for completing associated work items
within the completion dialog of a pull request.
Enable commit mention work item resolution

You can use the Commit mention work item resolution setting in the repository settings to enable or disable
this feature. This setting is configured on a per-repo basis, and is enabled by default.
Working with Git tags
Azure Repos | Azure DevOps Server 2019 | TFS 2018 | TFS 2017 | VS 2017 | VS 2015
Azure DevOps Services and TFS support both annotated and lightweight tags. Lightweight tags are a pointer to
specific commit, while annotated tags contain more information such as the tagger, message, and date. You can
create annotated tags using the web portal, and starting with Visual Studio 2017 Update 6, you can create both
lightweight and annotated tags from within Visual Studio. For more information on Git tags, see 2.6 Git Basics -
Tagging from the Pro Git book.
This article provides an overview of working with Git tags in Azure DevOps Services, TFS, and Visual Studio.
IMPORTANT
The Tags view in Visual Studio was introduced in Visual Studio 2017 Update 6. If you are on versions earlier than this, you
can view and create tags from the history and commit details views starting with Visual Studio 2015, but you won't be able
to perform the operations in the Tags view as described in this article.
View and filter tags

You can view tags in the Tags view and in the Commits view in the web portal.
NOTE
dev.azure.com/{your organization}/{your project} , but you can still use the existing visualstudio.com format. For
more information, see VSTS is now Azure DevOps Services.
View tags in the Tags view

1. To view the tags in your repo, navigate to your project in the web portal, choose Repos, Tags, and select the
desired repo.
Annotated tags are displayed with a tag name, message, commit, tagger, and creation date. Lightweight tags
are displayed with a tag name and commit.
2. To filter the list of tags, type a search term into the Search tag name box and press Enter.
View tags in the Commits view

1. To view tags for a specific branch in the Commits view, navigate to your repo in the web portal, choose
Repos, Commits, and select your branch.
You can view tags in the Tags view and in the Commits view in the web portal.
NOTE
dev.azure.com/{your organization}/{your project} , but you can still use the existing visualstudio.com format. For
more information, see VSTS is now Azure DevOps Services.

1. To view the tags in your repo, navigate to your project in the web portal, choose Code, select the desired
repo, and choose Tags.
Annotated tags are displayed with a tag name, message, commit, tagger, and creation date. Lightweight tags
are displayed with a tag name and commit.
2. To filter the list of tags, type a search term into the Search tag name box and press Enter.
View tags in the Commits view

1. To view tags for a specific branch in the Commits view, navigate to your repo in the web portal, choose
Code, Commits, and select your branch.
Visual Studio
You can view tags in the Tags view and in the History view.
1. To view all tags in a repo, select Tags from the Home view.
2. Tags are displayed under the currently connected repo name.
Annotated tags display a tooltip that contains the tag name, tagger, tag date, and message. Lightweight tags
have only the tag name in the tooltip.
For more information about the tagged commit, right-click the tag and select View Commit Details.
3. To filter the list of tags, type a search term into the Type here to filter the list box.
To retrieve the current list of tags from the source repo, perform a fetch operation.
View tags in the History view
You can also view tags in the History view, for example by navigating to the Branches view, right-clicking the
desired branch, and choosing View History. The red shapes are branches, and the green shapes are tags.
Create tag
To create a tag, you must have the Create Tag permission, which is included by default in the Contributors group
and higher.
You can create annotated tags using the web portal from both the Tags view and the Commits view.
IMPORTANT
You can only create annotated tags in the web portal. To create a lightweight tag, you can use Git command line or Visual
Studio.
Create tags from the Tags view

1. Select Create Tag from the Tags view in the web portal to create a new annotated tag.
2. Specify a Name, select the branch to Tag from, enter a Description (required since you are creating an
annotated tag), and select Create.
3. The new tag is displayed in the tag list.

Create tags from the Commits view
1. To create a tag directly from the commits view, right-click the desired tag and choose Create tag.
You can create annotated tags using the web portal from both the Tags view and the Commits view.
IMPORTANT
You can only create annotated tags in the web portal. To create a lightweight tag, you can use Git command line or Visual
Studio.

1. Select Create Tag from the Tags view in the web portal to create a new annotated tag.
2. Specify a Name, select the branch to Tag from, enter a Description (required since you are creating an
annotated tag), and select Create.
3. The new tag is displayed in the tag list.
Create tags from the Commits view

1. To create a tag directly from the commits view, right-click the desired tag and choose Create tag.
Visual Studio
You can create both annotated and lightweight tags in Visual Studio from both the Tags view and the History
view. To create an annotated tag, provide both a name and a message when creating the tag. To create a
lightweight tag, omit the message and supply only a name.
1. Select New Tag in the Tags view to create a new tag.
2. To create a tag against the tip of the current branch, specify a name in the Enter a tag name box, optionally
provide a tag message, and select Create Tag.
To select the branch to create the tag from, clear the Create tag against tip of current branch check box,
and select a branch from the Select a branch drop-down.
3. The new tag is created locally. Right-click the new tag and choose Push to push it to the remote repo. Select
Push All to push all new local tags to the remote repo.
Create tags from the History view
1. To create a tag directly from the history view, right-click the desired commit and choose Create Tag.
Delete tag
IMPORTANT
Use caution when deleting tags from your repo. If the repo has been pulled, forked, or cloned by another user, the tag will
still exist in their copy of the repo. You should only delete local tags, or if you are sure that the repo hasn't been pulled,
cloned, or forked since you created your tag.
To delete a tag, you must have the Force Push permission at the Repository level or the All tags level (which
inherits its permissions from the repository level if not explicitly set).
Delete a tag in the remote repo
The steps in this procedure show you how to delete a tag in the remote repo using the Azure DevOps Services
web portal.
1. To delete a tag, select the ellipsis to the right of the tag name and choose Delete tag.
2. Select Delete to confirm.
3. The tag is deleted, and won't be displayed the next time you navigate to the Tags view.
Delete a tag in the remote repo

The steps in this procedure show you how to delete a tag in the remote repo using the Azure DevOps Services
web portal.
1. To delete a tag, select the ellipsis to the right of the tag name and choose Delete tag.
2. Select Delete to confirm.
3. The tag is deleted, and won't be displayed the next time you navigate to the Tags view.
Visual Studio
The steps in this procedure show you how to delete a tag in the local repo using Visual Studio 2017 Update 6.
1. Right-click the tag to delete and choose Delete Locally
IMPORTANT
If your tag has already been pushed to the remote repo, you should not delete it. If the repo has been pulled, forked, or
cloned by another user, the tag will still exist in their copy of the repo. You should only delete local tags.
Create branch from a tag

1. To create a branch from a tag, select the ellipsis to the right of the tag name and choose New branch.
2. Specify a Name, optionally select any Work items to link, and choose Create branch.
3. The branch is created and you are taken to the new branch in the web portal.
1. To create a branch from a tag, select the ellipsis to the right of the tag name and choose New branch.
2. Specify a Name, optionally select any Work items to link, and choose Create branch.
3. The branch is created and you are taken to the new branch in the web portal.
Visual Studio
1. To create a branch from a tag, right-click the tag and choose New Local Branch From. You can also choose
Create Branch From Tag.
2. Specify a branch name, verify the desired tag, and choose Create Branch. To checkout the new branch after
it is created, choose Checkout branch.
3. To view your newly created branch, select Branches from the Home view.
4. Note that your new branch is created locally. To push the branch, right-click it and choose Push Branch.
View tag history

1. To view the history for a tag, select the ellipsis to the right of the tag name and choose View history.
2. You are taken to the commits view for the tag.
1. To view the history for a tag, select the ellipsis to the right of the tag name and choose View history.
2. You are taken to the commits view for the tag.
Visual Studio
1. To view the history for a tag, right-click the tag and choose View History.
2. The history is displayed in the History view.
RPC failures and http.postBuffer
Azure Repos | Azure DevOps Server 2019 | TFS 2018 | TFS 2017 | TFS 2015 | TFS 2013
If you see an RPC failed error during git push , such as:
error: RPC failed; result=22, HTTP code = 404
error: RPC failed; result=22, HTTP code = 411
Unable to rewind rpc post data - try increasing http.postBuffer error: RPC failed; result=56, HTTP code = 0
... and search for help on Stack Overflow or MSDN forums, you'll see a lot of old recommendations to set
http.postBuffer .
Don't do it! At least not blindly. First, review the suggestions in this article.
Upgrade Git
If you're still running a Git client that's version 2.8 or older, you should upgrade Git first. There are a bug fixes in
newer versions of Git that should obviate the need to set http.postBuffer .
We had enough support requests from internal users and external customers hitting bugs in older versions of Git
that we decided to add a server-side reminder to Azure DevOps Services/TFS.
c:\mydir>git fetch
remote: Microsoft (R) Visual Studio (R) Team Services
remote: We noticed you're using an older version of Git. For a better experience, upgrade to the latest version
at https://git-scm.com/downloads
remote: Found 4 objects to send. (6 ms)
Unpacking objects: 100% (4/4), done.
Check hotfixes
Check if these hotfixes are applicable if your TFS server is running Windows 2012 R2 or earlier:
A large file upload or a large repository clone fails on VSO in Windows Server 2012 R2
Pushing large files to Team Foundation Server by Git client hangs
Check if you're using a proxy or load balancer

If you're using a terrible proxy that's buggy or doesn’t support chunked encoding, you'll see errors for larger
pushes. The same thing can happen if you put on-prem TFS behind a misconfigured load balancer. If the same
push succeeds when bypassing the proxy, or bypassing the load balancer (e.g. by pushing to localhost from the
server itself), then fix your proxy or load balancer instead!
What if my proxy or load balancer is broken, but I don't have any control over it?
This is the only scenario that we've seen where setting http.PostBuffer is useful for newer versions of Git.
http.postBuffer questions
Is setting http.postBuffer harmful?
In our experience, it's more unnecessary than harmful, but there are a few negative side effects:
Increasing it above the default may increase latency for larger pushes (since the client will buffer the HTTP
request into larger chunks).
If you set it larger than the HTTP chunk size limit for your HTTP server (e.g. maxAllowedContentLength and
maxRequestLength in web.config for TFS servers), then all pushes larger than the chunk size limit will start
failing.
How do I unset http.postBuffer if I've already set it?
To check if it's set, run:
git config --show-origin --get-all http.postBuffer
You may have to unset it in both your global .gitconfig file:
git config --global --unset http.postBuffer
As well as in your repo level .git/config (which overrides the global setting):
git config --local --unset http.postBuffer

Git command reference
Overview
Visual Studio's Team Explorer lets you perform most common Git tasks you'll need for your day to day work right
from Visual Studio. Open Team Explorer through the View menu in Visual Studio, or with the Ctrl+, Ctrl+M
hotkey.
Team Explorer and the Git command line work great together. When you make updates and perform commands
through one interface, you'll see those changes reflected in the other.
Git Installation instructions are available if you don't have Git installed on your computer.
TIP
Windows users: If you aren't using Visual Studio, installing Git for Windows will set up the Git credential manager for
Windows. The credential manager makes it easy to authenticate with Azure Repos.
While in Visual Studio, open a command prompt in your repo from Team Explorer's Connect view. Right-click on
your local repo and select Open Command Prompt
IMPORTANT
Some commands require having specific Git permissions in Azure Repos to complete.
Repos
HOW DO I ? GIT COMMAND LINE VISUAL STUDIO
Create a repo in a new folder git init foldername Select the Connect button ( ) in
Team Explorer to open the Connect
view, then select New under Local Git
repositories
Create a repo with code in an existing git init foldername Create the repo from the command
folder git add --all line, then open Team Explorer's
git commit -m "Initial commit" Connect view and select Add under
Local Git repositories
Create a repo from an existing Visual git init foldername Open the solution and select Publish (
Studio solution cd foldername ) from the status bar in the
git add --all lower right.
git commit -m "Initial commit"
Create a new repo in your Project Not applicable From the web, select Repos (or Code if
you haven't enabled the new navigation
preview), then select the drop-down
next to the current repo name and
choose New Repository...
Clone a repo into a local folder git clone URL foldername Select Clone under Local Git
repositories in Team Explorer's
Connect view
Clone a repo in your Project git clone URL foldername Open the Connect view in Team
Explorer and right click the Git repo in
your Project under the account name.
Select Clone...
Add an existing repo to Visual Studio Not applicable Open the solution file in Visual Studio
(this will automatically add the repo to
Team Explorer) or select Add under
Local Git repositories in the Connect
view
Delete the Git repo and history, but Delete the hidden .git folder created at Delete the hidden .git folder created at
keep the current version of the files the root of the repo the root of the repo from Windows
Explorer or the command line
Delete a local repo and all files Delete the folder containing your repo Close any open solutions using files in
from your computer's filesystem the repo, then delete the folder
containing your repo from your
computer's filesystem.
Delete a repo in your Project Not applicable Select the settings icon ( ) in Azure
DevOps Services/TFS, then select the
Version Control tab. Find the Git
repository to delete and select the ...
next to the name. Choose Delete
Repository from the options.
Add a remote git remote add name url Open the repository using the Connect
view in Team Explorer, then open the
Settings view in Team Explorer. Select
Repository Settings, and select Add
under Remotes
Update a remote git remote set-url name url Open the repository using the Connect
view in Team Explorer, then open the
Settings view in Team Explorer. Select
Repository Settings, and select Edit
under Remotes
Learn more:
Create a new repo Clone an existing repo
Share your code in Git with the command line
Share your code in Git with Visual Studio 2015
Share your code in Git with Visual Studio 2013
Create a new repo in your Project
Delete a repo in your Project
Branches
Create a new branch git branch branchname Open the Branches view in Team
Explorer, then right-click a branch and
choose New Local Branch From...
Swap to a different branch git checkout branchname Open the Branches view in Team
Explorer, then double click a local
branch. Alternatively, click the current
branch name from the status bar and
select a different branch.
Create and switch to a new branch git checkout -b branchname Open the Branches view in Team
Explorer, then right-click a branch and
choose New Local Branch From...
Delete a local branch git branch -d branchname Open the Branches view in Team
Explorer, then right-click the branch and
select Delete. You must be checked out
to a different branch than the one you
want to delete.
Delete a remote branch git push origin --delete branchname Open the Branches view in Team
Explorer, expand the remote that has
the branch you want to delete. Right-
click the remote and select Delete
Branch from Remote
Lock a branch, preventing updates to it From the web, select the Branches tab Same as command line
while viewing your repo. Select the ...
next to the branch you want to lock
and choose Lock. Unlock the branch
with Unlock
Set a default branch in your Azure Select the settings icon on the web ( Same as command line
DevOps Services/TFS repo ), then select the Version Control tab.
Select your Git repository, then select
the ... next to the branch name and
choose Set as default branch
Set a compare branch for pull requests From the web, select the Branches tab Same as command line
in your Azure DevOps Services/TFS while viewing your repo. Select the ...
repo next to the branch you want to lock
and choose Compare branch
Learn more:
Create and manage your work in branches
Managing your Git branches in Azure DevOps Services/TFS
Delete a Git branch on your Azure DevOps Services/TFS repo
Lock and unlock an Azure DevOps Services/TFS branch
Commits
HOW DO I ? GIT COMMAND VISUAL STUDIO
Create a new commit git commit -m "message" Open the Changes view in Team
Explorer. Stage changes by right-
clicking on the modified files and
selecting Stage. Enter a commit
message and select Commit Staged.
Amend the last commit with staged git commit --amend -m "Updated Open the Changes view in Team
changes message" Explorer, stage your changes, then
select Amend Previous Commit from
the Actions drop-down.
Stage all file changes git add --all Open the Changes view in Team
Explorer. Select the + icon in the
Changes list to stage all changes for
the next commit.
Stage a specific file change git add filename Open the Changes view in Team
Explorer. Stage changes by right-
clicking on the changed file and
selecting Stage.
Review unstaged changes git status --untracked Open the Changes view in Team
Explorer. Unstaged changes are listed
under Changes section.
Delete a file git rm filename Delete the file through Solution

git commit -m "Deleted filename" Explorer, the command line, or any
other means. Right-click the deleted file
in Team Explorer's Changes view and
select Stage . Select Commit Staged
to commit the deletion.
Move a file git mv filename Move a file from one location to

git commit -m "Moved filename" another in your repo through Solution
Explorer, the command line, or any
other means. Right-click the moved file
in Team Explorer's Changes view and
select Stage . Select Commit Staged
to commit the move.
Tag a commit git tag -a tagname -m "description" Open the Changes view in Team
Explorer, then choose View history..."
from the Action drop-down. Locate the
commit in the History view, then right-
click and select Create Tag
Learn more:
Save your work with commits
Compare files and versions

Compare the current contents of a git diff HEAD filename Right-click on the change in the
single file and the contents in the last Changes view in Team Explorer and
commit select Compare with unmodified.
Compare your current version with a git diff branchname Right-click on a file in Solution Explorer
branch and select View History..., then select
both on the latest commit on your
current branch and the latest commit
on the remote branch. Right-click and
select Compare
Compare changes between two git diff branchname1 branchname2 Right-click on a file in Solution Explorer
branches and select View History..., then select
the most recent commits for both
branches. Right-click and select
Compare
Learn more:
Compare versions and review history
Sync changes
Download new branches and commits git fetch Open the Sync view from Team
from a remote repo, but do not merge Explorer and select Fetch.
them into your local branches
Merge updates from a remote repo git pull remote branchname While working on the branch in your
into your local repo local repo, open the Sync view in Team
Explorer, then select Pull.
Publish a local branch to a remote repo git push -u remote branchname Open the Sync view in Team Explorer
and select Publish under Outgoing
Commits.
Synchronize your local branch with a git pull remote branchname Open the Sync view in Team Explorer.
remote branch, pushing your local git push -u remote branchname Select Sync.
changes and pulling remote ones
Force push a branch, rewriting the git push --force -u origin Use command line
remote branch history with the history remote_branchname
of your current branch
Learn more:
Update your code with fetch and pull
Merge and rebase

Merge a branch into the current branch git merge branchname In the Team Explorer Branches view,
right-click the branch you want to
merge and select Merge From... Verify
the options set and select Merge.
Merge a remote branch into the git pull origin branchname In the Team Explorer Branches view,
current branch right-click the remote branch you want
to merge and select Merge From...
Verify the options set and select
Merge.
Rebase your current branch onto the git rebase branchname In the Team Explorer Branches view,
history of another branch right-click the branch you want to
rebase your current branch changes
onto and select Rebase Onto.."
Do an interactive rebase of the last n git rebase -i HEAD~n (Linux and Use command line
commits macOS)
git rebase -i "HEAD^n" (Windows)
Cherry-pick a commit into the current git cherry-pick commitID Open the Changes view in Team
branch Explorer, then choose View history..."
from the Action drop-down. Locate the
commit in the History view, then right-
click and select Cherry-pick
Learn more:
Catch up and replay changes with rebase
Undo
WARNING
If you are not an experienced Git user, exercise caution when using the reset command. Learn more
Revert all changes and roll back to the git reset --hard HEAD Open the Changes view in Team
most recent commit Explorer. Select Actions and choose
**View History from the drop-down.
Right-click the commit where the
branch is currently located and select
Reset and Delete changes....
Revert staging of files, but keep file git reset --mixed HEAD Open the Changes view in Team
changes Explorer. Select Actions and choose
Right-click the commit where the
branch is currently located and select
Reset and Keep changes....
Delete untracked files git clean -f In the Changes view in Team Explorer,
right-click the files to remove under
Changes marked with [add] and select
Delete.
Reset your local branch to the most git reset --hard remote/branchname Right-click the branch from Team
recent commit on a remote branch (for example, git reset --hard Explorer's Branches view and select
origin/master) Reset and Delete changes....
Revert a commit pushed to a remote git revert commitID Open the Changes view in Team
repository Explorer. Select Actions and choose
Right-click the commit to revert and
select Revert.
Learn more:
Undo changes and commits
Syntax guidance for basic Markdown usage
Azure DevOps Services | Azure DevOps Server 2019 | TFS 2018 | TFS 2017 | TFS 2015
IMPORTANT
Make sure that you select the correct version of this article for Azure DevOps Services or Azure DevOps Server, renamed
from Team Foundation Server (TFS). The version selector is located above the table of contents.
Here you can find some basic Markdown syntax guidance and specific guidance for using Markdown in Azure
DevOps features. You can use both common Markdown conventions and GitHub-flavored extensions.
Having the right guidance at the right time is critical to success. Use Markdown to add rich formatting, tables, and
images to your project pages, README files, dashboards, and pull request comments.
For additional syntax that's supported for Wiki pages, see Wiki Markdown guidance.
You can provide guidance in the following areas using Markdown:
Project wiki
Publish code as wiki
Markdown widget added to a dashboard
Project page or Welcome pages
Repository README files
Pull request comments
Definition of Done (Kanban board)
Project wiki
NOTE
Rich Markdown rendering in code repositories is supported for TFS 2018.2 and later versions. You can create rich
README.md files in the code repositories. The Markdown rendering of the MD files in code repositories supports HTML tags,
block quotes, emojis, image resizing, and mathematical formulas. There is parity in Markdown rendering in Wiki and MD files
in code.

NOTE
With TFS 2017.1, welcome pages, the Markdown widget on team dashboards, and the Definition of Done on Kanban boards
no longer supports file links in their Markdown. As a workaround, you can include your file link as text in the Markdown.

Headers
Structure your comments using headers. Headers segment longer comments, making them easier to read.
Start a line with a hash character # to set a heading. Organize your remarks with subheadings by starting a line
with additional hash characters, for example #### . Up to six levels of headings are supported.
Example:
# This is a H1 header
## This is a H2 header
### This is a H3 header
#### This is a H4 header
##### This is a H5 header
Result:
Paragraphs and line breaks

Make your text easier to read by breaking it up with paragraphs or line breaks.
In pull request comments, select Enter to insert a line break, and begin text on a new line.
In a Markdown file or widget, enter two spaces before the line break to begin a new paragraph, or enter two
consecutive line breaks to begin a new paragraph.
In pull request comments, select Enter to insert a line break, and begin text on a new line. In a Markdown file or
widget, enter two spaces prior to the line break to begin a new paragraph, or enter two consecutive line breaks to
begin a new paragraph.
In a Markdown file or widget, enter two spaces prior to the line break to begin a new paragraph, or enter two line
breaks consecutively to begin a new paragraph.
Example - pull request comment:
Add lines between your text with the Enter key.
This spaces your text better and makes it easier to read.
Result: Add lines between your text with the Enter key. This spaces your text better and makes it easier to read.
Example - Markdown file or widget:
Add two spaces prior to the end of the line.(space, space)

This adds space in between paragraphs.
Result:
Add two spaces prior to the end of the line.
Space is added in between paragraphs.
Block quotes
Quote previous comments or text to set the context for your comment or text.
Quote single lines of text with > before the text. Use many > characters to nest quoted text. Quote blocks of
lines of text by using the same level of > across many lines.
Example:
> Single line quote

>> Nested
>> multiple line
>> quote
Result:
Horizontal rules
To add a horizontal rule, add a line that's a series of dashes --- . The line above the line containing the --- must
be blank.
Example:
above
----
below
Result:
above
below
Emphasis (bold, italics, strikethrough)

You can emphasize text by applying bold, italics, or strikethrough to characters:
To apply italics: surround the text with an asterisk * or underscore _
To apply bold: surround the text with double asterisks ** .
To apply strikethrough: surround the text with double tilde characters ~~ .
Combine these elements to apply emphasis to text.
NOTE
There is no Markdown syntax that supports underlining text. Within a wiki page, you can use the HTML tag to
generate underlined text. For example, underlined text yields underlined text.
NOTE
There is no Markdown syntax that supports underlining text. Within a wiki page in TFS 2018.2 and later versions, you can
use the HTML tag to generate underlined text. For example, underlined text yields underlined text.
NOTE
There is no Markdown syntax that supports underlining text.
Example:
Use _emphasis_ in comments to express **strong** opinions and point out ~~corrections~~
**_Bold, italicized text_**
**~~Bold, strike-through text~~**
Result:
Use emphasis in comments to express strong opinions and point out corrections
Bold, italicized text Bold, strike-through text
Code highlighting
Highlight suggested code segments using code highlight blocks. To indicate a span of code, wrap it with three
backtick quotes ( ``` ) on a new line at both the start and end of the block. To indicate code inline, wrap it with one
backtick quote ( ` ).
Example:
```
sudo npm install vsoagent-installer -g
```
Result:
sudo npm install vsoagent-installer -g

Example:
To install the Microsoft Cross Platform Build & Release Agent, run the following: `$ sudo npm
install vsoagent-installer -g`.
Result:
To install the Microsoft Cross Platform Build & Release Agent run the following command:
$ sudo npm install vsoagent-installer .
Within a Markdown file, text with four spaces at the beginning of the line automatically converts to a code block.
Set a language identifier for the code block to enable syntax highlighting for any of the supported languages.
``` language
code
```
Additional examples:
``` js
const count = records.length;
```
const count = records.length;
``` csharp
Console.WriteLine("Hello, World!");
```
Console.WriteLine("Hello, World!");
Tables
Organize structured data with tables. Tables are especially useful for describing function parameters, object
methods, and other data that has a clear name to description mapping. You can format tables in pull requests, wiki,
and Markdown files such as README files and Markdown widgets.
Place each table row on its own line
Separate table cells using the pipe character |
The first two lines of a table set the column headers and the alignment of elements in the table
Use colons ( : ) when dividing the header and body of tables to specify column alignment (left, center, right)
To start a new line, use the HTML break tag ( ) (Works within a Wiki but not elsewhere)
Make sure to end each row with a CR or LF.
A blank space is required before and after work item or pull request (PR ) mentions inside a table cell.
Example:
| Heading 1 | Heading 2 | Heading 3 |
|-----------|:-----------:|-----------:|
| Cell A1 | Cell A2 | Cell A3 |
| Cell B1 | Cell B2 | Cell B3 second line of text |
Result:
HEADING 1 HEADING 2 HEADING 3
Cell A1 Cell A2 Cell A3
Cell B1 Cell B2 Cell B3

second line of text
Lists
Organize related items with lists. You can add ordered lists with numbers, or unordered lists with just bullets.
Ordered lists start with a number followed by a period for each list item. Unordered lists start with a - . Begin
each list item on a new line. In a Markdown file or widget, enter two spaces prior to the line break to begin a new
paragraph, or enter two line breaks consecutively to begin a new paragraph.
Ordered or numbered lists
Example:
1. First item.
2. Second item.
3. Third item.
Result:
1. First item.
2. Second item.
3. Third item.
Bullet lists
Example:
- Item 1
- Item 2
- Item 3
Result:
Item 1
Item 2
Item 3
Nested lists
Example:
1. First item.
- Item 1
- Item 2
- Item 3
1. Second item.
- Nested item 1
- Nested item 2
- Nested item 3
Result:
1. First item.
Item 1
Item 2
Item 3
2. Second item.
Nested item 1
Nested item 2
Nested item 3
Links
In pull request comments and wikis, HTTP and HTTPS URLs are automatically formatted as links. You can link to
work items by entering the # key and a work item ID, and then choosing the work item from the list.
Avoid auto suggestions for work items by prefixing # with a backslash ( \ ). This can be useful if you want to use #
for color hex codes.
In Markdown files and widgets, you can set text hyperlinks for your URL using the standard Markdown link syntax:
[Link Text](Link URL)
When linking to another Markdown page in the same Git or TFVC repository, the link target can be a relative path
or an absolute path in the repository.
Supported links for Welcome pages:
Relative path: [text to display](/target.md)
Absolute path in Git: [text to display](/folder/target.md)
Absolute path in TFVC: [text to display]($/project/folder/target.md)
URL: [text to display](http://address.com)
Supported links for Markdown widget:

Supported links for Wiki:

Absolute path of Wiki pages: [text to display](/parent-page/child-page)
NOTE
Links to documents on file shares using file:// aren't supported on 2017.1 and later versions. This restriction has been
implemented for security purposes.
For information on how to specify relative links from a Welcome page or Markdown widget, see Source control relative links.
Example:
[C# language reference](https://msdn.microsoft.com/library/618ayhy6.aspx)
Result:
C# language reference
Source control relative links
Links to source control files are interpreted differently depending on whether you specify them in a Welcome page
or a Markdown widget. The system interprets relative links as follows:
Welcome page: relative to the root of the source control repository in which the welcome page exists
Markdown widget: relative to the team project collection URL base
For example:
WELCOME PAGE MARKDOWN WIDGET EQUIVALENT
/BuildTemplates/AzureContinuousDeploy.11.xaml /DefaultCollection/Fabrikam
Fiber/_versionControl#path=$/Tfvc
Welcome/BuildTemplates/AzureContinuousDeploy.11.xaml
./page-2.md /DefaultCollection/Fabrikam
Fiber/_versionControl#path=$/Tfvc Welcome/page-2.md
Anchor links
Within Markdown files, anchor IDs are assigned to all headings when rendered as HTML. The ID is the heading
text, with the spaces replaced by dashes (-) and all lower case. In general, the following conventions:
Punctuation marks and leading white spaces within a file name are ignored
Upper case letters are converted to lower
Spaces between letters are converted to dashes (-).
Example:
###Link to a heading in the page
Result:
The syntax for an anchor link to a section...
[Link to a heading in the page](#link-to-a-heading-in-the-page)
The ID is all lower case, and the link is case sensitive, so be sure to use lower case, even though the heading itself uses
upper case.
You can also reference headings within another Markdown file:
[text to display](./target.md#heading-id)
In wiki, you can also reference heading in another page:
[text to display](/page-name#section-name)
Images
To highlight issues or make things more interesting, you can add images and animated GIFs to the following in
your pull requests:
Comments
Markdown files
Wiki pages
Use the following syntax to add an image:
![Text](URL)
The text in the brackets describes the image being linked and the URL points to the image location.
Example:
![Illustration to use for new users](https://azurecomcdn.azureedge.net/cvt-

779fa2985e70b1ef1c34d319b505f7b4417add09948df4c5b81db2a9bad966e5/images/page/services/devops/hero-
images/index-hero.jpg)
Result:
The path to the image file can be a relative path or the absolute path in Git or TFVC, just like the path to another
Markdown file in a link.
Relative path: ![Image alt text](./image.png)
Absolute path in Git: ![Image alt text](/_img/markdown-guidance/image.png)
Absolute path in TFVC: ![Image alt text]($/project/folder/_img/markdown-guidance/image.png)
Resize image: ![Image alt text]($/project/folder/_img/markdown-guidance/image.png =WIDTHxHEIGHT)
Checklist or task list

Lightweight task lists are great ways to track progress on a list of todos as a pull request creator or reviewer in the
PR description or in a wiki page. Select the Markdown toolbar to get started or apply the format to selected text.
You can Use [ ] or [x] to support checklists. You need to precede the checklist with either -<space> or
1.<space> (any numeral).
Example - Apply the task list Markdown to a highlighted list

After you've added a task list, you can check the boxes to mark items as completed. These are expressed and
stored within the comment as [ ] and [x] in Markdown.
Example - Format a list as a task list
- [ ] A
- [ ] B
- [ ] C
- [x] A
- [x] B
- [x] C
Result:
NOTE
A checklist within a table cell isn't supported.
Emoji
In pull request comments and wiki pages, you can use emojis to add character and react to comments in the
request. Enter what you're feeling surrounded by : characters to get a matching emoji in your text. The full set of
emojis are supported.
In pull request comments, you can use emojis to add characters and react to comments in the request. Enter what
you're feeling surrounded by : characters to get a matching emoji in your text. The full set of emojis are
supported.
Example:
:smile:
:angry:
Result:
To escape emojis, enclose them using the ` character.

Example:
`:smile:` `:)` `:angry:`
Result:
:smile: :) :angry:
Ignore or escape Markdown syntax to enter specific or literal characters

SYNTAX EXAMPLE/NOTES
To insert one of the following characters, prefix with Some examples on inserting special characters:
a \ (backslash).
Enter \\ to get \
\ , backslash
Enter \_ to get _
` , backtick
_ , underscore Enter \# to get #
{} , curly braces Enter \( to get (
[] , square brackets
Enter \. to get .
() , parentheses
# , hash mark
Enter \! to get !
+ , plus sign
- , minus sign (hyphen)
. , period
! , exclamation mark
Attachments
In pull request comments and wiki pages, you can attach files to illustrate your point or to give more detailed
reasoning behind your suggestions. To attach a file, drag and drop it into the comment field or wiki page edit
experience. You can also select the paper-clip icon in the upper right of the comment box or the format pane in
wiki page.
In pull request comments, you can attach files to illustrate your point or to give more detailed reasoning behind
your suggestions. To attach a file, drag and drop it into the comment field. You can also select the paper-clip icon in
the upper right of the comment box.
NOTE
Attachments in pull requests is available with TFS 2017.1 and later versions.
If you have an image in your clipboard, you can paste it from the clipboard into the comment box or wiki page and
it renders directly into your comment or wiki page.
Attaching non-image files creates a link to the file in your comment. Update the description text between the
brackets to change the text displayed in the link. Attached image files render directly into your comment or wiki
pages. After you save or update a comment or wiki page with an attachment, you can see the attached image(s)
and can select links to download attached files.
Attachments support the following file formats.
TYPE FILE FORMATS
Code CS (.cs), Extensible Markup Language (.xml), JavaScript Object

Notation (.json), Hypertext Markup Language(.html, .htm),
Layer (.lyr), Windows PowerShell script (.ps1), Roshal Archive
(.rar), Remote Desktop Connection (.rdp), Structured Query
Language (.sql) - Note: Code attachments aren't permitted
in PR comments
Compressed files ZIP (.zip) and GZIP (.gz)
Documents Markdown (.md), Microsoft Office Message (.msg), Microsoft

Project (.mpp), Word (.doc and .docx), Excel (.xls, .xlsx and .csv),
and Powerpoint (.ppt and .pptx), text files (.txt), and PDFs
(.pdf)
Images PNG (.png), GIF (.gif), JPEG (both .jpeg and .jpg), Icons (.ico)
Visio VSD (.vsd and .vsdx)
Video MOV (.mov), MP4 (.mp4)
NOTE
Not all file formats are supported within pull requests, such as Microsoft Office Message (.msg) files.
Mathematical notation and characters

Both inline and block KaTeX notation is supported in wiki pages and pull requests. The following supported
elements are included:
Symbols
Greek letters
Mathematical operators
Powers and indices
Fractions and binomials
Other KaTeX supported elements
To include mathematical notation, surround the mathematical notation with a $ sign, for inline, and $$ for block,
as shown in the following examples:
NOTE
This feature is supported within Wiki pages and pull requests for TFS 2018.2 or later versions.
Example: Greek characters
$
\alpha, \beta, \gamma, \delta, \epsilon, \zeta, \eta, \theta, \kappa, \lambda, \mu, \nu, \omicron, \pi, \rho,
\sigma, \tau, \upsilon, \phi, ...
$
$\Gamma, \Delta, \Theta, \Lambda, \Xi, \Pi, \Sigma, \Upsilon, \Phi, \Psi, \Omega$
Result:
Example: Algebraic notation
Area of a circle is $\pi r^2$
And, the area of a triangle is:
$$
A_{triangle}=\frac{1}{2}({b}\cdot{h})
$$
Result:
Example: Sums and Integrals

$$
\sum_{i=1}^{10} t_i
$$
$$
\int_0^\infty \mathrm{e}^{-x}\,\mathrm{d}x
$$
Result:
Related articles
README files
Markdown widget
Dashboards
Widget catalog
Add and edit Wiki pages
Frequently Asked Git Questions
Is there an easy way to get a remote branch downloaded into my local repository?
As long as you have an origin repository configured (which happens automatically via git clone ), when you
checkout a branch that doesn't exist locally Git will see if there is a remote branch with the same name. If there is,
Git will create a local branch with a reference to the remote branch of that name. Then you can git pull to
download the commits and have Git catch up on the branch history locally.
How can I find out which branch I am working in?
git branch with no arguments shows the local branches and highlights the one you are checked out on. In Visual
Studio, the status bar also displays the current branch when you are working with a project stored in a local Git
repository.
When should you make Git commits?
This is up to you and your team. An accepted practice is to make separate commits for logically separate changes.
Think of commits as entries in a logbook-whenever you've made a change that's worth noting, record it in a
commit. A popular option is to allow everyone to commit locally as much as they want, but before they push the
local commits, they squash them first through rebasing. This gives users a lot of personal flexibility to make
frequent commits while keeping the commit history streamlined.
If every branch retains its full commit history even when merged into master, doesn't that make the commit
history of master hard to follow over time?
Large projects with many commits and a range of contributors can result in commit histories for the master
branch that represent the development history of the topic branches merged into master more than the
development history of the overall project. Git provides a facility for condensing commits on branches through
squashing commits and rebasing. Squashing commits makes the commit history on a branch less verbose and
makes for a simpler commit history on the master branch once merged.
How can I find out who made a specific change to a file in my Git repository?
The git blame command can quickly track down who made a particular change to a file. From your local
repository, you can run git blame with the -L parameter specifying which lines of interest. Blame produces
formatted output showing the commit that last updated the line as well as the name of the person who made the
commit.
> git blame foo.js -L 20,+40 # show the blame output for the next forty lines starting at line 20
215d1108 (Francis Totten 2015-11-21 09:54:23 -0800 20) line 20 of the code
Blame does the searching through the commit history for you. You can also go back through the a file's history in
the web portal as well for a different approach to determining who made a change and when. Go into the Code
Explorer for your repository and branch, then click on the file of interest. Azure Repos will show a complete
commit history for that file on the current branch.
I've made changes to some files and now I can't checkout to a different branch or rebase my work.
Checking out to a different branch in Git will affect the state of files on your filesystem as Git uses the commit
history to make sure you are working with the files that represent the state of your branch. If you attempt to
change branches while you have uncommitted changes, those changes would be overwritten during the checkout.
Git doesn't want you to accidentally lose your changes, so it prevents the checkout from happening. You can
resolve this by:
Abandoning the changes and return to the most recent commit. See undoing changes in Git for instructions on
how to roll back to the most recent commit.
Committing the changes. See saving your work in Git with commits.
Stashing your current work, saving the changes for later and cleaning up the workspace to the last commit.
I've done some work but need to swap to something else. How can I save my work for later without committing
the changes?
The problem with these options is that sometimes you want to keep the changes, but not commit them because
they are not at a point where you are comfortable doing so. Git provides a compact way of doing this using stash .
Stash takes the current staged and unstaged changes in your branch and saves the work, then returns your branch
back to the state of the last commit. You can change to the other branch, do your work, then when you return to
this branch run stash apply to restore the changes.
> git stash

Saved working directory and index state WIP on feature1: be26067 updated endpoint docs
HEAD is now at be26067
Once you run git stash apply the most recently stashed changes will be applied to your current branch. If there is
a conflict applying the stashed changes, stash will restore the changes for the files that do not conflict and create
conflict markers in the files that do conflict for you to resolve. You should merge the changes manually in this case.
Once you are done with the stash, delete it with git stash drop . This will remove the last set of stashed changes.
A final note about stash is that you can have multiple stashes, but doing so requires more manual manipulation as
you have to explicitly apply and drop stashes. You can read more about this from in the Git Stash documentation.
How can I change the default editor that is used when working with Git command line tools?
By default, command line Git will use a command-line editor when asking for commit messages, performing
rebases, and other work that requires additional information to complete. The default editor is configured using
git config :
> git config core.editor _path_to_editor_ _options_to_editor_
Note that Git For Windows makes it very easy to set notepad as the editor:
> git config core.editor notepad
Which will configure Windows' Notepad to edit Git information as needed and properly pass through the text
from Git to Notepad. You can also specify
> git config format.commitMessageColumns 72
To keep the text columns in the commit messages to the preferred 72 and line wrap after hitting that character limit
on a line.
How can I change the username and email displayed in my commits?
Git puts a user name and email address information inside each commit, and Azure Repos uses this information
when viewing commits and when working with pull requests. If you are working on the command line, you can
update the name and email information displayed using the git config command:
> git config --global user.email "frank@fabrikam.com"
> git config --global user.name "Francis Totten"
Note that the --global option will set the email and name included in commits for all Git repositories on this
system. If you want to change the settings for a single repository, you must change to the directory where the Git
repository is located and run the above commands without the --global flag.
You can also change the name and email settings from Visual Studio. In Team Explorer, choose Settings and under
Git, click the Global Settings or Repository Settings link.
Commit history
Commit history view

The commit history view shows you the history of all the commits for a particular branch in a repository. By
default, all results are shown in reverse chronological order.
For each commit, you can view the following key elements:
Author details - You can view the author and committer of each commit along with the associated time.
Complete commit message - If the commit message is too long, you can click on the down-arrow to expand
the commit message to view the entire commit message.
Copy commit SHA - You can copy the 40 character commit SHA by clicking on the Copy full SHA to
clipboard button. You can click on a commit ID or commit message to open the commit details page.
Build and PR information - You can view the pull request that brought this commit to the branch selected
on the page, and view the build status of the current commit.
You can select a repository from the repository picker to view the history of a particular repository.
You can select a particular branch or tag from the branch picker to view associated history.
You can further filter the results by selecting a particular file from the code explorer.
You can also find a file or folder to view its history. In the following example, when you type "get", you see
results of all files and folders in the repository that contain the word src.
History result filtering
You can filter the results using the following advanced filtering modes: simple history, first parent, full history,
and full history with simplified merges. For more information, see advanced git history options.
You can also filter commits by authors. You will see authors of most recent commits in the author filter drop down.
In case you are not able to find an author in the drop down, then you can type the author name or email address
and search for all commits by that author.
In case you want to view commits that were authored between any two dates, you can use the From date and To
date filter to scope down the list of commits.
Commit search
You can also search for a commit using its Commit ID. You can search for all commits starting with a commit ID. If
you enter the 40 character Commit ID then you will be redirected directly to the commit details page.
Commit for file renames
In case a file or folder is renamed, you will see all commits until the file or folder got renamed. You will also see a
link suggesting Show rename history.
When you click on Show rename history you can view all the commits of the file or folder before the rename.
Commit details
Commit details view

The commit details view provides information regarding all the changes made as part of a commit. You can view
additional metadata associated with the commit and also perform certain actions to revert or cherry pick the
commit.
What information do you see on the commit details page?

Commit ID and commit message - You can view the commit Id and commit message of the commit. You
also have the option to copy the commit Id or commit message by clicking on the Copy buttons.
Author details - You can also view the author, committer, and pusher details in the author drop-down. Click
on the Pushed on link to access the associated push details
Associated pull requests - Once you navigate from the commit history to the commit details, the context of
the branch from the commit history page is retained. In the following example you can see that commit #33
brought this commit to the master branch. You can also view all the associated pull requests for this commit,
which are all the pull requests that brought this commit to one branch or another.
Associated work items - You can also view all the work items associated with this commit in the work items
dropdown.
Build status - You can also review the build status associated with the commit.
What actions can you perform?

You can perform the following actions on the commit details page.
Search in branches and tags - Click the Search in branches button to search a commit in a particular
branch or tags. You can view whether a particular branch or a tag includes this commit or not.
Cherry pick - Click on Cherry-pick to cherry pick a commit and port the changes to another branch.
Revert - Click on Revert to revert the changes of a commit . A topic branch is created with the reverted
changes and then you will be prompted to create a pull request to the target branch.
New branch - Click on New branch to create a new branch from a commit.
What are the changes included in the commit?
The source explorer allows you to select a file or a folder to view changes associated with a commit.
Diff to parent - Click on Diff on parent1 in the Source Explorer pane to view the difference between the
current commit and its parent commit.
The file explorer view provides all the capabilities that we get in the file explorer view i.e. you can
browse files in a side by side or inline diff view
use the navigation keys to browse the next set of changes
preview the files
compare file diff for previous commits
Default Git repository and branch permissions
Azure DevOps Services | Azure DevOps Server 2019 | TFS 2018 | TFS 2017 | TFS 2015 | TFS 2013
After you've been added as a team member, you are a member of the Contributors group. This membership allows
you to contribute to a Git repository. The most common built-in groups include Readers, Contributors, and Project
Administrators. These groups are assigned the default permissions for contributing to a branch or repository.
From the project admin content, on the Version Control page, you can set permissions on a repository.
From the Code > Branches page, you can set permissions for a specific branch and set branch policies.
Set permissions across all Git repositories by making changes to the top-level Git repositories entry. Individual
repositories inherit permissions from the top-level Git Repositories entry. Branches inherit a subset of
permissions from assignments made at the repository level. For branch permissions and policies, see Set branch
permissions and Improve code quality with branch policies.
TASK READERS CONTRIBUTORS BUILD ADMINS PROJECT

ADMINS
Clone, fetch, and explore the contents of a repository; also,

can create, comment on, vote, and contribute to pull
requests
Contribute to a repository, create branches, create tags,

manage notes
Create, delete, and rename repositories
Edit policies, Manage permissions, Remove others' locks
Bypass policies when completing pull requests, Bypass

policies when pushing, Force push (rewrite history, delete
branches and tags) (not set for any security group)
By default, the project-level Readers groups have read-only permissions.
TASK CONTRIBUTORS BUILD ADMINS PROJECT ADMINS
Branch Creation: At the repository level, can push their changes to

branches in the repository. Does not override restrictions in place
from branch policies. At the branch level, can push their changes to
the branch and lock the branch.
Contribute: At the repository level, can push their changes to

Note Management: Can push and edit Git notes to the repository.
They can also remove notes from items if they have the Force
permission.
Tag Creation: Can push tags to the repository, and can also edit or
remove tags if they have the Force permission.
Administer: Delete and rename repositories

If assigned to the top-level Git repositories entry, can add
additional repositories. At the branch level, users can set
permissions for the branch and unlock the branch. The
Administer permission set on an individual Git repository does
not grant the ability to rename or delete the repository. These
tasks require Administer permissions at the top-level Git
repositories entry.
Rewrite and destroy history (force push): Can force an update to

a branch and delete a branch. A force update can overwrite commits
added from any user. Users with this permission can modify the
The Project Collection Build Service can read from all repositories by default. Any pipeline which runs with project
collection scope can potentially read any repository in the organization/collection. You can remove this permission
for a repository: set "Read" to "Deny" for the Project Collection Build Service.
Related articles
Set repository permissions for Git or TFVC
Set permissions for a specific branch and set branch policies
Git permissions prior to TFS 2017 Update 1
Default permissions and access
Permissions and groups reference
Git limits
Azure Repos
We impose a few resource limits on Git repositories in Azure Repos. Our goal is to ensure reliability and availability
for all customers. Also, by keeping the amount of data and number of pushes reasonable, you can expect to have a
better overall experience with Git.
Git participates in rate limiting along with the rest of Azure DevOps. In addition, we impose limits on the total size
of repositories and pushes.
Repository size
Repositories should generally be no larger than 10GB. You can run git count-objects -vH in a command prompt,
and look for the entry called "size-pack" to determine how large your repository is:
D:\my-repo>git count-objects -vH
count: 482
size: 551.67 KiB
in-pack: 100365
packs: 25
size-pack: 642.76 MiB <-- size of repository
prune-packable: 83
garbage: 0
size-garbage: 0 bytes
In uncommon circumstances, repositories may be larger than 10GB. For instance, the Windows repository is at
least 300GB. For that reason, we do not have a hard block in place. If your repository grows beyond 10GB,
consider using Git-LFS, GVFS, or Azure Artifacts to refactor your development artifacts.
Push size
Very large pushes use up a lot of resources, blocking or slowing other parts of the service. Such pushes often don't
map to normal software development activities. Someone may have inadvertently checked in build outputs or a
VM image, for example. For these reasons and more, pushes are limited to 5GB at a time.
There's one exception where large pushes are normal. When you migrate a repository from another service into
Azure Repos, it comes in as a single push. We don't intend to block imports, even of very large repositories. If the
repository is more than 5GB, then you must use the web to Import the repository instead of the command line.
Whether your software project is large or small, using version control as soon as possible is a good idea. Version control systems
are software that help you track changes you make in your code over time. As you edit your code, you tell the version control
system to take a snapshot of your files. The version control system saves that snapshot permanently so you can recall it later if
you need it.
Azure DevOps Services and TFS provide two models of version control: Git, which is distributed version control, and Team
Foundation Version Control (TFVC ), which is centralized version control. This article provides an overview and a starting point for
using Team Foundation Version Control. If you're deciding which type of Azure DevOps Services/TFS version control to use, see
Choosing the right version control for your project.
5-Minute Quickstarts
Get started by creating a project, configuring your workspace, and reviewing and sharing your code. You can use any one of these
clients or IDEs:
Visual Studio
Xcode
Eclipse
Step-by-Step Tutorials
Learn the basics of working in TFVC with the following tutorial which shows a day in the life of a devops developer using Visual
Studio and TFVC.
Day in the life of a devops developer: suspend work, fix a bug, and conduct a code review
Visual Studio: Review Code
Resources
Learn more about TFVC
Use Team Foundation Version Control
Whether your software project is large or small, using version control as soon as possible is a good idea. Version
control systems are software that help you track changes you make in your code over time. As you edit your code,
you tell the version control system to take a snapshot of your files. The version control system saves that snapshot
permanently so you can recall it later if you need it.
Azure DevOps Services and TFS provide two models of version control: Git, which is distributed version control,
and Team Foundation Version Control (TFVC ), which is centralized version control. This article provides an
overview and a starting point for using Team Foundation Version Control. If you're deciding which type of Azure
DevOps Services/TFS version control to use, see Choosing the right version control for your project.
Why use version control?

Without version control, you're tempted to keep multiple copies of code on your computer. This is dangerous, as
it's easy to change or delete a file in the wrong copy of code, potentially losing work. Version control systems
solve this problem by managing all versions of your code but presenting you with a single version at a time.
Version control systems provide the following benefits:
Create workflows - Version control workflows prevent the chaos of everyone using their own development
process with different and incompatible tools. Version control systems provide process enforcement and
permissions so everyone stays on the same page.
Work with versions - Every version has a description for what the changes in the version do, such as fix a bug
or add a feature. These descriptions help you follow changes in your code by version instead of by individual
file changes. Code stored in versions can be viewed and restored from version control at any time as needed.
This makes it easy to base new work off any version of code.
Code together - Version control synchronizes versions and makes sure that your changes don't conflict with
other changes from your team. Your team relies on version control to help resolve and prevent conflicts, even
when people make changes at the same time.
Keep a history - Version control keeps a history of changes as your team saves new versions of your code.
This history can be reviewed to find out who, why, and when changes were made. History gives you the
confidence to experiment since you can roll back to a previous good version at any time. History lets you base
work from any version of code, such as to fix a bug in a previous release.
Automate tasks - Version control automation features save your team time and generate consistent results.
You can automate testing, code analysis, and deployment when new versions are saved to version control.
There are plenty of things that can take up your time as a developer: reproducing bugs, learning new tools, and
adding new features or content. As the demands of your users scale up, version control helps your team work
together and ship on time.
Team Foundation Version Control

Team Foundation Version Control (TFVC ) is a centralized version control system. Typically, team members have
only one version of each file on their dev machines. Historical data is maintained only on the server. Branches are
TFVC lets you apply granular permissions and restrict access down to a file level. Because your team checks in all
their work into your Team Foundation server, you can easily audit changes and identify which user checked in a
changeset. By using compare and annotate you can identify the exact changes that they made.
What do you want to do?

Set up your dev machine and get started
Spend a few minutes to set up your dev machine to take advantage of all the benefits of a version-
controlled codebase.
Choose your workflow model - server or local workspaces
Server workspaces - Before making changes, team members publicly check out files. Most
operations require developers to be connected to the server. This system facilitates locking
workflows. Other systems that work this way include Visual Source Safe, Perforce, and CVS. With
server workspaces, you can scale up to very large codebases with millions of files per branch and
large binary files.
Local workspaces - Each team member takes a copy of the latest version of the codebase with
them and works offline as needed. Developers check in their changes and resolve conflicts as
necessary. Another system that works this way is Subversion.
Develop your app in a version-controlled codebase
You don't have to think about version control in most situations. The system supports you when you need
to manage and understand your changes.
Suspend your work
Sometimes you need to set aside some or all of the work you are doing. Your version control system can
take away some of the pain and reduce the time wasted by interruptions.
Contribute your work to the team
Check in your changes so your team can build upon, test, and release the value you've created.
Isolate risk
Use branches and locks to isolate risk introduced by work done by different teams.
View and manage past versions
One advantage of a version control system is that you can look back in time to get detailed information
about what changes have been made to your files.
Compare folders and files
You can compare server folders and local folders to each other, and view the differences between the
contents of each folder.
Resolve Team Foundation Version Control conflicts
A big advantage of using version control is that several people can work concurrently on a file. One
drawback is that sometimes you must resolve conflicts. Although it can be frustrating to encounter
conflicts, the system provides information and tools to help you understand and resolve conflicts.
Work with version control locks
When you need to prevent a file or folder from being checked out and altered, you can lock it.
Related Sections
Build and test the app in your automated build system
Install a bit of software to create a build server, and then fill in a few fields to create a Continuous
integration (CI) or nightly build process that enables you to leverage the power, convenience, scalability,
and reliability of an automated build system to build your app.
Naming restrictions in Team Foundation
Provides information about naming syntax, conventions, and limitations.
Learn about TFVC permissions
We are not currently republishing the following sections. However, you can read the Visual Studio 2010 version of
this guidance.
Administering Team Foundation Version Control
Develop and share your code in TFVC using Visual
Studio
Whether your software project is large, small, or brand new, in most cases you'll be better off if you use version
control as early as possible. Here, we'll show you how to get started with Team Foundation Version Control
(TFVC ), a centralized system. If you want to work in a distributed system, you can instead use Git with Azure
Repos.
Is your code in another place? Learn how to migrate it here.
Open your project in Visual Studio

1. Before you start, if you haven't already:
Sign up and create your project.
Install Visual Studio 2013 or later.
2. Go to your project's page ( http://dev.azure.com/{your organization}/{your team project} ) and then open
Visual Studio to connect to your project.
3. Sign in to Azure DevOps Services from Visual Studio.
Configure your workspace

1. In Visual Studio, configure your workspace.
I don't see the Configure Workspace link. What do I do next?

2. Confirm your workspace path, map your workspace, and get the source.
3. Now you can check in source, queue builds, and manage work.
Create a new app

If you already have an app that you want to add to version control, skip down to Add an existing app.
Now that you've added your app, you can skip down to snapshot your code.
Add an existing app

Move and open the solution
1. Close the solution.
2. Open the workspace folder that you created when you configured your workspace.
3. Move the code you want to upload to the workspace folder.
4. Open your solution in Visual Studio.
Add the solution to Azure Repos

1. Open the solution explorer (Keyboard: Ctrl + Alt + L ).
2. Add your solution to version control.
3. Check in the solution.
4. Add a comment and check in.

5. Open the source control explorer.
Your solution is now in TFS.
Your whole team can work on the code now. All your changes are tracked in version control.
Snapshot (check in) your code

1. When you edit code in Visual Studio, the changed file is automatically checked out. For example, Site.css is
checked out after the border color has been changed to #ddd.
2. Compare the modified file with the latest version in source control.
You can see the difference between the two versions.

3. Check in the changes.
You can also check in from the code window, or the team explorer.
4. If you're working on a task or fixing a bug that's tracked as a work item, add that work item to your pending
changes. Source control will resolve the bug or close the task, and it'll link the changeset to the work item.
5. Add a comment and check in.
6. Open the source control explorer.
7. View the history of the file you changed.
All the changesets that include this file are listed.

Troubleshooting
My code is somewhere else. Can I migrate it to my TFVC project on Azure DevOps Services?
I don't see the Configure Workspace link shown in the steps above. What do I do next?
My code is somewhere else. Can I migrate it to my TFVC project on Azure DevOps Services?
Yes:
Upgrade From Visual SourceSafe.
Migrate from Team Foundation Server into Azure DevOps Services.
I don't see the Configure Workspace link shown in the steps above. What do I do next?
You might already have a workspace on your computer. To see your workspace, open Source Control Explorer. Or
change your workspace. Find out how to manage files under source control or manage workspaces.
Next steps
Get your code reviewed
Share your code in TFVC using Eclipse
Share your code with your team with Azure DevOps Services and Eclipse.
Before you start:
1. If you don't have an organization, create it first.
2. If you have not yet connected to a project in your organization, do that now.
If your project uses TFVC in your Azure DevOps organization, read on. However, if your project uses Git in your
Azure DevOps organization,then read Share your code in Git using Eclipse
Share using TFVC

1. If you haven't yet, Connect to Azure DevOps Services using Eclipse.
2. In Package Explorer, right-click the project and choose Team, Share Project.
3. Make sure you share it to Team Foundation Server.
4. Select the server and project.

5. Check in the files.
Your code is in TFVC, so now your teammates can contribute.
Next steps
Build your Eclipse projects
Share your code in TFVC using Xcode
Share your Xcode projects using a TFVC repository by using the Git-tf command line tool to push your changes
from the local Git repository to TFVC.
Download and configure Git-tf

1. Download and extract Git-tf.
2. Add Git-tf and the Java runtime to your path.
export JAVA_HOME=/Library/Java/Home
export PATH=$PATH:$JAVA_HOME/bin:/git_tf
3. Go to the root of your local repository.
pushd /ws/FabrikamFiber
4. To share your Git repository in Azure Repos, configure the connection and check in your code. You'll be
prompted for credentials.
git tf configure https://fabrikamfiber.visualstudio.com $/FabrikamFiber

git tf checkin
Or, if your team's code is already in Azure Repos, you can clone a local repository using Git-tf.
git tf clone https://fabrikamfiber.visualstudio.com $/FabrikamFiber
5. If you don't want to be prompted for credentials every time you run Git-tf, you can store your credentials in
your Git configuration.
git config git-tf.server.username fabrikamfiber4@hotmail.com

git config git-tf.server.password mypassword
Share your code

1. After you commit changes to your local Git repository, and you're ready to share them in Azure Repos,
check them in.
git commit -a
git tf checkin
If you've committed multiple changes locally, you'll still get just one changeset in Azure Repos.
2. Resolve a bug or close a task when you check in by providing the work item ID with the resolve flag.
git tf checkin --resolve=21972
The changeset and the work item are linked, and you'll be able to see which bugs are resolved and which
tasks were completed in the build reports.
3. You can make sure you're working with your team's latest code by pulling from Azure Repos.
git tf pull
Use git tf help to learn about the Git-tf commands.
Additional information
Should I use Git or TFVC for my project?
If my project uses Git Version control, can I still share my Xcode projects in Azure DevOps Services?
Should I use Git or TFVC for my project?
That depends on a number of factors, like the size of your codebase and the size and distribution of your team.
Learn which version control (Git or Team Foundation Version Control) works best for you.
If my project uses Git Version control, can I still share my Xcode projects in Azure DevOps Services?
Yes, see Share your code in Git using Xcode.
Next steps
Choosing the right version control for your project
Day in the life of a devops developer: suspend work,
fix a bug, and conduct a code review
A powerful one-click way to switch your working context from one thread of work to another is available in Visual
Studio Premium and Visual Studio Ultimate with Team Foundation Server. Also, team members can easily
exchange messages about proposed changes to the code. This topic illustrates these features, continuing a tutorial
that follows members of a fictitious agile team for a day.
Peter has been busy writing some code to fulfill a backlog item task. However, his colleagues have found a bug
that is blocking them, and he wants to fix it immediately. He suspends the work that he's doing and fixes the bug.
He asks Julia to review the fix and, after the review, checks in the fix and resumes work on his original task.
Note: The My Work and Code Review features that Peter uses are available only in Visual Studio Premium
and Visual Studio Ultimate.
Suspend current work

As Peter works on a backlog item, Julia comes to discuss a bug that is blocking her. It is in an area with which
Peter is familiar, so he creates a task to fix the bug and assigns it to himself. He decides to start work on the fix
immediately.
Before he starts to work on the new bug, Peter wants to make sure that his current work is set aside in a safe place
on the team's server. On the My Work page, Peter chooses Suspend to save (on Team Foundation Server):
All the work he has done, including changes to code, tests, and other files.
Open solutions, windows, breakpoints, watch window variables, and other bits of Visual Studio state.
Now that his workspace is clean, Peter drags the new task from Available Work Items to In Progress Work.
He's ready to research and write the fix.
Note: Your working context is linked to the work items that show as In Progress on the My Work page. By
using Suspend and Resume, you can quickly switch between different tasks. Your open solutions and files,
code changes, and Visual Studio layout are all switched together.
To suspend current work and begin work on a different task

1. Connect: If you are not already connected to the project that you want to work in, then connect to the
project:
a. In Team Explorer, choose Home, and then choose My Work.
2. Suspend your current task:
a. In the In Progress Work section, choose Suspend.
b. In the box that appears, specify the name that you want to give this set of suspended work, and then
choose the Suspend button. The default name is your currently in progress work item.
3. Start work on a new task, bug, or other work item:
a. Before selecting a work item, you might want to:
Create a new task or other work item by choosing New under Available Work Items; or
Select a different query under Available Work Items.
b. Drag a work item from Available Work Items to In Progress Work.
Alternatively, you can switch to a work item that you previously suspended by dragging it from
under Suspended Work.
Tip: The currently In Progress work items link to your current code changes and Visual Studio state. To allow
Visual Studio to help you organize your work, make sure that the appropriate items are in the In Progress
state when you switch from one task to another.
Investigate the bug

Peter opens and reads the bug work item. According to the description that has been written by a member of the
test team, a paid invoice is sometimes incorrectly flagged as unpaid. There is a lab environment snapshot attached
to the bug work item. Peter is able to open the virtual machines on which the test was run, see the incorrect
invoice, and step back through the IntelliTrace log. He traces the fault to the following method:
public class LocalMath
{
public static bool EqualTo(double a, double b)
{
return a == b;
}
From the IntelliTrace log, Peter sees that sometimes the method returns false because the parameters differ by an
extremely small amount. Peter knows that rounding errors of this kind are unavoidable in floating point
arithmetic, and that it is bad practice to test floating point numbers for equality.
Augment the tests to show the error

When a bug is found, it shows that there was a gap in the unit tests, or that the test did not match the users' actual
needs. Therefore, before fixing the bug, Peter adds a test that will demonstrate the presence of this error.
// Added 2012-02-02 for bug 654321:

/// <summary>
/// Make sure that number equality test allows for
/// small rounding errors.
/// </summary>
[TestMethod]
public void TestDoublesEqual()
{
// We allow a rounding error of 1 in 1000000:
TestEqual(1, 1e-7, true); // Less than allowed error
TestEqual(1, 1e-5, false); // More than allowed error
}
private void TestEqual(double value, double error, bool result)
{
// Try different combinations of error and value:
Assert.IsTrue(result == LocalMath.EqualTo(value + error, value));
Assert.IsTrue(result == LocalMath.EqualTo(value, value + error));
Assert.IsTrue(result == LocalMath.EqualTo(value - error, value));
Assert.IsTrue(result == LocalMath.EqualTo(value, value - error));
}
He runs the test and it fails as expected.
Make the tests pass

Peter fixes the code:

{
// Allow for rounding errors.
// For example, a == 2.0 and b = 1.99999999999
const double allowedError = 1/1000000;

return System.Math.Abs(a - b) < allowedError;
}
The test now passes:
Request a code review

Peter is satisfied with his fix for the bug, but he does not check in his work yet. His team uses code reviews to
increase overall code quality and reduce the risk of creating more bugs, so Peter uses Team Explorer to request a
code review from his teammates Julia and Adam.
To request a code review
1. In Team Explorer, on the My Work page, choose Request Review.
The New Code Review page appears.
2. Specify one or more reviewers.
3. Specify the name of the review.
4. Specify the area path.
5. Specify a comment to your reviewers.
6. Choose Submit Request.
The reviewers will be notified of the request by email.
You can also request a code review of suspended work, a shelveset, or a changeset. To see a list of changesets,
open Source Control Explorer and choose the History button.
Accept or decline a code review

Julia receives the code review request and accepts it. She reviews the code, writes some comments at the file- and
code-block levels, and then sends the code review back to Peter. Adam is too busy to review the code and declines.
In her comments, Julia points out that the test is wrong. The allowable error should be a specified fraction of the
input values, not a constant quantity. So the test should multiply the error by the value.
// We allow a rounding error of 1 in 1000000

// as a fraction of the value:
TestEqual(1000, 1000*1e-7, true); // Less than allowed error
TestEqual(1000, 1000*1e-5, false); // More than allowed error
Tip: Notice that the team members use the tests as a focus for discussion. If the tests are correct and
sufficient, the code will be also. Unlike the code, each test represents a separate case. For this reason, the tests
are often easier to discuss than the code.
To perform a code review

1. In Team Explorer, on the My Work page, go to the My Code Reviews & Requests section and open the
request.
2. On the Code Review page, you can:
Choose Accept or Decline to notify the author whether you will perform the review.
Choose Add Reviewer to add other reviewers to the code-review request.
View the changes to each file that has been updated for this work item.
Expand Comments to discuss the changes with the author and other reviewers.
Choose Add Overall Comment
-or-
Select a block of code and then choose Add Comment from the shortcut menu.
Choose Send Comments to make your contributions visible to the author and other reviewers.
Choose Send and Finish to complete your review, indicating whether the code needs more work.
Respond to a code review

Peter receives and responds to the code review from Julia.
To respond to a code review
The reviewers and author of the code can exchange comments as often as they like. The review ends when the
author closes it. With each contribution to the discussion, the other participants will be notified by email.
1. In Team Explorer, on the My Work page, go to the Code Reviews & Request section and double-click
the request.
You can also open the shortcut menu for the request and choose Open.
2. Read the comments and reply to them as needed. To reply to a comment, choose Reply, enter your
comment in the box that appears, and then choose OK. To send your comments, choose Send Comments.
3. To view a file and see the code-blocks that have comments, or to edit a file, go to the Comments section. In
the Files sub-section, open the shortcut menu for the file and choose either Compare (Read-Only) or
Edit File.
4. When you and the other reviewers finish responding to each other's comments and you are ready to close
the review, click Close Review, and then choose either:
Complete to indicate that the review is finished.
-or-
Abandon to indicate you are canceling the review.
Fix the test and the code

Having read Julia's comments, Peter fixes his unit test as she suggests. The test now fails. This shows that the code
is not yet correct.
Peter fixes the code:
/// <summary>
/// Returns true if two numbers are equal.
/// </summary>
{
// Allow for rounding errors.
const double allowedErrorMultiple = 1/1000000;
double allowedError = (System.Math.Abs(a) + System.Math.Abs(b)) * allowedErrorMultiple/2;
return System.Math.Abs(a - b) < allowedError;
}
The test passes once again:
Tip: To fix a bug, follow the same practice as in code development. Write a test that fails and then make the
test pass. Check in the code and the tests only when the tests pass.
Peter now turns his attention to the test case in which the bug was discovered. The steps to reproduce the bug are
clearly described in the test case work item. He follows the steps and discovers that the invoices are correctly
listed.
Check in the fix

Peter checks in the fixed code and the unit tests. The state of the bug is automatically set to Resolved, and the
Assigned To value is automatically reassigned to the member of the test team who discovered the bug. That team
member will verify that the bug has been fixed and close the work item.
To check in the fix
1. In Team Explorer, on the My Work page, choose Check In.
2. Review the contents of the Pending Changes page to make sure that:
All relevant changes are listed in Included Changes
All relevant work items are listed in Related Work Items.
3. Specify a Comment to help your team understand the purpose of these changes when they look at the
version control history of the changed files and folders.
4. Choose Check In.
Resume work on a task

Peter resumes work on his task. He is able to get back to work quickly because all his code changes are restored to
his workspace along with important bits of state such as open windows, breakpoints, and watch window variables.
To resume work on a task
In Team Explorer, on the My Work page, find the Suspended & Shelved Work list. Open the shortcut
menu for the item. You have two choices:
If you want to resume the suspended work and automatically suspend any pending changes in your
workspace, choose Resume.
If you want to merge the suspended work with pending changes already in your workspace, choose
Merge with In Progress.
When you resume your work
When you resume your

work, Visual Studio restores:
Your open solution
Your code changes
The state and position of open windows
Breakpoints
Watch window variables and expressions
Bookmarks
Get your code reviewed with Visual Studio
Before you check in your code, you can use Visual Studio to ask someone else from your team to review it. Your
request will show up in his team explorer, in the my work page.
To ask for a code review, make sure you have shared your code in TFVC.
(Are you using Git to share your code? If so, then use a pull request.)

Jamal has changed the border color in the Hello World app, and he asks Johnnie to review the change.
1. Before he checks in the change, Jamal goes to the my work page.
2. He requests a review.
3. He submits a request to Johnnie.

4. Jamal suspends his work on Hello World so that he can work on something else while he waits to hear back
from Johnnie.
Respond to the code review request

Johnnie will see the code review request in the team explorer, look at the changes, and give Jamal his feedback.
1. Johnnie opens the my work page.
2. He sees Jamal's code review request.
You can get email alerts for code reviews, too. If you aren't getting them, you can sign up in the team
explorer settings page.
3. Johnnie opens the code review request.

4. He accepts the review.
5. He opens the file that Jamal changed.

6. Johnnie sees that Jamal changed the color to #ddd. He selects the code in the difference window and adds a
comment (Keyboard: Ctrl + Shift + K).
7. He suggests a different color instead and sends the comment to Jamal.

Update the code based on the review feedback
1. When Jamal gets a response from Johnnie, he resumes the work on Hello World.
2. His changes are unshelved and the windows he had opened are restored, so he can incorporate the review
feedback.
Next steps
Create your backlog
Whether your software project is large or small, using version control as soon as possible is a good idea. Azure
Repos supports two types of version control: Git and Team Foundation Version Control (TFVC ).
Which version control system should I use?

Git is the default version control provider for new projects. You should use Git for version control in your projects
unless you have a specific need for centralized version control features in TFVC.
You can use TFVC repos with Git in the same Project so it's easy to add TFVC later if you need centralized version
control. To setup a new repo type for an existing project use these instructions.
Git (distributed)
Git is a distributed version control system. Each developer has a copy of the source repository on their dev
machine. Developers can commit each set of changes on their dev machine and perform version control
operations such as history and compare without a network connection. Branches are lightweight. When you need
to switch contexts, you can create a private local branch. You can quickly switch from one branch to another to
pivot among different variations of your codebase. Later, you can merge, publish, or dispose of the branch.
NOTE
Git in Visual Studio, Azure DevOps Services, and TFS is standard Git. You can use Visual Studio with third-party Git services,
and you can also use third-party Git clients with TFS.
To learn more, see Git and Azure Repos.

TFVC (centralized)
Team Foundation Version Control (TFVC ) is a centralized version control system. Typically, team members have
only one version of each file on their dev machines. Historical data is maintained only on the server. Branches are
TFVC has two workflow models:
Server workspaces - Before making changes, team members publicly check out files. Most operations
require developers to be connected to the server. This system facilitates locking workflows. Other systems
that work this way include Visual Source Safe, Perforce, and CVS. With server workspaces, you can scale
up to very large codebases with millions of files per branch and large binary files.
Local workspaces - Each team member takes a copy of the latest version of the codebase with them and
works offline as needed. Developers check in their changes and resolve conflicts as necessary. Another
system that works this way is Subversion.
To learn more, see TFVC overview
Moving from TFVC to Git
If you have existing TFVC repos, you can migrate them to Git repos using the git-tfs tool. The tool allows you to
migrate a TFVC repo to a Git repo in just a couple of commands.
Git and TFVC capabilities
Need more help to make a choice? These charts might help.
Capability TFVC Git
Changes Team members can concurrently Team members can concurrently

change files on their dev machines. change files on their dev machines.
You upload (check-in) changesets You create commits on your dev
to the server when you create machine independently of
them. You can upload your changes contributing them to the team.
at any time. However, you might be When you're ready you must pull
interrupted by conflicts. the latest commits before you
upload (push) yours to the server.
You can change the comment of a When you pull, you might be
changeset after you check it in. You interrupted by conflicts.
can link changesets to work items
and associate them with completed You can amend the latest local
builds. commit. You cannot change older
commits. You can link commits to
work items and associate them with
completed builds.
You can modify and combine local
commits from the command
prompt.
Branching Path-based branches are used Branching is lightweight and path

mostly as long-standing constructs independent. Many developers
to isolate risk of change among create a branch for each new
feature teams and releases. Team feature they are coding, sometimes
members typically set up an on a daily basis. You can quickly
additional workspace for each switch from one branch to another
branch they work on. to pivot among different variations
of your codebase. You can create
Changes in each branch are branches that exist only on your
independent from each other, so dev machine and share them if and
you don't have to check them in when you're ready.
before switching from one branch
to another. Merging between You must commit, branch, stash, or
sibling branches requires a baseless undo changes before switching
merging. branches. Merging is simple and
independent of the commit that
You can get visualizations of your the branch is based on.
branch structures and where your
changesets have been merged. You can compare branches to see
which commits exist on which
See Use branches to isolate risk in branches.
Team Foundation Version Control.
See Use Git branches to switch
contexts, suspend work, and isolate
risk.
Conflict resolution You might have to resolve conflicts You might have to resolve conflicts
when you get, check in, merge, or when you pull or merge. You can
unshelve. You can resolve all types of resolve content conflicts in Visual
conflicts in Visual Studio. Studio or from the command prompt.
Capability TFVC Git
File storage You can check in large binary files. You You can check in small binary files as
might also want to use NuGet in you would regular files. When working
combination or as an alternative. with large binary files, use Git-LFS to
store your large binary files in Azure
Repos.
History File history is not replicated on the File history is replicated on the client
client dev machine and so can be dev machine and can be viewed even
viewed only when you're connected to when not connected to the server. You
the server. You can view history in can view history in Visual Studio and on
Visual Studio and on the web portal. the web portal. You can annotate files
You can annotate files to see who to see who changed a line, and when
changed a line, and when they changed they changed it.
it.
Tag your files You can apply labels to a version of one You can apply tags from the command
or more files from either Visual Studio prompt to individual commits. View
or the command prompt. Each file can tags in the Visual Studio history
have label applied to a different version. window.
Roll back changes You can roll back one or more You can revert a commit.
changesets
Scale You can work on small or very large You can quickly begin small projects.
scale projects using local workspaces. You can scale up to very large projects,
Supports massive scale (millions of files but you have to plan ahead to
per branch and large binary files) modularize your codebase. You can
projects using server workspaces. create multiple repositories in a project.
Server
Capability TFVC Git
Server Azure DevOps Services, TFS Azure DevOps Services, TFS and Git
third-party services
Alerts Team members can receive email alerts Team members can receive email alerts
when check-ins occur. when commits are pushed to the
server.
Auditability Because your team checks in all their You can identify which user pushed a
work into a centralized system, you can commit. (Anyone can claim any identity
identify which user checked in a as the author or committer.) You can
changeset and use compare to see identify when changes were made what
what they changed. Looking at a file, was changed using history, compare,
you can annotate it to identify who and annotate.
changed a block of code, and when
they did it.
Builds (automated by TFBuild) You can use all TFBuild capabilities to You can use most TFBuild capabilities to
build any combination of content you build one project at a time, and one or
want within the project collection. more repositories at a time.
Capability TFVC Git
Code reviews Yes; see Day in the life of an devops Yes; see Conduct a pull request. For
Developer: Suspend work, fix a bug, more lightweight discussions, you can
and conduct a code review. For more also comment on and send email about
lightweight discussions, you can also a commit from the web portal.
comment on and send email about a
changeset from the web portal.
Files Each project contains all files under Each project can contain one or
a single root path (for example: more Git repositories and each Git
$/FabrikamTFVC). You can apply repository can contain one or more
permissions at the file level. You can branches. The most granular
lock files. permissions you can apply are to a
repository or a branch. Files cannot
You can browse your files on the be locked.
web portal and using Source
Control Explorer in Visual Studio. You can browse your files on the
web portal.
Your project exists on only one
server. You can push commits to multiple
remote repositories (for example to
both your project repository and to
your web site hosted on Windows
Azure.
Quality gates You can use CI builds, gated check-in You can use CI builds and gated check-
builds and check-in policies. in builds through branch policies.
Client
Capability TFVC Git
Client software Visual Studio, Eclipse (with Team Visual Studio, Eclipse, and other third-
Explorer Everywhere) party tools
Files You can browse your files using Source You can browse your files using
Control Explorer in Visual Studio, or Windows File Explorer or the command
using Windows File Explorer or the prompt.
command prompt.
Manage work on your dev machine Pending changes and my work pages. Changes, commits, and branches pages.
Suspend your work You can suspend from my work page or You can create a branch from (from
shelve your changes. Visual Studio or the command prompt)
or stash (from the command prompt)
Capability TFVC Git
User interface Visual Studio: Offers all Visual Studio: Offers many
commonly used features and commonly used features.
many advanced features. Features for some common
TFS web portal: Can browse, tasks are not yet available.
comment, annotate, and see TFS web portal: Can browse,
history of the codebase. comment, annotate, and see
TF Command prompt: history of the codebase.
Installed with Visual Studio. Third-party command
Used for advanced, prompt: You can install it from
administrative, and other less Visual Studio. Used for some
common tasks. common and many less
common tasks.
Visual Studio compatibility You can use all supported previous Git is built in with Visual Studio
versions of Visual Studio. 2017, 2015, and 2013.
You can also use Visual Studio
2012 Update 4 (you must also
install Visual Studio Tools for Git).
Web portal You can browse your codebase You can browse your codebase, view
(including branches), view history, history, compare branches, annotate
annotate and comment on changesets and comment on commits, and perform
and shelvesets, and perform other tasks other tasks such as ad hoc
such as ad hoc downloading of selected downloading of selected parts of your
parts of your codebase as a .zip file. codebase as a .zip file.
Integration and migration
Capability TFVC Git
CodePlex support CodePlex is supported. CodePlex is supported.
Migration path Git-TFS Git-TFS

Use Git and TFVC repos in the same project
In Team Foundation Server 2015 Update 1, a project administrator can add a Git repo to a project created with
Team Foundation Version Control (TFVC ). You can also add a TFVC repo to a project created with Git. This allows
you to adopt a new version control system while preserving all the data in your project.
Enable access to the new repo type

Because permissions are applied at project creation time by a process template, there will be a small amount of
work to correct permissions for a new repo type.
Add Git repos to a Team Foundation Version Control project
If your TFVC project was created prior to TFS 2015 Update 1, a project administrator will need to apply some
project-level permissions once the first Git repo is created. Go to the Version Control administration page and
select the "Git repositories" node in the tree. To set up the same group permissions as any of our default process
templates (Agile, Scrum, CMMI), add the following TFS groups and permissions:
1. [ProjectName]\Readers
Allow: Read
Not set: All others
2. [ProjectName]\Contributors
Allow: Branch creation, Contribute, Note management, Read, Tag creation
Not set: All others
3. [ProjectName]\Build Administrators
Allow: Branch creation, Contribute, Note management, Read, Tag creation
Not set: All others
If your TFVC project was created after TFS 2015 Update 1, these permissions have already been applied for you,
and no action is necessary except creating the repository.
Add a Team Foundation Version Control repo to a Git project
The project administrator will need to apply some project folder-level permissions when the project folder is
created. Go to the Version Control administration page and select the "$/ProjectName" node in the tree. To set up
the same groups as any of our default process templates (Agile, Scrum, CMMI), add the following TFS groups and
permissions:
1. [ProjectName]\Readers
Allow: Read
Not set: All others
2. [ProjectName]\Contributors
Allow: Check in, Check out, Label, Lock, Merge, Read
Not set: All others
3. [ProjectName]\Build Administrators
Allow: Check in, Check out, Label, Lock, Merge, Read
Not set: All others
Projects with multiple repo types in Visual Studio
To see both types of repos in Visual Studio, you need Visual Studio 2015 Update 1. Older versions of Visual Studio,
including 2015 RTM, will only see the type of repo created with the project. For example, if the project was created
with Git you will only see Git repos when you connect from Visual Studio 2015 RTM or earlier.
Projects with multiple repo types in Team Explorer Everywhere

To see both types of repos in Eclipse, you need the Team Explorer Everywhere Plugin for Eclipse 14.0.2. Older
versions of the plugin will only see the type of repo created with the project. For example, if the project was created
with Git you will only see Git repos when you connect with Team Explorer Everywhere 14.0.1 or earlier.
Learn to map your familiar Team Foundation Version
Control (TFVC) commands and workflows to Git
Do you plan to adopt Git, are familiar with TFVC actions, and wondering how they map to Git? Both are powerful
and mature source control systems. However, mapping common actions you have grown accustomed to in the one
to the other can be a confusing experience.
This article will not delve deep into the Git commands, as they are well documented in the product documentation,
but show examples to help you make the right decisions, while moving through a typical create -> clone -> branch
-> change -> commit -> push workflow.
Start at the beginning by creating a new repo

Each Project can host TFVC and Git repositories in the same project, creating one TFVC, and one or more Git
repositories.
Once the repo is created, you are presented with step-by-step instructions to quickly get started.
Click on the `Create a ReadMe file' at the end of the instruction page, to give the repo context and to create some
history.
Create a workspace and get latest

When connecting to a TFVC repo for the first time, you typically create a workspace and get the latest code. so,
how do you get started in Git?
Similar to a workspace in TFVC you clone the Git repository to a folder on your machine. Cloning will download
all of the contents and history of the repository, to your local machine. Once you have the cloned repo, nearly all
operations are performed locally. You are able to work offline with a full backup of the centralized repository.
Command Line
Visual Studio
git clone https://dev.azure.com/demo-fabrikam/Fabrikam/_git/Mapping-TFVC-actions-to-Git
You only need to clone once per repo, but like TFVC workspaces, you can have multiple clones to isolate in-
progress work. However, branching is typically a better way to isolate changes.
Create a branch
With Git, you are always working in a branch and by default in the "master" branch. You are recommended to
create multiple local branches. It's a process that takes seconds and allows you to seamlessly context switch
between branches and work in isolation. Unlike TFVC branches, which are paths scoped, Git branches are
repository scoped. They are lightweight, can be local only, or shared with others when you are ready to share your
changes.
Consider branching if you need to work in isolation, need to suspend your work, focus on new features, or if you
are planning to conduct a Git pull request.
As a TFVC user, repeat a few times:
Branching is recommended!
Git branching is inexpensive, fast, and powerful!
Git encourages you to use local branches.
Publish local branches to your centralized repository as needed.
Always verify your branch context before making changes.
Name the branch using a common convention such as users/alias/branchname for example:
users/doris/newfeature
Create and switch to a local topic branch, named francis/demo -feature. It is good practice to run a git status first,
to verify that you are on the right branch to start with.
Command Line
Visual Studio
git checkout -b francis/demo-feature

Make a change by adding files
Similar to the TFVC experience, new files in the working folder are not automatically part of the repository. You
stage your new files with the git add command, which is synonymous to performing an add Items to Folder
operation in TFVC.
Here's a sample project to try adding files to your repo.
Command Line
Visual Studio
git add <file>
or
git add --all
Using the pre-baked sample, you will have 13 new files that have been included and staged in the local repository.
View pending changes

Wondering what changes are now sitting in your working environment? As before, the Git status command or
the Changes view in the Visual Studio IDE will show changes in your working tree.
Command Line
Visual Studio
git status
Checkin changes and commit locally
In TFVC, you share your changes with a Check In, which sends your pending changes to the server. The Git process
is a bit different. First, you commit to the local repository, creating a commit object (like a changeset), then you
push to send those changes with the server.
You commit the changes to your local repository using git commit , which feels like doing a
Checkin Pending Changes in TFVC. A key difference is that the git commit commits your changes to the local, not
the remote repository.
Command Line
Visual Studio
git commit
Check in changes with the server/remote repo

First you need to publish your local francis/demo-feature branch to the remote server, which includes all
committed changes.
Command Line
Visual Studio
git push --set-upstream origin francis/demo-feature
To synchronize further updates in your local with the remote repository, you need to push your changes using
git push . The recommended practice using the git command or the Visual Studio IDE is to:
fetch to download content and preview incoming changes from others.

pull to download and then merge changes from others.
push to share your local changes.
View history
To see the commit, you just created you can review the local history.
Command Line
Visual Studio
For a compact history, use:
git log --oneline
For a detailed, view, use:
git log
As shown above, git log lists the author, email, date written, and the commit SHA-1 checksum. As a TFVC user
you may want to use the --stat option to include more information, such as file name and change statistics.
You can also view the history of the centralized repository using the Azure DevOps Services web portal.
In the Azure DevOps Services web portal, choose CODE > History or CODE > Explorer > History
At this point, you have successfully explored the create -> clone -> branch -> change -> commit -> push
workflow, based on common TFVC actions.
You also have the option of issuing a pull request, to publish and stage your changes on the server/remote repo at
this point.
Other actions
Switch branches
When working with Git, you do not change branches by switching to separate folders and locations on your
machine. You change the context by doing a checkout , making the entire working directory match the selected
branch or commit. Fast and simple!
Command line
git checkout <branch>
If you forgot what branches you have in your local repository, use git branch to list the default and known
branches.
Keep in mind which branch you are working on! When you work with multiple branches in Git, you switch
branches in place in the same working directory. Switching between branches is a fast operation, and making sure
you are on the right branch at all times is good practice.
Get latest version
There are lots of reasons to want to get updates. For example, when you need to switch context to another project,
refresh your development machine with the latest version of the codebase.
Command line
git pull
or
git fetch
followed by
git merge FETCH_HEAD
Always get the latest version and resolve merge conflicts locally.
Undo local changes
There may be a valid reason to revert all revisions you made in your local repository and reset your working
environment to the latest version from the remote repository.
Command line
git reset --hard HEAD
followed by
git pull origin
followed by
git clean -xdf
The scenario is synonymous to doing a Get > Latest Version with the
Overwrite writable files that are not checked out and
Overwrite all files if the local version matches the specified version options in TFVC.
Alternatively you can manually delete your local repo - after making a validated copy off course - and then clone
the repository again.
There are a lot more actions and options available to Git users. Here are some useful reference sites for further
reading:
Git commands covered herein, refer to git documentation
Think like (a) Git, a Guide for the Perplexed.
How to undo (almost) anything with Git, by Joshua Wehner
Q&A
What about sync?
"Does the Visual Studio IDE Commit and Sync not magically do all this?", you may be asking yourself.
With magic comes responsibility! Many users dislike the sync as it can sometimes mess up your local history and
add a merge commit on top of your current commit. Once you are in a bad state, you have to revert to the
command line as there is currently no reset support in the IDE.
Authors: Jesse Houwing, Martin Hinshelwood, Mike Fourie, and Willy Schaub from the ALM | DevOps Rangers.
Connect with them here.
This document does not provide you with any legal rights to any intellectual property in any Microsoft product.
You may copy and use this document for your internal, reference purposes.
Explore the feature isolation strategy using Team
Foundation Version Control (TFVC)
Are you planning to implement Team Foundation Version Control's feature isolation strategy in Team Foundation
Server (TFS ) or Azure DevOps Services? You probably have a few questions, such as:
Is it practical with large development teams?
Does it align well with your agile process(es)?
What's the proper lifetime of isolated feature branches?
This article aims to answer those questions, and give you a clear perspective on feature isolation in TFVC. (For
guidance on TFVC branch strategies overall, read Branching Strategies with TFVC.)
NOTE
This article covers TFVC. For Git, refer to adopt a Git branching strategy.
What's feature isolation?

The feature isolation strategy allows you to work on features or fix bugs in feature branches (also known as "topic
branches") based off parent branch. It isolates your changes from the rest of your team to:
Experiment with a feature
Roll back your changes easily
Merge your changes with your parent branch
NOTE
The reference to "feature" is not related to the Feature work item type. This strategy can be used with Epic, Feature, Program
Backlog Item, User Story, or whatever work item type you've defined in your process.
It's typical to create one feature branch per feature or bug, but in this strategy, you can create a miscellaneous
feature branch to isolate a couple of low risk features.
Unlike Git branches, which are repository-scoped, TFVC branches are path-scoped and therefore not as
lightweight. To work around this, limit the number of and the lifetime of your TFVC feature branches, and optimize
your workspace using explicit, implicit, cloaked, and non-recursive folder mappings, to improve performance, and
to reduce required disk space on your machine.
TIP
Your workspace should contain only the files you need. Consider creating multiple workspaces to isolate and switch among
multiple feature branches. To avoid confusing yourself, use a consistent naming convention for both your workspace and
feature branch.
Naming convention is important

Use a consistent naming convention for your feature branches. Branches should be self-describing and easily
identified by your users. Some suggestions:
features/username/description for work performed by an individual. For example, features/sandra/sdk-java.
features/workitem for feature work associated with a specific work item. For example, features/115673.
sprint/username/description for work done by an individual in a specific sprint. For example,
S53/bill/dictionary-refactor.
bugfix/username/bugid for work done specific to an engineering bug. For example, bugfix/takashi/707.
Creating feature branches

Create a feature branch when you need to work on a feature, typically within the context of a sprint or iteration.
To protect your parent branch and minimize merge conflicts, regularly forward integrate (FI) changes from the
parent branch to your feature branch. It ensures that you resolve merge conflicts on your feature branch, not the
parent branch.
This strategy also keeps features from getting out of sync with the parent branch. Remember to FI before you
reverse integrate (RI) your changes back to the parent branch!
TIP
Keep your feature branch short-lived!
Unlike main or other central branches, feature branches have a limited life time. They are scoped to features, bugs, and hot
fixes, which are typically developed within a sprint or iteration. Consider removing your feature branch once your feature has
met your team's definition of done DoD and changes have been merged with the parent branch.
As the number of your feature branches increase, your storage requirements and branch hierarchy visualization
noise increases. With only five feature branches, the diagram is already noisy and rapidly losing its monitoring
qualities. Can you imagine the impact of your team creating hundreds of feature branches?
Similarly, the Source Control Explorer view becomes noisy and impractical as the number of branches increases.
Unless you have a consistent naming convention, finding a specific feature branch among hundreds of feature
branches is challenging.
TIP
Delete your feature branch when you're done!
Impact of deleting a feature branch

By deleting feature branches, you minimize noise and focus on active feature development.
Remember it's a soft delete and your history isn't lost. Deleted branches can be unhidden:
Select Tools > Options > Visual Studio Team Foundation Server.
From the submenu, select Show deleted items in the Source Control Explorer to view the deleted
branch(es).
If needed, you can also restore deleted branches and associated items.
If no one in your team has destroyed a branch using the destroy command, you'll have the complete history
needed for auditing and migration tools that rely on replaying history.
NOTE
Use the destroy command with caution. It's a permanent delete!
By keeping your branches short-lived and adopting a consistent naming convention, the feature isolation
strategy is effective for small and large teams.
Now that you're using feature isolation, you should explore continuous integration, feature toggles, and other
complementary strategies.
Reference information
Branching Strategies with TFVC (new guidance)
Branching and Merging Guidance (latest copy of classic guidance)
Continuous Integration
Feature Toggles
Team Foundation Version Control (TFVC )
Author: Willy Schaub | Find the origin of this article and connect with the ALM | DevOps Rangers here
Test Impact for partially mapped TFVC repositories in
TFS/Azure DevOps Services
Azure DevOps Services | TFS 2018 | TFS 2017 Update 1

Test Impact Analysis (TIA) has been part of VSTest task starting with version 2. This feature helps speed up the
DevOps cycle by helping you run only relevant tests for a build. Effectively, you end up running tests which are
affected by incoming changes and not the entire test suite. For more information about Test Impact Analysis, see
Accelerated Continuous Testing with Test Impact Analysis - Part 1.
In addition to supporting GitHub and Git in TFS/Azure DevOps Services, TIA also supports TFVC. This article
describes a known limitation about TIA in build/release pipelines based on TFVC and a work around to get past
this limitation.
Issue with partially mapped TFVC repositories

The way TIA works is by collecting data on the files that a test method touches during its first run, also called the
base line run. The collector which collects this data has visibility only of the enlisted repository on the agent
machine. With TFVC based pipelines, you get an option to enlist partial repositories. For example, consider a
repository that has the following structure.
Now, in your build/release pipeline you see Get sources tile under Process as shown in the following example.
Select Get sources and you'll see options on the right blade to partially map your repository.
If you enlist the entire repository, as shown in the previous example, TIA continues to work fine, but if you enlist
partially, as shown in the following example, TIA fails to find the impacted tests.
When a TFVC repository is partially enlisted, TIA fails to find the impacted tests because the collector is able to
collect changes only for the partially enlisted repository on the agent and does not have visibility of the entire path.
When a code change flows in from the server, it provides the entire path, and the matching attempt with the
mapped path fails.
Workaround
To work around this issue, you can map your partial repository to the complete code structure on the server, so that
the full path of the files on your local enlistment match the full server path. To do this, you can specify a Local path
that matches the server path, as shown in the following example.
This ensures that the server path matches the path collected by the collector and impacted tests are correctly listed.
Explore how to manage branching strategies with a
DevOps mindset in Team Foundation Version Control
(TFVC)
Are you planning to embrace DevOps using the Team Foundation Version Control (TFVC ) with Team Foundation
Server (TFS ) or Azure DevOps Services? You probably have a few questions, such as:
How do I decide on the right branching strategy?
Is there an effective strategy for DevOps?
How do I support applications with single or multiple versions?
TFVC is a centralized version control system to maintain code and make teams more effective. It provides
collaboration and consistent code sharing, publishing, and review features.
Keep it simple!
By adopting an effective branching strategy, you'll:
Foster a DevOps culture
Promote collaboration flow and increased productivity
Enable teams to spend more time developing and less time managing code
To embrace DevOps, it's important to keep your branch strategy simple and strive for high quality. Some
suggestions:
Start with a simple strategy and evolve as needed
Use consistent naming conventions for branches
features/username/description for work performed by an individual - example, features/sandra/sdk-java
bugfix/username/bugid for work done specific to an engineering bug - example, bugfix/takashi/707
releases/version for planned releases - example, releases/V1.00
Frequently reverse integrate (RI) and merge into your main branch
Encourage consistent code reviews - garbage in, garbage out
Implement a CI/CD pipeline, using:
Gated checkins
Automated testing
Start with a simple branching strategy

Create a source control structure that identifies shippable release units. The concept of releasable units is a
foundational piece of this strategy, which Steve St Jean describes as follows:
The physical unit of versioning and delivery.
The primary unit to support the branching and release models.
Can be at the Suite-, Application-, or Component-level.
For Suites, all applications must version and patch together. For example, Microsoft Word and Excel are part of
the Microsoft Office Suite. Visio is not, as it may release or patch independent of the rest of the Microsoft
Office Suite.
In TFVC, this would be the root node under the team project node.
Can be equated to a repo in Git
You typically start with having to support only one production version, with parallel defect corrections and
development of new features. Typical examples include web sites, corporate line-of-business applications, and
interim tools.
Start with the simple main-only branching strategy.
Automate your build to trigger with every checkin to the main branch, run automated tests, and if successful,
deploy the release to a development (dev) environment.
BRANCH BUILD ENVIRONMENTS NOTES
Main CI_Bld Dev Triggered with every checkin

to main
When you complete a release cycle, create a release branch. Use the release branch to stabilize the release, and
continue development for your next version in main. Reverse integrate (RI) and merge validated bug fixes with
your main branch frequently, to minimize your overall technical debt.
Automate your build and release to:

Trigger with every checkin to the release branch
Run automated tests
Deploy to your development and other environments
BRANCH BUILD PIPELINES NOTES

to main
V1.00 RC_Bld Dev -> QA -> UAT -> Triggered with every checkin
Staging -> Prod to release
When version 2 becomes the Release Candidate, you can update your existing RC build pipeline to point to the
V2.00 branch. It will now build and release just as V1.00 did when it was the current version.

to main
V2.00 RC_Bld Dev -> QA -> UAT -> Triggered with every checkin
Staging -> Prod to release
V1.00 Hotfix_Bld Hotfix -> Staging -> Prod Triggered with every checkin
to hotfix
Expand branching strategy as needed

When the need arises to support more than one production version, for example a commercial solution such as
Word, you can expand your branching strategy.
For every completed release cycle you need to support, create a new release branch and continue next version
development in main, using feature isolation. Note the reverse integration (RI) merges from v1.0 and v2.0 to
main. They represent bug fixes that are released to production.
By using a simple branching strategy and adopting a consistent naming convention, you'll be able to support:
Applications that have one or more supported releases
Continuous development of new features
Continuous delivery of value to your users
Checklist and lessons from the field

Checklist
Keep it simple and expand branching complexity as needed
Organize your code into shippable units
Use a consistent naming strategy for your branches
Build with every check-in
Create a CI/CD pipeline using gated checkins and automated testing
Lessons from the field - things to avoid
Avoid going branch crazy!
merging changes comes with complexity and a cost
there's no need to have a separate branch per environment
Avoid using cherry-picking to get your code to production
Do not attempt to solve people or process problems with tools
Continuous Integration
Interview with Abel Wang and Steve St Jean
Team Foundation Version Control (TFVC )
What is DevOps - Definition
What is DevOps - Sticker
Authors: Sergio A Romero | Find the origin of this article and connect with the ALM | DevOps Rangers here
Use branches to isolate risk in Team Foundation
Version Control
Consider some challenges team members typically face when they work on a software project that is staffed by
more than five or ten people:
The group has a few (or maybe several) different feature teams, each working on a set of functionality that
is reasonably discrete. But each team also depends on functionality built by other teams. You need to
isolate the risk of the changes introduced by the work done in each of these teams, and yet eventually, you
need to merge all their efforts together into one product.
The test team needs a stable version of the code to test, and yet simultaneously, the developers need to
continue moving forward with new features that will occasionally destabilize the product.
The software has two previous versions and one current version in progress. Even though most of the
development effort is invested in the current version, the previous versions must still be supported with
occasional releases of service packs, critical fixes and security patches, and other changes.
In This Section
This section describes the branching and merging tools provided by Team Foundation version control to enable
you to meet these and other challenges faced by groups of people who collaborate on a software project.
Explains the procedure used to create branches by using Team Foundation version control.
Branch strategically
Your team can create and use branches in version control to optimize your application development strategy.
Explains the procedure used to merge branches by using Team Foundation version control.
View where and when changesets have been merged
Explains how to view and work with actionable diagrams that illustrate where and when merges have occurred.
View the branch hierarchy of a project
Explains how to view and work with an interactive diagram that illustrates the branch hierarchy of your project.
Associate a file type with a merge tool
Describes the steps used to specify the file type extensions associated with merging.
Reference
Related Sections
Explains how to compare or diff files, folders, and shelvesets.
Lists topics about how to resolve merges, check in procedures, and get retrieve conflicts.
See Also
Other Resources
Visual Studio TFS Branching Guide
You can use branches to accomplish the following goals:
Manage concurrent work by multiple teams on the same codebase
Isolate risks that are introduced by different sets of changes to the codebase
Take snapshots and then support subsequent isolated changes (for example, to create a release branch)
For example, the following illustration shows how the DinnerNow company developed a branch structure to meet
its business needs.
The following screenshot shows the DinnerNow branch structure in the Hierarchy window.
Feature Team A and Feature Team B each do their work in separate branches. When the teams are ready to
integrate their work, they merge their branches into the Dev branch. When the builds from the Dev branch are
stable and ready to test, the teams merge the Dev branch into the Test branch.
As each version is released, the Main branch is branched into a new version branch, such as the Version1 branch
and the Version2 branch. By following this strategy, the company can enhance or fix each past version of the
product separately if necessary.
You can perform a branching operation by using either Source Control Explorer, as this topic demonstrates, or
the Branch command at a command prompt. For more information, see Branch Command.
Tip:
Branching is an important and powerful technique for creating a parallel set of versions of your files.
However, using branches can add complexity and cost to your project. For example, when you merge two
branches, you may have to resolve conflicts.
Before you create a branch, you should consider whether you can better meet your needs by applying a label.
By applying a label, you can quickly and easily take a snapshot of the state of your files so that you can then
later retrieve or build the files in that state. For more information, see Use labels to take a snapshot of your
files.
Convert a Folder to a Branch
The release of Visual Studio Team Foundation Server 2010 began a distinction between branches and folders.
The following illustration shows the top-level of the DinnerNow folder structure:
DinnerNow folder structure in Source Control Explorer
As the illustration shows, you can still use folders to organize branches within a project's version control
hierarchy. However, folders and branches have a different appearance and different capabilities. When you right-
click a folder or branch and click Properties, you display different information and different functionality.
When you perform branch operations, branches have important advantages over folders. Branches support
version control features that provide extra visibility into your branch structure and into where your changesets
have merged. (For more information, see the links in the See Also section later in this topic.)
Although you can still branch and merge among folders, the best practice for your team is to branch and merge
only among branches. The following procedure explains how to convert a folder to a branch.
Required Permissions
To perform the following procedure, your Manage branch permission must be set to Allow. For more
information, see Permissions and groups reference.
To convert a folder to a branch
1. In Source Control Explorer, make sure that the folder that you want to convert exists on the server.
2. If the pending addition icon ( ) appears next to the folder, right-click the folder, and then clickCheck In
Pending Changes.
3. Right-click the folder that you want to convert, point to Branching and Merging, and then click Convert
to Branch.
The Convert Folder to Branch dialog box appears.
IMPORTANT
If you are converting a folder that you have already branched, you should probably select the Recursively
perform this conversion for all branched child folders check box. This option also converts to branches all
folders that were branched from this one folder.
4. (Optional) In the Owner field, type the name of the person who owns this branch.
NOTE
The Owner field is for information only. Being named in the Owner field grants no additional permissions.
5. (Optional) In the Description field, type information that you think would be helpful to other team
members who must use this branch or understand its purpose.
6. Click Convert.
IMPORTANT
You cannot nest branches; therefore, you cannot convert any folder to a branch if it either contains a branch or is contained
by a branch. For example, the following illustration shows how neither the parent nor the child of the FeatureTeamA
branch can be converted to a branch.
After you have converted a folder to a branch, you can convert it back to a folder if your team decides to change
your branch structure.
To convert a branch to a folder
1. In Source Control Explorer, click the branch that you want to convert.
2. On the File menu, point to Source Control, point to Branching and Merging, and then click Convert to
Folder.
3. When the Convert Branch Back To Folder message appears, click Yes.
Branch a branch
After you have converted a folder to a branch, you can then create other branches from that branch. The
following procedure shows how you can use the graphical user interface of Visual Studio to branch a branch. (For
information about how to perform this task at the command prompt, see Branch Command.)
To perform this procedure, your Manage branch permission must be set to Allow for the paths to the source
and target branches. Your Merge permission for the path of target branch must set to Allow. For more
To branch a branch
1. In Source Control Explorer, right-click the branch that you want to branch, point to Branching and
Merging, and then click Branch.
The Branch from dialog box appears.
2. In the Target Branch Name box, specify the path of the new branch.
3. (Optional) In the Branch from version section, click one of the following options in the By list:
If you click Latest Version, the branch is created for the most recent version in version control.
If you click Changeset, you can specify the number of the changeset in the Changeset box. As an
alternative, click the ellipses (...) to open the Find Changesets dialog box.
For more information, see Find and view changesets.
If you click Date, you can specify a date in the Date box.
4. Click Branch.
The branch is created and appears in Source Control Explorer.
NOTE
Unlike most version control operations, this operation does not generate a pending change. Rather, the operation is
completed immediately and you cannot undo it.
Branch a folder or file

Although you can branch a folder or file directly, we recommend that you avoid it. Otherwise, you will not be able
to view your branch hierarchy or track your changesets. The best practice is to branch and merge only among
branches, as described earlier in this topic.
But if you have a special need to branch a folder or file, you can use the following procedure to perform this task.
(For information about how to perform this task at the command prompt, see Branch Command.)
To perform this procedure, your Check out permission and your Merge permission for the target path must be
set to Allow. For more information, see Permissions and groups reference.
To branch a folder or file
1. In Source Control Explorer, right-click the folder or file that you want to branch, point to Branching and
Merging, and then click Branch.
The Branch dialog box appears.
2. In the Target box, modify the location and name for the new branch.
You can also click Browse to specify a target.
3. In the Branch from version section, click one of the following options in the By list:
If you click Latest Version, the branch is created for the most recent version in version control.
If you click Changeset, you can specify the number of the changeset in the Changeset box. As an
alternative, you can click the ellipses (...) to open the Find Changesets dialog box.
For more information, see Find and view changesets.
If you click Date, you can specify a date in the Date box.
If you click Label, you can type the label name in the Label box. As an alternative, you can click the
ellipses (...) to open the Find Label dialog box.
For more information, see Use labels to take a snapshot of your files.
If you click Workspace Version, the branch is created for the version in your workspace.
4. (Optional) Select the Create local working copies for the new branch check box to create a copy of the
version-controlled item on the local workspace. Clear the check box if you do not need a local copy and
you want to improve performance by not downloading many items to your computer.
5. Click OK.
The branch is created and appears in Source Control Explorer.
NOTE
A Browse For Folder window appears if you selected the Create local working copies for the new branch
check box and the local folder that you specified is not mapped in the current workspace. Browse for a folder or click
Make New Folder, specify a folder to synchronize to the version-controlled items, and then click OK.
See Also
Other Resources
Use Source Control Explorer to manage files under version control
Branch Command
Branches Command
Visual Studio TFS Branching Guide
Learn about branching strategies for Team
Foundation Version Control (TFVC) and how to select
an effective strategy
Do you plan to adopt Team Foundation Version Control (TFVC ) with Team Foundation Server (TFS ) or Azure
DevOps Services? Are you wondering how to best use branches? This article will not delve deep into branching
features, as they are well documented in the product documentation and guidance, but will explore a few common
branching strategies to help you make the right decision.
Unlike Git branches, which are repository scoped, TFVC branches are path scoped and not as lightweight. Set your
bar for creating branches high and only branch when you have a need for code or release isolation.
Main Only
The Main Only strategy can be folder-based or with the main folder converted to a Branch, to enable additional
visibility features. You commit your changes to the main branch and optionally indicate development and release
milestones with labels.
RISK: The mutability and lack of history with TFVC labels can add risk of change control.
Start with the main only branching strategy, branch strategically and adopt other strategies to evolve into more
complex strategies as needed.
Development isolation
When you need to maintain and protect a stable main branch, you can branch one or more dev branches from
main. It enables isolation and concurrent development. Work can be isolated in development branches by feature,
organization, or temporary collaboration.
It's possible that there are changes in the main branch. Always forward integrate (FI) main to the dev branch and
resolve merge conflicts. Then reverse integrate (RI) changes back to main. Maintain the same quality bar across
branches. Build and run build verification tests (BVTs) on dev the same way you are doing on main.
NOTE: With this strategy, teams are likely to keep the dev branch around forever, potentially building a large
merge ticket history.
Feature isolation
Feature isolation is a special derivation of the development isolation, allowing you to branch one or more feature
branches from main, as shown, or from your dev branches.
When you need to work on a particular feature, it might be a good idea to create a feature branch.
Keep the lifetime of feature work and the associated feature branch short-lived. Forward integrate (FI) changes
from the parent branch frequently. Reverse integrate (RI) back to the parent only when some agreed team criteria,
for example definition of done, is met. Rollback of features on main can be costly and may reset testing.
Release isolation
Release isolation introduces one or more release branches from main. The strategy allows concurrent release
management, multiple and parallel releases, and codebase snapshots at release time.
When the release is ready to be locked down, it's time to create a new branch for the release.
Never forward integrate (FI) from main. Lock release branches using access permissions, to prevent unintended
modifications to a release. Patches and hot fixes made to the release branch can be reverse integrated (RI) back to
the main branch.
NOTE: None of the branching scenarios are immutable, which is why you notice emergency hotfixes
performed on release branches. Evolve each strategy to match your requirements, without losing sight of
complexity and associated cost.
Servicing and Release isolation

Servicing and Release Isolation strategy introduces servicing branches. This strategy allows concurrent service
management of service packs, and codebase snapshots at release time.
Use this strategy if you need a servicing model for customers to upgrade to the next major release and additional
service packs per release.
Like the release isolation, the servicing isolation and release branches are created when the release is ready to be
locked down. Never forward integrate from main to servicing, or from servicing to release. Lock the release
branch to prevent modifications. Future servicing changes can be done on the servicing branch.
Create new servicing and release branches for subsequent releases if you require that level of isolation.
Servicing, Hotfix, Release isolation

Although not recommended, you can continue to evolve the strategies, by introducing additional hotfix branches
and associated release scenarios.
At this point, you have successfully explored a few of the common TFVC branching scenarios. You can evolve them,
or investigate other strategies such as feature toggling, toggling features on and off to determine whether a feature
is available at run time.
Q&A
Why should branches be short-lived?
By keeping branches short-lived, merge conflicts are kept to as few as possible.
Why only branch if necessary?
To embrace DevOps, you need to rely on automation of build, test, and deployment. Change is continuous,
frequent, and merge operations more challenging as merge conflicts often require manual intervention. It is
therefore recommended to avoid branching and rely on other strategies, such as feature toggling.
Why remove branches?
Your goal should be to get changes back into main as soon as possible, to mitigate long-term merge
consequences. Temporary, unused, and abundant branches cause confusion and overhead for the team.
Can a codebase be branched across projects?
Yes. It is not recommended, unless teams must share source and cannot share a common process.
What about the code promotion strategy?
The Code Promotion strategy feels like a relic from the waterfall development era. It is typically with long testing
cycles, and separate development and testing teams. The strategy is no longer recommended. For more
information on this strategy, see the branching guidance.
When merging dev to main branch, why are no changes detected?
You have likely ignored changes in previous merges, for example, using the keep source conflict resolution option.
See merging development branch to main: there were no changes to merge for details.
Are there similarities between TFVC and Git branch strategies?
The TFVC Feature Isolation branching strategy is similar to the Git topic branches.
Authors: Jesse Houwing, Marcus Fernandez, Mike Fourie, and Willy Schaub from the ALM | DevOps Rangers.
You can contact them here.
Source code is an important asset in your development effort. But it can be a challenge to effectively manage and
evolve source files when multiple developers work concurrently on file updates. You can use a version control
system to store source code in shared repositories, to isolate parallel development efforts, to integrate code
changes, and to recover previous file versions. A key element in version control is branching that enables
simultaneous development. If you branch strategically, you can maintain the order and consistency of multiple
versions of your software.
Team Foundation provides a flexible and reliable version control system. You can use Team Foundation version
control to manage multiple revisions during development of source code, documents, work items, and other
critical information that is worked on by your team.
How does your team manage code while it introduces multiple

changes simultaneously through several project releases?
When you work with a version control system, you must consider how to set up a branch structure. You can create
a branch by mirroring the source code file. Then you can change the branch without affecting the source. For
example, as the branch structure in the following illustration shows, the MAIN branch contains completed
functionality that has passed integration tests, and the DEVELOPMENT branch contains the code that is under
construction. When a new functionality in the DEVELOPMENT branch is completed and can pass integration
tests, you can promote the code from the DEVELOPMENT branch to the MAIN branch. This process is referred to
as reverse integration. Conversely, if you merge the code from the MAIN branch to the DEVELOPMENT branch,
the process is referred to as forward integration.
For more information about how to create and merge code branches, see the following page on the CodePlex
Web site: Team Foundation Server Branching Guide 2.0.
Branching and merging entail the following principles:
1. Each branch must have a defined policy about how to integrate code into this branch. For example, in the
branch structure of the previous illustration, you can assign a team member to own and manage the MAIN
branch. This member is responsible for performing the initial branch operation, reverse integrating changes
from the DEVELOPMENT branch to the MAIN branch, and forward integrating changes from the MAIN
branch to the DEVELOPMENT branch. Forward integration is important when the MAIN branch also
integrates changes from other branches.
2. The MAIN branch must contain code that has passed integration tests so that it is always ready for a
release.
3. The DEVELOPMENT (or work) branch constantly evolves because team members check in changes
periodically.
4. Labels are snapshots of the files in a branch at a specific time.
For more information, see Use labels to take a snapshot of your files.
Team Foundation Build allows you to choose from several types of builds for your branches: manual, continuous,
gated, rolling, and scheduled. We recommend that the MAIN branch has a gated check-in build type. This means
that the DEVELOPMENT branch must pass all requirements for the MAIN branch before you can commit a
reverse integration. The DEVELOPMENT branch should run a continuous build type because your team must
know as soon as possible when a new check-in affects the DEVELOPMENT branch.
How often should your team reverse integrate and forward integrate?
As shown in the following illustration, reverse integration and forward integration should occur at least when you
complete a user story. Although each team might define completeness differently, completion of a user story
generally means that you complete both the functionality and the corresponding unit tests. You can reverse
integrate to the MAIN branch only after unit tests have verified the stability of the DEVELOPMENT branch.
If you have more than one work (DEVELOPMENT) branch, forward integration to all work branches should occur
as soon as any branch integrates into the MAIN branch. Because the MAIN branch is kept stable, forward
integration is safe. Conflicts or failures at the work branches might occur because you cannot guarantee that the
work branches are stable.
It is important that you resolve all conflicts as soon as possible. By using a gated check-in for the MAIN branch,
you help make the reverse integration much easier because quality gates help avoid conflicts or errors in the
MAIN branch. For more information, see Check in to a folder that is controlled by a gated check-in build process.
How does your team manage sources that implement different user
stories?
As the following illustration shows, you can check in changes to a work branch periodically to complete a user
story. You can implement multiple user stories in the same branch at the same time. However, you can reverse
integrate to the MAIN branch only when you complete all the in-progress work. It is recommended that you
group user stories by similar size because you do not want a large user story to block the integration of many
small ones. You can split the two sets of user stories into two branches.
When should the team add a branch?

You should create branches in the following situations:
When you must release code on a different schedule/cycle than the existing branches.
When your code requires a different branch policy. If you create a new branch that has the new policy, you
can add strategic value to your project.
When functionality is released to a customer and your team plans to make changes that do not affect the
planned release cycle.
You should not create a branching for each user story because it creates a high integration cost. Although TFVC
makes branching easy, the overhead of managing branches can become significant if you have many branches.
How does the team manage releases from the version control
perspective?
Your team should be able to release code at the end of any sprint. By using Team Foundation Server, you can label
a branch to take a snapshot of the code at a specific point in time. As the following illustration shows, you can
label the MAIN branch for a release. This lets you return the branch to its state at this point.
Because you must implement updates on releases, creating a branch for a release helps your team continue to
work independently on the next sprint without creating conflicts with future releases. The following illustration
shows a branch that contains code for an update and that is reverse integrated into the MAIN branch after a
release at the end of the second sprint.
When you create a branch for a release, you should create that branch from the MAIN branch, which is the most
stable. If you branch for release from a work branch, it can cause integration challenges because the stability of
work branches is not guaranteed.
For the various reasons described in Branch folders and files, many software development teams work in a
codebase that is forked into various branches. If you use branches, eventually your team must integrate the work
that has been completed on different branches during certain phases of your project. For example, when you are
ready to test a full version of your software, you will need the changes made on different feature team branches to
be merged together.
The procedures in this topic advise how you can use the graphical user interface of Visual Studio to merge
together changes made in different branches. For information about how to perform merges at the command
prompt, see Merge Command.
To perform these procedures, you must have the following permissions set:
You must have the Read permission for the item in the source tree and your Check out permission for the
item in the target tree set to Allow.
You must have the Merge permission set for the target path.
If the item in the target tree is being renamed, you must have the Check out permission for both the source
tree and the target tree set to Allow.
If any files affected by the operation are locked, you must have the Lock permission set to Allow. For more
information about permissions, see Permissions and groups reference.
Initiate a Merge from the Source Control Window

IMPORTANT
The release of Visual Studio Team Foundation Server 2010 began a distinction between branches and folders. For example, in
the following illustration you can see how branches and folders are displayed with different icons.
While you can still branch and merge among folders, the best practice for your team to follow is to branch and merge only
among branches. For more information, see Branch folders and files.
Merge branches, files and folders from Source Control Explorer

1. In Source Control Explorer, select the branch, folder, or file that you want to merge.
2. Click the File menu, point to Source Control, point to Branching and Merging, and then click Merge.
The Source Control Merge Wizard is displayed. For information about how to use this wizard to
complete the merge, see Use the Source Control Merge Wizard to Complete a Merge.
Initiate a Merge from the Tracking Changeset Window

You can use the Tracking Changeset window to view information such as, where a changeset was made, where it
was merged, and when these events occurred. Branches where a changeset has not been merged are also
highlighted. If you see such a branch where you know the changeset is needed but is missing, you can use a drag
and drop operation to fix this problem.
IMPORTANT
This procedure can be performed only for changesets that affect a branch. For example, in the following illustration you can
view how branches and folders are displayed with different icons.
For more information, see Branch folders and files.
Drag and Drop a Changeset into the Tracking Changeset Window

1. In Source Control Explorer, select either a branch, a folder, or a file which is contained within a branch.
2. Right-click the selected item and click View History.
3. In the History **window, right-click the changeset that you want to view and select **Track
Changeset.
The Select Branches dialog box appears.
4. (Optional) In the Target branches list, check the branches that you want to view and uncheck the branches
that you want to hide.
5. Click Visualize.
The Tracking Changeset window appears.
6. Drag the branch which contains the changeset to the target branch.
The Source Control Merge Wizard appears. For information about how to use this wizard to complete
the merge, see Use the Source Control Merge Wizard to Complete a Merge.
Example: Where is that New Method?
To illustrate how you might use the preceding procedure, consider the following example. Julie has asked Chris to
implement a new method in some of the FeatureTeamA code that she leverages in her FeatureTeamB code.
Chris writes code for the new method and then he checks it into the FeatureTeamA branch. He meets Julie in the
hallway as he is leaving for the day and mentions that he has checked in the new method.
Julie gets back to her desk and finds the latest source, but she does not see the new method that Chris checked in.
She navigates to Source Control Explorer, views the History window for the FeatureTeamA branch, and she
can see that with changeset 50 Chris did indeed check in the new method. She right-clicks changeset 50 and clicks
Track Changeset, and the following window appears:
Tracking Changeset Window: Merge to Parent Branch
From the Tracking Changeset window, Julie can see that Chris checked in the method with changeset 50, and
merged it to the Dev branch with changeset 51. But Julie cannot get the new code until changeset 50 is merged
into the FeatureTeamB branch. So she drags the Dev branch onto the FeatureTeamB branch to launch the
Source Control Merge Wizard, which she then uses to complete the merge.
Use the Source Control Merge Wizard to Complete a Merge

After you complete one of the above procedures, the Source Control Merge Wizard appears. This wizard
enables you to specify the source and target of the merge. You can merge one entire branch to another branch, or
you can pick a specific changeset or group of changesets that you want to merge.
Use the Source Control Merge Wizard to merge files, folders, or branches
1. In the Source Control Merge Wizard, in the Source branch box, either type the name of the project
source branch, or click Browse to select one from the list.
2. In the Target branch drop-down list, select the target project branch to which you want to merge the
source branch.
3. Select the range of changes that you want to merge into the target branch by selecting either the All
changes up to a specific version or Selected changesets option, and click Next.
Tip: If possible, click All changes up to a specific version, as it will reduce the risk of conflicts in
future merges.
If you selected All changes up to a specific version, then the Select the versions of the source
items page appears. Select the version of the items that you want to use.
Changeset Merge by specifying a changeset version.
Date Merge by specifying a date version.
Label Merge by specifying a label version.

Latest Version Merge by specifying the latest version.
Workspace Merge by specifying a workspace version.
If you selected Selected changesets, then the **Select changesets to merge into the target branch
**page appears. Select the changeset you want to merge.
Tip: You can press and hold the CONTROL or SHIFT keys and then select multiple items in a
continuous range.
4. Click Next, and then on the Perform the merge operation page, click Finish.
One or more pending changes are generated.
5. (Optional) If you want to check in the pending changes immediately, you can perform these steps:
a. Click the View menu, point to Other Windows, and then click Pending Changes.
b. Use the Pending Changes window to check in the changes. For more information, see Check in your
work to the team's codebase.
See Also
Other Resources
Use branches to isolate risk in Team Foundation Version Control
Merge Command
Merges Command
Branching your code base can be a useful way to isolate concurrent development efforts and to take snapshots.
However, when your team members are working in a branched code base, they may have trouble finding
information about which branches have received a particular set of changes and when those changes were
merged.
For example, your team (Feature Team B ) waits for a fix to a bug in some code on which your code depends. You
receive an e-mail message that states that the bug has been fixed, but you can still reproduce the bug in the builds
that come from your branch.
By opening the Tracking Changeset window, you can determine which branches have and have not received a
set of changes. For example, in the following illustration, the Tracking Changeset window shows how changeset
38 was merged from the Dev branch to a child branch and then baselessly merged to two other branches.
Tracking Changeset window shows branches to which a changeset has merged
To perform these procedures, your Read permission must be set to Allow for the branches with which you are
working. For more information about permissions, see Permissions and groups reference.
View the Tracking Changeset Window

Important:
These procedures can be performed only on a branch, not on a folder.
For more information about how to branch, see Branch folders and files.
To view the Tracking Changeset Window from the History window of a branch or file
1. In Source Control Explorer, click a branch or a folder or file that is contained by a branch.
2. Click the File menu, point to Source Control, and then click View History.
3. In the History window, right-click the changeset that you want to view, and click Track Changeset.
4. (Optional) In the Branches list, select or clear the check boxes for the branches that you want to show or
hide.
As you select or clear check boxes, a preview of your selections appears on the right-hand side of the
dialog box.
5. (Optional) If your team has a lot of branches, click the buttons above the preview to select the branches
that you want more easily.
You can move the pointer over each button to get information about what the button does.
6. Click Visualize.
To view the Tracking Changeset window from a work item that is linked to a changeset
1. Open a work item that is linked to one or more changesets, and then click Track Work Item.
2. (Optional) In the Branches list, select or clear the check boxes for the branches that you want to show or
hide.
dialog box.
3. (Optional) If your team has lots of branches, click the buttons above the preview to select the branches that
you want more easily.
You can move the pointer over each button to show information about what the button does.
4. Click Visualize.
Overview of the Tracking Changeset Window
The following illustration shows an example of a changeset in the DinnerNow project.
Tracking Changeset window elements
The previous example illustrates how you can use the Tracking Changeset window to visualize the following
information:
The branches to which the changeset has been merged (displayed in green), including the numbers of
changesets in which the merge was implemented.
Tip:
You can click one of these branches (for example, Version2 in the previous example) to highlight all the
merges that were required for the changeset to reach that branch.
Whether the merge was a standard merge (solid line) or a baseless merge (dashed line).
If a branch has received some (but not all) of the changes in a changeset, the branch is filled with a pattern,
and an asterisk follows the changeset numbers within that branch. For example, the previous illustration
shows that only some of the changes in changeset 38 were merged to the Test branch.
The branches to which the changeset has not been merged (displayed in light blue).
Switch to Timeline View

You can get information about when a changeset was merged to one or more branches by switching to the
Timeline View. This view shows not only the sources and targets of each merge but also when the merge
occurred.
To perform these procedures, your Manage branch object permission must be set to Allow. For more
information about permissions, see Permissions and groups reference.
To display the Timeline View of a changeset
Open the Tracking Changeset or Tracking Work Item window, and then click Timeline Tracking.
Example: Using Timeline View
The previous illustration shows that two baseless merges and one standard merge occurred. When you click
Track on Timeline View, the Tracking Changeset window switches to a view that shows the sequence of the
merges.
Timeline View provides detailed chronological data
The branches that have received the changeset appear at the top of the view. In the previous example, the user has
clicked the Version1 branch to show the date and time when the merge occurred.
The branches to which the changeset has not been merged (for example, FeatureB and Main in the previous
illustration) appear in white at the bottom of the view.
Use the Drag and Drop Operation to Merge Branches

You can use the drag and drop feature to merge a changeset or a branch to another branch. For more
information, see Merge folders and files.
As a project grows, typically the branch structure also grows and becomes more complex. Your team members,
especially those who are new, will require answers to simple questions such as the following:
What branches are in our project?
How are these branches related to each other?
If I need changes from another feature team, which branches will those changes have to go through to get
back to me? Who owns these branches?
The following procedures explain how to use Team Foundation version control to answer these types of questions.
To View and Work with Your Branches

You can use the Hierarchy window to perform the following tasks:
View a subset, or all, of your branches in a hierarchical view.
View properties of a specific branch.
Complete tasks for a specific branch.
IMPORTANT
This procedure can be performed on a branch and not on a folder. For example, in the following illustration you can see
which objects are branches and which are folders.
For more information, see Branch folders and files.
Display the Hierarchy Window from Source Control Explorer

1. In Source Control Explorer, click the branch from which you want to begin to explore your branch
structure.
2. Click the File menu, point to Source Control, point to Branching and Merging, and then click View
Hierarchy.
Adjust the View to Show the Data You Need
When you first display the Hierarchy window, by default, the branch that is shown is the branch from which you
started the window, including its ancestors and its descendants.
For example, the following illustration shows the Hierarchy window for the DinnerNow Test branch.
Hierarchy window showing DinnerNow Test branch with ancestors and descendants
The options that you can use to modify the
view in this window are explained in the following list:
A. Show menu You can select a typical view from the **Show menu: **All hierarchies, Full
hierarchy, Ancestors and descendants, Ancestors, Parent and children, Children, or Customized.
Tip: If you want to see the full hierarchy for every version control path in your project, including those
that are outside the scope of the active project in Source Control Explorer, select All hierarchies.
**B. Customize branch list button **Click this button to individually select the specific branches that you
want to show.
In the Branches list, select or clear the check boxes for the branches that you want to show or hide.
dialog box.
If your team has many branches, you can more easily specify the branches that you want by clicking
the buttons above the preview. You can point to each button to display information about what the
button does.
C. View controls on branches-If you want to fine tune details of your diagram, you can click a specific
branch and then click one of the following controls:
Click X to hide the branch (or press DELETE while the branch is selected).
Click the plus (+) symbol (or press INSERT while the branch is selected) to select or de-select which
child branches you want to display.
View Properties and Take Actions
After you view the branch hierarchy, you may need more information, or you may be ready to take some action.
You can right-click any branch in the Hierarchy window and perform any one of the following steps:
Select Properties to display the Properties dialog box, which you can use to view additional information
about the branch, including its path, who owns it, and who has permissions to work with it.
The Owner field is only for information. Being named in the Owner field conveys no additional
permissions.
Select an action such as: Branch, Merge, Compare, or Open in Source Control Explorer.
Associate a file type with a file-comparison tool
You can compare text files by using the default file-comparison tool integrated with Visual Studio, the Diff window.
However, you can, for file types that you specify, enable the file-comparison tool that you prefer to use. You can use
any comparison tool that supports, as command-line arguments, the full paths of the two files that you want to
compare.
To perform this procedure, you must be a member of the Administrators or Users security group on the
computer where Visual Studio is installed. For more information, see Permissions and groups reference.
To associate a file type with a third-party compare tool
1. Perform either of the following sets of steps.
a. In Visual Studio, on the menu bar, choose Tools, Options.
b. In the Options dialog box, expand Source Control, choose Visual Studio Team Foundation Server,
and then choose Configure User Tools.
--or--
c. In Windows, choose Start, All Programs, Microsoft Visual Studio 2012, Visual Studio Tools,
**Developer Command Prompt **.
d. Type tf diff /configure.
2. In the Configure User Tools dialog box, choose Add.
The Configure Tool dialog box appears.
3. In the Extension box, specify the extension (for example, .cpp) that you want to associate with your tool.
Tip:
Specify .* if you want to associate all types of files with your tool.
4. In the Operation list, choose Compare.

5. In the Command box, either type the path and name of your tool, or choose the ellipses (...) to locate and
specify it. The result should resemble the following example:
C:\Program Files\OtherDiff\otherdiff.exe
6. In the Arguments box, type any arguments that your tool requires:
%1: The path to the source file.
%2: The path to the target file.
%5: The options that the user specified by using the /option option of the Difference command. For
more information, see Difference Command.
%6: Label ("friendly name") of the source file.
%7: Label ("friendly name") of the target file.
Tip:
For information about frequently used external tools and the arguments that they require, see the
following page on the Microsoft website: diff/merge configuration in Team Foundation - common
Command and Argument values.
Use white space to delimit the arguments.

For example, you might specify the following syntax to compare two files:
%1 %2
Use quotation marks to pass white space or quotation marks to the tool.
If an argument includes one or more spaces, you must enclose it in quotation marks (""). If an argument
contains one or more quotation marks, you must add another quotation mark immediately after any
quotation mark in the argument. For example, you could specify the following argument:
"This "" embeds a double quote"
Pass labels ("friendly names") to the tool.

If your tool supports displaying a label (a "friendly name"), such as
c:\workspace\test\MyWindow.xaml.cs;C5 (server) 4/26/2010 1:32 PM, you can include the %6 and
%7 tokens to pass label values to the tool. If you do not specify these tokens, the tool may show names of
temporary files, which can be difficult to read.
For example, you might specify the following syntax to display labels.
%1 /title1=%6 %2 /title2=%7
Note:
This capability is not related to version-control labels, which you apply to specific versions of items in
version control, as described in Use labels to take a snapshot of your files.
7. In the Configure Tool dialog box, choose OK.

8. If you want to specify more types of files, repeat steps 4-9.
9. In the Configure User Tools dialog box, choose OK.
Set up Team Foundation Version Control on your
dev machine
To set up Team Foundation Version Control (TFVC ) on your dev machine, you just need to create a workspace
and then add your code.
Before you start
If you don't have Visual Studio, get it here.
If you don't have a project, create or get access to one.
Create a workspace and get the code

From Visual Studio, go to the Team Explorer Connect page (Keyboard: Ctrl + 0, C ) and then connect to the project.
(If the project you want to open is not listed, choose Select Projects and then connect to the project.)
Map the project to a folder on your dev machine.
Map the workspace and get your code.
Work in a "Main" parent folder

Do you want to prepare for when your team grows large enough to need branches to manage your work? Put all
your code in a parent called Main (for example: $/MyTeamProject/Main/ ).
1. Go to the Team Explorer Home page (Keyboard: Ctrl + 0, H), and then open Source Control Explorer.
2. In Source Control Explorer, select your project in the left pane.
3. On the menu bar choose File, Source Control, New Folder.
Name the folder.

Open the context menu of the Main folder and choose Check in.
4. Check in the new folder.
Your changeset is checked in.
When your team decides to branch the codebase, you can convert the Main folder to a branch. See Branch folders
and files.
Add your code to version control

Create a new solution under version control
If you've got an idea for a new app, you can use version control from the start. Create a new code project
(Keyboard: Ctrl + Shift + N ), and add it to TFVC version control:
Tip: We suggest that you put your new project in c:\Users\YourName\Source\Workspaces\.
When the Choose Source Control dialog box appears, choose Team Foundation Version Control.
When you are ready, check in your changes (Keyboard: Ctrl + 0, P ).
Put an existing solution under version control
You've already got an app in progress and you want to begin working on it under TFVC version control.
1. Move your solution into your workspace folder (for example:
c:\Users\YourName\Source\Workspaces\YourTeamProject\Main\).
2. If you have not already done so, open your solution, (Keyboard: Ctrl + Shift + O ) and then open Solution
Explorer (Keyboard: Ctrl + Alt + L ).
3. Add your solution to source control.
4. On the Choose Source Control dialog box, choose Team Foundation Version Control.
5. When you are ready, check in your changes (Keyboard: Ctrl + 0,P ).
Q&A
Q: I'm really new to all this; can I get more help?
A: Yes, let us walk you step by step to get started.
Q: Is your folder structure complex or do you use branches?
A: If so, you can create one or more workspaces and then optimize them to meet your needs.
Try this next

Set up a CI build
Dig deeper
Develop your app in Team Foundation version control
Your workspace is your local copy of the team's codebase. This is where you develop and test your code in
isolation until you are ready to check in your work. In most cases the only workspace you need is created
automatically for you and you don't have to edit it.
In some cases, you might want to modify your workspace or create multiple workspaces to isolate and switch
among the changes you are making in different branches.
Add, edit, or remove a workspace

After you have connected to the project (Keyboard: Ctrl + 0, C ), you can manage your workspaces from the
Team Explorer home page (Keyboard: Ctrl + 0, H)
or from Source Control Explorer.
Choose Show remote workspaces if you want to view all the workspaces you own (including those on other
computers).
After you choose Add or Edit you can modify working folders in a new or an existing workspace.
If you want to remove the workspace, before you do so, make sure there are no pending changes (Keyboard:
Ctrl + 0, P ). If you have pending changes, you can either check them in or shelve them.
Switch workspaces
When you switch from one workspace to another, to avoid confusing yourself, make sure you switch to the same
workspace in both Team Explorer and Source Control Explorer.
1. Connect to the project (Keyboard: Ctrl + 0, C ).
2. On the home page (Keyboard: Ctrl + 0, H) choose the workspace you want to use.
3. In Source Control Explorer, choose the workspace the workspace you want to work in.
Work from the command prompt

You can create and manage your workspaces from the command prompt. You can also perform some tasks that
are not possible in Visual Studio. For example, you can delete another user's workspace if you have sufficient
permissions. See Workspace Command, Workspaces Command, and Workfold Command.
Q&A
Q: Why would I need to change the working folders? How should I do it?
A: In general, you should map your entire project to a single local folder under
c:\Users\YourName\Source\Workspaces\. For example:
Some tips on
effective folder names:
Keep all folder, sub-folder, and file names short to simplify your work and avoid potential long-path
issues that can occur with some types of code projects.
Avoid whitespace if you want make command-line operations a little easier to perform.
If your team has a large and complex codebase or if you want your workspace to contain only the files you need
to improve performance, you can optimize your workspace.
Q: Can I reuse and share folder mappings?
A: Yes. If you want to reuse or share folder mappings with other team members, you can copy the folder
mappings. Simply open the shortcut menu in the Working folders list and choose Copy. To reuse the folder
mappings, paste them into another version control workspace or a build definition workspace. To share the
folder mappings with your teammates, paste them into a text file and then share the file.
Q: What does "Cloaked" mean?
A: Choose Cloaked to exclude that folder from your workspace. For details and examples, see Optimize your
workspace.
Q: How do I add a folder non-recursively?
A: Optimize your workspace.
Q: How do I choose advanced workspace options?
A: When you choose the Advanced button, some additional options appear.
Owner: Only the owner of a workspace can use it.
Tip: Instead of changing the owner of your workspace when someone else needs to continue your
work you can suspend (or shelve) your work and then share the shelveset with them.
Computer: This box identifies the dev machine where the workspace exists, and it is read-only. You
cannot move a workspace from one computer to another. However, if the name of your dev machine has
changed and you want that change to appear in this field, run tf workspaces /updatecomputername.
Permissions: For a workspace you are using on a dev machine for a single developer, set this to Private
workspace. Choose Public workspace if you want to use a single computer for a team to collaborate
on an effort such as resolving a large number of conflicts. If you want any team member to be able to use
a workspace but not check in their work, choose Public workspace (limited). This option reserves
check-in permission for the Owner.
Location: Local is the best choice in most cases. See Decide between using a local or a server
workspace.
File Time:
Choose Checkin if you want the date and time stamp of each file to generally match the stamp of
the changeset of the version in your workspace. A few issues and exceptions are:
When you modify the local file, the date and time stamp will match the date and time when
you modified the file.
This feature is available only if you are using Visual Studio 2012 or later and Visual Studio
Team Foundation Server 2012 or later.
The setting does not apply to folders, unless there is a pending add or delete operation to a
file contained by the folder.
You might not be able to build your code project incrementally. Instead, you will have to
rebuild).
Choose Current if you want the date and time stamp to match the date and time when you last
modified the local file. For example, a team member checked in the latest change to the file on
Monday. On Tuesday, you perform a get operation to update the file. The date and time stamp is
set to Tuesday.
Q: Can I use the same workspace in multiple instances of Visual Studio?
A: Although Visual Studio does not block you from running multiple instances against the same workspace, this
usage is not supported. Also, working this way is more likely to cause problems if you are using a local
workspace.
Q: How do I add code, get code, develop my app, and check in?
Add files to the server, download files from the server, develop your app, and check in.
Q: I work at a remote site. Is there any way I can save bandwidth?
A: Install Team Foundation Proxy and set up a remote site.
Optimize your workspace
Does your team have a large and complex codebase? Do you want your workspace to contain only the files you
need to improve performance, reduce network traffic, and reduce the disk space required on your dev machine?
Optimize your folder names
Optimize your workspace using explicit, implicit, cloaked, and non-recursive folder mappings
Use workspaces to isolate and manage work among different branches
Optimize your folder names

If you don't yet use branches, on your server, you should put all your code in a subfolder called Main (for
example: $/TFVCTeamProject/Main/ ). If you do, then you'll be ready when your team grows big enough to require
branches to manage your codebase. On your dev machine, you should use a short, understandable folder path
that matches your project structure such as
C:\Users\\YourName\Source\Workspaces\TFVCTeamProject\Main\SolutionName\ .
Some more tips on effective folder names:

Keep all folder, sub-folder, and file names short to simplify your work and avoid potential long-path issues
that can occur with some types of code projects.
Avoid whitespace if you want to make command-line operations a little easier to perform.
Optimize your workspace using explicit, implicit, cloaked, and non-

recursive folder mappings
If your codebase is large, you can avoid wasting time, network bandwidth, and local disk space by optimizing
your workspace folder mappings.
When you map a folder, make sure that you choose a folder high enough in the code tree that you get all the files
you need to create a local build, but low enough that you are not getting more files than you need. You can also
use some tools to more simply and quickly create a usable workspace: explicit, implicit, cloaked, and non-
recursive folder mappings.
When you look at the workspace of fictitious developer, Raisa, below, you might wonder to yourself: why didn't
she simply map $/SiteApp/ to c:\\code\\SiteApp\\ and be done with it? A simple workspace like this would
implicitly map all the folders she needs in $/SiteApp/Main/ .
The main problem with this approach is that it would also provide her with a lot of files she does not need, and
thus waste time and resources. So Raisa creates some tailored folder mappings.
Raisa doesn't develop customized build processes so she
doesn't need $/SiteApp/BuildProcessTemplates . Over
time she expects the codebase to grow, and she also
does not want to automatically download every new bit
of code added to $/SiteApp/Main/ . As teams working
in those other folders change those files, when Raisa gets
the latest files from the server, she could incur long
delays waiting for updates to files she doesn't need.
To develop her code, Raisa needs all the code projects
that comprise the FabrikamFiber solution. Rather than
explicitly including each code project (for example,
$/SiteApp/Main/FabrikamFiber/FabrikamFiber.DAL )
she instead maps $/SiteApp/Main/FabrikamFiber/ ,
and thus she implicitly maps all the sub-folders that
contain the code projects she needs.
Raisa does not need the files in
$/SiteApp/Main/FabrikamFiber/3DModels or
$/SiteApp/Main/FabrikamFiber/Docs , and because
they are implicitly mapped by , she uses two cloaked
mappings to exclude these folders from her workspace.
Raisa and others on her team maintain and sometimes

augment a set of some fundamental libraries. She needs
almost all current libraries in this folder and expects to
need libraries her team adds there in the future, so she
maps $/SiteApp/Main/libraries/Common .
Raisa needs only a small segment of a large folder,

$/SiteApp/Main/libraries/Common/LibraryC , so she
maps it as cloaked and then explicitly maps just the
sub-folder she needs:
$/SiteApp/Main/libraries/Common/LibraryC/Sub-
Library1
.
Raisa needs some of the files immediately within

LibraryD , but she does not need the large contents of
its sub-folders, so she applies a non-recursive mapping
to this folder:
$/SiteApp/Main/libraries/Specialized/LibraryD/* .
Use workspaces to isolate and manage work among different

branches
If your company uses branches to isolate risk in your codebase, then you should create a separate workspace for
each branch you work in.
For example, at Fabrikam Fiber, the codebase and the staff have grown. To isolate the risk among their many
teams, they've branched their codebase. Raisa continues her work within her small team, but now she uses a few
workspaces to manage the work that she now does in multiple branches.
Develop features She modifies her default workspace to

do work in the Extranet branch, where she participates in
the development of the customer-facing website in this
branch.
Integrate and stabilize She creates two new
workspaces to do work in the Test and Dev branches,
where she collaborates with other developers and testers
to stabilize the code during integration.
Raisa manages her work in three workspaces, each of which maps folders in a branch on the server with the
folders on her dev machine.
Note:
Branching or suspending (or shelving) are the preferred ways to isolate different work efforts against the
same codebase. However, if neither of these approaches meets your needs, you can map the same server
folder in more than one workspace. In most cases you should not need to do this. If you do map the same
server folder in more than one workspace, remember that you could have separate and different pending
changes to the same file stored in each workspace.
Decide between using a local or a server workspace
When you create or edit a workspace, you can specify whether its location is Local or Server. In most cases,
local is best because it provides several advantages. Most notably, you can perform core version control
operations even when you're not connected to your Team Foundation Server.
Why should I use a local workspace?

When you use a local workspace, you get the following advantages:
Work offline easily. You can quickly begin editing a file when your network connection is unavailable or
unreliable. From Solution Explorer you can add, edit, delete, rename, undo, and compare items in your
workspace even when you're not connected to your Team Foundation Server.
Easily restore files that you have deleted locally. To restore locally deleted files, just get your files.
Visual Studio automatically detects changes. When you add or delete files outside of Visual Studio, the
program automatically detects these changes.
Important:
One drawback to using a local workspace is that performance degrades as the number of items increases.
See the next section for details.
When might I need to use a server workspace?

When you use a server workspace, Visual Studio keeps only one copy of each file. This can significantly reduce
disk space usage and improve performance when you have a lot of items. We recommend that you use a server
workspace if:
Your workspace contains more than 100,000 items.
You want to use Visual Studio 2010 or earlier versions to work with the workspace.
You need to use the Enable get latest on check-out option.
Work offline with difficulty and with poor performance. When you are offline in a server workspace, you
cannot work with your local files because they are read-only until you check them out. You can check out files
only from Solution Explorer, and only after you switch to offline mode (as explained below ). While you're offline,
you can't perform any other operations, such as add, delete, rename, or undo.
Tip: You can improve responsiveness by enabling asynchronous checkout. For more information, see
Manage project collection workspace settings for your team.
Switch to offline mode when using a server workspace

When you use a server workspace and cannot connect to your Team Foundation Server, Source Control
Explorer is disabled. However, if you have local copies of your files in your server workspace, you can still edit
them from Solution Explorer. After the server becomes available again, you can check the changes into version
control.
Tip: If working offline is important to you, then you should consider using a local workspace instead of a
server workspace See Local Workspaces earlier in this topic.
To work with version-controlled files when the server is offline

1. From your local working folder, open the solution that you want to work on.
If the server is offline, the Go Offline dialog box appears.
2. Choose OK, and then edit your solution files.
3. On the File menu, choose Save.
4. In the Save of Read-Only File dialog box, choose Overwrite to remove the write-protection from the
file.
To commit your offline changes to the server when it is available
1. In Solution Explorer, open the context menu for the solution or file, and then choose Go Online.
The Go Online dialog box appears and shows the changes that you made offline.
2. Under Name, select the check box for each change that you want to check in, and then choose Go
Online.
The changes that you made offline are added to Team Foundation version control as pending changes.
3. In Solution Explorer, open the context menu for the files that you edited offline, and then choose
Check In to commit the changes to the server.
Manage project collection workspace settings for your team

If you are an administrator, you can specify which type of workspace Visual Studio creates for your team
members by default: Local or Server. You can also enable asynchronous checkout for your team's server
workspaces.
1. On the menu bar, choose Team, Project Collection Settings, Source Control.
The Source Control Settings dialog box appears.
2. On the Workspace Settings tab, choose either the Local or Server option button.
3. You can reduce the time the system takes to check out files to server workspaces by selecting Enable
asynchronous checkout in server workspaces. If you select this option:
The PendChange permission is no longer enforced.
Checkout locks are disabled

Workspace Command and Workspaces Command: Create and manage your workspaces from the
command prompt.
Q&A
Q: Someone checked out a file even though a check-out lock was applied to it. How did this happen?
A: The use of local workspaces makes check-out locks un-enforceable. If you have sufficient permissions you
can use the workspaces command to see the local workspaces being used in your project collection.
tf workspaces /format:detailed /owner:* /collection:https://YourServer/YourCollection/
Q: Why can't I see when some members of my team of checked out a file?
Pending changes of team members who use local workspaces are not visible to other team members in Source
Control Explorer.
Q: Is it OK to switch the location of my workspace?
A: Yes, you can change the location of your workspace from server to local or from local to server whenever
you need to. See Create and work with workspaces.
Q: Can I use the same workspace in multiple instances of Visual Studio?
A: Although Visual Studio does not block you from running multiple instances against the same workspace, this
usage is not supported. Also, working this way is more likely to cause problems if you are using a local
workspace.
Q: How does a local workspace work?
A: A local workspace caches the unmodified version of each of your files to enable you to edit, compare, and do
other things without being connected to the server.
Add Check-In Policies
Administrators of Team Foundation version control can add check-in policy requirements. These check-in policies
require the user to take actions when they conduct a check-in to source control, for example a user can be required
to associate a work item with a changeset. For more information about check-ins, see Check In Pending Changes.
By default, the following check-in policy types are available:
Builds Requires that the last build was successful before a check-in.
Code Analysis Requires that code analysis is run before check-in.
Work Items Requires that one or more work items be associated with the check-in.
Visual Studio 2017 : Check-in policies in Visual Studio 2017 must be set through Team Explorer, tf.exe, or
through registry keys declared in the pkgdef of a Visual Studio extension. Policies only apply to a single
installation of Visual Studio 2017 on your computer. If you have multiple installations of Visual Studio 2017,
you'll need to set the check-in policy on each installation. Learn more
Procedure
To create a check-in policy
1. From Team Explorer, select the Settings page, then select Source Control under the Project section.
The Source Control Settings dialog box appears.
2. Click the Check-in Policy tab and then click Add.
The Add Check-in Policy dialog box appears.
3. In the Check-in Policy list, select the policy type you want and then click OK.
The list includes the following selections:
Select Builds if you want to require that a previous build was successful before any new changes can
be checked in.
Select Code Analysis if you want to require that code analysis is run before code can be checked in.
The Code Analysis Policy Editor dialog box appears.
Select the check boxes for the types of code analysis that you want performed. Options are Enforce
check-in to only contain files that are part of current solution, Enforce C/C++ Code Analysis
(/analyze), and Enforce Code Analysis For Managed Code. If you select the Enforce Code
Analysis For Managed Code check box, select the desired rule settings under Rule settings for
Managed Code Analysis.
For more information about how to use code analysis tools, see Create Code Analysis Check-In
Policies.
When you are finished, click OK.
If you selected Work Items, the policy is added to the list that a work item must be associated with
the check in.
4. When you are satisfied with the settings for the check-in policies, click OK; the new check-in policy now
displays with future check-ins.
See Also
Reference
Configure Command
Concepts
Set and Enforce Quality Gates
Other Resources
Walkthrough: Customizing Checkin Policies and Notes
Develop code and manage pending changes
Most changes that you make to your files are queued as pending changes. As you work, you can organize,
manage, and get details about what you've changed.
Work in Solution Explorer

From the team explorer home page (Keyboard: Ctrl + 0, H), you can begin coding in a new or in an existing
solution.
After you open your solution, open the solution explorer (Keyboard: Ctrl + Alt + L ).
When you open and modify a file from the solution explorer, the file is automatically checked out for you. Icons
appear to indicate which files you have not changed , those you have checked out , and those you have
added to the solution .
If you're working in a solution that contains a lot of files, you'll probably find it convenient to filter the solution
explorer to show only the files you have changed (Keyboard: Ctrl + [, P ).
Use the My Work page to manage your work

If you're using Visual Studio Premium or Visual Studio Ultimate, you can use the My Work (Keyboard: Ctrl + 0,
M ) page in the team explorer to manage your work.
You can use My Work to:
Track your work against work items
Suspend and later resume your work (including file changes, associated work items, and Visual Studio state
such as window positions and breakpoints)
For a step-by-step example, see Day in the life of an devops Developer: Write new code for a user story, and Day
in the life of a devops Developer: Suspend work, fix a bug, and conduct a code review.
Tips
You can control the kinds of work items that appear in the Available Work Items section. Choose one of the
default options or any of your personal queries that are contained in the root My Queries folder. To work
with these queries, in the team explorer choose Home, and then choose Work Items.
When you move a work item to Available, In Progress, or Suspended, the work item state or comments
are updated so that your team is automatically advised on the status of your work. For example, the task
board for your team is updated to show your status. See Collaborate [redirected].
If your project contains customized work item type definitions, you might have problems using My Work,
unless an Administrator for your project has taken certain steps. See Configure and customize Agile planning
tools for a project and Update a customized process template to access new features.
Use the Pending Changes page to manage your work

You can use the Pending Changes page (Keyboard: Ctrl + 0, P ) in the team explorer to manage your work.
Tip:
You can undock the Pending Changes page from the team explorer and open it in a new window.
You can toggle between list and tree view from the actions menu.
Almost every change that you make to the files on your dev machine is stored in your workspace as a pending
change until you check it in:
add
branch
delete
edit
rename (includes moving items)
property
rollback
type (file encoding)
undelete
Work with automatically detected changes
If you are working in a local workspace, Visual Studio can detect changes that you make outside the system. If
you edit a file outside Visual Studio (for example, in Notepad) the change automatically appears in your
Included Changes.
If you add or remove a file outside Visual Studio, for example, in Windows Explorer (File Explorer in Windows 8),
the Detected changes link appears in the Excluded Changes section. Choose this link if you want to include
these changes. The Promote Candidate Changes dialog box appears. You can open the context menu of added
items and choose Browse in Windows Explorer to display them or Delete from disk to delete them.
Note: Empty folders will not appear.
If items that you don't need to check in appear regularly in the Promote Candidate Changes dialog box, you
can select one of them, open its context menu, and choose Ignore this local item to ignore the item. You can
also choose Ignore by extension or Ignore by file name to create a file that will cause Visual Studio to
systematically ignore this kind of file. For more information on .tfignore files, see Add files to the server.
Associate work items
It's a best practice to associate work items (such as tasks or bugs) with your changes. Under Related Work Items,
drag work items from a query or add it by ID.
Exclude changes
See Specify the files you want to check in
See what you changed

You can remind yourself about what you've changed in a file.
Use Pending Changes to view what you changed
On the Pending Changes page, open the context menu for the item and choose:
Compare with Workspace Version to see what you've changed to the version in your workspace
Compare with Latest Version to see how your changes compare to the latest version of the file in
your team's codebase
Use Solution Explorer or Source Control Explorer to view what you changed
1. Locate and select the item in Solution Explorer or in Source Control Explorer.
2. Open the context menu for the item, and then choose Compare.
3. On the Compare dialog box, from the Type menu, choose:
Workspace Version to see what you've changed in the version in your workspace
Latest Version to see how your changes compare to the latest version of the file in your team's
codebase
One of the other options: Changeset, Date, or Label.
4. Choose OK.
The Diff window appears. See Compare files.
Undo your pending changes

You can discard one, a few, or all of the pending changes in your workspace.
Note:
A few other options:
You can first put the changes away in a shelveset on your server before removing them from your
workspace.
If you have already checked in the change and want to revert it, see Roll back changesets.
To undo a few of your pending changes

1. In Solution Explorer, the Pending Changes Window, or Source Control Explorer, select one or more items,
open their context menu and choose Undo or Undo Pending Changes.
Tip:
To undo all changes you have made in your solution or a code project, open the context menu, and
then choose Undo Pending Change.
2. In the Undo Pending Changes dialog box, make sure the changes you want to undo are selected, and
then choose Undo Changes.
To undo all your pending changes
On the Pending Changes page, choose the Actions link, and then choose Undo All.
Use the command prompt

Status command : Display pending changes in the command prompt.
Checkin command : View pending changes in the Check In dialog box.
Undo command : Undo pending changes.
Tip:
You can use this command to undo another user's check-out if you have sufficient permissions.
Difference Command : See what you have changed in a file.
Next steps
When you're ready:
To request a code review of your pending changes, on the Pending Changes page, choose Request Review.
See Day in the life of an devops Developer: Suspend work, fix a bug, and conduct a code review.
If you need to set aside your changes, see Suspend your work and manage your shelvesets.
Check in and add your changes to the team's codebase, see Check in your work to the team's codebase.
Tips
If you are new to developing an app with Visual Studio and Team Foundation Server: Walk step by step with
an agile team as they collaborate to develop an app.
When you begin a new work item, it is probably a good idea for you to download the latest files from the
server before you check out files and begin your work.
Use Source Control Explorer to manage your files in version control.
Add files to the server
Adding a file to version control is often automatic when you use Solution Explorer and your project is under
version control. However, in some cases, you have to take some extra steps to add the project to version control.
TIP
Before you add files to version control, you should first set up the workspace on your dev machine
Create a new code project and solution under version control

You can simultaneously create a new project and add it to version control so that you and your team can
immediately enjoy all the benefits of version control beginning from the first line of code you write.
1. In Visual Studio, if you have not already done so, connect to the project.
2. Choose File, New, Project (Keyboard: Ctrl + Shift + N ).
The New Project dialog box appears.
3. Select the type of code project that you want to create.
4. In the Name box, specify the name of the code project.
5. If the Solution list appears, make sure Create new solution is selected.
6. In the Location list, specify the path to a good local working folder (such as c:\code\SiteApp\Main\) in
the workspace you created when you set up your dev machine.
Make sure the Create directory for solution and Add to source control check boxes are selected.
7. Choose OK to create the code project, which you can then view in Solution Explorer (Keyboard: Ctrl + Alt +
L ).
8. In Solution Explorer, open the context menu of the solution you created or modified and then choose
Check In to submit your pending changes.
Place an existing solution and code projects under version control

To add an existing solution to version control, move all the solution files into your workspace, and then add them.
NOTE
Avoid using the Add Solution to Source Control dialog box to upload your solution into version control. Use the following
procedure instead.
2. Choose View, Other Windows, Source Control Explorer.
3. In Source Control Explorer, navigate to a logical parent folder for your solution, such as $/SiteApp/Main,
where SiteApp is the name of your project. Why is this a good parent folder?
4. Choose the link next to Local Path to open the parent folder in Windows Explorer (File Explorer in
Windows 8).
What do I do if the link text is "Not Mapped"?
5. Move the folder that contains your solution into the parent folder.
6. In Visual Studio, choose File, Open, Project/Solution, and then use the Open Project dialog box to open
the solution.
7. In Solution Explorer (Keyboard: Ctrl + Alt + L ), select the solution, open its context menu, and then choose
Add Solution to Source Control.
8. In Solution Explorer, select the solution, open its context menu, and then choose Check In.
9. In Team Explorer, the Pending Changes page appears.
10. Are there any Detected items shown in the Excluded Changes section?
No: Skip to the next step.
Yes: Choose the Detected link. The Promote Candidate Changes dialog box appears. The files in
listed in this dialog box are not referenced by any code projects in your solution. If your team will
need these files, make sure they are selected and then choose Promote to move them into the
Included Changes section of the Pending Changes page. For more information, see Check in
your work to the team's codebase.
11. When you're ready,submit your pending changes.
Add one or more files to version control

When you use Solution Explorer to add a file to your code project, the system automatically adds it to version
control. However, you can also add files that are not referenced by your code projects.
TIP
If you are creating an automated process or prefer to use the command prompt, you can use Add command instead of the
following procedures.
Automatically add one or more files to version control

IMPORTANT
These steps only apply when using a local workspace. Files saved when working in a server workspace will add and check in
without showing as a pending change in Team Explorer.
If you are using a local workspace, then new files are automatically detected by the Pending Changes page.
3. In Source Control Explorer, navigate to the folder where you want to add the files or folders.
4. Choose the link next to Local Path to open the target folder in Windows Explorer (File Explorer in
Windows 8).
Move your files and folders into this folder.
What do I do if the link text is "Not Mapped"?
5. In Visual Studio, in Team Explorer, choose Pending Changes.
6. On the Pending Changes page, in the Excluded Changes section, select the Detected link.
7. In the Promote Candidate Changes dialog box, make sure only files that you want to check in are
selected, and then choose Promote.
8. Submit your pending changes.
Manually add files to version control
You can also manually add files to version control.
2. In Source Control Explorer, navigate to the folder where you want to place your files.
IMPORTANT
Make sure this folder is checked in before you proceed. If you are creating the folder now, open its context menu and choose
Check In, and then check in the new folder before proceeding.
3. Drag the folders or files from Windows Explorer (or File Explorer) into the folder in Source Control
Explorer.
4. When the Add to Source Control dialog box appears, make sure all the files you want to add are selected,
and then choose Include item (s).
5. Choose Finish.
6. In Team Explorer, when the Pending Changes page appears, make sure the binaries that you want to add
appear in the Included Changes section. Choose Check In.
Leverage third-party binaries that your code does not build

Many teams develop code that depends on binaries that are not built by the solution in which they manage their
code. Typically these binaries are part of a library that the team has licensed from a third party.
Sometimes these binaries come from another team in the same company. For example, Team A depends on
binaries produced by Team B, and each team must for some reason work in different project collections. As a
result, Team B delivers binaries to Team A, which then checks them into version control.
TIP
If your dev machines and build agents can access the Internet, then NuGet may make it easier for your team to manage
your dependencies and keep your binaries up to date. You can store your packages in TFS or Azure DevOps Services using
Azure Artifacts.
The folder and workspace structure you should use to store your third-party binaries depends on the way your
solutions depend on these libraries.
Add the binaries within your folder or branch structure
If you place your third-party binaries in the same parent folder that contains your solution folders, then all your
code projects in all solutions can reference the libraries with the same relative path.
For example, a team uses this folder structure:
Every code project can then reference the libraries folder with the following relative path: ../../Lib
If, later in your project, your team needs to isolate separate efforts that require different versions of the binaries,
you can branch the library folder along with your solution folder.
For example, Version 1 an app leverages Version 1 of a library. As some developers on the Data Access team work
on the next version, they leverage Version 2. But the other teams are not yet ready to upgrade. You can use
branches to manage this kind of situation.
Use a workspace to map in the binaries

Some companies must manage more complicated dependencies on third-party libraries. For example, multiple
projects contain solutions with different dependencies on a common set of libraries. In cases like this, you can
store your third-party libraries in a dedicated project. Contributors to the various projects map in the folders that
contain the libraries they need.
For example, FabrikamFiber puts the following project, branch, and folder structure in place:
Raisa sets up her dev machine with two workspaces for two different efforts, each of which map in the libraries
she needs:
Customize which files are ignored by version control
By default certain types of files (for example, .dll files) are ignored by version control. As a result:
When you add ignored files to folders that are mapped in a local workspace, they do not appear in the
Pending Changes page in Team Explorer.
When you try to add ignored files using the Add to Source Control dialog box (for example by dragging
them into Source Control Explorer), they automatically appear in the Excluded items tab.
You can configure which kinds of files are ignored by placing text file called .tfignore in the folder where you want
rules to apply. The effects of the .tfignore file are recursive. However, you can create .tfignore files in sub-folders to
override the effects of a .tfignore file in a parent folder.
.tfignore file rules
The following rules apply to a .tfignore file:
# begins a comment line
The * and ? wildcards are supported.
A filespec is recursive unless prefixed by the \ character.
! negates a filespec (files that match the pattern are not ignored)
.tfignore file example
######################################
# Ignore .cpp files in the ProjA sub-folder and all its subfolders
ProjA\*.cpp
#
# Ignore .txt files in this folder
\*.txt
#
# Ignore .xml files in this folder and all its sub-folders
*.xml
#
# Ignore all files in the Temp sub-folder
\Temp
#
# Do not ignore .dll files in this folder nor in any of its sub-folders
!*.dll
Create and use a .tfignore file

While you can manually create a .tfignore text file using the above rules, you can also automatically generate one
when the Pending Changes page has detected a change.
IMPORTANT
This only applies when using a local workspace. Files changed when working in a server workspace will check in without
showing as a pending change in Team Explorer.
To automatically generate a .tfignore file

1. In the Pending Changes page, in the Excluded Changes section, select the Detected link.
The Promote Candidate Changes dialog box appears.
2. Select a file, open its context menu, and choose Ignore this local item, Ignore by extension, Ignore by
file name, or Ignore by folder.
3. Choose OK or Cancel to close the Promote Candidate Changes dialog box.
4. A .tfignore file appears in the Included Changes section of the Pending Changes page. You can open this
file and modify it to meet your needs.
The .tfignore file is automatically added as an included pending change so that the rules you have created will
apply to each team member who gets the file.

Add command Upload files from the workspace on your dev machine to your server.
See Also
Other Resources
Decide between using a local or a server workspace
Download (get) files from the Server
In general, you should get the latest files from the server on a regular basis so that the code you develop is
compatible with the code developed by others on your team and to minimize the risk of creating bugs when you
check in your code. You can download the latest version or a previous version of one or more files from your
Team Foundation Server to your workspace on your dev machine.
Required permissions
You must be one of the Contributors for your project. See Team Foundation Server default groups, permissions,
and roles.
Get the latest version of some files

You should get the latest files from your server after you set up your dev machine. Then you can begin
developing your app.
Later, as you develop functionality in the workspace on your dev machine, your code is isolated from the changes
that are made by other developers. But when you are ready (for example, you have completed and checked in the
code that completes a task), you should get the latest version of your team's files.
To get the latest version of some files
In Solution Explorer or Source Control Explorer, browse to the files or the folders that contain the files that
you want to get, select them, open their shortcut menu, and choose Get Latest Version.
Get a specific version of some files

In special cases (for example, to fix a regression bug), you might need to get and work with a specific version of
one or more files.
Note: Keep in mind that if you get an older version of a file, make changes to it, and then try to check it in,
there is an increased chance that you will need to resolve conflicts before you can complete the check-in.
To get a specific version of some files from the History window

1. In Solution Explorer or Source Control Explorer, browse to the folder or file, open its shortcut menu, and
choose View History.
2. In the History window, open the shortcut menu of a version and choose Get This Version.
To get a specific version of some files from Solution Explorer or Source Control Explorer
1. In Solution Explorer or Source Control Explorer, browse to the files or the folders that contain the files you
want to get, select them, open their shortcut menu, and choose Get Specific Version.
The Get dialog box appears.
2. Choose an option from the Type drop-down list:
Changeset Get a version by specifying a changeset. For more information, see Find and view
changesets.
Date Get a version by specifying a date. If selected, select a date in the Date list.
Label Get a version by specifying a label. For more information, see Use labels to take a snapshot of
your files.
Latest Version Select this option to get the latest version on the server.
Workspace Version Gets a version by specifying a workspace.
3. (Optional) Select the Overwrite writable files that are not checked out option.
If selected, files from the server will overwrite all files that do not have the read-only attribute associated
with them and are not checked out. Only files on the server, which are different, will overwrite the files in
the local workspace. By default, this option is not selected.
Tip: This option is equivalent to running the following command: tf get /overwrite.
4. (Optional) Select the Overwrite all files even if the local version matches the specified version
option.
If selected, files from the server overwrite all files.
Tip: This option is equivalent to running the following command: tf get /force.
5. Choose Get.
Source Control Explorer appears. If you chose Latest Version in step 5, the system updates the Latest
column with the status of Yes.

LocalVersions Command Display the version of one or more items in your workspace.
Get command Get files from the server.
Tips
When you get files and folders from the server, the system also deletes any checked-in files from your
local workspace that have been deleted from the server. Files that have been renamed or moved on the
server are changed in your workspace to match the changes on the server.
In Source Control Explorer you can verify whether you have the latest version of a file in the Latest
column. You can see specific version information about an item by opening its shortcut menu and
choosing Properties.
If you are using a server workspace, and you have accidentally deleted some files that you want to
restore, you must use the tf get /all command to restore the deleted files.
Check out and edit files
When you want to edit a file you can open it from Solution Explorer or from Source Control Explorer. When you
begin editing a file, it is automatically checked out to you. In rare situations (for example, you want to check out
and lock the file to make sure your changes are checked in before changes from other team members), you might
need to manually check out (and optionally lock) an item.
and roles.
Manually check out items

To manually check out items
1. In Solution Explorer or in Source Control Explorer, select the files that you want to edit, open their shortcut
menu, and choose Check Out for Edit.
2. (Optional) You can lock the file.
Important:
As a best practice, use the Lock type option with discretion and notify your teammates why you are
locking an item, and when you plan to remove the lock.
On the Lock type menu, choose:

Unchanged: Do not apply a lock to the items.
Check Out: Prevent other users from checking out and checking in the items until you check in and
unlock them.
Note:
In Visual Studio Team Foundation Server 2012 this option is not available if you are using a local
workspace. Also, this lock is not enforceable because other users might be using local
workspaces. See Understand lock types.
Check In: Allow other users to check out the items you are checking out, but prevent them from
checking in their changes until you check in your changes and unlock the items.
Note:
The Lock type menu is not available if:
Another team member has locked the file.
The Enable multiple check-out option has been cleared (not a recommended practice) by an
Administrator of your project. Administrator: On the menu bar, choose Team, Project Settings,
Source Control).
If any other users have locked any of the specified items, the lock operation will fail. For more information,
see Lock and unlock folders or files.
3. Choose Check Out.
In Solution Explorer and in Source Control Explorer, a check mark appears next to the items that you have
checked out. In Team Explorer, a pending edit change to the file is displayed on the Pending Changes page. In
Source Control Explorer, a pending edit change is visible to you and to members of your team.

Checkout (or Edit) command Check out files from the server.
Tips
If you are beginning a new task, it's probably a good idea for you to download the latest files from the server
before you check out files and begin your work.
To help you and your team organize and track your work, you should use the My Work or Pending Changes
page to associate a task or a bug with the work you are doing. See Develop code and manage pending changes.
If you use a server workspace, files that you have not checked out are read-only.
You can review and manage your work, suspend your work, and ultimately contribute your work to the team's
codebase.
Check in your work to the team's codebase
Use the Pending Changes page (Keyboard: Ctrl + 0, P ) in Team Explorer to check in your code into a new
changeset.
Choose the files you want to check in

You can specify which file changes you want to check in by dragging them between the Included Changes
and Excluded Changes sections of the Pending Changes page in Team Explorer. You can also check-in as
you work in other areas of Visual Studio:
In Solution Explorer, select one of the following:
The solution
One or more of the code projects
One or more files
After you select the items, right-click and select Check In.
In Source Control Explorer, select one or more items with pending changes or one or more folders that
contain items with pending changes. (Items with pending changes are indicated by this symbol: ).
Open the context menu for the selected items, and choose Check In.
IMPORTANT
The Check in option is not displayed if there are no pending changes to the item selected.
TIP
If you don't see pending changes for an item, make sure that it is not already listed as an excluded change. Open Team
Explorer's Pending Changes view and select the Detected: .. link under Excluded Changes. Check the changes to
include from the list and select Promote to move the excluded changes into the Included Changes section. These
changes can now be checked in.
Associate work items
When you check in changes, you should associate such work items with the changes. Benefits of doing so
include:
A team member who looks at the work item can link directly to the changeset to see the work that you did.
A team member who reviews the history of a file you changed can view the changeset and see the work
items that were the justification for the change.
If you build your changes in your automated build system (for example with a CI Build or a Gated Check-in
Build your team members can see in which completed build the task was completed or the bug was fixed.
To associate work items with your check-in:
Choose the Add Work Item by ID link in the Related Work Items section.
Drag a work item from a work item query window from Team Explorer's Work Item page into the Related
Work Items section.
Next to each work item, select how it should be related to your check-in: Associate or Resolve (available only
if the work item is not already in a state that precludes this relationship, such as Resolved, Done, or Closed).
Check in your changes

1. In Team Explorer, choose Home, and then choose Pending Changes (Keyboard: Ctrl + 0, P ).
2. On the Pending Changes page, enter a Comment so that teammates who later need to review and
understand the history of your files will understand what you did. For example: Implemented
shopping cart controller.
3. Some teams prefer that their members to provide certain kinds of information about each check-in. In
some cases they even implement a check-in policy to require this. If an Administrator of your project
has enabled check-in notes, then you can type the information into each field in the Notes section.
4. Choose the Check In button.
One of the following outcomes occurs:
Your changes are checked in
All the included file changes from your workspace along with the comment, check-in notes, and links to related
work items are stored on the server as a single changeset on your server.
Conflicts block your check in
The system presents you with conflicts between your changes the latest version of the files on the server. See
Resolve Team Foundation Version Control conflicts.
Your check in is blocked because it violates a check-in policy.
Administrators of your project can implement check-in policies to encourage your team to follow best
practices. For example, a check-in policy can encourage team members to associate at least one work item with
their changes. For more information, see Set and Enforce Quality Gates.
In some cases, you might want to override these check-in policies. In the Policy Warnings section, choose
Override Warnings.
In the Reason box, explain why you chose to override the policy.
Check in changes to a folder that is controlled by a gated check-in build process
If you are checking in changes into
version control folders that are controlled by a gated check in build process, the Gated Check-in dialog box
-
appears. For information about how to complete your check-in operation, see Check in to a folder that is
controlled by a gated check-in build process.
Subscribe to alerts
If you want to be notified when someone checks in code in your TFVC project, you can subscribe to receive
email alerts. [Here's how ]

Checkin command : View pending changes and check in files
Tips
You can undock the Pending Changes page from Team Explorer and open it in a new window.
You can toggle between list and tree view from the Actions menu.
Before checking in new code, you should consider conducting a code review. See Day in the life of an
devops Developer: Suspend work, fix a bug, and conduct a code review.
You can manage and, if necessary, undo your pending changes. See Develop code and manage
pending changes.
If you need to set aside your changes, see Suspend your work and manage your shelvesets.
A check-in is performed atomically-the operation either succeeds completely or fails completely
(with one exception). If any one of the changes cannot be submitted to your Team Foundation server,
none of the changes is committed and a changeset is not created. For example, if you lose network
connectivity in the middle of a check-in, the whole operation fails.
The exception is the association of work items with the changeset. If work item association fails but all
other aspects of the check-in succeed, then the changeset is created. You can manually associate a work
item with a changeset. See Manage dependencies, link work items to support traceability.
Rename or move files and folders in TFVC
IMPORTANT
If you're not using TFVC for version control, use Solution Explorer to move and rename files in your current open Visual
Studio solutions or projects.
Move an item in TFVC

You can use Source Control Explorer to move one file or folder at a time. You should not use Source Control
Explorer to move folders or files that are referenced by a Visual Studio project or solution. Move these files with
Solution Explorer instead and check in the move in a new changeset.
1. In Source Control Explorer, select the item that you want to move, open its shortcut menu, and choose
Move.
2. In the Move dialog box, either manually type the destination for the item in the To box, or choose Browse
to use the Browse for Folder dialog box.
3. Choose OK.
Rename an item in TFVC

1. In Source Control Explorer, select the file that you want to edit, open its shortcut menu, and choose
Rename.
2. Type the desired name for the item.
Fix the outcome after you rename an item in your operating system
You should avoid renaming items managed by TFVC using your operating system (for example, using Windows
File Explorer, or the rename command in the Windows command prompt). When you have used your operating
system to rename an item in a local workspace, Visual Studio detects the change as two changes: an add and a
delete. You can join the two actions into a rename action.
NOTE
Git version control users can move and rename files from the command line or Windows Explorer without this concern. The
changes will be reflected in Team Explorer.
1. In Visual Studio, in Team Explorer, choose Home, and then choose Pending Changes.
2. In the Excluded Changes section, choose the Detected: link.
3. In the Promote Candidate Changes dialog box, select the delete and add actions, open their shortcut
menu, and choose Promote as Rename.
4. A single rename change now appears in the Included Changes section.

Rename Command (Team Foundation Version Control) : Rename or move a file.
Tips
and roles.
If you are beginning a new task, it's a good practice to download the latest files from the server before you
make changes to files in your workspace.
Avoid renaming an item that has been branched but not yet checked in. If you try to do so, a conflict will occur.
You can review and manage your work, suspend your work, and ultimately contribute your work to the team's
codebase.
Delete or restore files and folders in Team
Foundation Version Control (TFVC)
You can delete files and folders from TFVC and also restore them, from both in the workspace on your dev
machine or on the server.
Requirements
See Permissions and groups reference.
Delete an item
Before you delete an item:
Before you delete a file, look for a check mark icon , which indicates pending edits in the file . If there
are pending edits, you should view them (open the context menu by right-clicking the file and choosing
Compare) and make sure that you do not need them. If you think you might need the edits in the future,
consider checking in the file before you delete it.
If you delete a folder, the system will pend delete actions for any folders and files that it contains.
If you delete a file on which other files have dependencies, the system will automatically pend delete
actions for those files. For example, if you delete a form file, the code and resource file will also be pended
for deletion.
To delete an item
1. In either Solution Explorer or Source Control Explorer, browse to the folder or file that you want to delete.
2. Select the items that you want to delete, open their context menu (right-click), and choose Delete.
TIP
If you are deleting a file from Solution Explorer, the following warning message may appear: <file name> will be
deleted permanently. The file deletion will not be implemented on the server until you check in this change. If the
file was checked in to version control before the delete, then you can recover the file. Choose OK if you want to
proceed with deleting the file.
3. When you are ready, check in your changes.
Restore items deleted from Visual Studio

NOTE
If you're already checked in the delete of an item in TFVC, you can restore the deleted item from the server long as no one
on your team has destroyed it.
If you're not using TFVC, use Solution Explorer to delete items and files in your Visual Studio solution. Files deleted through
Solution Explorer are moved to the Recycle Bin on your computer, where they can be restored. Once restored from the
Recycle Bin, right-click your solution in Solution Explorer and select Add.. and then Existing item... to restore the file into
your solution.
From Team Explorer

Open the Pending Changes page in Team Explorer (View, then Team Explorer, then select Pending Changes).
Right-click the deleted items in the Included Changes area and choose Undo....
From Source Control Explorer
Open Source Control Explorer and browse to the folder where you deleted the file(s). Right-click the file and select
Undo Pending Changes... Verify the checkboxes to make sure they include the deleted files, then select Undo
Changes
Restore an item deleted from the server
1. From the menu bar choose Tools, Options.
2. On the Options dialog box, navigate to Source Control, Visual Studio Team Foundation Server.
3. Select Show deleted items in the Source Control Explorer, and then choose OK.
4. From the menu bar choose View, Other Windows, Source Control Explorer.
5. In Source Control Explorer, navigate to the folder that contains the item you want to restore.
6. Open the item's context menu (select the item and right-click it) and then choose Undelete.
Restore TFVC managed items deleted from your dev machine outside
of Visual Studio
From time to time you may need to restore an item you have deleted outside Visual Studio (possibly by accident).
The method you use to restore such an item depends on whether you are using a local or a server workspace. See
Decide between using a local or a server workspace.
Use a local workspace to restore an item you deleted outside Visual Studio
When you use a local workspace, Visual Studio detects and enables you to resolve changes you have made
outside the system.
To use a local workspace to restore an item you deleted outside Visual Studio
1. In Team Explorer, choose Home, and then choose Pending Changes.
2. In the Excluded Changes section, choose the Detected changes link.
3. In the Promote Candidate Changes dialog box, select an item for which delete appears in the Change
column, open its context menu (right-click), and choose Restore this item.
Use a server workspace to restore an item you deleted outside Visual Studio
When you accidentally delete an item outside Visual Studio and you are using a server workspace, when you try
to open the item in Visual Studio you may see an error message such as: TF10187: Could not open document
file name The system cannot find the file specified.. You can restore the item by getting it from the server.
To use a server workspace to restore an item you deleted outside Visual Studio
1. In Source Control Explorer, browse to the folder that contains the deleted items.
2. Open the context menu of the folder (select the folder and right-click it) and choose Get Specific Version.
3. On the Get dialog box, select Overwrite all files even if the local version matches the specified
version.
Choose Get.
TIP
You can also use the tf get /force command.

Delete Command (Team Foundation Version Control) Delete a file from the server.
Destroy Command (Team Foundation Version Control) Permanently destroy an item.
Undelete Command Restore a file deleted from the server.
Undo command Undo pending changes.
Check in to a folder that is controlled by a gated
check-in build process
When you check in files to a version control folder that is controlled by a gated check-in build process, there are
some additional steps that you must take to complete the check-in.
and roles.
Begin checking in changes to a folder that is controlled by a gated

check-in build
If the Gated Check-in dialog box appears during your check-in, then your changes must first be built by Team
Foundation Build before they can be checked in.
To check in changes to a folder that is controlled by a gated check-in build
1. In the Gated Check-in dialog box:
If a build pipeline is displayed, proceed to the next step.
If the Build pipeline menu is displayed instead of the name of a build pipeline, on the Build
pipeline menu, choose the build pipeline that your build engineer suggests that you use.
2. Decide how you want to proceed:
Cancel the check-in operation and continue working: If you do not want to try building your
changes yet, choose Cancel, and then when the system asks you if you want to delete the shelveset,
choose Yes.
Cancel the check-in operation and start a private build of your changes: If you want to build
the code yourself in a private build, choose Cancel. You can now build the shelveset manually. For
more information, see Get started with CI/CD.
Proceed with the check-in operation while keeping your changes in your workspace: To
proceed with the check-in operation and continue working with your changes, see Proceed with the
Gated Check-in after Keeping the Changes in Your Workspace.
Proceed with the check-in operation while deleting changes in your workspace: If you do not
need to continue working with your changes, see Proceed with the Gated Check-in after Deleting the
Changes in Your Workspace.
Bypass the gated check-in requirement: If you have the Override check-in validation by build
permission set to Allow, you can bypass the gated check-in requirement. Choose Show options,
and then choose Bypass validation build and check in my changes directly (requires
permissions).
Proceed with the gated check-in after keeping the changes in your
workspace
The gated check-in process provides a way to proceed with the check-in and continue working with your changes.
The drawback of proceeding in this way is that if the build completes successfully you must reconcile the changes
in your workspace with the changes that are checked into version control.
To proceed with the gated check-in after keeping your changes in your workspace
1. Follow the steps in Begin Checking in Changes to a Folder that is Subject to Gated Check-in.
2. In the Gated Check-in dialog box, choose Build Changes.
In Team Explorer, when the information message appears in the Pending Changes page, monitor the
build by choosing the here link to display the build results window. You can also choose Home, and then
choose Builds to monitor the build on the Builds page.
3. After the build is completed:
Check-in committed: We recommend that you reconcile your workspace before you continue
developing your code. If you are using the Build Notifications application, the Gated Check-in
dialog box appears. Choose Reconcile. Otherwise, in Team Explorer, on the Builds page, under
My Builds, open the shortcut menu for the completed build, and then choose Reconcile
Workspace. When the Reconcile Workspace dialog box appears, use this dialog box to resolve
version control conflicts.
Check-in rejected: Correct the problems that caused the check-in to be rejected. In Team Explorer,
on the Builds page, under My Builds, double-click the build (or open the shortcut menu for the
build, and then choose Open). The build results window appears and contains information that can
help you resolve the problem that caused the build to fail. For some types of problems, you may be
able to choose the error or issue to view the file that requires corrections.
Proceed with the gated check-in after deleting the changes in your
workspace
If you want to proceed with the gated check-in operation and you do not plan to continue working with your
changes, you can delete the changes in your workspace. Your changes are preserved in a shelveset and built by the
system. If the build completes, then your changes are checked in. If the build fails, then you can unshelve the
shelveset to get the changes back into your workspace.
To proceed with the gated check-in after deleting changes in your workspace
1. Follow the steps in Begin Checking in Changes to a Folder that is Subject to Gated Check-in.
2. In the Gated Check-in dialog box:
Choose Show Options and then clear Preserve my pending changes locally.
Choose Build Changes.
3. In Team Explorer, when the information message appears in the Pending Changes page, monitor the
build by choosing the here link to display the build results window. You can also choose Home, and then
choose Builds to monitor the build on the Builds page.
4. After the build is completed:
Check-in committed: Now that your changes are checked in, you may want to get the latest version
of the files so that your workspace contains these changes. For more information, see Download
(get) files from the Server.
Check-in rejected: Correct the problems that caused the check-in to be rejected.
a. In Team Explorer, on the Builds page, under My Builds, double-click the build (or open the
shortcut menu for the build and then choose Open). The build results window appears.
b. In the build results window, look for information that can help you resolve the problem that
caused the build to fail. For some types of problems, you may be able to choose the error or
issue to view the file that requires corrections.
c. Retrieve your changes from the shelveset. For more information, see Suspend your work and
manage your shelvesets.
d. In your files, correct the problems that caused the build to fail.
See Also
Other Resources
Use a gated check-in build process to validate changes
Check In Pending Changes
Suspend your work and manage your shelvesets
Get the history of an item
One advantage of a version control system is that you can look back in time to get detailed information about
what changes have been made to your files. Team Foundation version control maintains historical data related to
every version of every file that has ever been checked in.
Often when you look over the history of a file, folder, or branch, you are trying to solve a problem or answer a
question. By using the Team Foundation version control History window, you can more easily resolve questions
and situations such as the following:
What changes have been made in the past weeks or months?
What work item was completed by this change to the file?
Who checked in this change? What did they say about the change? What did they change?
Unexpected changes occurred in this file, causing a bug in an area of the product that we thought was
stable. Who made this change, and why did they make it?
A change in this branch fixes a bug that also needed to be fixed in other branches. How can I make sure
that the change was merged to those branches?
Use the History window to get detailed historical data about a project, branch, folder, or file.
and roles.
To display the History window:
In Source Control Explorer, select an item, open its shortcut menu, and then choose View History.
TIP
You can customize the position of the window by right-clicking the title and then choosing one of these options:
Float, Dock, or Dock as Tabbed Document.
Use the History Command.

The History window displays the historical data about the item in two tabs:
The Changesets tab lists every change (including edits, renames, and merges) made to the item.
The Labels tab lists every label that has been applied to the item.
Changesets Tab
The Changesets tab displays detailed data about every change that has been made to an item. All changesets
that have modified the item are listed in a table that includes the following columns:
Changeset The ID of the changeset.
User The name of the user who checked in the changeset.
Date The date and time the changeset was checked in.
Comment The comment entered by the user who checked in the changeset.
NOTE
If you open this window by using the History command and you are displaying data about a project, branch, or folder,
then the history of children items (for example, the files contained by a folder) is shown only if you use the /recursive
option.
If the item is a file, then additional data is displayed in the following columns:
Change The types of changes that were made to the file with the changeset. Examples of values that can
appear in this column include add, edit, rename, and merge.
Path The path to the file.
TIP
Sometimes you need to share this kind of data with someone else. You can select one or more rows from the table in the
Labels tab, right-click them, click Copy to copy the data to the clipboard, and then paste the data into an e-mail message,
document, or spreadsheet.
Common Tasks
By using the Changesets tab, you can perform the following tasks:
TASK SUPPORTING CONTENT
View the item as it existed when the changeset was None

checked in: Double click the changeset or right-click it,
and then click View. (This command is available only if
the item is a file.)
Get more details about a changeset: Right-click a Find and view changesets
changeset and then click Changeset Details to get
information such as:
Other source files that are part of the changeset.
Work items associated with the changeset.
Any check-in notes left for reviewers.
Compare a past version with the current version: Compare files

Right-click a changeset and then click Compare.
Compare folders
Compare a past version with another past version:
1. Select a changeset.
2. Press and hold the CONTROL key and then select
the second changeset.
3. Right-click the second changeset and click
Compare.
Get a past version of the item: Right-click a changeset Download (get) files from the Server
and then click Get This Version to download the past
version of the item to your workspace.
View which users made specific changes within a file: View file changes using annotate
Right-click a changeset and then click Annotate. (This
command is available only if the item is a file.)
Get more details about a merge: If the changeset None

resulted from a merge change, you can expand this
item. Expand the node to display the changesets that
were merged into this item from another branch. (This
Get more details about changes that were made None

before a rename change: If the changeset includes a
rename change, you can expand this item. Expand the
node to display the changesets that occurred before the
rename change was made.
View other branches to which this changeset has View where and when changesets have been merged
been merged: Right-click the changeset and click Track
Changeset.
Roll back changes from one changeset Select a single Roll back changesets
changeset and choose Rollback Entire Changeset.
Roll back changes from two or more consecutive Roll back changesets
changesets Select a set of consecutive changesets and
choose Rollback.
Display non-recursive history of a folder You can get History Command

this data only from the command prompt.
Labels tab
All labels that have been applied to the item are listed in a table that includes the following columns:
Name The name of the label.
User The user who applied the label.
Date The date and time the label was applied.
Changeset The changeset to which the label applies.
Comment The comment made by the user who applied the label.
NOTE
When you display historical data about a project, branch, or folder, the data about labels applied to children items (for
example, the files contained by a folder) is not shown.
TIP
Sometimes you need to share this kind of data with someone else. You can select one or more rows from the table in the
Labels tab, right-click them, click Copy to copy the data to the clipboard, and then paste the data into an e-mail message,
document, or spreadsheet.
Common Tasks
TASK SUPPORTING CONTENT
View the item as it existed when the labeled changeset None

was checked in: Right-click a label and then click View. (This
Edit the label: Right-click the label and click Edit Label. Use labels to take a snapshot of your files
Delete the label: **Right-click the label and click Use labels to take a snapshot of your files
**Delete Label.
Compare a past version of the item with the current Compare files Compare folders
version: Right-click a label and then click Compare to
compare a past version of the item with the current version.
Get a past version of the item: **Right-click a label and Download (get) files from the Server
then click **Get This Version to download the past version
of the item to your workspace.
View other branches to which the labeled changeset has View where and when changesets have been merged
merged: **Right-click the label and click **Track
Changeset. (This command is available only if the item is a
file.)
View which users made specific changes within the View file changes using annotate
labeled version of a file: Right-click a changeset and then
click Annotate. (This command is available only if the item is
a file.)
See Also
Other Resources
View file changes using annotate
You can annotate a file to learn who made changes and what changes they made in all earlier versions of the file.
To perform these procedures, you must have the Read permission set to Allow. For more information, see
Permissions and groups reference.
To annotate a file
1. On the menu bar, choose View, Other Windows, Source Control Explorer.
2. In Source Control Explorer, go to the version of the file you want to annotate, open its shortcut menu,
and then choose Annotate.
The Annotated window displays the annotated file.
Each annotation appears to the left of the text that was changed and displays:
Changeset number, or Local if you have pending changes in your local workspace. To get more
information about the changeset, choose the changeset number.
The name of the person who made the change.
Date.
When you move the pointer over an annotation, the following information appears:
Path: The path of the changeset.
Changeset: The changeset number.
Owner: The name of the person who made the change.
Change: The type of change.
Date: The date of the changeset.
Lines: The line numbers where the changes were made.
Comment: The changeset check-in comment.
3. You can open the shortcut menu for an annotation, and then choose:
Changeset Details to display, in Team Explorer the Changeset Details page.
View History to open the History window.
Compare With Previous Version to compare, in the Diff window, the version you are examining
with the previous version.
If you have pending changes in your local workspace you can open the shortcut menu for the Local
annotation information and choose Compare With Workspace Version (<server name>) to
compare, in the Diff window, the version you are examining with the version you checked out from
the server.
Annotate This Version to open a new Annotate window that displays annotation information for
the selected version and all earlier versions of the file.
Track Changeset: to see to which branches the changeset has been merged. For more information,
see View where and when changesets have been merged.
Get This Version to download the selected version of the file to your local workspace.
See Also
Other Resources
Compare files
Use labels to take a snapshot of your files
Labels let you take a snapshot of your files so that at a later date you can refer back to that snapshot. By using
your label, you can view, build, or even roll back a large set of files to the state they were in when you applied
the label.
To apply a label, you must have the Label permission set to Allow. To find, list, or view labels, you must have
the Read permission set to Allow. To modify or delete a label, you must own the label or have the Administer
Labels permission set to Allow.
Using Labels
In many software projects, when the code has reached a reasonable level of quality and stability, the team will
build and release a new version of the product. The team needs to mark the current version of each file so that
even as the files continue to change, the team can still get and build the new version of every file in their project.
Theoretically, you could record the ID of each changeset for each file manually; but clearly this kind of process is
not practical. Team Foundation version control makes the job simple: You apply a label to the folder, branch, or
project that contains the files. You can give the label a name that follows whatever naming convention you
prefer. Some examples of label names include: "Sprint 5", "M1", "Beta2", and "Release Candidate 0".
After you have applied the label, you can use it to qualify operations such as building, branching, merging,
comparing, and getting specific versions of files and folders.
Sometimes after you apply a label you decide that you need to change it. Team Foundation version control
enables you to apply a label to additional files, remove a label from certain files, and even to modify which
version of a specific file to which the label applies.
Tip:
Applying a label provides many of the same benefits as creating a branch, but typically with lower cost and
complexity. The tradeoff is that for large databases, operations such as merging may take much longer
when running against a label.
Apply a Label
Tip:
When you use Visual Studio to apply a label that already exists, the operation removes the label from all file
versions and then applies the label. From the command prompt, however, the label operation is additive.
See Label Command (Team Foundation Version Control).
Apply a label
1. In Source Control Explorer, open the shortcut menu for the collection, project, branch, folder, or file to
which you want to apply a label and choose Advanced, Apply Label.
The New Label dialog box appears.
2. In the Name box, type a name for the label.
3. (Optional) Type your comments in the Comment box.
4. In the Version list, Latest Version is selected by default. This option is the one most typically used, but if
you need the label to target a specific version, select:
Changeset: Specify the number of the changeset in the Changeset box. Alternatively, choose the
ellipses (...) to open the Find Changesets dialog box. For more information, see Find and view
changesets.
Date: Specify a date in the Date box or select a date from the calendar on the drop-down menu.
Label: Specify an existing label upon which to base the new label. Either type the label name in
the Label box, or choose the ellipses (...) to open the Find Label dialog box. For more
information, see Find, Edit, and Remove Labels.
Workspace Version: The label is created for the version in your workspace.
5. When you are satisfied with your settings, perform one of the following steps:
To apply the label, choose Create.
To apply the label and then modify it after it has been applied, choose Create and Edit. This
applies the label and then displays the Label window. For more information about using the
Label window to edit a label, see Use the Label Window to Work with Labels.
Note:
When you apply a label using a name that already exists, the system warns you and asks if you want to
continue. If you choose OK to continue, any items not contained in the path to which you are applying the
label will no longer have that label.
Rename a Label
While you cannot modify the name of an existing label, you can easily apply a new label to exactly the same files
and same versions to which another label applies.
Apply a label based on an existing label
1. In Source Control Explorer, open the shortcut menu for the project collection node (the root node), and
then choose Advanced, Apply Label.
The New Label dialog box appears.
2. In the Name box, type a name for the label.
3. (Optional) In the Comment box, type a comment.
4. In Version list, select Label.
The Label box appears.
5. Perform one of the following steps:
Type the name of the existing label.
If you are not sure of the name of the existing label, choose the browse button with the ellipses (...)
next to the Label box.
The Find Label dialog box appears.
Use the options in the Find Label dialog box to filter the list of labels and find the existing label to
which you want to apply the new label. (For more information, see Find, Edit, and Remove Labels.)
6. Choose Create.
7. (Optional) After you have created the new label, you can remove the old label. For more information, see
Find, Edit, and Remove Labels.
List, Find, View, Edit and Remove Labels

There are two ways to list and find labels: the Find Label dialog box and the Label tab in the History window.
After you find the label you are interested in, you can then view it, edit it, remove it, or work with the files to
which it applies.
Find and work with labels by using the Find Label dialog box
1. In Source Control Explorer, on the menu bar choose File, Source Control, Find, Find Label.
The Find Label dialog box appears.
2. (Optional) Refine your search by performing one or more of the following steps:
In the Name text box, type the name of the label.
In the Project list, select the project that contains the label that you want to find.
In the Owner text box, type the name or alias of the owner of the label.
3. Choose Find.
The Results list displays labels that match the search criteria that you entered.
4. (Optional) Perform one of the following steps:
To view or edit a label, select it and choose Edit.
The Label window appears. For more information, see Use the Label Window to Work with
Labels.
To delete a label, select it and choose Delete.
Choose Close.
Sometimes you may not be sure of the name of a label, but you know that the label was applied to a particular
item under version control. The following procedure explains how to find and then work with a label in this
situation.
List and work with labels that apply to a specific item
1. In Source Control Explorer, open the shortcut menu for the item to which the label you want to find
applies, and then choose View History.
The History window appears.
2. Choose the Labels tab to display the list of labels that apply to this item.
3. (Optional) Perform one of the following steps:
To view or edit a label, open its shortcut menu and choose Edit Label.
The Label window appears. For information about how to use this window, see Use the Label
Window to Work with Labels.
To delete a label, open its shortcut menu and choose Delete Label.
Open the shortcut menu for the label and choose other actions such as Get This Version, and
Compare.
For more information about how to use the label tab in the History window, see Get the history of an item.
Download Labeled Versions of Files to Your Workspace

Labeling a set of files is like taking a snapshot of how they existed at a certain point in time. Weeks or months
after you have taken this snapshot, you may need to view or work with the files as they existed in that snapshot.
The following procedure explains how to download the labeled versions of a set of files to your workspace.
Download labeled versions of files to your workspace
1. In Source Control Explorer, open the shortcut menu for the project collection, project, branch, or folder
that contains the items you want to download and then choose Advanced, Get Specific Version.
The Get dialog box appears.
2. From the Type list, select Label, and then either type the label name in the Label box, or choose the
ellipses (...) to open the Find Label dialog box. For more information about how to use this dialog box,
see Find, Edit, and Remove Labels.
3. Review, and if appropriate, select any of the additional options in the Get dialog box.
4. Choose Get.
Use the Label Window to Work with Labels

After you have opened the Label window by using one of the preceding procedures, you are ready to begin
working with the label. At the top of the window is a box that displays the comment, which you can edit if you
want.
You can use the Label window to perform the following tasks:
Add an item to the label
Remove an item from the label
Change the version of a file
Perform other actions on an item
Add an item to the label
1. In the Label window, choose Add Item.
The Choose Item Version dialog box appears.
2. In the Choose Item Version dialog box, navigate to and then select the item that you want to add.
Tip:
You can press and hold the CONTROL or SHIFT keys and then select multiple items.
3. (Optional) If you need the label to target a specific version, from the Version list, select:
Latest Version: The label will be applied to the latest version that is in version control.
changesets.
4. Choose OK.
5. Choose File, Save.
Remove an item from the label
1. In the Label window, locate the collection, project, branch, folder, or file that you want to remove from
this label.
2. Open the shortcut menu for the item and choose Remove from Label.
The label is removed from the item. If the item is a project collection, project, branch, or folder, then the
label is also removed from all the items it contains.
Change the version of a file
1. In the Label window, locate the file that you want to modify.
2. Open the shortcut menu for the file and choose Change Labeled Version.
3. The Change Labeled Version dialog box appears.
4. Select:
Latest Version: Apply the label to the latest version that is in version control.
changesets.
Perform other actions on a labeled item
When you open the shortcut menu for an item in the Label window, you can also choose one of the following
commands:
View (files only)
View History
Compare (files only)
Annotate (files only)
Get This Version

Label Command (Team Foundation Version Control) Apply or remove a label.
Tip:
When you use this command to apply a label, you can specify a scope other than the project.
Labels Command List labels.
See Also
Other Resources
When you check in your changes, they are stored on the server as a changeset. Changesets contain the history
of each item in version control.
You can view a changeset to see what the exact file changes were, discover the owner's comments, find linked
work items, and see if any policy warnings were triggered.
You must be one of the Contributors for your project. See Team Foundation Server default groups,
permissions, and roles.
Find a changeset by ID
In Source Control Explorer, press Ctrl + G.
The Go to Changeset dialog box appears.
Type the number of the changeset and choose OK.

If you don't know the number, choose Find. See Find a changeset.
List changesets that update a specific file or folder

1. In Solution Explorer or Source Control Explorer, browse to the folder or file, open its shortcut menu,
and choose View History.
2. In the History window, select the row that contains the changeset for which you want to view details,
open its shortcut menu, and then choose Changeset Details.
The Changeset Details page appears in Team Explorer.
TIP
You can undock the Pending Changes page from Team Explorer and open it in a new window.
You can toggle between tree and list view from the Actions menu (Visual Studio 2013) or View Options menu
(Visual Studio 2015).
Search for changesets

1. In Source Control Explorer, on the menu bar, choose File, Source Control, Find, Find Changesets.
The Find Changesets dialog box appears.
2. (Optional) Next to the Containing File **box, choose **Browse.

3. (Optional) In the By User box, type the alias or the name of the project team member who is associated
with the changeset.
4. (Optional) In the Range section, choose one of the following options:
All changes Retrieves all changesets that were applied to that file or folder.
Changeset number Retrieves changesets from a range of numbers. In the from and to boxes,
type the range.
Created date Retrieves changesets from a range of dates. In the between and and boxes, use
the calendars to specify start and end dates.
5. Choose Find.
Changesets that match your criteria appear in the Results list.
6. Right-click the changeset for which you want information, and select Changeset Details...
The Details for Changeset dialog box appears.
7. In the Details for Changeset dialog box, view the change types that were added and any comments,
work items, check-in notes, and policy warnings that are associated with the changeset.
8. Close the Details for Changeset dialog box.
9. Choose OK.
Work with changesets

The Changeset Details view in Team Explorer has links to perform the following tasks:
Rollback to remove the effects of the changeset. See Roll back changesets.
Track to determine which branches have and have not received a set of changes. See View where and
when changesets have been merged.
Actions, Request Review to request a code review.
Actions, Open in Browser to view the changeset in your browser (for example, if you want to copy the
URL into an email to discuss the change with your team).
To find a changeset from the command prompt:
c:\users\jamal\workspaces\fabrikam>tf changeset
To view or modify changesets and to learn about other options, see Changeset Command.
Tips
You can download the version of a file in a changeset. See Download (get) files from the Server.
You can add a link between a changeset and one or more work items. See Manage dependencies,
link work items to support traceability.
Roll back changesets
A changeset is a permanent part of the history of your version-controlled items and cannot be undone or
removed. However, you can roll back the effects of one or more changesets.
Tip:
You can confirm the changes that result from rolling back some items match what you intend to do before
you commit them to the server. See Tips for details.
and roles.
Roll back changes from a single changeset

For example, a developer wants to remove the effects of a changeset:
To roll back a changeset from the Changeset Details page

On the Changeset Details page, choose Rollback.
To roll back a changeset from the History window
In the History window, open the shortcut menu of a version and choose Rollback Entire Changeset.
To roll back a changeset from Source Control Explorer
1. In Source Control Explorer, select an item, open its shortcut menu, and choose Rollback.
Note:
The items you select determine the scope that the rollback changes.
2. In the Rollback dialog box, select Rollback changes from a single changeset.
Roll back changes from a range of changesets

For example, a developer wants to remove the effects of some consecutive changesets:
To roll back a changeset from the History window
In the History window, select two or more consecutive versions, open their shortcut menu, and choose
Rollback.
To roll back a changeset from Source Control Explorer
Note:
The items you select determine the scope that the rollback changes.
2. In the Rollback dialog box, select Rollback changes from a range of changesets.
Roll back to a specific version

For example, a developer wants to roll back a file to an earlier version, eliminating the effect of all changesets that
occurred after that version:
To roll back to a specific version

2. In the Rollback dialog box, select Rollback to a specific version.

Rollback Command (Team Foundation Version Control)
Tips
If your change is still pending (you have not yet checked it in), you can undo the change instead of rolling it
back. See Develop code and manage pending changes.
Like most changes you make to files, a rollback change is queued as a pending change. After you roll
back the files, you can view the files you are changing and compare the content of the files with the latest
version on the server. After you confirm the actual changes match what you intend to do, you can then
check them in.
Rollback does not delete changesets or any data. If you change your mind, use rollback to revert the
content of the files back to their state before the rollback.
Suspend your work and manage your shelvesets
For a variety of reasons, sometimes you need to set aside some or all of your work in progress. Shelvesets are
useful when you want to stop work for:
Interruption: You have pending changes that are not ready for check in, but you need to work on a
different task.
Collaboration: You have pending changes that are not ready for check in but you need to share them
with another team member.
Code Review: You want another team member to perform a code review of your pending changes.
Tip:
If you are using Visual Studio Premium or a more powerful edition, you can use the Code Review
feature.
Private Build: Before you check in your changes, you can use your automated build system to build
and test your code.
Backup: You have work in progress that you cannot finish now so you want a backup copy that is
stored on your server and available to other team members who might need to access it.
Handoff: You have work in progress that you want to hand off to another team member.
You can move your pending changes to a shelveset on the server and then clean your workspace. The
shelveset saves and stores not only your file revisions, but also the Comment, the list of Related Work Items,
and check-in notes (if you evaluate policies before shelving).
You must be one of the Contributors for your project. See Team Foundation Server default groups,
permissions, and roles.
Suspend and resume your work from the My Work page

Note:
The My Work feature is available only in Visual Studio Premium and Visual Studio Ultimate.
From the My Work page you can save and then restore not only your file changes and related work items, but
also the position of your open windows, breakpoints, and other important cues.
In Team Explorer, choose Home, and then choose My Work. On the My Work page, choose Suspend &
Shelve, and then type a description of the suspended work.
When you are ready to resume the work, go the Suspended & Shelved Work section of the My Work page,
select a set of suspended work, and choose Resume.
Shelve your changes

Tip: In either Solution Explorer or Source Control Explorer, you can shelve a specific subset of the files that
you are working with: select them, open their context menu, and then choose Shelve Pending Changes.
The Pending Changes page appears, ready to shelve only the files you selected.
To shelve your changes

2. In the Pending Changes page, make sure that the changes you want to shelve are listed in the
Included Changes section. You can drag files between Included Changes and Excluded Changes
(Keyboard shortcut: open the context menu of an item, and then choose Include or Exclude.
3. Choose the Shelve link.
4. Type a name for the shelveset.
5. (Optional) Select either of the following check boxes:
Preserve pending change locally
By default, this check box is selected. When this check box is selected, your pending changes
(including the comment and the Related Work Items list) are not removed from your workspace.
If you want to clean your workspace to work on another task, you should clear this check box.
Evaluate Policies and check-in notes before shelving
When you select this check box, all check-in policies are evaluated before the shelveset is created.
For more information about check-in policies, see Set and Enforce Quality Gates.
6. Choose the Shelve button.
Find a shelveset
To find a shelveset
2. Choose the Actions link, and then choose Find Shelvesets.
3. On the Find Shelvesets page, enter the name or alias of a project team member in the box, and then
choose the Enter key.
Tip:
If you don't know the name of the owner, you can type ***** to list shelvesets for all users.
4. A list of shelvesets appears in the Results list. You can type a filter to reduce the size of the list.
View and work with a shelveset

After you have a list of shelvesets (explained in "To find a shelveset") in the Find Shelvesets page, double-click
the shelveset to view it.
The Shelveset Details page appears.
You can toggle between list and tree view from the Actions menu.
To get more information about a change to a file, open its context menu, and then choose Open, View
History, or one of the Compare options.
Choose Unshelve Changes if you want to retrieve the changes in the shelveset into your workspace:
1. For any file changes that you do not want to unshelve, open the context menu of the file, and then
choose Exclude.
2. If you want to delete the shelveset, clear the Preserve shelveset on server check box.
3. If you do not want to restore the work item list and check-in notes that are stored in the shelveset
clear the Restore work items and check-in notes check box.
4. Choose the Unshelve button.
If there are conflicts between changes in the shelveset and the file versions in your workspace, the
system will prompt you to resolve them.
Choose Delete Shelveset if you want to delete the shelveset.
Caution:
Be sure you do not need any of the work stored in a shelveset before you delete it. There is no way
to recover a deleted shelveset.

Shelve Command : Create or delete a shelveset.
Shelvesets Command : List shelvesets.
Unshelve Command : Unshelve a shelveset.
Difference Command : Compare the changes to a file in a shelveset with another version.
Tips
Unlike a changeset, a shelveset is a non-versioned entity. If you or another user unshelve the items of
which a shelveset consists, edit several files, and then later reshelve the shelveset, the system does not
create a new version of the items for future comparison and maintains no record of who revised the
items, when, or in what manner. The original shelveset is completely replaced.
Conflicts can occur and prevent you from resuming suspended work. If this happens, see Resolve
Team Foundation Version Control conflicts.
This section explains how to compare folders and files. You can compare server folders and local folders to each
other, and view the differences between the contents of each folder. You can compare two server files, two local
files, or a server file against a local file and view the differences between the files.
In This Section
Compare files
Describes how to view the differences between two server files, two local files, or a server file and a local file.
Compare folders
Describes how to compare two server folders, two local folders, or a server folder and a local folder.
Describes the name filters that are used to match the names of files or folders you are comparing.
Reconcile differences between two folders
Describes how to reconcile the differences between a server folder and local folder, and how to resolve conflicting
pending changes in your local folder.
Associate a file type with a file-comparison tool
Describes how to associate a specific file type with a third-party compare or difference tool.
Compare files
This article provides a guide for comparing files when using Team Foundation Version Control (TFVC ). If you're
using Git for version control, see comparing files with Git and Visual Studio.
NOTE
Even if you're not using version control, you can use the Diff window in Visual Studio to compare two files. To open the
Diff window directly in Visual Studio, you can use the devenv.exe tool with the /diff option from the Developer Command
Prompt to compare any two files on your computer.
Compare any two files using the Compare dialog

You can compare any two files using the Compare dialog. The files can both reside on the local system, both on
your Team Foundation Server, or one on each.
2. In Source Control Explorer, right-click a file and select Compare.
The Compare dialog box appears.
3. Specify the two files you want to compare - one under Source Path and the other under Target Path:
Type a path, or open the Browse menu, choose Local Path or Server Path, and then browse to
choose the file.
Choose an option to specify file the server file version when specifying a Server Path from the
Type menu: Changeset, Date, Label, Latest Version, or Workspace Version.
TIP
To compare any two local files, select Local Path... from both Browse... drop downs in the Compare dialog.
4. Choose OK.
Compare files in your workspace with the most recent version

Compare your work with the latest version on your Team Foundation Server while continuing to make
changes.
1. If you are not already connected to the project that you want to work in, then connect to the project.
2. From Team Explorer, open the Pending Changes view.
3. On the Pending Changes view, locate the file in the Included Changes list. Open the shortcut menu
for this file (select the file and right-click), and then:
Choose Compare with Workspace Version to see what changes you have made to the version
you checked out.
TIP
You can also press Ctrl+Shift and then double-click the file.
Choose Compare with Latest Version to see how the changes you have made compare to the
latest version of the file on your Team Foundation Server.
4. The Diff window appears. You can continue to make changes to the file in this window.
TIP
You can also use Solution Explorer and the Source Control Explorer windows to compare the file in your workspace
with a version of the file on the server. Select a file, open its shortcut menu (right-click), and then choose Compare.
When the Compare dialog box appears, choose OK.
Compare two versions of a file in your TFVC history

Compare two versions of a file already checked into Team Foundation Version Control:
2. In Source Control Explorer, right-click a file and select View History.
3. Select two versions of the file, right-click and select Compare.
Use the Diff window

When you compare files using the instructions in the previous sections, Visual Studio displays the files in the
Diff window. The Diff window shows the difference between two files. If one of the files is checked out in your
workspace, you can modify the file as you run the comparison.
NOTE
Even if you're not using version control, you can use the Diff window in Visual Studio to compare two files. To open the
Diff window directly in Visual Studio, you can use the devenv.exe tool with the /diff option from the Developer Command
Prompt to compare any two files on your computer.
Deleted text
Added text
Changed text
Code review comment
Visual summary of the differences between the files
Here are some tips for working with the Diff window:
Although Side-by-side mode is generally more effective in most cases, you can use whichever mode
works best for you and the code you are examining.
To skip:
To the next difference, choose Next difference (Keyboard: F8).
To the previous difference, choose Previous difference (Keyboard: Shift+F8).
Back and forth in the file, choose a section of the visual summary.
When you participate in a code review, you use the Diff window to see the code changes that are the
subject of the review. For more information, see Day in the life of a devops Developer: Suspend work, fix
a bug, and conduct a code review.
Merge changes between versions

Copy and paste changes from the diff view into the version in your workspace to make quick updates to bring
in updates from one version to another. Merge more complex changes between two versions when you resolve
merge conflicts in TFVC before making a check-in.
If you need to merge two files with significant differences outside of TFVC conflict resolution, use the
vsdiffmerge command line tool. The vsdiffmerge tool allows you to merge changes side-by-side and pick which
contents you want to keep for each difference between the files. Run the command with four file parameters
followed by the /m flag from the Visual Studio Developer Command Prompt to bring up the merge tool
directly against any two files.
The basic syntax for vsdiffmerge.exe is:
vsdiffmerge.exe "File1" "File2" "Base file" "Result file" /m
File1 and File2 are the full path to the files you want to merge. The Base file is the full path to the file both
files are based off of, and Result file is the full path to where you want to write the merged results.
Use the command prompt

Difference command Compare two files from the command prompt.
See Also
Compare folders
Compare folders
You can compare the differences between two server folders, two local folders, or a server folder and a local
folder.
To perform these procedures, you must have the Read permission set to Allow. For more information, see
Note:
To compare two local folders, you do not need Team Foundation Server permissions.
To compare folders by using Folder Difference

1. On the View menu, choose Other Windows, and then choose Source Control Explorer.
2. In Source Control Explorer, locate the source folder you want to compare, open its shortcut menu, and
then choose Compare.
The Compare dialog box appears and the version control path of the folder that you selected is in the
Source Path box.
3. Under Source Version, select the Type you want to use for comparison: Changeset, Date, Label, Latest
Version, or Workspace Version.
4. Enter the Target Path or choose Browse and locate the target folder.
5. If the Target Path is to a server folder, under Target Version, select the Type you want to use for
comparison: Changeset, Date, Label, Latest Version, or Workspace Version.
6. Under Filter, you can add or remove file and folder filters.
For more information, see Folder comparison filters.
Select the Filter local paths only box if you want to apply the filter only to local paths.
7. Under View Options, select which items that you want shown in the comparison results. You can select a
combination of view options by checking or clearing the following boxes:
Show items that exist only in source path.
Show items that exist only in target path.
Show items that are different.
Show items that are the same.
8. Choose OK.
The Folder Difference window displays a list of items that are compared in the source and target folders.
You can compare the differences between two versions of a file by opening its shortcut menu and
choosing Compare. The Diff window appears.
If there are differences between a server folder and your local folder, you can reconcile them.
See Also
Other Resources
Compare files
The folder comparison filter is an ordered list of name filters that is used to match the names of files or folders
that you are comparing. You can use Compare to evaluate the file or folder names against the name filters. Once
Compare finds a match or exclusion, the comparison stops.
The default name filters are as follows:
!*.pdb;!*.obj;!*.dll;!*.exe;!*.res;!*.resources;!*.cache;!*.ilk;!*.ncb;!obj\;!objd\;!bin\
Name Filters
The following wildcard characters have special meaning when they are used in a name filter:
? - Matches exactly one character.
* - Matches zero or more characters.
! - Specifies an exclusion name filter.
\ - Specifies a folder name filter.
; - Name filter delimiter.
IMPORTANT
The following characters are not allowed in name filters: " < > | \b \0 \t and characters 0-31.
The name filters are applied to the file and folder names by using the following rules:
When Compare evaluates a file or folder name, it compares the name to each filter in the order that you
specified the filters. As soon as the file or folder name matches a filter, the name is a match and it is not
compared against the remaining filters.
A folder filter must end with the \ wildcard character.
An exclusion filter must begin with the ! wildcard character.
If you specify any filters that are not the exclusion filter, only files or folders that match the specified filters
are included in the results.
If you specify an exclusion filter, all files or folders that do not match the exclusion filter are included in the
results.
If you want to exclude a subset of file or folder names, you must specify the filter for the file or folder name
that you want to match first and then specify the exclusion filter.
Examples
The following table lists filter name mask examples.
NAME MASK DESCRIPTION
*.cs Matches all C# files.
My*.bmp Matches all bitmap files that begin with My.
!*.exe Excludes all executable files.
!objd\ Excludes all objd folders.
The following table lists filter examples.
FILTER DESCRIPTION
*.cs;!objd\;!obj\;!bin\ Matches all C# files except those in objd, obj, or bin folders.
!*.resx;!*.ini;!resources\;!*junk*\ Excludes all .resx and .ini files, all files in the resources folder,
and all files in any folder that has a name that includes the
word junk.
See Also
Other Resources
Compare folders
After you compare a server folder and a local folder, you can reconcile the differences between the folder contents
and between files that have conflicting pending changes in your local folder. For more information, see Compare
folders.
To perform these procedures, you must have the Read and Check out permissions set to Allow. For more
Note: To reconcile two local folders or files, you do not need Team Foundation Server permissions.
To reconcile differences
1. In Source Control Explorer, right-click a folder, and then click Compare.
The Compare dialog box appears.
2. In the Compare dialog box. select the folder versions to compare. For more information see Compare
folders.
The Folder Difference window appears.
3. In the Folder Difference window, right-click the folder or file you want to reconcile, and click Reconcile.
Note: You can select multiple folders and files by holding down the CTRL key and clicking additional
folders or files. Also, you can press CTRL+A to select all folders and files.
The Reconcile Folder Differences window appears.

4. For Files that are not in your workspace, either click Get to download the latest version of files that you
do not have in your local workspace, or click Ignore to leave these files only on the server.
5. For Files that are not on the server, either click Add to Server to upload files that do not appear on the
server or click Ignore to leave these files only in your local workspace.
6. For Files that have pending changes, select one of the following options:
Ignore to keep the changes made to these files in your local workspace.
Undo Pending Changes to disregard changes made to these files in your local workspace.
Get to download the latest version of these files to your local workspace.
7. For Files that do not have pending changes, select one of the following options:
Click Get to download the latest version of files that you do not have in your local workspace.
Click Check Out to check out the server version of files. If you have made any changes to your local
version, you will have an option to merge these changes with the server version when you check in
the files.
Click Ignore to leave these files only on the server.
8. Click OK.
If you have pending changes in your local workspace that conflict with the server version of a file and you
chose to Get the latest version of the file, the Resolve Conflicts window appears. For more information,
see Resolve Team Foundation Version Control conflicts.
See Also
Other Resources
Compare folders
Compare files
An advantage of using Team Foundation version control to manage your files is that several people can work
concurrently on a file. One drawback is that sometimes you must resolve conflicts before you can get, check in,
unshelve, merge, or roll back your files.
Although it can be frustrating to encounter conflicts, the system provides information and tools to help you
understand and resolve conflicts.
Resolve conflicts
AutoResolve all conflicts
AutoMerge an individual conflict
Manually resolve an individual conflict
Understand the automatic options
Get tips
Resolve conflicts
Use the Resolve Conflicts window to resolve conflicts that are blocking you.
By default, the
window shows only the conflicts caused by the most recent operation you attempted. When the window is in
this state, a message appears that begins: Path filter applied. To show all conflicts in your workspace, choose
Get All Conflicts. A message that begins with: n Conflict(s) appears.
If a lot of time has passed since you made changes to files in your workspace, new conflicts might have
occurred. To refresh the Resolve Conflicts window, choose Refresh.
Each conflict contains information and sometimes links that might help you resolve it. To get more information,
you can select the conflict and choose:
History to see the history of the file. If the operation that caused the conflict is a Merge or a Rollback,
then you can choose the menu control to the right of History and then select either Source History or
Target History.
See Get the history of an item.
Annotate to view details on all changes that were made to the most recent version of the file,
including who made each change and when they made it. See View file changes using annotate.
Compare (or the menu to the right of the button and then choose a command). The Diff window
appears.
AutoResolve all conflicts

By default the system automatically attempts to AutoResolve All conflicts unless you have turned off this
option (see Tips). In the Resolve Conflicts window, you can also manually choose AutoResolve All, and then
choose:
Select All Conflict Types if you want the system to attempt to resolve the conflicts automatically by
using all its heuristics.
Select Specific Conflict Types if you want the system to attempt to resolve the conflicts, but you want
to exclude some heuristics.
The Choose Conflicts to Resolve dialog box appears. Check or clear the options that you want to
enable or disable, and then choose AutoResolve. For more information, see Understand the automatic
options below.
The system attempts to automatically resolve the conflicts displayed in the Pending Changes window. Any
conflicts the system was unable to resolve will remain in the window. You have to manually resolve these
conflicts.
AutoMerge a single conflict

Choose AutoMerge if you want to try to resolve selected conflicts using all the AutoMerge options described
in Understand the automatic options below.
Tip:
You can press and hold either the Ctrl or the Shift key and then select multiple conflicts.
Note:
If AutoMerge is disabled, then this conflict must be manually resolved.
Manually resolve a single conflict

If the system cannot automatically resolve a conflict, or if you want to make sure you understand what is
changing, you must manually resolve the conflict. Within each conflict, the system displays the actions that you
can take to resolve the conflict. The actions displayed depend upon the conflict type, and the operation that
caused the conflict.
Merge changes in merge tool
When a conflict is caused by conflicting content changes, you can choose Merge Changes in Merge Tool.
When you choose this action, the Merge window appears.
The outcome of your work to resolve the

conflict is shown in the Results pane.
In this window you can:
Select the layout of the window: Vertical View, Horizontal View, Mixed View.
Navigate among the differences and the conflicts.
Select items from the left and right versions of the file to include them in the result.
Type additional content into the file in the Result pane.
View the History of the file. See Get the history of an item.
Compare the various versions of the file.
Annotate the file to see who changed what. See View file changes using annotate.
When are satisfied with the contents of the Result pane, choose Accept Merge.
Understand the automatic options
In special cases, you may want to restrict the types of conflicts automatically resolved by the AutoResolve All
option.
When you choose AutoResolve All, and then Specific Conflict Types, the Choose Conflicts to Resolve
dialog box appears.
IF YOU WANT THE SYSTEM TO

AUTOMATICALLY RESOLVE
CONFLICTS THAT OCCURRED
BECAUSE... AS EXPLAINED IN THIS EXAMPLE... THEN SELECT THIS CHECK BOX...
Non-conflicting content changes In the file version on the left, a Conflicts with any content
were made in each version of a file zero was added at the beginning. changes
In the file on the right, a three
was added at the end:
Content changes were made that four and five were added to the Conflicts with content changes
are unique to the workspace workspace or target version: made only in the local
(during get or checkin operation) workspace or target branch
or target version (during merge or
rollback operation)
Content changes were made that four and five were added to the Conflicts with content changes
are unique to the server (during server or source version: made only in the server version
get or checkin operation) or or source branch
source version (during merge or
rollback operation)
A file on the server (during get or You checked out a file that is Conflicts caused by renaming
checkin operation) or in the named launch.cs and worked on file in the server version or
source branch (during merge or it. During that time, someone else source branch
rollback operation) was renamed checked in a changeset that
affected the same file. That
changeset did not modify the
contents of the file, but it did
change the name of the file to
start.cs.
Common content changes Changes to each version resulted Conflicts caused by identical
were made that resulted in in identical file content. The change in the server and
identical content in each changes can be to the content in workspace
version the files, as shown in the following
example:
You changed a file,
checked it in through a
Gated Check-in build, and
selected the Preserve my
pending changes locally
option
This option also resolves conflicts
that are caused by all other
operations (for example, rename,
delete, undelete, and branch) and
that result in identical files.
TIP
If you select this check box,

when you proceed, the system
will resolve these changes by
taking (downloading) the
server version onto your
workspace.

Resolve Command
Tips
By default the system automatically attempts to AutoResolve All conflicts. To change the option,
from the menu bar choose Tools, Options, and then in the Options dialog box, navigate to Source
Control, Visual Studio Team Foundation Server. Clear the Attempt to automatically resolve
conflicts when they are generated checkbox.
Does your team need to collaborate to resolve a large number of conflicts (for example, which might
occur after merge operation in a large codebase)? If so, a public workspace on a shared dev machine
might help. See Create and work with workspaces.
You can use the lock command to temporarily prevent changes to a particular file or folder in the source control
server. This can be helpful if you want to change an item in your workspace and then check it in without being
forced to resolve any merge conflicts. Only one user at a time may hold a lock on a particular file or folder. If you
want to prevent access to an item in a persistent way, you should use the Permission Command instead.
Lock Types
Team Foundation provides two types of locks: check-in locks and check-out locks.
Check-in lock
A check-in lock is less restrictive than a check-out lock. When you apply a check-in lock, users can continue to
make local changes to the item in other workspaces. But those changes cannot be checked in until you explicitly
remove the check-in lock from the item or implicitly remove it by checking in your changes to the file.
Check-out lock
In Visual Studio Team Foundation Server 2012, check-out locks are generally not effective because of local
workspaces (see Decide between using a local or a server workspace ). Specifically, check-out locks are:
Not enforceable because other users might be using local workspaces.
Not available if you are using a local workspace.
Disabled if a member of the Administrators security group of your project collection has enabled
asynchronous checkout for your team's server workspaces.
A check-out lock prevents users who are using server workspaces from checking out and making changes to the
locked item in their workspaces. You cannot apply a check-out lock to an item for which any pending changes
exist, in any workspace other than your own.
How Locking Works

If a file is checked out when you lock it, its check-out record is modified to contain the new lock type. If the files
are not checked out, a "lock" change is added to the set of pending workspace changes. Unlike the check-out
command, the lock command does not automatically make a file editable.
Team Foundation unlocks an item automatically when you check in pending changes in the workspace where it
is locked. Locks are also released if the pending changes for a file are undone by using the undo command.
Locks on folders are implicitly recursive. If you lock a folder, you do not have to lock the files that it contains
unless you want to apply the more restrictive check-out lock to a file in a folder that has a check-in lock.
Only one user at a time may hold a lock on a particular file or folder. You can learn which files are locked in the
Team Foundation version control server and by whom they were locked by using the Status command.
A lock may be placed either as its own operation or as part of several other operations. These include rename,
checkout, delete, undelete, merge, branch, and add to source control. When you lock an item as part of an add to
source control or branch operation, Team Foundation places the lock on the server path where the new item will
be created. This prevents another user from adding or branching a file to the same location. When you lock an
item by using the rename command, both old and new server paths are locked.
Unlocking an Item
You can unlock an item explicitly by using the unlock command or implicitly when you check in. When you check
in pending changes to a locked item, Team Foundation removes any locks.
Note:
By default, the UnlockOther permission is granted to administrators only. If you have the UnlockOther
permission, you can remove a lock from an item in the workspace of another user by using the Lock
Command.
See Also
Other Resources
Work with version control locks
Lock and unlock folders or files in Team Foundation
Version Control
NOTE
This content applies to files managed by Team Foundation Version Control (TFVC) that you need to lock or unlock. For help
unlocking files in use by programs on your PC, use the Handle and Process Explorer tools to help you find which program
that is locking your file(s).
A folder or file tracked by TFVC can be locked or unlocked to deny or restore the user's privileges. Privileges
include checking out an item for edit into a different workspace or checking in Pending Changes to an item from a
different workspace. For more information, see Create and work with workspaces.
You can use a lock to temporarily freeze the server version of an item so that you can check in a pending change
without having to resolve any merge conflicts. If you want to permanently prevent access to an item on the server,
you should use the Permission Command instead.
TIP
You can use the Lock command to remove another user's lock if you have sufficient permissions.
Requirements
See Permissions and groups reference.
To lock a folder or file from Source Control Explorer
IMPORTANT
These options will appear only when you are making changes in a server workspace. The use of local workspaces in your
Project makes check-out locks un-enforceable. Learn more.
1. On the View menu, choose Other Windows,and then choose Source Control Explorer.
You can also double-click Source Control in Team Explorer.
2. In Source Control Explorer, right-click on the file you want to apply a lock, and select Advanced.., then
Lock.. (Visual Studio 2015) or Lock.. (Visual Studio 2013)
3. In the Lock dialog box select the file or folder you want.
4. Choose either the Check Out lock or the Check In lock type, and then choose Lock . Learn more about
TFVC lock types.
Under Pending Changes, Source Control Explorer displays the status: lock. The next time your pending
changes are checked into the workspace, the lock will be removed. For more information, see Check in your
work to the team's codebase and understanding locks
NOTE
You can also lock folders and files from the command line. For more information, see Lock Command.
To unlock a folder or file from Source Control Explorer
IMPORTANT
You can only unlock files other members of your team have locked if you have UnlockOther permissions. If you don't have
permission to unlock a file the option will be inaccessible.
1. While working in the server workspace, navigate to the View menu and choose Other Windows, then
choose Source Control Explorer.
2. In Source Control Explorer, open the shortcut menu for the folder or file from which you want to remove a
lock, and then choose Unlock.
See Also
Other Resources
Lock Command
Set repository permissions for Git or TFVC
Azure DevOps Services | Azure DevOps Server 2019 | TFS 2018 | TFS 2017 | TFS 2015 | TFS 2013
By default, members of the project Contributors group have permissions to contribute to a repository. However, to
create and manage permissions for a repository, you must be a member of the Project Administrators group. You
can grant or restrict access to a repository by setting the permission state to Allow or Deny for a single user or a
security group.
Prerequisites
You must have a project. If you don't have a project yet, create one in Azure DevOps or set one up in an on-
premises TFS.
You must be a member of the Project Administrators Group or have your Manage permissions set to Allow
for Git repositories or the TFVC repository.
Default repository permissions

To contribute to the source code, you must be granted Basic access level or greater. Users granted Stakeholder
access for private projects have no access to source code. Users granted Stakeholder access for public projects
have the same access as Contributors and those granted Basic access. To learn more, see About access levels.
To contribute to the source code, you must be granted Basic access level or greater. Users granted Stakeholder
access have no access to source code. To learn more, see About access levels.
For a description of each security group and permission level, see Permissions and group reference.
Git
You can use Git repositories to host and collaborate on your source code. For an overview of code features and
functions, see Git.
TASK READERS CONTRIBUTORS BUILD ADMINS PROJECT

ADMINS
Clone, fetch, and explore the contents of a repository; also,

can create, comment on, vote, and contribute to pull
requests
Contribute to a repository, create branches, create tags,

manage notes
Create, delete, and rename repositories
Edit policies, Manage permissions, Remove others' locks

Bypass policies when completing pull requests, Bypass
policies when pushing, Force push (rewrite history, delete
branches and tags) (not set for any security group)
By default, the project-level Readers groups have read-only permissions.
TASK CONTRIBUTORS BUILD ADMINS PROJECT ADMINS
Branch Creation: At the repository level, can push their changes to

Contribute: At the repository level, can push their changes to

Note Management: Can push and edit Git notes to the repository.
They can also remove notes from items if they have the Force
permission.
Tag Creation: Can push tags to the repository, and can also edit or
remove tags if they have the Force permission.
Administer: Delete and rename repositories

If assigned to the top-level Git repositories entry, can add
additional repositories. At the branch level, users can set
permissions for the branch and unlock the branch. The
Administer permission set on an individual Git repository does
not grant the ability to rename or delete the repository. These
tasks require Administer permissions at the top-level Git
repositories entry.
Rewrite and destroy history (force push): Can force an update to

a branch and delete a branch. A force update can overwrite commits
added from any user. Users with this permission can modify the
The Project Collection Build Service can read from all repositories by default. Any pipeline which runs with project
collection scope can potentially read any repository in the organization/collection. You can remove this permission
for a repository: set "Read" to "Deny" for the Project Collection Build Service.
TFVC
Team Foundation Version Control (TFVC ) provides a centralized version control system to manage your source
control.
TASK READERS CONTRIBUTORS BUILD ADMINS PROJECT ADMINS
Contribute to a centralized version control, Read only

including Code Review (Check in, label, lock,
merge, pend a change)
Check in, revise, undo, or unlock other users'
changes
Manage branches, manage permissions
Set Git repository permissions

You can set the permissions for all Git repositories for a project, or for a single repository.
1. Open the web portal and choose the project where you want to add users or groups. To choose another
project, see Switch project, repository, team.
2. To set the permissions for all Git repositories for a project, choose Git Repositories and then choose the
security group whose permissions you want to manage.
For example, here we choose (1) Project Settings, (2) Repositories, (3) Git repositories, (4) the
Contributors group, and then (5) the permission for Create repository.
To see the full image, click to expand.
Otherwise, choose a specific repository and choose the security group whose permissions you want to
manage.
NOTE
If you add a user or group, and don't change any permissions for that user or group, then upon refresh of the
permissions page, the user or group you added no longer appears.
3. When done, choose Save changes.

1. Open the web portal and choose the project where you want to add users or groups. To choose another
project, see Switch project, repository, team.
2. Choose the gear icon to open the administrative context.
3. Choose Version Control.

4. To set the set the permissions for all Git repositories for a project, (1) choose Git Repositories and then (2)
choose the security group whose permissions you want to manage.
Otherwise, choose a specific repository and choose the security group whose permissions you want to
manage.
5. Choose the setting for the permission you want to change.
Here we grant permissions to the Contributors group to (3) create repositories.
6. When done, choose Save changes.
Set TFVC repository permissions

1. To set the set the permissions for the TFVC repository for a project, choose TFVC Repository and then
choose the security group whose permissions you want to manage.
For example, here we choose (1) Project Settings, (2) Repositories, (3) the TFVC repository, (4) the
Contributors group, and then (5) the permission for Manage branch.
To see the full image, click to expand.
NOTE
If you add a user or group, and don't change any permissions for that user or group, then upon refresh of the
permissions page, the user or group you added no longer appears.
2. Save your changes.

1. From the web portal, open the admin context by choosing the gear Settings icon and choose Version
Control.
2. Choose the TFVC repository for the project and then choose the security group whose permissions you
want to manage.
3. Change the permission setting to Allow or Deny.
For example, here we change the Manage branch permission to Allow for all members of the Contributors
group.
4. Save your changes.
Related articles
Default Git permissions
Default TFVC permissions
Default permissions and access
You can use version control commands to do nearly all tasks you can do in Visual Studio, and also several tasks
that can't be done in Visual Studio. You can use the tf.exe tool to run version control commands from a
command prompt or within a script.
Run a command
To launch the Visual Studio command prompt, from Windows Start, choose Visual Studio 2015, then choose
the Developer Command Prompt for V2015 shortcut.
Visual Studio 2017 users: The tf.exe binary is no longer in a fixed location in the Visual Studio install path
as in previous releases (for example, C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE ).
Scripts using tf.exe should not hardcode a path to the file based on the Visual Studio 2017 install path.
In most cases, you run the version control command in the context of a directory that is mapped in the
workspace. For example, $/SiteApp/Main/ is mapped to c:\\code\\SiteApp\\Main\\ . To get the latest version of
all items in the workspace:
c:\code\SiteApp\Main\SolutionA>tf get
Set up your dev machine and manage workspaces

Your workspace is a local copy of your team's codebase. Because it is a local copy on your dev machine, you
can develop and test your code in isolation until you are ready to check in your work. Here are some
commands to manage your workspace:
Proxy Command (Visual Studio 2010)
Workfold Command (Visual Studio 2010)
Workspace Command (Visual Studio 2010)
Workspaces Command (Visual Studio 2010)
See also: Set up Team Foundation Version Control on your dev machine, Create and work with workspaces
Develop your app
Use these commands to develop your app under version control with your team:
Add command
Adds files and folders to version control.
Checkout (or Edit) command
Checks out a file and changes its pending change status to "edit".
Delete Command (Team Foundation Version Control) (Visual Studio 2010)
Get command
Gets (downloads) the latest or a specified version of one or more files or folders from Team Foundation Server
to the workspace.
Rename Command (Team Foundation Version Control) (Visual Studio 2010)
Status command
Displays information about pending changes to files and folders items in one or more workspaces, or in a
shelveset.
Undo command
Discards one or more pending changes to files or folders.
Undelete Command (Visual Studio 2010)
See also: Develop your app in Team Foundation version control
Suspend your work
For a variety of reasons, sometimes you need to set aside some or all of your work in progress. To suspend and
resume your work, and to manage your shelvesets, use these commands:
Shelve Command (Visual Studio 2010)
Shelvesets Command (Visual Studio 2010)
Unshelve Command (Visual Studio 2010)
See also: Suspend your work and manage your shelvesets.
Contribute your work
Here's how to check in your code to the team's codebase:
Checkin command
Checks in pending changes to files or folders to the server.
See also: Check in your work to the team's codebase
Manage files and solve problems
View and Manage Version Control Files and Folders
Properties (or Info) Command (Visual Studio 2010)
Property Command (not documented)
Dir Command (Visual Studio 2010)
Destroy Command (Team Foundation Version Control) (Visual Studio 2010)
LocalVersions Command (Visual Studio 2010)
See also: Use Source Control Explorer to manage files under version control
View and Manage Past Versions
Changeset Command (Visual Studio 2010)
History command
Displays the revision history of one or more files or folders.
Label Command (Team Foundation Version Control) (Visual Studio 2010)
Labels Command (Visual Studio 2010)
Rollback Command (Team Foundation Version Control) (Visual Studio 2010)
Unlabel Command (Visual Studio 2010)
View Command (Visual Studio 2010)
See also: View and manage past versions
Compare Folders and Files
Difference Command (Visual Studio 2010)
Folderdiff Command (Visual Studio 2010)
See also: View and manage past versions
Resolve File Conflicts
Resolve Command (Visual Studio 2010)
See also: Resolve Team Foundation Version Control conflicts.
Work with Version Control Locks
Lock Command (Visual Studio 2010)
See also: Work with version control locks.
Isolate risk
Use the following commands to isolate risk using branches:
Branch Command (Visual Studio 2010)
Branches Command (Visual Studio 2010)
Merge Command (Visual Studio 2010)
Merges Command (Visual Studio 2010)
See also: Use branches to isolate risk in Team Foundation Version Control.
Administer Version Control
Use the following commands to administer your version control system:
Configure Command (Visual Studio 2010)
Permission Command (Visual Studio 2010)
See also: Administering Team Foundation Version Control (Visual Studio 2010).
Get Help on Version Control Commands
Use the following commands to get more information about version control commands:
Help Command (Team Foundation Version Control) (Visual Studio 2010)
Msdn Command (Visual Studio 2010)
Understand command syntax

The syntax of each command appears at the top of each reference topic.
Required and optional arguments
Non-bracketed arguments are required. [Brackets] indicate optional arguments that are not required to
complete a command. However, some optional arguments have defaults that are applied to the command
even if you do not specify the option.
Exclusive arguments
When options are separated by a pipe (|), you can specify one of the options.
Verbatim and replaceable arguments
Bold items are options that you include verbatim. Italicized items are arguments that you must replace with
actual characters to perform a command.
Command Shortcuts and Aliases
Some commands support shortcuts. For example, you can call the Delete command with either tf delete or tf
del.
Example
For example, the Checkout command:
tf checkout [/lock:( none|checkin|checkout)] [/recursive] itemspec [/login: username,[ password]]
Let's review the arguments from this example:

itemspec: You must replace this argument with an itemspec that specifies the items you are checking
out.
/lock:(none|checkin|checkout): You are not required to specify the /lock option. If you do not specify
it, then the system by default specifies /lock:none. Otherwise, you can specify one of the lock options.
The following arguments are optional and if you do not supply them, none of their effects apply to the
command:
/recursive: If you want to recursively check out multiple items in a folder, you must specify this
option verbatim.
/login:username,password: If you want to run the command as another user, you must specify
the /login option verbatim, replace username with the name of the user, and if necessary, you
can supply the password.
Specify the items affected by a command

You can use itemspecs and versionspecs to specify which items are affected by a command.
Use an itemspec argument to specify affected items
You use an itemspec (item specification) to specify the items affected by a command. You can specify items
either on a client machine or on your Team Foundation Server. You can use wildcard characters such as \* and
?.
Client itemspec arguments
A client itemspec argument specifies a path to items on a client machine such as a folder (for example,
c:\code\SiteApp\Main\SolutionA\) a file (for example,
c:\code\SiteApp\Main\SolutionA\Project1\program.cs or multiple files (for example,
c:\code\SiteApp\Main\SolutionA\*.cs. You can also specify UNC paths such as
\\myshare\code\SiteApp\Main.
Server itemspec arguments
A server itemspec argument specifies a path to items on your Team Foundation Server such as a folder (for
example, $/SiteApp/Main/SolutionA ) a file (for example,
$/SiteApp/Main/SolutionA/Project1/program.cs or multiple files (for example,
$/SiteApp/Main/SolutionA/*.cs.
You typically use server itemspec arguments when you need run a command on items not on the client
machine. For example, you are working on a dev machine and need to get some revision history data about
some items that are in a project collection you don't work in:
c:\>tf history /collection:http://fabrikam-3:8080/tfs/DefaultCollection

$/SiteApp/Main/SolutionA/Project1/* /recursive
/noprompt
Multiple itemspec arguments

For some commands, you can specify multiple itemspec arguments. For example:
c:\code\SiteApp\Main\SolutionA\Project1\>tf checkout program1.cs program2.c
Checks out program.cs and program2.c.

Use a versionspec argument to specify affected versions of items
You use a versionspec (version specification) to specify the version of items affected by a command. To provide
a versionspec you can:
Use the /version option. For example: /version:C44.
Append the versionspec to an itemspec with a semicolon. For example: program1.cs;C44.
When you use the History command or the Difference Command, you can specify a range of versions by
separating the versions with a tilde (~). For example:
c:\code\SiteApp\Main\SolutionA>tf history /noprompt * /recursive /v:D4/12/2012~D4/24/2012
Use the following syntax to specify a versionspec.
TYPE SYNTAX DESCRIPTION

Changeset [C]n Specifies items based on a
changeset number. If an item that
is in scope was not modified in the
specified changeset, the system
takes the latest version of the
item that occurred before the
specified changeset.
TIP
You can omit the C if you

specify only a number.
Examples
c:\code\SiteApp\Main>tf get
readme.txt /v:C8
-- or --
readme.txt /v:8
-- or --
readme.txt;8
If readme.txt was modified in

changeset 8, gets that version of
the file. Otherwise, gets the most
recent version of readme.txt
before version 8.
Label Llabel Specifies items to which label was
applied.
Examples
readme.txt;LJulyHotFix
Gets the version of readme.txt

that was labeled JulyHotFix.
/version:LLastKnownGood
Retrieves the version of all labeled

items (and deletes those items not
labeled) in the workspace as they
existed when the changeset
labeled as LastKnownGood was
created, for example, perhaps as
part of an automated build
process.
Date and time Dyyyy-mm-ddTxx:xx Specifies a changeset created on a

specified date and time.
-or-
Examples
Dmm/dd/yyyy
-or- c:\code\SiteApp\Main>tf get
/version:D2004-03-22
Any .NET Framework-supported
format.
Updates the workspace to match
-or- the codebase as it existed on
Any of the date formats 3/22/2004 at 00:00 (midnight).
supported on the local machine.
/version:D2004-03-22T09:00
Updates the workspace to match

the codebase as it existed on
3/22/2004 at 09:00 (9 AM).
For more information about .NET
Framework-supported date and
time formats see DateTime and
Standard Date and Time Format
Strings.
Workspace (current) W Specifies the version in your

workspace.
Workspace (specified) Wworkspacename; Specifies the version in a specified
workspaceowner workspace.
For example:
WResolveRIConflicts;PeterW
Tip T Specifies the most recent version.
Use options to modify how a command functions

You can use some common options to modify how a command functions.
Use the /noprompt option to suppress requests for data input and redirect output data to the command
prompt window
Use the /noprompt option to suppress requests for data input and redirect output data to the command
prompt window. This option can be useful when you need to use version control commands in a script because
the command proceeds without intervention by a user, and the data is available for the script to perform
operations such as parsing or capturing.
When you use this option, the system:
Suppresses all requests for input:
Questions are not asked in the command prompt window. For example, when you use the Undo
command with this option, the system does not prompt you to confirm if you want to proceed
with undoing the changes.
Windows and dialog boxes are not presented. For example, you use this option with the Checkin
command. Instead of displaying the Check In dialog box for you to confirm your options (which
items you want to check in or which work items to associate), the system proceeds with the check
in without confirmation.
Redirects output data to the command prompt. For example, you use this option with the History
command. The data is displayed in the command prompt window instead of the History window.
Use /login option to specify credentials when running a command
Use the /login option to specify the Team Foundation Server user account to run a command. This option can
be useful when you are working at the machine of another team member.
For example, Julia is working with Peter at his dev machine. She uses the Lock command to unlock a file that
she locked earlier:
c:\code\SiteApp\Main> tf lock /lock:none program.cs /login:JuliaI,JuliaPassword
If she wants to avoid having her password appear in the command prompt, she can enter the command
without the password:
c:\code\SiteApp\Main> tf lock /lock:none program.cs /login:JuliaI
After she enters this command, the system then prompts her to type her password in a dialog box that masks
her input.
Use the /lock option to apply or remove a lock
IMPORTANT
As a best practice, use the /lock option with discretion and notify your teammates why you are locking an item, and
when you plan to remove the lock.
Use the /lock option to apply or remove a lock at the same time you run another command such as Add or
Edit.
/lock:(none|checkin|checkout)
None: No lock is placed on an item. If a lock is already in place, it is removed.

Checkin or Checkout: Applies a lock. See Understand lock types.
Note:
In a few cases, the lock operation can fail:
If any other users have locked any of the specified items, the lock operation will fail.
The system ignores this switch if there is already a pending change to the item. In this case, you must
use the Lock Command to change a lock on an item.
Use option shortcuts

You can abbreviate the following options.
OPTION OPTION ALIAS
/comment -C
/computer -M
/delete -D
/force -P
/format -F
/help -?, -H
/lock -K
/login -Y
/newname -N
/noprompt -I
/owner -O
/recursive -R
/server -S
/slotmode -X
/template -T
/user -U
/version -V
/workspace -W
Understand exit codes

Version control commands return the following exit codes:
EXIT CODE DEFINITION
0 Success.
1 Partial success; this means at least something, or

possibly everything, failed to succeed.
2 Unrecognized command.
100 Nothing succeeded.
For example:
If one of the files you are trying to check out does not exist on the server, the command returns 1 to indicate
partial success.
Git permission command
Modifies the user access control list (ACL ) and displays authorization settings for a git repository or branch within
a git repository.
Requirements:
To view permissions, you must be able to view the artifact for the type of information you are requesting:
View collection-level information for project collections, View project-level information for projects,
and Read for repository (and branch if you are viewing branch permissions).
To manage permissions, you must have Manage permissions for the desired artifact.
For more information, see Permissions and groups reference.
tf git permission [/allow:(* |perm1[,perm2,...]]

[/deny:(* |perm1[,perm2,...])]
[/remove:(* |perm1[,perm2,...])]
[/user:username1[,username2,...]]
[/group:groupname1[,groupname2,...]]
/collection:TeamProjectCollectionUrl
[/teamproject:TeamProjectIdentifier]
[/repository:RepositoryIdentifier]
[/branch:BranchName]
[/login:username,[password]]
Parameters
PARAMETER DESCRIPTION
/allow:(* |perm1[,perm2,...]) The permissions to allow.
/deny:(* |perm1[,perm2,...]) The permissions to deny.
/remove:(* |perm1[,perm2,...]) The permissions to remove (sometimes referred to as not set).

You can use all three of /allow, /deny, and /remove in the
same invocation. For more information on how allow, deny,
and remove settings interact, see Permission settings.
/user:username1[,username2,...] The user or users for which to allow, deny, or remove. You
must specify at least one user or group.
/group:groupname1[,groupname2,...] The groups or groups for which to allow, deny, or remove. You
must specify at least one user or group. Groups and
individuals can be used together.
/collection:TeamProjectCollectionUrl Specifies the URL of the project collection that contains the
permissions to view or modify. For example:
http://myserver:8080/tfs/DefaultCollection or
https://fabrikam-fiber.visualstudio.com. This parameter is
required.
/teamproject:TeamProjectIdentifier Specifies the name of the project that contains the

permissions to view or modify.
/repository:RepositoryIdentifier Specifies the name of the repo that contains the permissions
to view or modify.
/branch:BranchName Specifies the name of the branch that contains the

permissions to view or modify. If you specify /branch, you
must also specify /repository.
/login:username,[password] Specifies the user account to run the command. See Use Team
Foundation version control commands.
See Git repository permission namespaces and actions for a list of the permissions that can be administered by the
tf git permission command.
Examples
NOTE
The following examples are broken into multiple lines for readability. To copy and paste them into the command-line and run
them, first copy them and paste them into notepad or another tool and edit them so the commands are contained on a
single line.
View collection level permissions

The following examples lists the permissions for the fabrikam-fiber collection.
tf git permission /collection:https://dev.azure.com/fabrikam-fiber

/login:FabrikamUser@hotmail.com,FabrikamPassword
View project level permissions

The following examples lists the project level permissions for the FabrikamFiber project which is in the fabrikam-
fiber collection.

/teamproject:FabrikamFiber
View repository level permissions

The following examples lists the project level permissions for the FabrikamFiber repository which is in the
FabrikamFiber project.

/teamproject:FabrikamFiber
/repository:FabrikamFiber
Require branch folders commands

The following examples show how to create a branch policy that enforces the following constraints:
Only master can exist at the repository root.
All users will be allowed to create branches under the features/ and users/ folders.
Administrators will be able to create branches under the releases/ folder.
In this example we'll use the following collection, project, and repository:
/collection:https://fabrikam -fiber.visualstudio.com
/teamproject:FabrikamProject
/repository:FabrikamRepo
First, block the Create Branch permission at the repository root for the project's contributors.
tf git permission /deny:CreateBranch

/group:[FabrikamProject]\Contributors
/collection:https://dev.azure.com/fabrikam-fiber/
Then, allow contributors to create branches under features and users .
tf git permission /allow:CreateBranch

/branch:features

/branch:users
Allow administrators to create branches under releases .

/group:"[FabrikamProject]\Project Administrators"
/branch:releases
Finally, allow administrators to create a branch called master (in case it ever gets deleted accidentally).

/group:"[FabrikamProject]\Project Administrators"
/branch:master
Git view command
Retrieves a file from a Git repository to a temporary location on your computer and displays it.
Requirements: See Permissions and groups reference.
tf git view /collection:TeamProjectCollectionUrl

/teamproject:TeamProjectIdentifier
/repository:RepositoryIdentifier
(/blobId:blobId | /path:path [/commitId:commitId])
[/output:localfile]
[/console]
Parameters
/collection:TeamProjectCollectionUrl Specifies the URL of the project collection that contains the file
to view. For example:
http://myserver:8080/tfs/DefaultCollection or
https://dev.azure.com/fabrikam-fiber. This parameter is
required.
/teamproject:TeamProjectIdentifier Specifies the name of the project that contains the repo. This
parameter is required.
/repository:RepositoryIdentifier Specifies the name of the repo that contains the file to view.
This parameter is required.
/blobId:blobId Specifies the ID of a blob to retrieve. This option cannot be

used with the path parameter. One of either path or blob is
required.
/path:path Specifies the path of the file. This option cannot be used with
the blob parameter. One of either path or blob is required.
/commitId:commitId Specifies the commit that contains the file to open for viewing.
If you omit this option, view retrieves the latest version from
the default branch (typically master). This parameter can only
be used with the path option.
/output:localfile The path and name under which to save the retrieved file. If
not supplied, the file is saved in %Temp%\TFSTemp .
/console Specifies that the file output should be directed to the console.
This is useful if you want to write the file out to disk using
console redirection (with a different name or location than the
versioned item).
Examples
The following example retrieves a file from the default branch (typically master) and saves it to the current folder,
and prompts the user for their credentials.
NOTE
The following examples are broken into multiple lines for readability. To copy and paste them into the command-line and run
them, first copy them and paste them into notepad or another tool and edit them so the commands are contained on a
single line.
tf git view /collection:https://dev.azure.com/fabrikam-fiber /teamproject:FabrikamProject

/path:FabrikamApp/Global.asax.cs
/output:Global.asax.cs
The following example retrieves a file from the default branch (typically master), and does not prompt for
credentials since they are supplied.
tf git view /collection:https://dev.azure.com/fabrikam-fiber

The following example retrieves a file from the specified commit.
tf git view /collection:https://dev.azure.com/fabrikam-fiber

/commitID:a2db383ffefa46a6f6638605a806925ea7c16ad9
Add command
Adds files and folders to version control.
Tip:
Before you add files to version control, you should first set up the workspace on your dev machine. See
Workspace Command or Set up Team Foundation Version Control on your dev machine.
tf add itemspec [/lock:(none|checkin|checkout)] [/encoding:filetype]

[/noprompt] [/recursive] [/noignore] [/login:username,[password]]
Parameters
/encoding: filetype Ignore this parameter.
itemspec Specifies the scope of the items to add. You can specify more
than one itemspec argument.
/lock Applies or removes a lock. See Use Team Foundation version

control commands.
/noignore By default certain types of files (for example, .dll files) are
ignored by version control. The rules in a .tfignore files apply
to the Add command when you specify a wildcard in your
itemspec. To override the application of the rules in this case,
specify /noignore.
You can configure which kinds of files are ignored using a
.tfignore file (see Add Files: .tfignore file).
/noprompt Suppresses the display of windows and dialog boxes and

redirects output data to the command prompt. See Use Team
/recursive Recursively adds items in the specified directory and any

subdirectories.
Examples
In all the following examples, assume that $/SiteApp/Main/ is mapped to c:\\code\\SiteApp\\Main\\ in the
workspace.
Add all new files in a local workspace
New files in a local workspace are automatically detected. You can promote these newly detected files to your
pending changes.
c:\code\SiteApp\Main\SolutionA\Project1>tf add
Adds the latest versions of all items (except those that are ignored) in a local workspace.
c:\code\SiteApp\Main\SolutionA\Project1>tf add /noignore
Adds the latest versions of all items in a local workspace.

Add individual items
c:\code\SiteApp\Main>tf add program1.cs program2.c
Adds the files program1.cs and program2.c.

Recursively add all items of a specific type
c:\code\SiteApp\Main>tf add *.cs /recursive
Adds all C# code files (.cs) in the current directory and any subdirectories.
Work in Visual Studio

Add files to the server Use Visual Studio to add files to the server.
Tips
The results of this command are queued as pending changes (see Status command) and do not take effect on
the server until you check in (see Checkin command).
If you need to set aside changes (and perhaps also want to clean your workspace for another task), use the
Shelve Command.
Checkin command
Checks in your pending changes to files or folders to the server.
Almost every change that you make to the files on your dev machine is stored in your workspace as a pending
change until you check it in. When you check in your changes, they are stored as a changeset on the server.
Although the Checkin command provides a different user interface than the one you can use in Visual Studio
(see Check in your work to the team's codebase), the process is fundamentally the same.
tf checkin [/author:author name] [/comment:("comment"|@comment file)]

[/noprompt] [/notes:("Note Name"="note text"|@notefile)]
[/override:(reason|@reasonfile)] [/recursive] [/saved] [/validate] [itemspec] [/bypass] [/force]
[/noautoresolve] [/login:username,[password]] [/new]
tf checkin /shelveset:shelvesetname[;shelvesetowner] [/bypass] [/noprompt] [/login:username,[password]]

[/collection:TeamProjectCollectionUrl][/author:author name] [/force]
Parameters
/author:author name Identifies the author of the pending changes so that one
user can check in changes on behalf of another user.
Requires the CheckinOther permission. See Permissions
and groups reference
/bypass Bypasses a gated check-in requirement. For more

information, see Check in to a folder that is controlled by
a gated check-in build process.
/collection:TeamProjectCollectionUrl If you use the shelveset option, the /collection option

specifies the URL of the project collection that contains
the shelveset. For example:
http://myserver:8080/tfs/DefaultCollection.
By default, the project collection is presumed to be the
one that contains the workspace that maps the current
directory.
/comment Associates a comment with the changeset using one of

the following arguments:
Comment: A user-provided comment about the
check-in.
@comment file: The path to a file on disk that
contains the comment for the check-in.
/force Forces a check-in on items with pending edits even when
there are no content changes in the file.
itemspec Specifies the scope of the items to check in from the

user's workspace. You can specify more than one
Itemspec argument. For syntax, see Use Team
/login:username,[password] Specifies the user account to run the command. See Use
Team Foundation version control commands.
/new The selected state of each pending change (as shown in

the Check In dialog box), the comment, associated work
items, check-in notes, and check-in policy override
reason, are stored on your dev machine as pending
changes until you check them in. The /new option clears
this check-in metadata before you check in.
This option and the behavior it modifies have no effect
when you use the /noprompt option.
/noautoresolve By default, the system automatically attempts to

AutoResolve All (see Resolve Team Foundation Version
Control conflicts). Specify this option to disable this
default behavior.
/noprompt Suppresses the display of windows and dialog boxes

(such as the Check In dialog box) and redirects output
data to the command prompt. See Use Team Foundation
version control commands.
/notes Provides one or more check-in notes to associate with

the changeset using one of the following arguments:
NoteFieldName=NoteFieldValue: Sets the value
of the check-in note field. You can provide
multiple, semicolon-separated "field=value"
expressions.
Notefile: The user-provided path of a file on disk
that contains check-in note field names and
values in the format of "field=value". A semicolon
separated note tile can span multiple lines, for
example:
Field1=Value1;
Field2=First line of Value2
Second line Value2;
Field3=Value3;
/override Overrides a check-in policy using one of the following
arguments:
reason: A user-provided reason why the check-in
policy is being ignored.
Reasonfile: The path to a file that contains a user-
provided description of the reason why the
check-in policy is being ignored.
/recursive Recursively checks in items in the specified directory and

any subdirectories.
/saved Ignore this parameter.
/shelveset:shelvesetname[;owner] Specifies a shelveset to check in. The optional owner

argument is used to specify a shelveset that the current
user does not own.
NOTE
After you check in the shelveset, the system deletes it.
/validate Tests whether the check in would succeed without

checking in the files. The system evaluates check-in
policies, check-in notes, and lists conflicts.
NOTE
If you do not specify the /noprompt option, you must

choose the Check In button on the Check In dialog box
to validate the check in. After you choose this button, the
system will not check in the files.
Examples
Check in all pending changes in the current workspace
c:\code\SiteApp\Main>tf checkin
Displays the Check In dialog box, which displays all pending changes in the current workspace. You can use the
Check In dialog box to select or clear the pending changes you want to check in, add a comment, associate work
items, and perform other tasks and then choose the Check In button when you are ready to proceed.
Check in all pending changes with a comment
c:\code\SiteApp\Main>tf checkin /comment:"Re-implemented Pi calculator"
Checks in all pending changes in the current workspace and provides a comment to help your teammates
understand the purpose of your changes.
Check in a change to a single item without using the Check In dialog box
c:\code\SiteApp\Main>tf checkin program.cs /noprompt
Checks in your pending changes to program.cs. The Check In dialog box is not displayed, and if any conflicts
block the check in, the system does not display the conflicts window.

Check in your work to the team's codebase Use Visual Studio to check in your changes to the server.
Tips
To set aside changes (and perhaps also want to clean your workspace for another task), use the Shelve
Command.
If conflicts block your check-in, you can use the Resolve Command to resolve them.
If a machine and user account do not have a workspace mapped to the Project Collection that contains
the shelveset, you can use the /shelveset and /collection options to check in a shelveset.
Checkout (or Edit) command
Checks out a file and changes its pending change status to Edit. You can call this command using either
Checkout or Edit.
tf checkout [/lock:(none|checkin|checkout)] [/recursive] [/encoding:encoding] itemspec [/login: username,

[password]]
Parameters
/encoding Ignore this parameter.
itemspec Specifies the scope of the items to check out. For syntax, see
Use Team Foundation version control commands.
/lock Applies or removes a lock. See Use Team Foundation version

control commands.
/recursive Recursively checks out items in the specified directory and

any subdirectories.
Examples
Check out a single item
c:\code\SiteApp\Main\SolutionA\Project1\>tf checkout program.cs
Checks out program.cs.

Check out two items
Checks out the files program1.cs and program2.c.

Check out and edit files Use Visual Studio to check out files.
Tips
If you are beginning a new task, it's probably a good idea for you to download the latest files from the
server before you check out files and begin your work. See Get command.
When you begin editing a file in a local workspace, it is automatically checked out for you.
You can view a list of your pending changes:
And work with related data such as Comments and Associated Work Items in the Check In dialog
box using the Checkin command.
At the command prompt by using the Status command.
When you are ready to check in your changes to the team's codebase on the server, use the Checkin
command.
If you need to set aside changes (and perhaps also want to clean your workspace for another task), use
the Shelve Command.
If you use a server workspace, files that you have not checked out are read-only.
Get command
Gets (downloads) either the latest version or a specified version of one or more files or folders from Team
Foundation Server to the workspace. Although the Get command provides a different user interface than
Visual Studio (see Download (get) files from the Server), the process is fundamentally the same.
tf get [itemspec] [/version:versionspec] [/all] [/overwrite] [/force] [/remap]

[/recursive] [/preview] [/noautoresolve] [/noprompt]
Parameters
/all If you use a local workspace (recommended), then it's

unlikely you will have to use this option.
You can use this option to restore an item that you have
accidentally deleted from a server workspace.
Your Team Foundation Server maintains an internal
record of all the items the workspace contains, including
the version of each. By default, when you get files, if the
internal record on the server indicates the workspace
already has the version you are getting, then it does not
retrieve the item. This option gets the items regardless
of the data contained in this internal record.
/force Combines /all and /overwrite.
itemspec Specifies the scope of the items to get. You can specify
more than one itemspec argument. If no itemspec is
provided, the system recursively gets all items in the
current workspace.
For syntax, see Use Team Foundation version control
commands.
/noautoresolve By default, the system automatically attempts to

AutoResolve All (see Resolve Team Foundation Version
Control conflicts). Specify this option to disable this
default behavior.
redirects output data to the command prompt. See Use
/overwrite If you use a local workspace (recommended), then it is

unlikely you will have to use this option.
By default, the system does not retrieve an item if it is
writable (that is, if its read-only attribute is cleared) on
the client machine. This option overrides the default
behavior and overwrites a writable item, unless the item
is checked out.
/preview Displays what would occur, without actually performing

the Get operation.
/recursive Recursively gets items in the specified directory and any

subdirectories. If you do not specify an itemspec, then
this option is implied.
/remap See phkelley's blog: tf get /remap.
/version:versionspec Specifies the maximum version, or the minimum and the

maximum versions, to display in the history data. The
default is /version:T (the latest version).
commands.
Examples
workspace.
Get the latest version of all items in a workspace
c:\code\SiteApp\Main\SolutionA>tf get
Gets the latest versions of all items in the workspace. For example, the above command would recursively get
all files in $/SiteApp/Main/ including all its child folders.
Recursively get the latest version of items of a certain type in a folder
c:\code\SiteApp\Main\SolutionA\Project1>tf get *.cs /recursive
Gets the latest version of all C# (.cs) files in c:\\code\\SiteApp\\Main\\SolutionA\\Project1 .

Get the latest version of a file
c:\code\SiteApp\Main\SolutionA\Project1>tf get program.cs
Gets the latest version of program.cs in Project1.

Get a specific version of a file
c:\code\SiteApp\Main\SolutionA\Project1>tf get program.cs;8
Gets version 8 of program.cs in Project1.

Get the latest version of two files
c:\code\SiteApp\Main\SolutionA\Project1>tf get file1.cs file2.cs
Gets the latest version of file1.cs and file2.cs in Project1.

Synchronize a workspace to match a version of the team's codebase
c:\code\SiteApp\Main>tf get /v:15
Synchronizes the workspace to match the codebase as it existed when changeset 15 was created:
The name and content of every item in the workspace is changed to match the state it was in on the
server.
Items that were deleted after that changeset are restored to the workspace.
Items that were added after that changeset are deleted from the workspace.
Synchronize a workspace to match a labeled version of the team's codebase
c:\code\SiteApp\Main>tf get /v:LLastKnownGood
Synchronizes the workspace to match the items in the codebase that are labeled LastKnownGood:
The name and content of every labeled item in the workspace is changed to match the state it was in on
the server.
Labeled items that were deleted are restored to the workspace.
Items that are not labeled on the server are deleted from the workspace.

Download (get) files from the Server Use Visual Studio to get files and folders.
Tips
If you are beginning a new task, it's probably a good idea for you to run tf get (you can do so from
any directory in your workspace) to download the latest files from the server before you check out files
and begin your work.
As needed, this command creates folders on disk to contain the child items that the command is
downloading.
You can view information about the history of an item using the History command and the Changeset
Command.
If you are concerned about what changes might occur to the files in the workspace, you can use the
/preview option to see the changes that would occur without actually implementing them.
Conflicts could block your get. A typical cause of conflicts is trying to get an item on which you have
pending changes. You can use the Resolve Command to resolve these conflicts.
History command
Displays the revision history of one or more files or folders. The data is displayed in either the History window, or
if /noprompt option is specified, at the command prompt.
tf hist[ory] itemspec [/version:versionspec]

[/stopafter:number] [/recursive] [/user:username]
[/format:(brief|detailed)] [/slotmode] [/itemmode] [/noprompt]
[/login:username,[password]] [/sort:ascending,descending]
[/collection:TeamProjectCollectionUrl]
Parameters
/collection: TeamProjectCollectionUrl Specifies the URL of the project collection that contains
the items. For example:
By default, the project collection is presumed to be the
one that contains the workspace that maps the current
directory.
/format Specifies how much detail to display about each

changeset when the /noprompt option is specified:
Brief (default): Displays one line about each
changeset that includes: ID number, changes
made, user who made the changes, date, and
comment. Some of the data may be truncated.
Detailed: Displays a full description of each
changeset. In addition to the above information,
this option displays additional data such as date
with time, items changed, check-in notes, and
check-in policy warnings.
/itemmode You cannot combine this option with the /slotmode

option. See Matt Mitrik: Changing to Slot Mode in TFS
2010 Version Control.
itemspec Specifies the items for which to display history. For

syntax, see Use Team Foundation version control
commands.
/noprompt This option:
Suppresses the display of windows and dialog
boxes (such as the History window) and redirects
output data to the command prompt. See Use
Does not display the history of revisions that
occurred before an item was moved, renamed,
branched, or merged.
/recursive Recursively retrieves historical data on items in the

specified directory and any subdirectories.
/slotmode You cannot combine this option with the /itemmode

option. See Matt Mitrik: Changing to Slot Mode in TFS
2010 Version Control.
/sort Sorts the revision history for one or more files or folders
in either of the following orders:
Ascending: from the oldest to the most recent
revision.
Descending (default): from the most recent to
the oldest revision.
You must use the /noprompt option with this option.
/stopafter:number Specifies the maximum number of changesets to display

in the history data.
/user:username Filters the historical data to show changes made by the

specified user. An asterisk (*) symbol includes data on
changes from all users (the default).
/version:versionspec Specifies one of the following limits on the history data:

The maximum version
The minimum and the maximum versions using
the range ~ syntax.
The default is /version:W (the version in the
workspace).
commands.
You cannot combine this option with the /slotmode
option.
Examples
Get history of a single file
c:\code\SiteApp\Main\SolutionA\Project1>tf history program2.cs
Displays all changes made to program.cs in the History window.
c:\code\SiteApp\Main\SolutionA\Project1>tf history program2.cs /noprompt
Displays all changes made to program.cs in the command prompt window. For example:
Changeset Change User Date Comment

--------- -------------------------- ----------------- ---------- --------
29 edit Jamal Hartnett 4/23/2012 Fix bug
20 add Raisa Pokrovskaya 4/12/2012 Add new
Get history of all items in a folder
c:\code\SiteApp\Main\SolutionA>tf history * /recursive
Displays all changes made to all items in SolutionA (including those in subfolders) in the History window.
Get history of the last five changes to all items in a folder
c:\code\SiteApp\Main\SolutionA>tf history * /noprompt /recursive /stopafter:5
Displays the latest 5 changes made to items in SolutionA (including those in subfolders):
Changeset User Date Comment

--------- ----------------- ---------- ----------------------------------------
31 Raisa Pokrovskaya 5/15/2012
29 Jamal Hartnett 4/23/2012 Fix bug in new method
20 Raisa Pokrovskaya 4/12/2012 Add new method, add program2.cs to Proje
Get history from version x and earlier
c:\code\SiteApp\Main\SolutionA>tf history /noprompt * /recursive /v:30
Displays changes made to all items in SolutionA (including those in subfolders) in version 30 and earlier:

--------- ----------------- ---------- ----------------------------------------
20 Raisa Pokrovskaya 4/12/2012 Add new method, add program2.cs to 15 Raisa Pokrovskaya
4/8/2012
Get history from date D and earlier

c:\code\SiteApp\Main\SolutionA>tf history /noprompt * /recursive /v:D4/24/2012
-- or --
c:\code\SiteApp\Main\SolutionA>tf history /noprompt * /recursive /v:D2012-04-24T12:00
Displays changes made to all items in SolutionA (including those in subfolders) on 4/23/12 or earlier:

--------- ----------------- ---------- ----------------------------------------
20 Raisa Pokrovskaya 4/12/2012 Add new method, add program2.cs to 15 Raisa Pokrovskaya
4/8/2012
Get history from version x to version y
c:\code\SiteApp\Main\SolutionA>tf history /noprompt * /recursive /v:D4/12/2012~D4/24/2012
Displays changes made to all items in SolutionA (including those in subfolders) between 4/12/2012 and
4/23/12:

--------- ----------------- ---------- ----------------------------------------
20 Raisa Pokrovskaya 4/12/2012 Add new method, add program2.cs to
Get detailed history
c:\code\SiteApp\Main\SolutionA>tf history /noprompt * /recursive /v:D4/12/2012~D4/24/2012 /format:detailed
Displays details about changes made to all items in SolutionA (including those in subfolders) between
4/12/2012 and 4/23/12:
Changeset: 30
User: Raisa Pokrovskaya (Fabrikam)
Date: Monday, April 23, 2012 1:23:05 PM
Comment:
Much better name for this file
Items:
rename $/SiteApp/Main/SolutionA/Project1/programBig.cs
delete, source rename $/SiteApp/Main/SolutionA/Project1/program3.cs;X15
-------------------------------------------------------------------------------
Changeset: 29
Date: Monday, April 23, 2012 1:03:13 PM
Comment:
Fix bug in new method
Items:
edit $/SiteApp/Main/SolutionA/Project1/program1.cs
edit $/SiteApp/Main/SolutionA/Project1/program2.cs
-------------------------------------------------------------------------------
Changeset: 20
Date: Thursday, April 12, 2012 5:09:35 PM
Comment:
Add new method, add program2.cs to Project1
Items:
add $/SiteApp/Main/SolutionA/Project1/program2.cs
Check-in Notes:
Documentation:
An important new part of our codebase.
Policy Warnings:
Override Reason:
Jamal agrees with me that we can bypass for this check-in.
Messages:
The Code Analysis Policy requires files to be checked in through Visual
Studio with an open solution.
Get the non-recursive history of a folder
c:\code\SiteApp\Main\SolutionA>tf history .
Displays the history of the SolutionA folder in the History window, which enables you to explore earlier changes
to the folder. For example, if the most recent change to the folder was a rename, you can expand the changeset to
see changes that occurred before the rename.
c:\code\SiteApp\Main\SolutionA>tf history . /noprompt
Displays the most recent change to the SolutionA folder in the command prompt window.

Get the history of an item Use Visual Studio to get revision history.
Tips
For information about how to use the History window, see Get the history of an item.
To get more detailed information about a changeset (for example, you want to see associated work
items):
In the History window, double-click the changeset or open its context menu and choose Changeset
Details.
From the command prompt, use the Changeset Command.
For more information about changesets, see Find and view changesets.
The /collection option is useful for running this command from a machine and user account that does
not have a workspace mapped to the Project Collection that contains the items.
See View and manage past versions.
Status command
Displays information about pending changes to files and folders in one or more workspaces. Or, when you use
the /shelveset option, displays information about pending changes in a shelveset.
tf stat[us] itemspec [/collection:TeamProjectCollectionUrl]

([/workspace:workspacename[;workspaceowner]]
| [/shelveset:shelvesetname[;shelvesetowner]])
[/format:(brief|detailed)] [/recursive][/user:(*|username)]
[/nodetect]
Parameters
ARGUMENT DESCRIPTION
/collection: TeamProjectCollectionUrl When you use the /workspace option, specifies the URL
of the project collection that contains the workspace that
contains the pending changes. For example:
http://myserver:8080/tfs/DefaultCollection. If not
specified, by default the project collection is presumed to
be the one that contains the workspace that maps the
current directory.
Ignored if you do not use the /workspace option.
NO TE
See Remarks, below, for the limitations of this option.
/format Specifies how much detail to display about each pending

change:
Brief (default): Displays one line about each
pending change that includes: file name, changes,
whether the item is locked (indicated by an
asterisk () symbol), local path, and user (if using
the /collection and /workspace options ). Some
of the data might be truncated.
Detailed: Displays a full description of each
pending change. In addition to the above
information, this option displays additional data
such as date and time, and lock.
itemspec Specifies the items for which you want pending change
data. For syntax, see Use Team Foundation version
control commands. You can specify more than one
itemspec argument.
/login Specifies the user account to use to run the command.

See Use Team Foundation version control commands.
/recursive Recursively retrieves data about pending changes to

items in the specified directory and any subdirectories.
/shelveset:shelvesetname[;shelvesetowner] Specifies the shelveset that contains the changes you

want to list.
This option cannot be combined with the /workspace
option.
/user Lists all pending changes made by the specified user. An

asterisk () symbol includes data about changes from all
users. The default is the current user.
NO TE
/workspace workspacename[;workspaceowner] Specifies the name of the workspace that contains the
pending changes. If not specified, the workspace is the
one that maps the current directory.
You can specify workspaceowner to get data about
pending changes in a workspace that belongs to a
specific user. If not specified, the workspace is presumed
to be the current user, or if specified, the
/login:username.
This option cannot be combined with the /shelveset
option.
NO TE
Remarks
You can use the Status command to view pending changes in the current workspace (for example, the workspace
that maps the current directory in the command prompt window ) regardless of whether it is a local workspace or
a server workspace. You can also use this command to view pending changes in a remote server workspace (for
example, changes made by another user on another dev machine) by using the /collection, /user, and
/workspace options. However, you cannot view pending changes in a remote local workspace.
Also see: Decide between using a local or a server workspace.
Examples
workspace.
List all changes in the current workspace
c:\code\SiteApp\Main\SolutionA\>tf stat
Lists all pending changes in the workspace.

List all changes in a folder
c:\code\SiteApp\Main>tf stat SolutionA\*
Lists all pending changes to all items in the SolutionA folder.

List all changes in a folder and its subfolders
c:\code\SiteApp\Main>tf stat SolutionA\* /recursive
Lists pending changes to all items in the SolutionA folder, including those in its subfolders).

Develop code and manage pending changes Use Visual Studio to view and manage pending changes.
Tips
Most changes you make to files under version control are queued as pending changes in your workspace. See
Develop code and manage pending changes and Create and work with workspaces.
You can use the Difference Command to get details about edit changes (changes to the content) in a file.
If you need to set aside changes (and perhaps also want to clean your workspace for another task), use the
Shelve Command. For more information about shelvesets, see Suspend your work and manage your
shelvesets.
When you are ready to check in changes to the server, use the Checkin command.
Undo command
Discards one or more pending changes to files or folders.
tf undo [/workspace:workspacename[;workspaceowner]]
[/recursive] itemspec [/noprompt] [/login:username,[password]]
[/collection:TeamProjectCollectionUrl]
Parameters
/collection : TeamProjectCollectionUrl Specifies the URL of the project collection that contains
the items. For example:
If you do not use the /workspace option, by default the
project collection is presumed to be the one that contains
the workspace that maps the current directory.
itemspec Specifies the scope of the items. You can specify more
than one itemspec argument. For syntax, see Use Team
/login Specifies the user account to use to run the command.

See Use Team Foundation version control commands.

redirects output data to the command prompt. See Use
/recursive Recursively undoes changes to items in the specified

directory and any subdirectories.
/workspace workspacename[;workspaceowner] Specifies the name of the workspace in which you want to
undo pending changes. If not specified, the workspace is
the one that maps the current directory.
You can specify workspaceowner to undo a pending
change in a workspace that belongs to a specific user. If
not specified, the workspace is presumed to be the
current user, or if specified, the /login:username. You
must have the UndoOther permission set to Allow to
undo changes in another user's workspace.
NO TE
If you use the undo command to undo a pending

change in a remote workspace that is still in use, then
before continuing work in that workspace, a user must
log on to the machine that hosts the workspace and
then get (and in some cases get /all) the items affected
by the undo.
Remarks
For each item on which there is a pending edit change, the undo command determines if the file has been
modified on disk. If the file has been modified and the /noprompt option has not been specified, the system
prompts you to confirm that you want to proceed. Choose the N key to leave the change in place, the Y key to
proceed with only the current change, or the A key to proceed with this and any other modified files that are
subsequently detected.
The undo command removes any locks on the items.
Examples
Remove pending changes to a file
c:\code\SiteApp\Main\SolutionA\Project1>tf undo program.cs
Removes all pending changes to program.cs.

Recursively remove pending changes to all items in a folder
c:\code\SiteApp\Main>tf undo * /recursive
Removes all pending changes in the c:\code\SiteApp\Main folder and all its subfolders.
Remove pending changes to a file in a remote workspace
c:\>tf undo /collection:http://fabrikam-3:8080/tfs/DefaultCollection

/workspace:FABRIKAM-1;JuliaI $/SiteApp/Main/SolutionA/Project1/program.cs
Removes all pending changes to program.cs in the specified collection and workspace.

Develop code and manage pending changes Use Visual Studio to undo pending changes.
Tips
To view a list of pending changes in the current or in a remote workspace, use the Status command.
You can use the /workspace option (and as needed, the /collection option) to undo changes on a remote dev
machine. This capability is especially useful in cases when, for example, a file has been checked out and
possibly locked on a dev machine that you cannot access. See the above explanation of the /workspace for
information about how this works.
If you need to clean your workspace (for example, because your work is interrupted by a more urgent task)
and want to preserve the pending changes instead of undoing them, you can suspend them. See Shelve
Command. You can also preserve the position of your open windows, breakpoints, and other important cues.
See Suspend your work and manage your shelvesets.
You can also discard changes that have already been checked in. See Undelete Command and Rollback
Command (Team Foundation Version Control).
Delete Command (Team Foundation Version Control)
Removes files and folders from the Team Foundation version control server and deletes them from the disk.
NOTE
The results of this command are not visible in other workspaces until you perform a check-in operation. For more
information, see Check In Pending Changes.
To use the delete command, you must have the Check out permission set to Allow. If you include the /lock
option with a value other than none, you must have the Lock permission set to Allow. Additionally, you must
own the workspace or have the global Administer workspaces permission set to Allow. For more information,
see Permissions and groups reference.
tf delete [/lock:(none|checkin|checkout)] [/recursive] [/login:username,[password]] itemspec
Parameters
itemspec Identifies the file or folder to delete from the Team

Foundation version control server. For more information
about how Team Foundation parses itemspecs to
determine which items are within scope, see Command-
Line Options.
Note: You can specify more than one Itemspec
argument.
username Provides a value to the /login option. You can specify a

username value as either DOMAINUserName or
UserName.
OPTION DESCRIPTION
/lock Prevents other users from checking in or checking out the
specified items. For more information, see Understanding
Lock Types.
Lock Options:
None
Default. No lock is applied. If you have placed a
lock on the specified file, this option removes it. It
does not remove a lock placed by someone else.
Checkin
Other users can check out the specified items but
they cannot check in revisions to locked files until
you release the lock by performing a check-in. If
any other users have locked any one of the
specified items, the lock operation fails.
Checkout
Prevents other users from checking in or checking
out any one of the specified items until you
release the lock by performing a check-in. If any
other users have locked any one of the specified
items, the lock operation fails.
/recursive Deletes all files and/or folders and subfolders that match
the itemspec from the specified directory.
tf delete folder1\folder2 /recursive (where
folder1\folder2 exists and is a directory) deletes all
the files and subdirectories contained by
folder1\folder2 and folder1\folder2 itself.
tf delete folder1\folder2\filespec /recursive
deletes all files and subdirectories matching
filespec contained in folder1\folder2 and each of
its subdirectories, as well as all files and
subdirectories contained within any directory that
matches the filespec.
For example, in a workspace containing:
Folder1\AVeryLongDirectoryName (with some files
inside) and
Folder1\Folder2\AVeryImportantFile.txt
tf delete 'Folder1\AVer' /recursive
deletes
folder1\folder2\NeverDelete\AVeryImportantFile.tx
t because it matches the wildcard character.
/login Specifies the user name and password to authenticate the

user with Visual Studio Team Foundation Server.
Remarks
The delete command records a pending change of type "delete" in your workspace for the items that you have
specified. When you commit a pending change of type "delete" to the Team Foundation version control server by
using the** checkin** command, Team Foundation removes the item from the Team Foundation version control
server but does not delete it permanently. You can locate deleted items in the Team Foundation version control
server by using the Dir Command and you can restore deleted items using the Undelete Command.
If you have deleted an item in your workspace but have not checked in the change, you can restore the item to
your workspace and remove the deletion from your list of pending changes using the Undo Command.
You cannot delete an item for which another pending change exists. For example, a checked out file cannot be
deleted. To delete such items, you must undo the current pending change using the undo command.
When you check in a pending deletion, Team Foundation marks the file as deleted in the Team Foundation version
control server. Subsequently running a get of the item from other workspaces (either by you or other users)
deletes the item from those workspaces.
When your itemspec specifies a folder, Team Foundation deletes all its files and subfolders and the files they
contain, by default.
For more information on how to find the tf command-line utility, see Tf Command-Line Utility Commands.
Examples
The following example deletes 314.cs on disk in the specified local workspace folder and then, when you check in
the change, removes 314.c from the version control system non-permanently.
c:\projects>tf delete 314.cs
See Also
Tasks
Move, Rename, and Delete Version-Controlled Files and Folders
Reference
Undelete Command
Undo Command
Dir Command
Other Resources
Tf Command-Line Utility Commands
Properties Command
Displays information about items under version control.
To use the properties command, you must have the Read permission set to Allow for all specified files and
folders. For more information, see Permissions and groups reference.
tf properties [/collection:TeamProjectCollectionUrl] [/recursive] [/login:username,[password]]

itemspec [/version:versionspec] [/workspace]
Parameters
TeamProjectCollectionUrl The URL of the project collection that contains the items
for which you want to display properties (for example,
http://myserver:8080/tfs/DefaultCollection).
Itemspec Identifies the files and folders that are specified for
property retrieval.
For more information about how Visual Studio Team
Foundation Server parses itemspecs to determine which
items are within scope, see Command-Line Options.
Note: You can specify more than one Itemspec argument.
Versionspec Provides a value such as C3 for the /version option. For

more information about how Team Foundation Server
parses a version specification to determine which items
are within its scope, see Command-Line Syntax (Version
Control).

username value as either DomainUserName or
UserName.
OPTION DESCRIPTION
/recursive Displays all files and subfolders of a folder.
/version Specifies the version of the file to open for viewing the
properties on.
OPTION DESCRIPTION
/workspace Indicates the workspace to be used when displaying the "local"

properties (such as location on disk).
/collection Specifies the project collection.

user with Team Foundation Server.
Remarks
The properties command displays several pieces of information about a version-controlled item. Local and server
information is listed separately.
PROPERTY NAME DESCRIPTION
Local path Indicates the local path of the workspace folder for the
specified item.
Changeset Indicates the version number of the file or folder that was
last retrieved to the current workspace using the Get
Command.
Change Indicates where a change is pending.
Type Indicates the item type, for example file.
Server path Indicates the full path of the item on the version control
server.
Changeset Indicates the version number of the item.
Deletion ID If the item is deleted, the deletion identification; otherwise

0.
Lock Indicates the type of lock.

Checkin Check in is not permitted for the file.
Checkout Check out in not permitted for the file.
None A lock is not set. For more information, see
Lock Command.
Lock Owner Indicates the person who set a check-in lock.

Last modified Indicates the date and time stamp for when the item was
last modified.
Type Indicates the item type, for example file.
File Type Displays the file type encoding. For example, Windows-
1252.
Size Indicates the size of the file in bytes.
For links to other Team Foundation commands that describe the items on the server and the workspaces that map
to the server, see Informational Commands.
Examples
The following example displays properties information about the file 314.cs.
c:\projects>tf properties 314.cs
The following example displays the properties of the working folder c:\projects\objects.
c:\projects>tf properties objects
See Also
Tasks
View Version Control File and Folder Properties
Reference
Command-Line Syntax (Version Control)
Permission Command
Status Command
History Command
Changeset Command
Shelvesets Command
Concepts
Informational Commands
Other Resources
Rename Command (Team Foundation Version
Control)
The rename command changes the name or the path of a file or folder. You can use the rename command or the
aliases move or ren, to move a file or folder to a new location.
Note: The results of this command are not reflected in the Team Foundation version control server until you
perform a check-in operation. For more information, see Check In Pending Changes.
To use the rename command, you have the Check out permission set to Allow. For more information, see
tf rename [/lock:(none|checkout|checkin)] [/login:username,[password]] olditem newitem
Parameters
Argument
Description
olditem
The original name and path of the file or folder that is to be renamed. You can specify a local workspace path such
as C:\myfiles\314.cs or a Team Foundation version control server path such as $/myfiles/314.cs.
newitem
The new name of the file or folder. You can use this to specify a different local or a Team Foundation version
control server path location.
username
Provides a value to the /login option. You can specify a username value as either DOMAIN\UserName or
UserName.
OPTION DESCRIPTION
/lock Include this option to prevent other users from checking
in or checking out the specified items. If this option is not
specified, the existing lock status of the item is not
changed. For more information, see Understanding Lock
Types.
Lock Options:
None No lock is applied.
Checkin Other users can check out the specified
items but they cannot check in revisions to locked
files until you release the lock by performing a
check-in. If any other users have locked any one of
the specified items, the lock operation fails.
Checkout Prevents other users from checking in
or checking out any one of the specified items
until you release the lock by performing a check-
in. If any other users have locked any one of the

Remarks
You can use the rename command of the tf command-line utility to move or rename a version-controlled item in
your workspace. Use the rename command to move multiple files by specifying wildcard characters. The ability to
rename multiple version-controlled files or folders, is only available from the command-line.
Use Rename to do the following:
Rename the olditem to the newitem, such as tf rename 314.cs 315.cs .
Move the olditem to a new location in the Team Foundation version control server by providing a newitem
whose path differs from that of the olditem, such as ** ** tf rename 314.cs ..\\newdir\\314.cs .
If you provide a newitem that specifies a non-existent folder, the rename command creates the destination folder.
If newitem is a folder, olditem becomes a child of newitem.
You cannot rename an item if:
You have already deleted it before it was checked in to the same workspace.
The new name already exists in the Team Foundation version control server and is not a folder.
You have already added, branched, or renamed the pending check-in of the item.
The item is mapped in the workspace but not available on the local disk.
The item is cloaked.
You can rename an item for which another file of the same name has been added pending check-in but you cannot
rename an item that has been branched but not yet checked in. When you rename a file that has pending edits, the
edits are preserved.
An item that is explicitly mapped cannot be renamed without first changing the mapping. For example, if there is a
working folder mapping of $/ProjectX/MyApp to c:\MyApp, you cannot rename MyApp. You can rename items
under MyApp but not MyApp itself.
Examples
The following example changes the name of 314.c to 1254.c.
c:\projects>tf rename 314.c 1254.c
The following example renames 314.c to 1254.c and moves it to the newdir folder.
c:\projects>tf rename 314.c ..\newdir\1254.c
The following example changes the name of Form1.vb to MainPage.vb and applies a lock to it.
c:\projects>tf rename Form1.vb MainPage.vb /lock:checkin
See Also
Tasks
Move, Rename, and Delete Version-Controlled Files and Folders
Reference
Add Command
Get Command
Concepts
Understanding Lock Types
Pending Changes
Other Resources
Shelve Command
Stores a set of pending changes, together with pending check-in notes, a comment, and a list of associated work
items on the server that is running Visual Studio Team Foundation Server without actually checking them into
the version control server.
If you want to use the shelve command to delete a shelveset, you must be a shelveset owner, or your
Administer shelved changes permission must be set to Allow. For more information, see Permissions and
groups reference.
tf shelve [/replace] [/comment:("comment"|@commentfile)] [shelvesetname] [/validate][/noprompt]

tf shelve [/move] [/replace] [/comment:("comment"|@commentfile)]

[/recursive] [shelvesetname] itemspec [/validate] [/noprompt] [/login:username,[password]]
tf shelve /delete shelvesetname[;owner] [/login:username,[password]] [/collection:TeamProjectCollectionUrl]
Parameters
commentfile Specifies a file system path of a file from which comments for
the shelveset should be read.
comment Specifies the comment for the shelveset.
itemspec Identifies the files or folders to shelve. By default, all pending

changes in the current workspace are shelved if this
parameter is not specified. For more information about how
Team Foundation parses itemspecs to determine which items
are within scope, see Command-Line Options.
shelvesetname Specifies a name by which the shelveset can be retrieved

from the Team Foundation server. You can specify an existing
combination of shelvesetname *and *owner *but only if
**/replace* is also specified.
You must provide a value for this parameter.
owner Identifies the current or intended owner of the shelveset by

user name. By default, the current user is assigned ownership
of the shelveset if one is not specified.

username value as either DOMAIN*UserName* or
UserName.
TeamProjectCollectionUrl The URL of the project collection that contains the files or
folders that you want to shelve (for example,
http://myserver:8080/tfs/DefaultCollection/).
OPTION DESCRIPTION
/move Removes pending changes from the workspace after the

shelve operation is successful.
/replace Replaces the existing shelveset with the same name and
owner as the one that you specify.
/delete Deletes the specified shelveset. Only the /server option may
be combined with this option. If you do not include the
/noprompt option, a confirmation message appears when
the /delete option is specified.
/comment Adds a specified comment describing the shelved changes.
/recursive Shelves all items in the specified shelveset folder, its

subfolders and all items therein if the itemspec you provide is
a folder.
/noprompt Suppresses any prompts for input from you.
/validate Only valid when not combined with /noprompt.
This option selects the validation check box in the **Shelve -

Source Files **dialog box when it opens. When the validation
check box is selected, the dialog box will evaluate the check-
in policies and verify that require check-in notes have been
filled in. This option is useful when the changes are being
handed off for review and check-in by someone else.

Remarks
The shelve command of the tf command-line utility backs up pending changes, a list of associated work items,
in-progress check-in notes, and comments in a shelveset on the Team Foundation Server. A *shelveset *is much
like a changeset that is not committed to the server. Like a changeset, a shelveset can be retrieved from the
server into a local workspace by any user who has sufficient permissions.
Shelving is an alternative to checking in pending changes that have not been tested sufficiently. Use shelving
when you want to interrupt you work:
Share a set of local working files together with another developer or tester without checking in your
changes to the version control server.
Set aside a group of pending changes temporarily without checking them in so that you can instead work
on a higher priority issue. After you complete work on the high priority task, you can restore your shelved
changes using the Unshelve Command.
If you include the /move option, the shelve command rolls back all shelved file revisions to their base
workspace versions that is the last version retrieved from the server to the current workspace. Specifically, the
/move option makes sure that for all the items that you shelve:
Uses Undo to undo the changes that were shelved. The files that were pending additions are deleted
from the workspace.
The base workspace versions of all files for which pending editions exist are retrieved from the server into
the current workspace.
All items in the current workspace are marked read-only.
If you include the /delete option, Team Foundation permanently removes the specified shelveset from the Team
Foundation server.
Examples
The following example creates a new shelveset on the Team Foundation Server called Reflector_BuddyTest,
assigns ownership to the user Hans, then returns all items in the current workspace to the latest version
downloaded during the last get operation, and a sets a read-only state.
c:\projects> tf shelve Reflector_BuddyTest;Hans /move
The following example deletes the existing shelveset, "new -feature" from the server, creates a new shelveset by
that name, and retains all pending changes in the current workspace.
c:\projects> tf shelve new-feature /replace
The following example creates a shelveset named HelloWorld_TestMe that includes all pending changes to all .cs
files in the C:\projects working folder and its subfolders.
c:\projects> tf shelve HelloWorld_TestMe c:\projects\*.cs /recursive
The following example deletes the HelloWorld_24 shelveset.
c:\projects> tf shelve HelloWorld_24 /delete
See Also
Tasks
Shelve and Unshelve Pending Changes
Reference
Checkin Command
Changeset Command
Unshelve Command
Concepts
Working with Shelvesets
Pending Changes
Other Resources
Unshelve Command
Restores shelved file revisions, check-in notes, comments, and work item associations to the current workspace or
removes an existing shelveset from the server.
To use the unshelve command, you must have the Read permission set to Allow, and you must have the Check
out permission for the items in the shelveset set to Allow. Additionally, to delete a shelveset, you must be its
owner or have the Administer shelved changes global permission set to Allow. For more information, see
tf unshelve [/move] [shelvesetname[;username]] itemspec

[/recursive] [/noprompt][/login:username,[password]]
Parameters
Argument
Description
shelvesetname
The name of the shelveset to restore.
ownername
The name of the shelveset owner.
Itemspec
Identifies the file or folder revisions to unshelve into the current workspace. If this parameter is not included, all
pending changes in the specified shelveset are unshelved, by default. Server paths are not allowed.
For more information about how Team Foundation parses itemspecs to determine which items are within scope,
see Command-Line Options.
>Note:
>You can specify more than one Itemspec argument.
username
UserName</i.
OPTION DESCRIPTION
/move Deletes the specified shelveset from the server for Team
Foundation version control upon successful completion of
the unshelve operation. This option cannot be combined
with an itemspec.
You can also delete a shelveset using the shelve
command.
/recursive If specified, the itemspec is matched recursively.
/noprompt If specified, you are not prompted for input.

Remarks
The unshelve command of the tf command-line utility retrieves either all shelved file revisions or a defined
subset of all shelved file revisions from the Team Foundation server into the current workspace.
To unshelve an item, there must be no pending revisions against it in the destination workspace.
When you unshelve a shelveset, Team Foundation restores each shelved revision into the destination workspace
as a pending change as long as the revision does not conflict with a change that was already pending in the
workspace. For more details about what happens during the unshelve process, see Working with Shelvesets.
You can use the unshelve command to restore individual file revisions from a shelveset to your workspace. You
should run get after unshelving to reconcile any changes checked into the server since the shelveset was created.
Recycle Shelved Changes
If you want to integrate shelved revisions into your current workspace in order to make ongoing revisions,
unshelve the desired shelveset. As a best practice, get the latest version of your version-controlled files after
unshelving as well.
Unshelve and Review Another User's Code
You can also unshelve a shelveset in order to review changes from another user's workspace. To unshelve for this
reason, you have two options.
If the shelved items and the items with which they are related have not been revised, or have only been
revised lightly since the shelveset was created, you can retrieve the base version of all related items from
the shelveset owner's workspace. To do this, use some variation of the following command:
tf get \* /version;Wworkspacename , where workspacename is the name of the workspace from which the
other user created the shelveset.
If a significant amount of time has passed or if multiple revisions have been in the workspace since the
shelveset was created, retrieve the version of all related items from the server as of the date and time when
the shelveset was created.
You can unshelve another user's shelved change by appending the username to the shelveset name. However,
you can only remove a shelveset from the Team Foundation Server that was created by another user if you have
the AdminShelvedChangesets permission.
If you attempt to unshelve an item for which a pending change exists in the destination workspace, Team
Foundation does not merge differences between the items and does not retrieve the revision into your workspace.
You can delete a shelveset by using tf shelve /delete . For more information, see Shelve Command. In order to
automatically delete a shelveset after unshelving the entire shelveset, use tf unshelve /move .
Examples
The following example opens the Unshelve dialog box so that you can find and unshelve a shelveset into the
current workspace. You also have an option in the dialog box to have the shelveset deleted when the unshelve
operation completes.
c:\>tf unshelve
The following example unshelves the shelveset buddytest_1256 into the current workspace and removes it from
Team Foundation Server.
c:\>tf unshelve /move buddytest_1256
See Also
Tasks
Shelve and Unshelve Pending Changes
Reference
Shelve Command
Changeset Command
Concepts
Other Resources
Branch Command
The branch command copies an item or set of items, including metadata and version control history, from one
location to another in the Team Foundation version control server and in the local workspace.
NOTE
The results of this command are not reflected in the Team Foundation version control server until you perform a check-in
operation. For more information, see Check In Pending Changes.
To use the branch command, you must have the Read permission for the source item and the Check out and
Merge permissions for the target folder set to Allow. For more information, see Permissions and groups
reference.
tf branch olditem newitem [/version:versionspec] [/noget] [/lock:(none|checkin|checkout)] [/noprompt]

[/silent] [/checkin] [/comment:("comment"|@commentfile)] [/author:authorname] [/login:username, [password]]
[/recursive]
Parameters
olditem Specifies the name of the source file or folder being branched.
The olditem may also contain version information in the
format item;version.
newitem Specifies the name of the destination file or folder or the

parent folder for the destination. If newitem already exists
and is a Team Foundation version control server folder, Team
Foundation creates the branched items within it. Otherwise,
newitem specifies the name of the destination file or folder.
Conflicts can occur during check-in if the destination already
exists.
versionspec Provides a value for the /version option. For more

information about how Team Foundation parses a version
specification to determine which items are within its scope,
see Command-Line Syntax (Version Control).
comment Provides a comment about the branch.
@commentfile Specifies the path of a file that contains the comment that is
used for the branch.
authorname The user-provided value for the /author option.


UserName.
OPTION DESCRIPTION
/version The version of the item at which you want to create the
branch. You can specify a version by:
Date/time (D10/20/2005)
Changeset number (C1256)
Label (Lmylabel)
Latest version (T)
Workspace (Wworkspacename)
If no version is provided, Team Foundation uses the
following logic to decide which version of the item to
copy to the new branch:
If a Team Foundation version control server path
is specified, then Team Foundation branches the
item at the latest Team Foundation version
control server version. For example, tf branch
$/projects/help.cs uses the server version.
If a local path is specified for the source, Team
Foundation uses the local, workspace version to
create the new branch. For example, tf branch
C:\314.cs uses the local workspace version.
If you branch a file whose workspace version is older
than the latest version in the Team Foundation version
control server, the file is branched at the older version.
/lock Prevents other users from checking in or checking out
items until you check in your pending branch and
associated changes. For more information, see
Understanding Lock Types.
Lock Options:
None
Default. No lock is applied. If a lock exists on the
file that you are creating a branch for, this option
removes it.
Checkin
Checkout
release the lock by performing a check-in. If any
/noget If this option is specified, local copies of the files and

folders in the new branch are not created in the local
workspace. However, local copies will be retrieved into
the workspace the next time that you perform a recursive
Get operation.
Note:
You can prevent items, such as the contents of an /images
folder, from being retrieved to your workspace during
recursive Get and Get Latest operations by cloaking a
workspace folder. For more information, see Workfold
Command.
/silent Implies /noget and specifies that output is not written to

the Command Prompt window when you create a
branch.
/checkin Creates and checks in the branch to the server in one

operation. This option does not create any pending
changes in the local workspace.
/comment Adds a comment to the new branch. This option is used

only with the /checkin option.
/author Identifies the author of the new branch. This option is
used only with the /checkin option.
/recursive For folders branch all files inside, too
Remarks
If you specify a local path such as c:\00101 but do not specify a versionspec, Team Foundation uses the local
workspace version as the basis for creating the new branch.
However, if you specify a server path such as $/00101/*.cs and do not specify a versionspec, Team Foundation
uses the latest Team Foundation version control server version as the basis for creating the new branch instead.
Examples
The following example creates a branch file that contains the latest workspace version of 314.cs, names it
"314_branch", and saves it to the current directory on disk and also to the Team Foundation version control
server folder to which it maps.
c:\projects>tf branch 314.cs 314_branch
The following example copies all the files without pending edits in the workspace version of 314.cs from its
current Team Foundation version control server folder into the testdata Team Foundation version control server
folder and from the current directory on disk to the working folder that maps to the testdata Team Foundation
version control server folder.
c:\projects>tf branch C:\314.cs $/testdata
The following example copies all the files without pending edits in the current workspace version of the testfiles
folder and the files it contains for all items from its current Team Foundation version control server folder into
the testfiles_branch Team Foundation version control server folder and from c:\testfiles into the local folder that
maps to the testfiles_branch Team Foundation version control server folder.
c:\projects>tf branch C:\testfiles $/testfiles_branch
The following example creates a branch of 314.cs as it existed in changeset #4 for the file. In the working folder
on disk, as in the Team Foundation version control server, a branch file titled csharp_branch is created.
c:\projects>tf branch C:\314.cs;C4 csharp_branch
The following example creates a new branch of 314.cs as it was on 12/12/03. In the working folder on disk as in
the Team Foundation version control server, a branch file titled 314_branch is created.
c:\projects>tf branch 314.cs;D12/12/03 314_branch

The following example branches the version of 314.cs to which the "Beta1" label was applied, names it
"Beta1branch," and saves it to the current directory on disk in addition to the Team Foundation version control
server folder to which the current directory maps.
c:\projects>tf branch 314.cs;LBeta1 314_Beta1branch
See Also
Tasks
Branch Folders and Files
Reference
Branches Command
Merge Command
Concepts
Working with Changesets
Other Resources
Branches Command
Displays the history of a branch for a specified file or folder.
To use the branches command, your Read permission must be set to Allow for the item and any branches to
view their history. For more information, see Permissions and groups reference.
tf branches itemspec [/version:versionspec] [/collection:TeamProjectCollectionUrl] [/login:username,

[password]]
Parameters
Argument
Description
Itemspec
Identifies the file or folder that contains the branch you want to examine. For more information about how Team
Foundation parses itemspecs to determine which items are within scope, see Command-Line Options.
Versionspec
Provides a value for the /version option. For more information about how Team Foundation parses a version
specification to determine which items are within its scope, see Command-Line Syntax (Version Control).
TeamProjectCollectionUrl
The URL of the project collection that contains a file or folder in a branch for which you want to display the history
(for example, http://myserver:8080/tfs/DefaultCollection).
username
Provides a value to the /login option. You can specify a username value as either Domain\UserName or
UserName.
OPTION DESCRIPTION
/version Specifies the version for the path. This option is rarely
used.

## Remarks The branches command tells you when an item has been the source or destination of a branch operation.
The output displays the parent branch for each version.
Examples
The following example displays branch history for the version-controlled file C:\314.cs.
c:\projects>tf branches 314.cs
The following example displays branch history for the header.h item in the Team Foundation version control
server.
c:\projects>tf branches $/applications/header.h
The following example displays the branch history of the folder $/rel30/math.
c:\projects>tf branches $/rel30/math/
The following example displays the branch history for WindowsApplication13-branch. The results indicate the
history for the specified branch by using angle brackets.
D:\projects\ws1>tf branches WindowsApplication13-branch

$/jun16-1/WindowsApplication13
>> $/jun16-1/WindowsApplication13-branch Branched from version 3 <<
$/jun16-1/WindowsApplication13-branch-prime Branched from version 5
$/jun16-1/WindowsApplication13-branch2 Branched from version 3
See Also
Reference
Branch Command
Merges Command
Concepts
Other Resources
Branching and Merging
Changeset Command
Displays information about and lets you change the attributes, such as comments and check-in notes, that are
associated with a changeset.
To use the changeset command you must have the Read permission set to Allow for any files or folders in the
changeset for which you wish to display full information. The only users who can modify the notes and
comments that are associated with a changeset are the users who created the changeset or a user who has the
Revise other user's changes global permission. For more information, see Permissions and groups reference.
tf changeset [/comment:("comment"|@commentfile)]
[/notes:("NoteFieldName"="NoteFieldValue"|@notefile)] [/noprompt][/collection:TeamProjectCollectionUrl]]
[changesetnumber | /latest][/login:username,[password]]
Parameters
comment Provides a comment about the check-in.
@commentfile Specifies a path of a file on disk that contains the comment

used for the check-in.
NoteFieldName=NoteFieldValue Sets the value of the check-in note field. You can provide
multiple, semicolon-separated "field=value" expressions.
@notefile Provides the path of a file on disk that contains check-in note
field names and values in the format of "field=value" with one
per line.
TeamProjectCollectionUrl The URL of the project collection that contains a changeset

about which you want to display information or whose
attributes you want to modify (for example,
username Provides a value to the /user option. You can specify this
argument as either Domain*UserName* or UserName.
changesetnumber Identifies the changeset to be reviewed or modified. Cannot

be used with /latest.
OPTION DESCRIPTION
/comment Replaces the changeset comment that was created during

the check-in process, with a new comment.
OPTION DESCRIPTION
/notes Provides one or more check-in notes to associate with the

changeset.
/latest Specifies the most recent changeset. Cannot be used with

changesetnumber.
/login Specifies the user name and the password to authenticate

the user with Visual Studio Team Foundation Server.
Remarks
A changeset is a set of file and folder revisions that were committed to the Team Foundation version control
server as part of the same check-in event. For more information, see Working with Changesets.
You can use the changeset command to view the attributes of a changeset and modify its properties. You can
use the History command to determine which changeset you want to obtain information about. For more
information, see History Command.
For links to other Team Foundation commands that provide additional information about the items in your Team
Foundation version control server and all the workspaces that map to it, see Informational Commands.
Examples
The following example Displays detailed information about changeset 8675309 in an editable format in the
**Changeset **dialog box and replaces the existing comment with "This is a new comment."
After you press ENTER, the Details for Changeset <changeset number> - Source Files dialog box appears.
Click Save to associate the comment with the changeset.
c:\projects>tf changeset /comment:"This is a new comment." 8675309
The following example provides two check-in notes to associate with the changeset.
c:\projects>tf changeset /notes:reviewer=Jo;Security = checked 8675309
The following example provides two check-in notes that include spaces in the values and names to associate with
the changeset.
c:\projects>tf changeset /notes:"Code Reviewer"="John Smith";"Security Reviewer"="Chen Yang" 8675309
The following example associates the check-in notes included in the file notes.txt with the changeset 8675309.
c:\projects>tf changeset /notes:@notes.txt 8675309
Where the notes.txt can be in following format:

field1=value1;
field2=value that
spans multiple
lines;
field3 = value3;
The following example replaces the existing comment for changeset 8675309 and displays information about the
changeset in the Command Prompt window. The example does not start the **Changeset **dialog box.
c:\projects>tf changeset /comment:"This is an automatically generated comment." /noprompt 8675309
The following example displays non-editable information about changeset 8675309 in the Command Prompt
window.
c:\projects>tf changeset 8675309 /noprompt
Sample output:
Changeset: 8675309
User: DOMAIN\JohnG
Date: 01/21/2004 21:03:45
Comment: This check-in fixes issues in several features. I also refactored some items in buf.c into a new
file named bif.c because buf.c was too hard to parse.
Items:
$/baz/proj/bif.c Added
$/baz/proj/buf.c Modified, Renamed
Work Items:
34527 The "Access Denied" message is not descriptive enough.
35628 The UI flickers when I press the '8', 'y', 'Ctrl', and 'End' buttons at the same time.
Check-in Notes:
Code Reviewer: ShellM
Performance Reviewer: ShellM
Security Reviewer: ShellM
See Also
Reference
Checkin Command
Checkout and Edit Commands
Shelve Command
History Command
Configure Command
Concepts
Working with Changesets
Other Resources
Configure Command
Enables an administrator to view and change the following configuration settings for a project in the Source
Control Settings dialog box:
Check-out settings
Check-in policies
Check-in notes
To use the configure command, you must have the Edit server-level information permission set to Allow. For
more information, see Permissions and groups reference.
tf configure [PathOfTeamProject] [/collection:TeamProjectCollectionUrl][/login:username,[password]]
Parameters
PathOfTeamProject Path of the project whose configuration settings an

administrator can view, change, or both.
TeamProjectCollectionUrl The URL of the project collection that contains the project
that you specified (for example,

username value as either DOMAIN\UserName or UserName.
OPTION DESCRIPTION

Remarks
You can manage the following project settings using the configure command:
Check-out settings can be used to determine whether multiple users can edit files at the same time. Also,
they can be used to configure the get latest on check-out behavior.
Check-in policies provide controls that are invoked at check-in time, to make sure that defined criteria are
met before a user checks in pending changes.
Check-in notes define custom fields into which users provide information during the check-in process.
Check-in notes can be either required or optional.
The settings are configured in the Source Control Settings dialog box which appears after you run the
configure command. When you complete your changes, click OK to save them to the server.
For more information about these settings, see Walkthrough: Customizing Checkin Policies and Notes.
Examples
The following example displays the Source Control Settings dialog box in which you can examine and modify
the project settings of the workspace for the c:\projects folder.
c:\projects>tf configure
The following example displays the myproj project settings in the project collection at
c:\projects>tf configure $/myproj / http://myserver:8080/tfs/DefaultCollection
See Also
Tasks
Configure Check-Out Settings
Concepts
Managing File Types
Other Resources
Destroy Command (Team Foundation Version
Control)
Use the tf destroy command to destroy, or permanently delete, version-controlled files from Team Foundation
version control.
The destroy action cannot be reversed. You must not destroy files that are still needed. Sometimes you have to
clean up version control systems. For example, if some files are infected with a computer virus, you have to
remove them permanently from version control.
Before you run tf destroy without the /keephistory option, we recommend that you first delete the files you
want to destroy. For more information, see Delete Files and Folders from Version Control.
After you delete the files you can synchronize the Team Foundation warehouse. Otherwise, the warehouse will not
be synchronized with the destroyed items.
To use the destroy command, you must belong to the Team Foundation Administrators security group. For
tf destroy [/keephistory] <itemspec1>[;<versionspec>][<itemspec2>...<itemspecN>]

[/stopat:<versionspec>] [/preview] [/startcleanup] [/noprompt] [/silent] [/login:username,[password]]
[/collection:TeamProjectCollectionUrl]]
Parameters
itemspec1 [itemspec2...itemspecN] Specifies the server path of the file or folder to be

destroyed. Use multiple itemspec values to delete
multiple items. For example,
tf destroy $/TeamProject1 $/teamProject2
$/TeamProject3
.
Local paths are not supported.
versionspec Provides a version such as C58 for the /keephistory or

/stopat options. The allowed values are date, tip, or a
specific changeset. For more information about how Team
Foundation parses a version specification to determine
which items are within its scope, see Command-Line
Syntax (Version Control).

UserName.
TeamProjectCollectionUrl The URL of the project collection that contains files that
you want to destroy (for example,
OPTION DESCRIPTION
/keephistory Optional. Specifies that the history of a file is preserved

even as its contents are destroyed. This cannot be
specified with the /preview option.
/stopat Optional. Can be used only if /keephistory is specified

also.
Specifies the file version for the file, and the files that
follow thereafter, for which the history is preserved.
The default version for /stopat is tip (T) for the latest
checked-in version of an item.
You cannot use label or workspace versionspec values to
specify an item for /stopat option.
/preview Displays in the Command Prompt window the files that

would be destroyed. When tf destroy runs in the preview
mode, the files are not actually destroyed.
Note: The text in the Command Prompt window displays the
word "Destroyed" with each file that would be destroyed.
However, the file is actually not destroyed when the
/preview option is used.
/startcleanup Forces the TFVC metadata clean-up process to start

immediately after the deletion finishes. If the user does
not specify /startcleanup, the destroyed metadata clean-
up process occurs when the database maintenance cleans
up all the files that are no longer referenced by Visual
Studio Team Foundation Server. By default, the clean-up
is scheduled to run every 5 days. Seven days after the
TFVC metadata are cleaned up the content will be deleted
by another clean-up process. By default, this content
clean-up process runs once each day.
/noprompt Specifies that the destruction of files is non-interactive. /i

is an alias for /noprompt.
/i
/silent Specifies that, when you destroy files or folders, the

output is not written to the command prompt window.

Remarks
When you use tf destroy to destroy version-control files, the application tier of Team Foundation Server receives
the destroy request and checks to see whether you are a member of the Team Foundation Administrators
security group. If you are not a member, the system displays an error-message dialog box that tells you that you
do not have sufficient permissions to perform the operation.
After the system verifies your permissions, it runs the destroy command. This command deletes all file references,
shelvesets, and pending changes. The actual destruction of files, which is a permanent deletion, happens the next
time that the content that is no longer referenced by Team Foundation Server is cleaned up. You can also specify
the /startcleanup option to clean up the files immediately after tf destroy runs.
If you run tf destroy without specifying /i and /preview, the system displays a console Yes or No prompt for
each filespec value. Otherwise, you can specify Yes to all. If you do not specify /keephistory, you are prompted
by an interactive text that warns of pending changes, if they exist. The interactive text points to /preview if you
want more information about the changes. If you specify /keephistory, you are also prompted by Yes, No, or All
text. If you select Yes or All, the destruction process starts, and the server paths to the destroyed items appear in
the Command Prompt window.
Destroyed: <serverItem1>
Destroyed: <serverItem2>
Destroyed: ...
If you specified the versionspec value as a tip, the server paths displayed in the Command Prompt window
include deletion IDs. For example, X123 might appear in the Command Prompt window.
If you use the /preview option, the files are not destroyed, but the command-line text displays the files that would
be destroyed. For example, if, at the command-line, you type tf destroy /preview
$/Test1/MyProject/MyProject/Program.cs, the command window displays this text:
Destroyed: $/Test1/MyProject/MyProject/Program.cs
However, the file is actually not destroyed because you used the /preview option.
For more information about how to find the tf command-line utility, see Tf Command-Line Utility Commands.
Effects of /keephistory on Other Version Control Operations
If you specify the /keephistory option to retain the history of destroyed files, the files are treated as destroyed by
the following Team Foundation version control operations:
**Change content **If you try to change the content of a destroyed file, for example edit or branch, the
system issues an error message that states the content has been destroyed.
**Branch, merge, or unshelve **If you try to branch, merge, or unshelve destroyed items, the system issues
an error message that states the content of the items has been destroyed.
Destroying Previously Deleted Items
If an item has already been deleted, a deletion ID is attached to it and results in a filename change.
Effects of TF DESTROY on TFVC repo Code Search
Code Search does not handle TF DESTROY notifications and so using TF DESTROY for TFVC repos will not
automatically delete files in the Search index. As a result, these files appear in the code search results. To avoid
these ghost files scenario, users are recommended to delete files before TF DESTROY operation.
Examples
Description
The following example permanently deletes the file a.cs.
Code
C:\pi\ws1>tf destroy $/proj/pi/a.cs
Description
The following example deletes a folder, aFolder, type at the command line:
Code
C:\tf delete $/MyTeamProject/aFolder
Description
To destroy the deleted item, aFolder, you must type at the command line:
Code
tf destroy $/MyTeamProject/sFolder;x123
Where x123 is the deletion ID.
See Also
Tasks
Destroy Version Controlled Files
Concepts
Operations Available Only From the Command-Line (Team Foundation Version Control)
Other Resources
Difference Command
Compares, and if it is possible, displays differences between two files, files in two folders, or a shelveset and a
local or a server file.
To use the difference command, you must have the Read permission for all specified items set to Allow. For
tf diff[erence] itemspec [/version:versionspec] [/type:filetype]

[/format:format [/ignorespace] [/ignoreeol] [/ignorecase] [/recursive]
[/options][/noprompt][/login:username,[password]]
tf diff[erence] itemspec itemspec2 [/type:filetype] [/format: format]

[/ignorespace] [/ignoreeol] [/ignorecase] [/recursive] [/options] [/noprompt][/login:username,[password]]
tf diff[erence] [/shelveset:shelvesetname[;shelvesetowner]]
shelveset_itemspec [/type:filetype]
[/format: format] [/ignorespace] [/ignoreeol] [/ignorecase]
[/recursive] [/options] [/noprompt][/login:username,[password]]
tf diff[erence] /configure
Parameters
itemspec Required. Specifies the item to be compared. If no

version or path is specified, the current workspace
version is assumed. Accepts both local and Team
Foundation version control server paths.
For more information about how Team Foundation
parses itemspecs to determine which items are within
scope, see Command-Line Syntax (Version Control).
The difference command does not support wildcard
characters.
This parameter cannot be combined with the /shelveset
option.
Itemspec2 Optional. The item to which the itemspec is to be
compared. If you do not provide a second itemspec, the
latest Team Foundation version control server version of
the item is used.
Filetype Provides a value for the /type option. You can specify
"binary" or "text," and a codepage number or the friendly
name for a codepage.
Format Used with the /format option to specify an output

format of one of the following types:
Visual
Brief
Context
RCS
SS
SS_SideBySide
SS_Unix
Unified
Unix
These outputs formats are explained in the Remarks
section of this topic.
Versionspec The user-provided value for the /version option. For

more information about how Team Foundation parses a
version specification to determine which items are within
its scope, see Command-Line Syntax (Version Control).
Shelvesetowner Identifies the owner of the shelveset by user name. If a

value for this parameter is not provided, the current user
is assumed.
Shelvesetname Specifies the name of a shelveset. You can create more

than one shelveset with the same name on the server
that is running Team Foundation Server as long as a
different user owns each shelveset.
Shelveset_itemspec Specifies the name of a folder or file in the shelveset to

compare to the base shelveset version.

UserName.
OPTION DESCRIPTION
/type Overrides any detected encodings and uses the specified

encoding to present the files to the differencing engine.
/version Specifies the version of the file or folder to compare. By

default, Team Foundation uses the workspace version if you
do not provide a versionspec.
Instead of using the /version flag, you can specify versions

by appending a semicolon and version specifier to the end of
each file name.
/format Specifies an output format specified by the format argument.
/ignorespace Does not highlight white-space differences between the

compared files.
/ignoreeol Ignores differences between the new line characters in two

files or file versions. /ignoreeol works differently from
/ignoreSpace. /ignorespace treats eight spaces identically
to one. However, if you use the /ignoreeol option and File A
has two new line characters between unchanged areas of
text, and File B has one, the result displays as a difference. If
both files have only one new line, but File A uses \r\n as a
new line and File B uses \n , /ignoreEOL option would
ignore that as a difference.
/ignorecase Does not highlight differences in letter casing between the

compared files.
/recursive Compares the differences between the current folder and all
its subfolders.
/options Specifies an option string for the tool to be invoked by diff.

For more information, see Associate a File Type with a
Difference Tool and Associate a File Type with a Merge Tool.
/shelveset Specifies a shelveset to compare to the Team Foundation

version control server version upon which the shelveset is
based.
This option cannot be combined with an itemspec argument.

To compare individual shelveset items, you can provide a
shelveset_itemspec.
/noprompt Suppresses any dialog boxes that would otherwise be

displayed during the completion of this operation.
/configure Invokes the Configure User Tools dialog box. This tool is
available from the Visual Studio user interface. For more
information, see Associate a File Type with a Difference Tool.

Remarks
Note:
You can type tf diff or tf difference at the command line to run this command.
You can use the difference command to compare and if it is possible, display differences between:
Two different files or two versions of the same file.
One or more of the items in a folder.
One, some, or all the items in a shelveset on the Team Foundation Server.
You can use the difference command to compare both versioned and non-versioned files.
Team Foundation categorizes all files by type. Text files can be merged and compared, side by side and line by
line, as long as both files have the same encoding. If you want to compare two files whose encodings are not the
same, you can temporarily mask, or override the encoding property for a file by using the /type option. Binary
files can be compared but cannot be merged. When you pass one or more binary files to the difference
command, Team Foundation indicates whether differences exist between it and the item to which it is being
compared. For more information about how Team Foundation differentiates between and treats files of disparate
types, see Managing File Types.
If you specify two file names, the two files are compared. Instead of using the /version flag, you can specify
versions by appending a semicolon and version specifier to the end of each file name.
If you pass only one itemspec to the difference command:
If do not provide a versionspec, your current workspace version of the item is compared to the base
workspace version, by default. For example, tf difference header.h compares the current version of
header.h to the version upon which header.h is based.
If you include a versionspec in your itemspec such as , tf difference header.h;LBeta1, Team Foundation
compares that version to your current workspace version on disk.
If you specify a range of versions such as /version:C1~C4, the versions of the file at the two end points of
the range are compared.
Output Format types
The format parameter, used with the /format option, specifies many different output formats. The available
output types are
Visual
Visual format type opens an external difference application. By default diffmerge.exe is launched.
Brief
Brief format prints whether the files being compared differ.
Context
Context format provides lines of context for the differences in the files. This format is derived from the
UNIX based diff -c output format.
RCS
RCS format is similar to /format:unix, except context lines are not supplied.
No special handing for a missing end of line marker at the end of the file is provided.
SS
SS is default difference output format for Visual SourceSafe. For more information, see "Diff (Command
Line)" at the Microsoft Web site (http://go.microsoft.com/fwlink/?LinkId=99139).
SS_SideBySide
SS_SideBySide is the default side-by-side output format for Visual SourceSafe.
SS_Unix
SS_Unix is similar to the /format:unix output format, but /format:ss_unix includes context lines and
/format:unix does not.
Unified
Unified format is derived from the UNIX based diff -u output format. /format:context repeats identical
context lines between the difference strings although /format:unified does not.
Unified format produces a new unified difference string (@@ ... @@) line only when the distance to the
next difference string is larger than the number of context lines.
Unix
This output type is derived from the UNIX based diff command output format.
The Unix output format is constructed in the following way:
<metadataline>
"< " line prefix for lines from the first file
"---" line
"> " line prefix for lines from the second file
<metadataline> can be one of these possibilities:

#a#,# -- add lines from line # in file1 into file2 at lines #->#
#,#d# -- delete lines from line # -> # in file 1 from file2 at line #
#,#c#,# -- change lines from line # -> # in file1 into the lines in file2 at line # -> #
# signs separated by commas indicate a line range.

# signs before the character indicate line numbers in the first file
# signs after the character indicate line numbers in the second file
/// No end of line marker at the end of the file:

/// \ No newline at end of file
Examples
The following example displays the differences between the local version of 314.cs and the workspace
version of 314.cs that is the version of the file that was checked out from the Team Foundation version
control server.
c:\projects>tf difference 314.cs
The following example displays all files that have been changed in the src folder. Does not display files that have
been changed in subfolders of src.
c:\projects>tf difference src /format:visual
The following example displays the differences between changeset 3 and changeset 8 of 1254.cs.
c:\projects>tf difference /version:C3~C8 1254.cs
The following examples display the differences between the version of 314.cs that belong to the label "release"
and the version that belongs to changeset 3200.
c:\projects>tf difference 314.cs;Lrelease 314.cs;C3200
-or-
c:\projects>tf difference 314.cs;Lrelease~C3200
The following example displays the difference between the versions of e271.cs that a user named Nadia shelved
in shelveset PeerCodeReview8 and the base shelveset version that is the version upon which she based her
changes. Also displays the types of changes pending against e271.cs when Nadia shelved.
c:\projects> tf difference /shelveset:PeerCodeReview8;Nadia e271.cs
The following example displays the differences between all files in the PeerCodeReview2 shelveset and the base
shelveset version of those files.
c:\projects> tf difference /shelveset:PeerCodeReview2
See Also
Reference
Merge Command
Checkin Command
Shelvesets Command
Concepts
Managing File Types
Other Resources
Comparing Folders and Files
Dir Command
The dir command displays all or some of the contents of the server for Team Foundation version control.
To use the dir command, you must have Read permission set to Allow. For more information, see Permissions
and groups reference.
tf dir itemspec [/version:versionspec] [/recursive]

[/folders] [/deleted] [/login:username,[password]] [/collection:TeamProjectCollectionUrl]
Parameters
Argument
Description
itemspec
Identifies the file or folder to return information about. For more information about how Team Foundation parses
itemspecs to determine which items are within scope, see Command-Line Options.
Note
You can specify more than one Itemspec argument.
versionspec
The user-provided value for the /version option. For more information about how Team Foundation parses a
version specification to determine which items are within its scope, see Command-Line Syntax (Version Control).
username
UserName.
The URL of the project collection that contains one or more files or folders about which you want to display
information (for example, http://myserver:8080/tfs/DefaultCollection/).
OPTION DESCRIPTION
/version Specifies that Team Foundation should only show files and
folders of a certain version.
/recursive Displays all files and subfolders in the specified directory.

/folders Displays folders only.
/deleted Displays deleted items and existing items. The deleted

items are followed with ;X3 where 3 is the deletion id.

## Remarks The dir command operates on the Team Foundation version control server copies of files, not the local
copies. The command uses the local mapped folder to locate the appropriate Team Foundation version control server
path. You use this command to explore the Team Foundation version control server and identify files you may have to
obtain.
For links to other Team Foundation commands that provide additional information about items in your Team
Foundation version control server and the workspaces that map to it, see Informational Commands.
Examples
The following example displays a list of files, folders, subfolders, and the files therein in the Team Foundation
version control server folder to which c:\projects maps. The number of items is also listed. For more information
about how to view and edit working folder mappings, see Workspace Command and Workfold Command.
c:\projects>tf dir /recursive
The following example displays all Team Foundation version control server files at that path. The "314dir"
subfolder does not have to exist in the local folder.
c:\projects>tf dir 314dir
The following example displays the version of files labeled "My label" in that Team Foundation version control
server path. The "314dir" subfolder does not have to exist in the local folder.
c:\projects>tf dir /version:L"My label" 314dir
The following example displays all folders in the root of the Team Foundation version control server. The local
working folder is ignored because $/ denotes a Team Foundation version control server path.
c:\projects>tf dir /folders $/
The following example lists every file and folder in the Team Foundation version control server.
c:\projects>tf dir /recursive $/

The following example lists all items and deleted items in the current folder together with their deletion IDs.
c:\projects>tf dir /deleted
See Also
Tasks
Add and Remove a Working Folder in a Workspace
Reference
Workspace Command
Workfold Command
Concepts
Other Resources
Folderdiff Command
Use the folderdiff command to display and compare a visual representation of the differences between files in
two server folders, in a server folder and a local folder, or in two local folders.
To use the folderdiff command, you must have the Read permission set to Allow. For more information, see
tf folderdiff [sourcePath] targetPath [/recursive] [/noprompt] [/collection:TeamProjectCollectionUrl]

[/filter:filter] [/filterLocalPathsOnly] [/login:username,[password]]
[/view:same,different,sourceOnly,targetOnly]
Parameters
Argument
Description
sourcePath
The local or server path that is the source path in the compare operation. If this argument is not supplied and
targetPath is the local mapped path, sourcePath is the server path that is mapped to it.
targetPath
The local or server path that is the target path in the compare operation.
filter
Specifies a semicolon delimited list of inclusion and exclusion filter masks for the /filter option. Default is "*"
(include all). The Remarks section in this topic includes a detailed description of filters and masks.
The URL of the project collection that contains the files for which you want to display and compare the differences
username
UserName.
OPTION DESCRIPTION
/recursive Optional. Specifies that the two folders are fully compared
recursively.
/noprompt Optional. tf folderdiff runs without displaying user
interface. The output is displayed in the Command
Prompt window instead.
/filter Optional. Specifies a list of inclusion and filter masks that

are used to match the names of files and folders to be
compared.
/filterLocalPathsOnly Optional. Specifies that only the local paths will be filtered,
unless the corresponding server path exists.
/view Optional. Specifies what information is included in the

output using a comma separated list of the following
values:
same-output displays files with the same content in both
source and target directories.
different-output displays files with different content in
both source and target directories.
sourceOnly-output displays files that exist only in source
directory.
targetOnly-output displays files that exist only in target
directory.
The default is "different,sourceOnly,targetOnly"

Remarks
The Command Prompt window displays the output if you specify /noprompt. Otherwise, the Folder Difference
window displays the output. When the system compares the local mapped folder to the server folder to which it is
mapped, the output in the Folder Difference window includes a list of pending changes. Also, the output in the
Folder Difference window tells you whether the local folder contains the latest copy or not.
The output displayed in the Command Prompt window lists all the files in the folders in the following five sections:
Items that exist only in the server folder.
Items that exist only in the local folder.
Items that have different contents.
Items that have identical contents (you must specify the same argument with the /view option).
Summary.
File and Folder Filters
A filter is an ordered list of name masks used to match the name of files and folders to be compared. Each mask
can contain the wildcard characters question mark (?) and asterisk (*). '?' matches exactly one character and '*'
matches zero or more characters. The masks in a filter are delimited by semicolons (;). Folder masks must end in
backslash (\). To specify an exclusion mask, prefix the mask with an exclamation mark (!).
The filter is applied to the file and folder names using the following rules:
When both file and folder masks are specified together in a filter, the file masks are separated into a file
mask list and the folder masks are separated into the folder mask list. File masks are applied only to file
names. Folder masks are applied only to folder names.
When the command matches a file or folder name, it compares the name to each mask in the filter in the
order it was specified. As soon as the name matches a mask, the name is considered to be a match.
If the file masks in the filter contain an inclusion mask, files that do not match any of the file masks are
excluded.
If the file masks in the filter contain only exclusion masks, files that do not match any of the file masks are
included.
If the folder masks in the filter contain an inclusion mask, folders that do not match any of the folder masks
are excluded.
If the folder masks in the filter contain only exclusion masks, folders that do not match any of the folder
masks are included.
The following table lists filter name mask examples.
NAME MASK DESCRIPTION
*.cs Matches all C# files.
My*.bmp Matches all bitmap files that begin with My.
!*.exe Excludes all executable files.
!objd\ Excludes all objd folders.
The following table lists filter examples.
FILTER DESCRIPTION
*.cs;!objd\;!obj\;!bin\ Matches all C# files except those in objd, obj, or bin folders.
!*.resx;!*.ini;!resources\;!*junk*\ Excludes all .resx and .ini files, all files in the resources folder,
and all files in any folder that has a name that includes the
word junk.
Examples
The following example compares the files in the server folder and a local folder. It organizes the files in the
localFolder recursively and displays the output in the Command Prompt window.
C:>tf folderdiff $/serverFolder F:\localFolder /recursive /noprompt

See Also
Tasks
Compare Two Folders
View File Changes Using Annotate
Reconcile Differences Between Two Folders
Concepts
Folder Comparison Filters
Other Resources
Help Command (Team Foundation Version Control)
Displays help on the command line that contains information about syntax for a Team Foundation version control
command.
tf help commandname
Parameters
Argument
Description
commandname
Specifies a Team Foundation command for which to display help about the syntax.
## Remarks If you do not know which command you need, type tf help for a list of all commands.
If you specify the commandname parameter, the command line displays information about the arguments and
options for that command. If the system cannot find a match for the commandname, it searches for aliases and
short names. If it cannot find any matching command, alias, or short name, you will get an error.
The option /? is an alias for help. If you use the /? option together with a command, the system invokes the help
command and it displays information about syntax.
Examples
The following example displays a list of the version control commands.
c:\projects>tf help
The following example displays information about syntax for the workspace command.
c:\projects>tf help workspace
The following example also displays the same information about syntax for the workspace command.
c:\projects>tf workspace /?
See Also
Reference
Msdn Command
Other Resources
Label Command (Team Foundation Version Control)
Updated: October 2011
Attaches a label to or removes a label from a version of a file or folder in the server for Team Foundation version
control.
To use the label command, you must have the Label permission set to Allow. To modify or delete labels created
by other users, you must have the Administer labels permission set to Allow. For more information, see
tf label labelname[@scope] [/owner:ownername]

itemspec [/version:versionspec] [/comment:("comment"|@commentfile)]
[/child:(replace|merge)] [/recursive] [/login:username,[password]] [/collection:TeamProjectCollectionUrl]
tf label /delete labelname[@scope]

itemspec [/login:username,[password]] [/collection:TeamProjectCollectionUrl]
Parameters
labelname Identifies the name of the label to attach, modify, or

remove from the specified items.
@scope Specifies a Team Foundation version control server

directory within which the labelname is unique. This
parameter lets you independently create, manage,
retrieve, and delete one label or set of labeled items when
two labels of the same name are in different parts of the
Team Foundation version control server.
ownername Provides a value such as DOMAIN\JuanGo or just juango

to the /owner option.
itemspec Identifies the file or folder from which to label, re-label, or

modify. For more information about how Team
Foundation parses itemspecs to determine which items
are within scope, see Command-Line Syntax (Version
Control).
Note
versionspec Provides a value such as c2 for the /version option. For
version specification to determine which items are within
its scope, see Command-Line Syntax (Version Control).
comment A user-provided comment about the label.
@commentfile The user-provided path of a file on disk that contains the

comment to use for the check-in.

username value as either DOMAIN\UserName or
UserName.
TeamProjectCollectionUrl The URL of the specified project collection that contains a

version of a file or folder to which you want to attach a
label or from which you want to delete a label (for
example, http://myserver:8080/tfs/DefaultCollection).
OPTION DESCRIPTION
/owner Specifies the name of the user who owns the label.
/version Optional. Specifies the version of the file or folder to which

the label should be attached, modified, or from which the
label should be removed. These are changeset values, for
example, C93. By default, Team Foundation uses the base
workspace version if no versionspec is provided.
/comment Adds or modifies a description or comment for the label.
/child Not documented.
/recursive Labels all items in the directory that matches your itemspec
and versionspec. Cannot be used with the /delete option.
/delete Removes the label.

Remarks
A label is a marker that you can attach to a set of unrelated files and folders in the Team Foundation version
control server. Use the label to simplify their retrieval to a workspace for either development or build purposes.
Therefore, a label is like a changeset or date/time to which and from which you can arbitrarily add and remove
files and folders or change the versions of the items therein. A label is a version specification that can be passed to
the following Team Foundation commands:
Branch Command
Difference Command
Dir Command
Get Command
History Command
Merge Command
View Command
Common types of labels are milestone labels such as "M1," "Beta2," or "Release Candidate 0."
Labels are version-specific, that is, you can only attach a label to one version of a file or folder. Each version of an
item can support multiple labels.
A label is not a versioned object; therefore, the label history of files is not tracked. Additionally, a label operation
does not create a pending change in your workspace. When you issue the label command, the update is
immediately reflected in the Team Foundation version control server.
Removing and Deleting Labels
You can use the Unlabel Command to remove a label from a file or folder. Alternatively, you can delete a label
from the system using the tf label /delete command.
For information about an existing label that includes a list of the items to which the label has been attached, its
comment, scope, and owner, see Labels Command.
Managing Overloaded Labels
Label names must be unique throughout a specified scope. When you add a label, you reserve the use of that
label name at or under the specified or implied scope. The default value for the @scope parameter is the project,
for example, $/TeamProject1.
If another team or user adds a common label such as "M3" to a set of version-controlled files in a different part of
the Team Foundation version control server, you can apply the M3 label to version-controlled files in your project
as long as the root project folders are in different directories. For example, if files in the $/math directory are
labeled "M3," you can apply the "M3" to files in your $/projects directory.
To get, remove a label, or otherwise manage your M3-labeled items, you should specify the @scope parameter to
tell Team Foundation which M3 label you want to work with.
You can prevent other users from "overloading" a label such as "M3" in different parts of the Team Foundation
version control server by either creating your label at the root ($/) of the Team Foundation version control server
or by adjusting Label permissions for certain folders.
Examples
The following example attaches the "goodbuild" label to the workspace version of the "docs" folder and the files
and folders it contains.
c:\projects>tf label goodbuild docs /recursive
The following example attaches the "goodbuild" label to the "docs" folder but not the files and folders the docs
folder contains.
c:\projects>tf label goodbuild docs
The following example attaches the "goodbuild" label to version 3 of 314.cs in the Team Foundation version
control server.
c:\projects>tf label goodbuild /version:3 $/src/314.cs
The following example deletes the "badbuild" label from all items in the Team Foundation version control server.
c:\projects>tf label /delete badbuild
The following example uses the scope option to apply a label to 314.cs.
c:\projects>tf label goodbuild@$/TeamProject1 314.cs
See Also
Reference
Labels Command
Unlabel Command
Concepts
Use Labels to Take a Snapshot of Your Files
Other Resources
Change History
DATE HISTORY REASON
October 2011 Removed incorrect guidance on Content bug fix.

/child option.
Labels Command
Displays the list of labels in the server for Team Foundation version control.
To use the labels command, you must have the Read permission set to Allow for all files or folders to which the
specified label is attached. If you have permission to some, but not all the files referenced in the label, partial
results are displayed. For more information, see Permissions and groups reference.
tf labels [/owner:ownername] [/format:(brief|detailed)]

[/collection:TeamProjectCollectionUrl] [labelname] [/login:username,[password]]
Parameters
ownername Provides a username as DOMAIN\JuanGo or juango to the

/owner option.
labelname Specifies a string that should be used to filter the list of labels.
If this parameter is omitted, the label name field will not be
filtered.
TeamProjectCollectionUrl The URL of the project collection for which you want to
display the list of labels (for example,

username value as either DOMAIN*UserName* or UserName.
OPTION DESCRIPTION
/owner Specifies the name of the user who owns the label. By default,
the owner is the person who applies the label.
/format Displays information about the specified label in one of the

following formats:
Brief: Includes label, owner, and date created. This is
the default.
Detailed: Includes also comments, scope, and a list of
files and folders associated with each label.

Remarks
The labels command displays information about labels in the Team Foundation version control server. If you do
not specify a Team Foundation version control server, the Team Explorer tries to determine the Team Foundation
version control server based by using the current directory. If the current directory is not mapped to a Team
Foundation version control server, you must specify one by using the /s option.
By default, the results display the label name, owner and creation date for each label. If the format is changed to
"detailed," comments and the list of files and folders associated with each label are also displayed.
Foundation version control server and all of the workspaces that map to it, see Informational Commands.
Examples
The following example displays the list of labels created by user "jasonj."
c:\projects> tf labels /owner:jasonj
The following example displays information about "build1033" label and lists the files and folders to which the
label has been applied in the Team Foundation version control server.
c:\projects> tf labels /format:detailed build1033
The following example displays all labels in the Team Foundation version control server that have a labelname
that begins with "build" and are owned by the account executing the labels command.
c:\projects> tf labels build*
See Also
Reference
Unlabel Command
Concepts
Other Resources
LocalVersions Command
Displays the version of one or more items in a workspace.
To use the localversions command, you must have the Use permission to the workspace. For more information,
tf localversions ItemSpec
[/recursive] [/format:brief|detailed]
[/workspace:WorkspaceName[;WorkspaceOwner]] [/collection:TeamProjectCollectionUrl]
Parameters
Itemspec Specify either a file or a folder that contains the files for
which you want to display version numbers.
You can specify only a local file or folder. For example,
c:\project1\binder.cs is valid, but $/project1/binder.cs is
not.
Note
WorkSpaceName Use this argument with the /workspace option to specify

a workspace other than the one that is mapped to the
current directory.
WorkSpaceOwner Use this argument with the WorkSpaceName argument if

you want to specify a public workspace.
TeamProjectCollectionUrl The URL of the project collection that contains one or

more items for which you want to display the version (for
OPTION DESCRIPTION
/format Specify one of the following options to control how the
data returned by this command appears:
Brief
(Default.) Each directory appears only once,
followed by the files that it contains.
Detailed
Each file appears after its full path.
/recursive Specify this option if you want the operation to include

items in subfolders.
/workspace Specify this option to display data about the versions of

items that are in a workspace other than the one that is
mapped to the current directory.
Remarks
When you get or check out a file, you usually download the most current version. However, you may have older
versions of some files in your workspace.
For example, you might have checked out some files and not checked in your work for several weeks. Other
people on your team may have checked in changes to the same files during that time. In this case, the versions of
these files in your workspace would be older than the current versions on your server for Team Foundation
version control. You can use the localversions command to get information about which versions of these files
are in your workspace.
For information about other Team Foundation commands that provide additional information about items in your
server for Team Foundation version control and the workspaces that map to it, see Informational Commands.
For more information about how to find and use the tf command-line utility, see Tf Command-Line Utility
Commands.
Examples
The following example displays the version of the ControllerBase.cs file in the workspace that is mapped to the
c:\\workspaces\\FeatureA\\catalog\\controller folder.
c:\workspaces\FeatureA\catalog\controller>tf localversions ControllerBase.cs
The following example displays the versions of all files (including those in subfolders) in the workspace that is
mapped to the c:\\workspaces\\FeatureA\\catalog\\ folder. Because the /format:detailed option is specified, each
file appears with its full path.
c:\workspaces\FeatureA\catalog\>tf localversions . /recursive /format:detailed

See Also
Concepts
Other Resources
Lock Command
Locks or unlocks a file or folder to deny or restore the right of users to check out an item for edit into a different
workspace or to check in pending changes to an item from a different workspace.
To use the lock command, you must have the Lock permission set to Allow. Having the Unlock other user's
changes permission set to Allow is required to remove a lock held by another user if you do not have Write
permission for that user's workspace. For more information, see Permissions and groups reference.
tf lock itemspec /lock:(none|checkout|checkin)

[/workspace:workspacename] [/recursive] [/login:username,[password]] [/collection:TeamProjectCollectionUrl]
Parameters
itemspec Identifies the file or folder to lock or unlock. For more

information about how Team Foundation parses
itemspecs to determine which items are within scope, see
Command-Line Options.
Note: You can specify more than one Itemspec
argument.
workspacename The user-provided value for the /workspace option.

UserName.
TeamProjectCollectionUrl The URL of the project collection that contains the file or
folder that you want to lock or unlock (for example,
OPTION DESCRIPTION
/lock Specifies a lock type or removes a lock from an item. For
more information, see Understanding Lock Types.
Lock Options:
None
Removes a lock from an item.
Checkin
Enables an item to be checked out and edited in
all workspaces but prevents users from checking
in changes to the item outside the specified
/workspace until you explicitly release the check-
in lock. If the specified item is locked in any other
workspace, the lock operation fails.
Checkout
Prevents users from checking in or checking out
the specified items until you explicitly release the
lock. If users have locked any one of the specified
items, or if pending changes exists against any
one of the items, the lock operation fails.
/workspace Specifies the name of a different workspace in which to

apply the lock. By default, the lock is applied in the
workspace in which you are currently.
/login Specifies the user name and password to authenticate

Remarks
You can use the lock command to temporarily freeze the Team Foundation version control server version of an
item so that you can check in a pending change without having to resolve any merge conflicts. If you want to
permanently prevent access to an item in the Team Foundation version control server, you should use the
Permission Command instead.
Note:
As a courtesy to your teammates, notify them when you apply a lock to an item, explain why you are doing
this, and estimate when you plan to remove the lock, if you can.
How to Lock an Item
You can lock an item using the lock command or by specifying a lock option during the commission of several
other commands of the tf command-line utility that includes:
Rename Command (Team Foundation Version Control)
Undelete Command
Merge Command
Branch Command
Add Command
For add and branch, the lock is placed on the namespace where the new item will be created. Locks placed with
rename apply both to the old and new namespaces. For more information, see Lock and Unlock Folders or Files.
Lock Types
Team Foundation provides two types of locks: checkin and checkout.
A check-in lock is less restrictive than a check-out lock. When you apply a check-in lock, users can continue to
make local changes to the item in other workspaces. The changes cannot be checked in until you explicitly
remove the check-in lock from the workspace.
A check-out lock is more restrictive than a check-in lock. When you apply a check-out lock to a version-
controlled file or folder, users can neither check out the file for edit nor check in pre-existing pending changes.
You cannot acquire a check-out lock if there are currently any pending changes to an item.
For more information about when to apply a check-out lock and when to apply a check-in lock, see
How Locking Works
If you have a file checked out when you lock it, its status is modified to contain the new lock type. If the files are
not checked out, a "lock" change is added to the set of pending workspace changes. Unlike the checkout
command, lock does not automatically make a file editable.
Locks on folders are implicitly recursive. If you lock a folder, you do not have to lock the files it contains unless
you want to apply the more restrictive check-out lock to a file in a folder that has a check-in lock.
Unlocking an Item
You can unlock a locked item using the none option. Additionally, Team Foundation unlocks an item
automatically when you check in pending changes in the workspace.
You can determine which files are locked in the Team Foundation version control server and by whom the files
were locked using the Status Command.
Examples
The following example prevents other users from checking out 314.cs.
c:\projects>tf lock /lock:checkout 314.cs
The following example prevents other users from checking in changes to 1256.cs but enables them to check it
out in their workspaces.
c:\projects>tf lock /lock:checkin 1256.cs
The following example prevents other users from pending changes to any items in the src/ folder in the Team
Foundation version control server.
c:\projects>tf lock /lock:checkout $/src
The following example unlocks and makes all files in the src/ Team Foundation version control server folder
available for check-out and check-in by other users.
c:\projects>tf lock /lock:none src/
See Also
Reference
Status Command
Concepts
Create a Workspace to Work with your Project
Other Resources
Working with Version Control Locks
Merge Command
The merge command applies changes from one branch into another.
NOTE
The results of this command are not reflected in the Team Foundation version control server until you perform a check-in
operation. For more information, see Check In Pending Changes.
To use the merge command, you must have the Check out permission set to Allow for the workspace folder
that contains the destination and you must have the Read permission set to Allow for the workspace folder that
contains the source. For more information, see Permissions and groups reference.
tf merge [/recursive] [/force] [/candidate] [/discard]

[/version:versionspec] [/lock:none|checkin|checkout] [/preview]
[/baseless] [/nosummary] [/noimplicitbaseless] [/conservative] [/format:(brief|detailed)] [/noprompt]
[/login:username,[password]] source destination
Parameters
versionspec Provides a value such as C2 for the /version option. For

version specification to determine which items are within its
scope, see Command-Line Syntax (Version Control).
source Specifies the file or folder to act as the source of the merge.
destination Specifies the file or folder to act as the destination of the

merge.

UserName.
OPTION DESCRIPTION
/recursive Matches the source item specification in the current

directory and any subfolders.
/force Ignores the merge history and merges the specified

changes from the source into the destination, even if
some or all these changes have been merged before.
/candidate Prints a list of all changesets in the source that have not
yet been merged into the destination. The list should
include the changeset ID that has not been merged and
other basic information about that changeset.
/discard Does not perform the merge operation, but updates the
merge history to track that the merge occurred. This
discards a changeset from being used for a particular
merge.
/version For a selective merge, this option specifies the range that
should be merged into the destination. For a catch-up
merge, this parameter specifies the version before which
all un-merged changes should be merged.
For a selective merge, the version range denotes the
beginning and end points of the set of changes to be
merged. For example, if you attempt to merge version
4~6, the changesets 4, 5, and 6 are merged.
/lock Specifies a lock type or removes a lock from an item. For

more information, see Understanding Lock Types.
Lock Options:
None
No lock is placed on an item and removes any
existing lock from an item.
Checkin
Checkout
Prevents users from checking in or checking out
any one of the specified items until you explicitly
release the lock. If any other users have locked
any one of the specified items, or if there are
existing pending changes against any item, the
lock operation fails.
/preview Shows a preview of the merge.

/baseless Performs a merge without a base version. That is, allows
the user to merge files and folders that do not have a
merge relationship. After a baseless merge, a merge
relationship exists, and future merges do not have to be
baseless.
Note
Baseless merges cannot delete files in the target. You can
manually carry over such changes.
/noimplicitbaseless Specifies that Team Foundation will not perform an

implicit baseless merge between two items that have the
same relative name in two unrelated version-control
trees.
/nosummary Omits summary of conflicts, errors and warnings.
/conservative Results in more conflicts when you merge one branch to

another.
/format Specifies the formats of summarizing merge conflicts:

Brief: default value, summarizes only the total
number of conflicts, warnings, and errors.
Detailed: summarizes not only the total number
of conflicts, warnings, and errors but also lists
details about each conflict.
Note: This option applies only when the output contains
a summary of conflicts. The summary cannot be shown if
the /nosummary option is used or the merge caused
fewer than 10 conflicts, warnings, and errors.
/login Specifies the user name and password to authenticate

Remarks
You can use the merge command of the tf command-line utility to apply changes in an existing source branch to
an existing target branch. You can merge an individual revision or a complete changeset to the target branch. You
can merge changes from the source to the target branch or from the destination to the source branch.
The merge command also lets you query for changes in a source branch which have not been migrated to the
target branch. Additionally, it lets you indicate that certain changes will never be merged from the source to the
destination and should no longer be displayed as candidates for a merge operation.
Baseless Merge
Use baseless merge to merge items that are not directly branched from each other. To perform a baseless merge,
you must use the tf merge command. When you perform a baseless merge, Team Foundation does not have
any information about the relationship of the files in the branches. In a baseless merge, you must perform
manual conflict resolutions. After you have performed the baseless merge and resolved any conflicts, Team
Foundation records the merge history and establishes a relationship between the folders and files.
When you run tf merge, Team Foundation performs an implicit baseless merge between items that have the
same relative name in two previously related version-controlled trees. For example, you might want to merge the
related branches $SRC\ and $TGT. Both branches contain an unrelated file that is named a.txt. When you run tf
merge, Team Foundation establishes a relationship between the two a.txt files if the two files are the same, if
FIPS -compliant encryption is disabled, and if the source file is not related to any other file in the target.
If you run tf merge with the /noimplicitbaseless option set, when Team Foundation tries to merge the two
branches, the two a.txt files will create a namespace conflict when you try to check in the changes. To resolve the
conflict, you must rename one of the files.
Examples
The following example merges changes from MyFile_beta1 that have not been merged into MyFile_RTM.
c:\projects>tf merge MyFile_beta1 MyFile_RTM /recursive
The following example merges changeset 137 into branch2.
c:\projects>tf merge /version:C137~C137 branch1 branch2 /recursive
The following example merges all the changesets up to changeset 137 into branch2.
c:\projects>tf merge /version:C137 branch1 branch2 /recursive
The following example prints a list of the changesets in branch1 that have not been merged into branch2.
c:\projects>tf merge /candidate branch1 branch2 /recursive
The following example prints a list of changesets in branch2 that have not been merged back into branch1.
c:\projects>tf merge /candidate branch2 branch1 /recursive
The following example discards changeset 137 as a candidate for merging into branch2.
c:\projects>tf merge /discard /version:C137 branch1 branch2 /recursive
See Also
Tasks
Resolve Conflicts between Two Files
Reference
Branch Command
Merges Command
Other Resources
Merges Command
Displays detailed information about past merges between the specified source and destination branches.
To use the merges command, you must have the Read permission set to Allow for both source and destination
branches. For more information, see Permissions and groups reference.
tf merges [source] destination [/recursive] [/extended] [/format:(brief|detailed)] [/login:username,

[password]] [/showall]]] [/collection:TeamProjectCollectionUrl]
Parameters
Argument
Description
source
Filters the merge history to include only entries with the specified sources.
This parameter is optional.
destination
Specifies the destination branch for which merge history is displayed.
This parameter is required.
username
Provides a value to the /login option. You can specify a username value as either DOMAINUserName or
UserName.
The URL of the project collection that contains the branches about which you want to display the merge history
OPTION DESCRIPTION
/recursive Displays information for all merges in specified Team

Foundation version control server folder and its
subfolders.
/extended Displays a list of merges for a specific range of target
items (for example: tf merges tgt\file1.txt; C21-25). This
option displays the types of merges (for example, add or
edit) and detailed information about the source and
target items. This option implies /format: Detailed.
Note You cannot use this option if you have specified a
source item.
/format Specifies the formats in which merge history can appear:

Brief: default value, shows the changeset numbers
for both the source and target items and the
author and the date of the target checkin.
Detailed: shows the detailed paths and changeset
numbers for both the source and target items.

/showall Displays all past merges for a given target item under its
current name and all previously used names.
Remarks
Examples
The following example displays information about all merge operations performed between Beta1_branch and
RTM_branch.
c:\projects>tf merges /recursive Beta1_branch RTM_branch
Sample output:
Changeset Merged in Changeset Author Date

--------------------------------------------------------
135 162 Justin 10/31/2003
146 162 Justin 10/31/2003
147* 167 Bill 11/02/2003
The asterisk '*' next to changeset 147 indicates that only some of the changes in that changeset #147 were
merged into changeset #167.
See Also
Reference
Merge Command
Branch Command
Concepts
Other Resources
Msdn Command
Displays a help topic from the MSDN library that contains detailed information about a Team Foundation version
control command.
tf msdn commandname
Parameters
commandname Specifies a Team Foundation command for which to display a

help topic.
Remarks
When you need a command and are not sure which one to use, type tf msdn for a list of command reference
topics and links to additional resources. If you use the msdn command without specifying a commandname
parameter, you will see a topic that lists all commands together with usage requirements and a description.
When you specify the commandname parameter, the help topic opens for that specific command. If the system
cannot find a match for the commandname, it searches for aliases and short names. If it does not find a matching
command, alias, or short name, you will get an error message.
Examples
The following example displays a help topic that lists all the version control commands, including a brief
explanation of syntax.
c:\projects>tf msdn
The following example displays a help topic about the workspace command.
c:\projects>tf msdn workspace
See Also
Reference
Help Command (Team Foundation Version Control)
Other Resources
Permission Command
Modifies the user access control list (ACL ) and displays authorization settings for an item under version control.
To use the permission command, you must have the Manipulate security settings permission set to Allow for
the folders being modified, be a member of the Team Foundation Administrators security group, or be a
system administrator on the local computer (Windows Administrator security group). For more information, see
tf permission [/allow:(* |perm1[,perm2,...]]

[/deny:(* |perm1[,perm2,...])] [/remove:(* |perm1[,perm2,...])]
[/inherit:yes|no] [/user:username1[,username2,...]]
[/group:groupname1[,groupname2,...]] [/collection:TeamProjectCollectionUrl]
[/recursive] itemspec [/global][/login:username,[password]]
Parameters
perm Name of a permission or role to modify. For more

information about the permission names, see Team
Foundation Server Permissions.
Username Provides a value to the /user option. A username value

can be expressed in one of two ways, depending on the
network settings: DOMAIN\username or username.
Groupname The user-provided value for the /group option.
TeamProjectCollectionUrl The URL of the project collection that contains the item
for which you want to modify permissions (for example,
Itemspec Identifies the file or folder for which to modify

permissions. For more information about how Team
Control).
Note
Username Provides a value to the /login option. You can specify a
UserName.
OPTION DESCRIPTION
/allow Specifies a list of Team Foundation version control

permissions to add to the allow ACL.
/deny Specifies a list of denied Team Foundation version control

access permissions to add to the user access control list.
/remove Specifies a list of Team Foundation version control

permissions to remove from both the allow and the deny
ACLs.
/inherit If you select yes, all permissions associated with a parent

ACL are inherited by an item. Cannot be combined with
the /remove option.
/user Specifies the name of a user to modify permissions for.
/group Name of the group for which to modify permissions.
/recursive Applies the specified command to all items in the

directory and any subdirectories.
/recursive option works only when viewing the
permissions for items in a source tree. It does not work
when setting permissions, for example with /allow,
/deny and /remove options.
/global Used to view or assign any Team Foundation server
permission.
To assign permissions, use the /allow, /deny, or
/remove options.
The argument itemspec is not required. If it is listed, it is
ignored.
When used to view the Team Foundation server
permissions, the five permissions listed are as follows:
tf: AdminShelvesets
tf: AdminWorkspaces
tf: CreateWorkspace
tf: AdminConfiguration
tf: AdminConnections
For more information about permissions, see Team
Foundation Server Permissions.

## Remarks You can use the permission command (or alternatively its shortcut, perm ) to manage authorization
settings for Team Foundation version control server objects. However, this command does not let you manage
authentication settings such as creating or modifying Team Foundation security groups.
Examples
The following example displays the Team Foundation access control lists (ACLs) for 314.cs.
c:\projects>tf permission 314.cs
The following example displays the ACL information that relates to the group "developers" for the collection that
is located at http://myserver:8080/tfs/DefaultCollection/.
c:\projects>tf permission /group:[teamproject]\developers /collection:

http://myserver:8080/tfs/DefaultCollection/
The following example enables members of the "leads" group to change their local copies of all items in the
$/baseobjects Team Foundation version control server folder.
c:\projects>tf permission /allow:PendChange /group:[teamproject]\leads $/baseobjects
The following example removes all permission-related settings from the $/baseobjects folder for members of the
"developers" group.
c:\projects>tf permission /remove:* /group:developers $/baseobjects

The following example enables the group "testers" to change their local copies of all items in $/testproject.
c:\projects>tf permission /allow:PendChange /group:testers$/testproject
The following example enables user somealias to make pending changes to his local copy of $/testtproject/314.cs
in his workspace.
c:\projects>tf permission /allow:PendChange /user:somealias $/testproject/314.cs.
The following example denies user somealias the ability to make pending changes to his local copy of
$/testproject/1256.cs.
c:\projects>tf permission /deny:PendChange /user:somealias $/testproject/1256.cs
See Also
Reference
Other Resources
Proxy Command
Configures your client computer to use a proxy server. Adds, deletes, and lists proxy records about the location and
availability of one or more proxy servers within your deployment, including any remote sites.
To use the proxy command to configure a client computer, you must be a member of the User security group on
the local computer. To use the proxy command to work with proxy records, you must have the
AdminConfiguration permission. For more information, see Permissions and groups reference.
tf proxy ([/configure [Url]) [/collection:TeamProjectCollectionUrl]

[/login:UserName,[Password]]
tf proxy /add Url [/name:Name] [/site:SiteName]

[/description:Description] [/default:(global|site|all)]
[/collection:TeamProjectCollectionUrl] [/login:UserName,[Password]]
tf proxy /delete Url [/collection:TeamProjectCollectionUrl]

[/login:UserName,[Password]]
tf proxy /list [Url1 Yrl2 ...]

[/collection:TeamProjectCollectionUrl] [/login:UserName,[Password]]
tf proxy /enabled:(true|false)
Parameters
Url Identifies the proxy server. You must use the following
format: http://proxyServerName:proxyPortNumber.
Where proxyServerName is the name of the proxy server
and proxyPortNumber is the assigned listening port (for
example, http://server:8081).
TeamProjectCollectionUrl Identifies the project collection. You must use the

following format:
http://ApplicationTierServerName:PortNumber/Directory/
CollectionName.
Where ApplicationTierServerName is the name of the
application-tier server, PortNumber is the assigned
listening port, and Directory/CollectionName are the
names of the directory and the collection (for example,
http://server:8080/tfs/newcollection1).
UserName Provides a value to the /login option. You can specify a
user name value as either DomainUserName or
UserName.
Password Provides a password for the user name.
OPTION DESCRIPTION
/configure Configures your client computer to use a proxy server.
/login Specifies the user name and password to authenticate.
/add Adds a proxy record to Visual Studio Team Foundation

Server about the location and availability of proxy servers
on your network.
/name Associates a name with a proxy record.
/site Associates an Active Directory domain with a proxy

record.
/description Specifies a description of the proxy record.
/default Specifies the scope of the proxy record. If you add a proxy
record with the default set to global, the first time that a
developer performs a get operation, Team Foundation
Server will redirect that developer's request to the proxy
that is specified by the global record. If you add a proxy
record with the default set to site, the first time that a
developer from within the specified Active Directory
domain performs a get operation, Team Foundation
Server will redirect that developer's request to the proxy
that is specified by the record that is associated with the
site.
You can specify one of the following values:
global
site
all
/delete Deletes a proxy record from Team Foundation Server.

/list Lists proxy records in Team Foundation Server.
/enabled Enables or disables proxy.

true
false
Remarks
The proxy command has two purposes, and each purpose is aimed at a different type of user.
As a developer, you can use the proxy command to configure your client to use a proxy server or to override the
network defaults for a proxy server. This task is similar to configuring Team Explorer to use a proxy.
As a network administrator, you can use the proxy command to add and manage records about the location of
various proxy servers within your deployment of Team Foundation Server. You can use these records to help
developers configure their workstations to use a proxy. If you define a global proxy, Team Foundation Server can
automatically redirect developers to use it. If you have a complex network topology with multiple Active Directory
domains in various geographic locations, you can set up multiple records and associate each record with a
particular domain. These records can then help you automatically direct developers from each geographical
location to the appropriate proxy for their location.
Examples
The following example automatically detects and configures a client computer to use a proxy, if a proxy record has
been established:
c:\projects>tf proxy /configure
The following example overrides any proxy records on Team Foundation Server and configures a client computer
to use a specified proxy:
c:\projects>tf proxy /configure Url
The following example adds a global record to Team Foundation Server about the availability of this proxy. The
first time that a developer performs a get operation, Team Foundation Server will redirect all requests from that
developer to the specified proxy.
c:\projects>tf proxy /add http://server:8081 /default:global /collection:http://tfsserver:8080/
The following example adds a site record to Team Foundation Server for developers in an Active Directory domain,
which is named corp, to use this proxy server. The first time that a developer from that domain performs a get
operation, Team Foundation Server will redirect all requests from that developer to the specified proxy.
c:\projects>tf proxy /add http://server:8081 /default:site /site:corp /collection:http://tfsserver:8080/

See Also
Reference
Other Resources
Resolve Command
Lets you resolve conflicts between changed items in your workspace and the latest or destination versions of
items on the server.
To use the resolve command, you must be either the workspace owner or have the global Administer
workspaces permission set to Allow. You must also have the Read and Check out permissions for the items
involved in a resolve operation set to Allow. For more information, see Permissions and groups reference.
tf resolve [itemspec]
[/auto:(AutoMerge|TakeTheirs|KeepYours|OverwriteLocal|DeleteConflict|KeepYoursRenameTheirs)]
[/preview] [(/overridetype:overridetype | /converttotype:converttype] [/recursive] [/newname:path] [/noprompt]
[/login:username, [password]]
Parameters
Itemspec Used to identify the file or folder for which to resolve

version conflicts. If omitted, all items with conflicts will be
included. For more information about how Visual Studio
Team Foundation Server parses itemspecs to determine
which items are within scope, see Command-Line Syntax
(Version Control).
Note
overridetype Used with the /overridetype option. Specifies the

encoding type of the files involved. For example; binary.
converttype Used with the /converttotype option. Specifies the

encoding type, such as "unicode."
path Used with the /newname option. Specifies the new path
of the affected file or folder

UserName.
OPTION DESCRIPTION
/auto Resolves outstanding conflicts between different versions

of specified items in the current workspace using one of
the following options:
AutoMerge Automatically reconciles non-
overlapping content differences between the
specified workspace version of an item and the
latest server version.
If differences cannot be reconciled automatically,
either because the file is binary or because the
workspace and server versions contain
overlapping content changes, the conflict remains
unresolved pending the selection of one of the
following manual merge options.
The TakeTheirs option instructs Team Foundation
Server to overwrite workspace revisions with the
server revision. Further, for conflicts generated by
running the Merge command, this option accepts
the changes from the source of the merge and
overwrites the changes in the target.
The KeepYours option instructs Team Foundation
Server to keep your changes and discard the
changes in the server version of an item. For
conflicts generated by running the Merge
command, this option discards the changes from
the source of the merge and leaves the target
unchanged.
The OverwriteLocal option overwrites the file in
your workspace with the server version. This is
used to resolve conflicts that arise from a writable
file in your workspace.
The DeleteConflict option removes a conflict
from the conflict table, and the option/description
table.
The KeepYoursRenameTheirs option accepts the
contents and name of your file and renames their
file to a new name that the user specifies. This
option requires a single-item filespec, and the
/newname option must also be included.
/preview Displays current conflicts but does nothing with them.
/overridetype Specifies optional encoding for files involved in a three-

way merge. The files are treated as the specified encoding.
You must determine the correct encoding. Team
Foundation Server saves the resulting merge output in
the specified encoding in your workspace. For more
information about file encodings, see Managing File
Types.
Note
You cannot specify both an /overridetype and a
/converttotype.
/converttotype Specifies the encoding used for temporary conversion for
the input in a three-way merge operation. The merge
output is saved in the specified encoding in your
workspace. This option is an advanced option and seldom
used. For more information about file encodings, see
Managing File Types.
Note
You cannot specify both an /overridetype and a
/converttotype.
/recursive Resolves items in the specific directory and subdirectories.
/newname Option used to resolve a name collision conflict. Can only

be used in conjunction with AutoMerge and
KeepYoursRenameTheirs. With AutoMerge,
/newname is only valid with conflicts that involve rename
and/or undelete. If used, you must supply a new path.

/noprompt Suppresses any prompts for input.
## Remarks You can use the Resolve command to select a resolution for pending changes that conflict with the
server version.
If version conflicts are detected between your version and the version on the destination server during a get,
check-in, or merge operation, a prompt appears for you to select a conflict resolution using the resolve command.
You must resolve conflicts before you can check in your pending changes.
Examples
The following example invokes the Resolve Conflicts dialog box so that you can tell Team Foundation Server
how to deal with pending changes that conflict with the server version.
tf resolve
The following example attempts to resolve all conflicts by automatically merging the changes.
tf resolve /auto:automerge
See Also
Reference
Merge Command
Get Command
Checkin Command
Difference Command
Concepts
Managing File Types
Other Resources
Resolving Folder Differences and File Conflicts
Rollback Command (Team Foundation Version
Control)
You can use this command to roll back the effects of one or more changesets to one or more version-controlled
items. This command does not remove the changesets from an item's version history. Instead, this command
creates in your workspace a set of pending changes that negate the effects of the changesets that you specify.
To use this command, you must have the Read, Check Out, and Check In permissions set to Allow. For more
tf rollback /toversion:VersionSpec ItemSpec [/recursive] [/lock:none|checkin|checkout] [/version:versionspec]

[/keepmergehistory] [/login:username,[password]] [/noprompt]
tf rollback /changeset:ChangesetFrom~ChangesetTo [ItemSpec] [/recursive] [/lock:none|checkin|checkout]

[/version:VersionSpec]
[/keepmergehistory] [/noprompt] [/login:username,[password]]
Parameters
ChangesetFrom~ChangesetTo Use this argument with the /changeset option to specify

the changesets that you want to roll back. You can specify
the changesets in the following ways:
A single changeset
Example: /changeset:C11
A range of changesets
Example: /changeset:C7~C20
A date
Example: /changeset:D09/30/09
A range of dates
Example:/changeset:D09/23/09~D10/07/09
The most recent changeset
Example: /changeset:Tip or /changeset:T
ItemSpec Use this argument to specify one or more items that you
want to roll back. If you are using the /toversion option,
you must specify this argument.
For more information about how Team Foundation parses
item specifications, see Command-Line Syntax (Version
Control).
Note:
VersionSpec The user-provided value for both the /version option

and the /toversion option.
Use this argument with the /toversion option to revert a
file to its state in a specific changeset. You can specify the
version in the following ways:
A single changeset
Example: /toversion:C32
A date (at midnight)
Example: /toversion:D06/19/09
A date and a time
Example: /toversion:D06/19/09T14:32
A label
Example: /toversion:LTestLabel
The version in the workspace that is mapped to
the current directory
Example: /toversion:W
The version in a specific workspace
Example:
/toversion:WResolveRIConflicts;AKerry
For more information about how Team Foundation parses
versionspecs, see Command-Line Syntax (Version
Control).
OPTION DESCRIPTION
/changeset Use this option to specify one or more specific changesets

that you want to negate.
/keepmergehistory This option has an effect only if one or more of the

changesets that you are rolling back include a branch or
merge change. Specify this option if you want future
merges between the same source and the same target to
exclude the changes that you are rolling back.
/lock Specify this option to prevent other users from checking
in or checking out items until you finish rolling back all
associated changes. For more information, see
Lock Options
None
Default. No lock is applied. If the file that you are
rolling back has been locked, this option removes
the lock.
Checkin
Locks an item until you release the lock by
performing a check-in. Other users can check out
the specified items, but the users cannot check in
revisions until the lock is removed. You cannot
lock a file that is already locked.
Checkout
Prevents users from checking in or out a locked
item until you remove the lock by performing a
check-in.
/login For information about this option, see Command-Line

Options.
/noprompt Suppresses any dialog boxes that would otherwise appear

during this operation.
/recursive Specify this option if you want the operation to include

items in subfolders.
/toversion Specify this option to revert a file to its state in a specific

changeset. When you use this option, you negate the
effect of all changesets that have been applied since the
version that you specify.
/version Specifies the current version of the files and folders that
you want to roll back.
Remarks
The tf rollback command negates the effect of each changeset that you specify for each item that you specify. The
following table lists how the operation negates each kind of change.
...A ROLLBACK CHANGE AND THE FOLLOWING ADDITIONAL

IF YOU ROLL BACK THIS CHANGE... CHANGE ARE MADE
add, branch, or undelete delete
edit edit
...A ROLLBACK CHANGE AND THE FOLLOWING ADDITIONAL
IF YOU ROLL BACK THIS CHANGE... CHANGE ARE MADE
encoding encoding
rename/move rename/move
delete undelete
merge Change that negates whatever changes were merged into the
current branch.
The following list provides some examples of changes that result from the rollback command:
If you are rolling back a changeset in which an add change occurred, the rollback operation causes a
rollback change and a delete change.
If you are rolling back changeset 521 in which an edit change occurred, the rollback operation causes a
rollback change and an edit change that negates the changes encompassed by the edit change in
changeset 521.
In changeset 132, you merged from $/BranchA/File1.txt to $/BranchB/File1.txt. The changes included
in that merge included edit changes in changesets 92 and 104. In changeset 162, you roll back changeset
132, which results in a rollback change and an edit change to $/BranchB/File1.txt that negates the edit
changes in changesets 92 and 104.
Exit Codes
The exit codes in the following table appear after you run the tf rollback command.
EXIT CODE DESCRIPTION
0 The operation rolled back all items successfully.
1 The operation rolled back at least one item successfully but

could not roll back one or more items.
100 The operation could not roll back any items.
Examples
The following example negates the effect of changeset 23 on all items that were changed in that changeset.
c:\workspace> tf rollback /changeset:C23
The following example negates the effect of changeset 23 on the file a.txt.
c:\workspace> tf rollback /changeset:C23 a.txt
The following example changes the content of a.txt to match the version that was checked in with changeset 23.
c:\workspace> tf rollback /toversion:C23 a.txt
The following example changes the content of OurTeamProject to match the last changeset that was applied on
or before midnight on August 31, 2009.
c:\workspace> tf rollback /toversion:D08/31/2009 /recursive $/OurTeamProject/
Example: /keepmergehistory Option

When you roll back a changeset that includes a branch or a merge change, you usually want future merges
between the same source and the same target to include those changes. However, you can use the
/keepmergehistory option if you want future merges between the same source and the same target to exclude
changesets that were encompassed in a past merge operation.
For example, you can use this command in the following situation:
1. In On June 30, 2009, you perform a full merge of all items from $/BranchA/ to $/BranchB/:
c:\workspace> tf merge $/BranchA $/BranchB
You check in this merge as part of changeset 292.

2. In July, you make several changes $/BranchA/Util.cs. These changes are encompassed in changesets 297,
301, and 305.
3. On August 1, 2009, you merge $/BranchA/Util.cs to $/BranchB/Util.cs:
c:\workspace> tf merge $/BranchA/Util.cs $/BranchB/Util.cs
You check in the change as part of changeset 314. The result of this operation is that the edits that you
made in changesets 297, 301, and 305 to $/BranchA/Util.cs are now also applied to $/BranchB/Util.cs.
4. A week later, you realize that the edits that you made to $/BranchA/Util.cs in July are not appropriate for
$/BranchB/Util.cs. You can use the rollback command to negate these changes. When you use the
rollback command to roll back a merge change or a branch change, you have a decision to make.
If you want the changes that you made in July to $/BranchA/Util.cs to be re-applied to
$/BranchB/Util.cs in future merges, you should type the following command:
c:\workspace> tf rollback /changeset:314
If you want the changes that you made in July to $/BranchA/Util.cs to never be re-applied to
$/BranchB/Util.cs in future merges, you should type the following command:
c:\workspace> tf rollback /changeset:314 /keepmergehistory
5. A few weeks later, you merge $/BranchA/ into $/BranchB/:
c:\workspace> tf merge $/BranchA $/BranchB
If you omitted the /keepmergehistory option, the merge change will apply to $/BranchB/Util.cs
all changesets that were applied to $/BranchA/Util.cs since changeset 292, including changesets
297, 301, 305. In other words, a future merge will undo the rollback change.
If you included the /keepmergehistory option, the merge operation will apply to
$/BranchB/Util.cs all changesets that were applied to $/BranchA/Util.cs since changeset 292,
excluding changesets 297, 301, and 305. In other words, a future merge will not undo the rollback
change. Therefore, the content on BranchA might not match the content on BranchB.
See Also
Reference
Merge Command
Concepts
Operations Available Only From the Command-Line (Team Foundation Version Control)
Other Resources
Shelvesets Command
Displays information about a set of shelved changes.
To use the shelvesets command, you must the have Read permission and the Check out permission set to
Allow for the items in the shelvesets. For more information, see Permissions and groups reference.
tf shelvesets [/owner:ownername] [/format:(brief|detailed)] [/collection:TeamProjectCollectionUrl]]

[/login:username,[password]] shelvesetname
Parameters
ownername Provides a value such as * or DOMAIN\john to the /owner

option.
shelvesetname The name of the shelveset.
TeamProjectCollectionUrl The URL of the project collection that contains a set of

shelved changes about which you want to display information

OPTION DESCRIPTION
/owner Specifies one or more shelveset owners. You can use wildcard
characters.
/format Specifies what kind of format to display shelveset information

in.
Brief displays the shelveset name, the name of the user who
created it, and a shelveset comment, if one exists. Detailed
displays the shelveset name, owner, and comment in addition
to a list of associated work items and any check-in notes.
Brief is the default value.

Remarks
Shelvesets are created by the shelve command. Shelvesets are stored on the Team Foundation Server and can be
retrieved into a workspace by any user who has sufficient permissions using the Unshelve Command. Unlike a
changeset, a shelveset is a non-versioned entity. If you or another user unshelve the items of which a shelveset
consists, edit several files, and re-shelve the shelveset, Team Foundation does not create a new version of the
items for future comparison and maintains no record of who revised the items, when, or in what manner. For
more information about deciding whether to shelve or check in a set of pending changes and a general overview
of shelving, see Working with Shelvesets.
For detailed information about the individual source file revisions of which a particular shelveset consists, you can
use the Status Command with the /shelveset option.
You can compare a shelved revision to its base shelveset version without unshelving the item into your workspace.
You can use this feature to conduct a quick peer code review.
Examples
The following example displays information about the BuddyTest_23 shelveset for the Team Foundation Server to
which the current directory maps.
c:\projects>tf shelvesets BuddyTest_23
The following example lists the shelvesets owned by "John."
c:\projects>tf shelvesets /owner:John
The following example displays information about the shelvesets on the Team Foundation Server to which the
current directory maps.
c:\projects>tf shelvesets /owner:*
See Also
Reference
Status Command
Changeset Command
Shelve Command
Unshelve Command
Concepts
Other Resources
Undelete Command
The undelete command restores items that were previously deleted.
Note:
** **The results of this command are not visible in other workspaces until you perform a check-in operation.
For more information, see Check In Pending Changes.
To use the undelete command, you must have the Check out permission set to Allow. If you include the /lock
option with a value other than none, you must have the Lock permission set to Allow. Additionally, you must
own the workspace or have the global Administer workspaces permission set to Allow. For more information,
tf undelete [/noget] [/lock:(none|checkin|checkout)]

[/recursive] itemspec[;deletionID] [/login:username,[password]]
Parameters
itemspec Identifies the file or folder to undelete. For more information

about how Team Foundation parses itemspecs to determine
which items are within scope, see Command-Line Syntax
(Version Control).
deletionID Specifies a unique identifier that disambiguates multiple

deleted items with the same name.

OPTION DESCRIPTION
/noget Restores the deleted item to your workspace and then,

pending completion of a check-in operation, restores the
item on the server but does not immediately retrieve a
physical copy of the item to disk.
/lock Prevents other users from checking in or checking out
the specified files. For more information, see
Lock Options:
None
Default. No lock is applied.
Checkin
Checkout
release the lock by performing a check in. If any
/recursive Restores all files and subfolders from the specified

directory.

Remarks
The Undelete command of the tf command-line feature schedules specified files or folders for restoration
pending the completion of a check-in operation. It also retrieves the specified items from the server to the local
disk unless you explicitly include the /noget option.
When files or folders that have the same name have been deleted from the same server folder, you must include
a value for the deletionID parameter to indicate which of the deleted items that you want to restore. You can
obtain a deletionID using the dir command.
If you want to change the file after restoring it, you may check out the file for editing with the checkout command
as usual.
When your itemspec specifies a folder, Team Foundation restores all its files and subfolders and the files they
contain, by default. If you do not want to restore all the items in a folder, you must first undelete the folder and its
items and then delete the items that you do not want to keep.
Examples
The following example restores 314.cs to the server folder from which 314.cs was deleted and retrieves a read-
only copy of the latest version in the current workspace.
C:\projects>tf undelete c:\math\314.cs
The following example displays deletion IDs for all items on the server that have been deleted more than one
time.
c:\projects>tf dir $/ /deleted
Sample output:
$/projects/math/314.cs;X10
$/projects/math/314.cs;X11
The following example restores the X11 version of 314.cs to the server folder from which the file was deleted and
retrieves a read-only copy of the latest version in the current workspace.
c:\projects>tf undelete 314.cs;X11
See Also
Reference
Rename Command (Team Foundation Version Control)
Delete Command
Dir Command
Concepts
Pending Changes
Other Resources
Unlabel Command
Removes an item from an existing label in the server for Team Foundation version control.
To use the unlabel command, you must either own the label, or have the Administer labels permission set to
Allow. For more information, see Permissions and groups reference.
tf unlabel [/collection:TeamProjectCollectionUrl] [/recursive] [/login:username, [password]] labelname

itemspec
Parameters
TeamProjectCollectionUrl The URL of the project collection that contains the item
that you want to remove from an existing label (for
labelname Specifies the name of the label to remove from the

specified items.
itemspec Identifies the file or folder from which to remove the

specified label. For more information about how Team
Control).
Note
You can specify more than one itemspec argument.

username value as either DOMAIN\UserName or
UserName.
OPTION DESCRIPTION
/recursive Unlabels all items in the particular directory and all the
subdirectories that match the itemspec.

Remarks
The unlabel command of the tf command-line utility removes an item from an existing label in the Team
Foundation version control server. For an introduction to labels, see Use Labels to Take a Snapshot of Your Files.
For information about how to assign a label to a set of files and folders, see Label Command (Team Foundation
Version Control).
If you remove all items from a label in the Team Foundation version control server, that label is deleted. You can
also delete a label using the command tf label /delete . To learn more about the existing labels in the system,
see Labels Command.
Examples
The following example removes the "goodbuild" label from 314.cs.
c:\projects>tf unlabel goodbuild $/src/314.cs
The following example removes the "Beta1" label from all files and folders in the collection at
c:\projects>tf unlabel Beta1 $/ /collection:http://myserver:8080/tfs/DefaultCollection /recursive
See Also
Reference
Labels Command
Concepts
Other Resources
View Command
The view command retrieves a specific version of a file to a temporary folder on your computer and displays it.
To use the view command, you must have the Read permission set to Allow. For more information, see
tf view [/collection:TeamProjectCollectionUrl] [/console] [/recursive] [/output:localfile]

[/shelveset:shelvesetname[;owner]] [/noprompt] itemspec
[/version:versionspec] [/login:username,[password]]
Parameters
Argument
Description
The URL of the project collection that contains a specific version of a file about which you want to retrieve
information (for example, http://myserver:8080/tfs/DefaultCollection).
shelvesetname [:owner ]
Identifies the shelveset. The optional owner argument is used to specify a shelveset that is not owned by the
current user.
Itemspec
Identifies the file or folder to retrieve. For more information about how Team Foundation parses itemspecs to
determine which items are within scope, see Command-Line Options.
Note
Versionspec
Provides a value such as C3 for the /version option. For more information about how Team Foundation parses a
version specification to determine which items are within its scope, see Command-Line Syntax (Version Control).
username
Provides a value to the /login option. You can specify a username value as either DOMAINUserName or
UserName.
localfile
Provides the path of the folder to which you want to output the file.
OPTION DESCRIPTION
/console Specifies that the file output should be directed to the

console. This is useful if you want to write the file out to
disk using console redirection (with a different name or
location than the versioned item).
/recursive Views all items in the specified directory and any

subdirectories.
/shelveset Specifies the shelveset by name.
/noprompt Specifies that Team Foundation should not prompt you

before displaying each file when you include a wildcard in
an itemspec that matches more than one file.
/version Specifies the version of the file to open for viewing. If you
omit this option, view retrieves the latest Team
Foundation version control server version.

/output Outputs the file to a local folder instead of invoking a

Windows shell to open the file.
## Remarks The view command of the tf command-line utility retrieves a read-only copy of a file from the Team
Foundation version control server to a temporary folder on your computer and displays its contents. Unless you
specify a particular version, Team Foundation retrieves the latest version of the file from the Team Foundation version
control server.
The view command does not retrieve files into your workspace or check them out. See Get Command and
Checkout and Edit Commands for more information about how to get the Team Foundation version control server
version of and check out files.
You can use the Difference Command to view the differences between two versions of a file.
Output Options
By default, Team Foundation displays the contents of the file in the viewer associated with its file type.
If you include the /console option, Team Foundation prints the contents of the file to the command console.
Likewise, if Team Foundation cannot locate a viewer for the type of file you have specified, it prints the contents of
the file to the command console.
Finally, you can redirect the contents of a file to standard out using | or > in order to save it in another file or pass
it to another program for post-processing.
Examples
The following example displays the latest version of the file 314.c.
c:\projects>tf view 314.c
The following example displays the version of 314.c that was checked in with changeset 1999.
c:\projects>tf view /version:C1999 314.c
The following example retrieves version 5 of 314.c and writes it to the file 314.old.
c:\projects>tf view /version:5 314.c > 314.old
The following example displays the latest version of each file that matches the wildcard "*.cs".
c:\projects>tf view *.cs
See Also
Reference
Get Command
Difference Command
Other Resources
Workfold Command
Creates, modifies, or displays information about the mappings between your workspace folders and the folders
on the server for Team Foundation version control.
To use the workfold command, you must be the owner of the specified or implied workspace or have the global
Administer workspaces permission set to Allow. For more information, see Permissions and groups reference.
tf workfold localfolder [/login:username,[password]]
tf workfold [/workspace:workspacename] [/login:username,[password]]
tf workfold [/collection:TeamProjectCollectionUrl] [/workspace:workspacename] [/login:username,[password]]

serverfolder
tf workfold [/map serverfolder localfolder] [/collection:TeamProjectCollectionUrl]

[/workspace:workspacename][/login:username,[password]
tf workfold /unmap [/collection:TeamProjectCollectionUrl] [/workspace:workspacename]

[/recursive] (serverfolder|localfolder) [/login:username,[password]]
tf workfold /cloak
serverfolder [/workspace:workspacename] [/collection:TeamProjectCollectionUrl] [/login:username,[password]]
tf workfold /decloak serverfolder

[/workspace:workspacename] [/collection:TeamProjectCollectionUrl][/login:username,[password]]
Parameters
Argument
Description
workspacename
Specifies the name of the workspace on which the command operates for the /workspace option.
serverfolder
Specifies the name of a Team Foundation version control server folder.
localfolder
Specifies the name of a local folder.
The URL of the project collection that contains the folders that you want to compare with server folders (for
example, http://myserver:8080/tfs/DefaultCollection/).
username
UserName.
OPTION DESCRIPTION
/workspace Specifies the name of the workspace to work in.
/map Specifies an association between a local folder and the

Team Foundation version control server folder. By default,
the workfold command uses this option, even if
unspecified, unless /unmap, /cloak, or /decloak is
specified.
/unmap Specifies which folder mapping should be removed from

the workspace.
/cloak Specifies that the folder should be excluded from any

version control actions made in the workspace.
/decloak Decloaks a folder so the folder can be retrieved into the

workspace.

Remarks
You can use the workfold command of the tf command-line utility to create and edit workspace mappings. A
workspace mapping creates a client-side folder into which all files and subfolders in the Team Foundation version
control server folder are retrieved when you execute a tf get operation. This get will not work if the client-side
folder is cloaked.
You can also specify an asterisk (*) wildcard to map a Team Foundation Server folder and its immediate items to
your local workspace. This is often referred to as single folder mapping.
Options for Workspace Mapping
A workspace mapping is a list of active and cloaked items. You can add Team Foundation version control server
items to the mapped list in the workspace using the /map option. You can also exclude an item from the
workspace explicitly by using the /cloak option. You can only cloak the items that have a mapped parent.
Cloaking is an effective way to improve the speed of batch Get operations and to conserve space on disk.
Use cloaking with discretion. To avoid compilation and integration problems, you should only cloak those items
that you know to be outside the scope of your current and future projects, such as images and external
documentation files.
You can use the /unmap and /decloak options to selectively delete mapped and cloaked entries from the
workspace mapping.
How Workspace Mappings are Applied
By default, workspace mappings are applied recursively. When you map a local folder to a Team Foundation
version control server folder, the system implicitly creates a mapping between all its current and future
subfolders. For example, if you map $/projects to c:\projects, subsequently add a project called
$/projects/project_one, and then run a get of the workspace, Team Foundation automatically creates a local
working folder named project_one in the C:\projects directory.
In this example, you can use a wildcard, "*", to map a server folder and its immediate items to your local
workspace:
tf workfold $/projects/MyTeamProject/* C:\MyLocalWorkfold\MyTeamProject
In this example, you can override the automatically-created mapping between $/projects/project_one and
C:\projects\project_one by using the workfold command as follows:
tf workfold $/projects/project_one C:\DifferentWorkfold
Mappings under Cloaks

Mappings of uncloaked folders that are located beneath a cloaked folder in the version control hierarchy can be
mapped to your local workspace.
Examples
The following example displays the mappings for the workspace in which c:\projects resides.
c:\projects>tf workfold
The following example cloaks the c:\projects\lib folder.
c:\projects>tf workfold /cloak c:\projects\lib
The following example displays the mapping for the local file word.cs.
c:\projects>tf workfold word.cs
The following example maps the folder C:\DifferentWorkfold to the Team Foundation version control server
folder $/projects/project_one and replaces the previous workspace mapping for the $/projects/project_one Team
Foundation version control server folder.
c:\projects>tf workfold $/projects/project_one C:\DifferentWorkfold
See Also
Tasks
Cloak and Uncloak Folders in a Workspace
Reference
Workspace Command
Concepts
Other Resources
Create a Workspace and Get Files for the First Time
Workspace Command
Lets you create, delete, view, or modify properties and mappings associated with a workspace.
To modify or delete an existing workspace, you must be the owner or have the global Administer workspaces
permission set to Allow. To create a workspace, you must have the global Create a workspace permission set
to Allow. To create workspaces for other users, you must have the Administer workspaces permission set to
Allow. For more information, see Permissions and groups reference.
tf workspace /new [/noprompt] [/template:workspacename[;workspaceowner]]

[/computer:computername] [/comment:("comment"|@comment file)]
[workspacename[;workspaceowner]] [/login:username,[password]]
[/collection:TeamProjectCollectionUrl] [/permission:(Private|PublicLimited|Public)]
[/location:(local|server)]
tf workspace /delete [/collection:TeamProjectCollectionUrl] workspacename[;workspaceowner] [/login:username,

[password]]
tf workspace [/collection:TeamProjectCollectionUrl] [/comment: ("comment"|@comment file)]

[/newname:workspacename]
[workspacename[;workspaceowner]] [/newowner:ownername] [/computer:computername] [/permission:
(Private|PublicLimited|Public)] [/login:username,[password]]
[/location:(local|server)]
Parameters
workspacename Specifies a name for the workspace which to create, edit,

delete, or display information about.
workspaceowner Specifies a username for the workspace. This parameter is

required when the workspace owner is not the person
performing the command.
computername Provides a value to the /computer option.
comment Provides a value to the /comment option.
@commentfile Specifies the path of a file where the comment should be

read.

UserName.
TeamProjectCollectionUrl The URL of the project collection that contains the workspace
about which you want to create, edit, delete, or display
information (for example,
ownername Provides a value to the /newowner option.
OPTION DESCRIPTION
/new Creates a new workspace.
/template Specifies an existing workspace to use as a template to create

the new workspace. The new workspace uses the mappings
of the existing workspace.
/delete Deletes the specified workspace.
/computer Specifies the name of the computer on which to create the

workspace. This option is an advanced option.
/comment Provides a comment describing the workspace.
/newname Renames an existing workspace.
/noprompt Performs the specified workspace command without

displaying a dialog box.
/permission Specifies the options of workspace permission:

Private: Only the owners can use, check in files to,
or administer the workspace.
Public Limited: Any valid user can use the
workspace. However, only the owners can check
in files to or administer the workspace.
Public: Any valid user can use, check in files to, or
administer the workspace.
/location Specifies where the workspace is created:

local: On the client machine. This is the default.
server: On the TFS server.

/newowner Specifies the user name for the new owner of the workspace.
Remarks
A workspace is a local copy of the files and folders on the server, plus any changes that you have made locally.
When you add, edit, delete, move, rename, or otherwise change any version-controlled item, your changes are
isolated in your workspace where you can make and test your changes. Your pending changes are committed to
the server and become available to other users outside your workspace when you perform a check-in.
Creating a Workspace
Before you can add files to the version control server or check out items on the server in order to edit them, you
must create a workspace or associate an existing one with the current directory. For more information, see
Create a Workspace and Get Files for the First Time.
To make the current directory a working folder for an existing workspace on your computer, type tf workspace
workspacename, where workspacename is the name of the existing workspace. The Edit Workspace dialog box
appears. Click click here to enter a new working folder, type the server path for which you want to map the
current directory in the Source Control Folder box, type the current directory in the **Local Folder box,
and click **OK.
When you create a new workspace, you can specify a template workspace as part of the /new option. When you
specify a template workspace, Team Foundation creates a new workspace on the current computer, sets the
owner to the current owner, and replicates the following workspace properties into the new workspace from the
template workspace: mappings and comment. If no name is specified, the system uses a name based on the
current computer name. When you create a workspace using a template, Team Foundation does not retrieve the
files to which it maps from the server. Use the Get Command to synchronize the new workspace with the latest
version on the server.
Single Folder Mapping
You can choose to map only the immediate children of a version control folder to a local workspace. To do this,
add an asterisk wild-card character in the Source Control Folder box in the Add Workspace dialog box. For
example, $/folder/*. Otherwise, by default, all the children of the version control folder are recursively mapped to
the local workspace.
Single folder mapping within a version control hierarchy is useful because it limits the number of items
downloaded to the client computer. Another way to limit downloaded files is to cloak files that you do not need to
have in your workspace. For more information, see Cloak and Uncloak Folders in a Workspace. This provides
faster download times and saves disk space on the client computer.
Deleting a Workspace
If you delete a workspace that contains pending changes, Team Foundation cancels the pending changes as part
of the delete process. Deleting a workspace does not delete the files and folders on the client computer that were
in that workspace.
NOTE
Commands run manually require the /noprompt option to bypass user acknowledgement. Be careful if using PowerShell's
Start() method to run commands, as this option can be automatically set.
Editing a Workspace
You can change the following workspace attributes:
Workspace Name
Comment
Working folder mappings
If no workspace specification is provided, the workspace for the current folder is used.
Examples
The following example opens the Add Workspace dialog box and creates a new workspace. You can use the
Add Workspace dialog box to edit the source control folder, owner, computer, comment, and local folders.
c:\projects>tf workspace /new /collection:http://myserver:8080/tfs/DefaultCollection
The following example creates a new workspace called Beta1 and assigns jenh as the workspace owner. You must
have the AdminWorkspaces permission to assign ownership of a new workspace to another user. For more
information on security permissions, see Permissions and groups reference.
c:\projects>tf workspace /new Beta1;jenh
The following example creates a new workspace by using the Beta1 workspace that is owned by jenh as a
template.
c:\projects>tf workspace /new /template:Beta1;jenh /collection:http://myserver:8080/tfs/DefaultCollection
The following example removes the Beta1 workspace from the server.
c:\projects>tf workspace /delete Beta1
The following example edits properties for the current workspace.
c:\projects>tf workspace
The following example opens the Beta1 workspace for which user jenh is the owner so that you can see its
properties and mappings. If you have the AdminWorkspaces permissions, you can change the workspace
properties and mappings.
c:\projects> tf workspace Beta1;jenh
See Also
Tasks
Cloak and Uncloak Folders in a Workspace
Reference
Workspaces Command
Concepts
Other Resources
Workspaces Command
Displays information about workspaces in the system and updates cached information about a user name or
computer name change on the server that is running Visual Studio Team Foundation Server.
To use the workspaces command, you must have the Read permission set to Allow. For more information, see
tf workspaces [/owner:ownername] [/computer:computername]

[/collection:TeamProjectCollectionUrl] [/format:(brief|detailed)]
[/updateUserName:oldUserName] [/updateComputerName:oldComputerName]
[workspacename][/login:username,[password]]
tf workspaces /remove:(*|workspace1[,workspace2,...])
/collection:(*|TeamProjectCollectionUrl)
Parameters
ownername Provides a value to the /owner option. Specify "" to

match workspaces created by any user.
computername Provides a value to the /computer option. Specify "" to

match workspaces on any computer.
workspacename Specifies the name of a workspace to display information

about. If a workspacename is not specified, information is
displayed about all the workspaces in a server. You can
also use the "*" wildcard character to display information
about all workspaces for a server.
oldUserName Provides the old user name for the /updateUserName

option.
oldComputerName Provides the old computer name for the

/updateComputerName option.
TeamProjectCollectionUrl The URL of the project collection that contains the

workspaces about which you want to display information
UserName.
OPTION DESCRIPTION
/owner Specifies the name of the user who created the

workspace. If no owner is specified, Team Foundation
returns information about workspaces owned by the
current user only.
/computer Specifies the name of a client computer by which to filter

the list of workspaces for the server. If no computer is
specified, Team Foundation returns information about
workspaces on the current computer only.
/format Specifies the format of the workspace information. Brief

returns workspace information without mappings.
Detailed returns workspace information and also the
mappings. The detailed format can only be used when
the /collection option is specified. Brief is the default
value.
/updateUserName Updates security identification information on the Team

Foundation server for a user whose network user name
has been changed. If you specify this option, you must
also specify a project collection by using the /collection
option.
/updateComputerName Instructs Team Foundation to update its tables to reflect

a change in the name of a client computer. If you specify
this option, you must also specify a project collection by
using the /collection option.
/remove Removes the specified workspace entries for the specified

project collection from the client cache.

Remarks
The workspaces command of the tf command-line utility displays information about workspaces on the current
computer, owned by a specified user, or for all workspaces associated with a specific Team Foundation Server. For
each workspace, Team Foundation displays the name, owner, comment, and computer name. With detailed
output, it also shows the workspace mappings. Unless you provide a filter such as owner, computer or workspace
name, Team Foundation only displays information about the workspaces that you have created.
For more information about how to edit workspace properties, see Workspace Command.
Examples
The following example displays a list of all workspaces for the current user on the current computer.
c:\projects>tf workspaces
The following example displays the list of all workspaces for all users on all computers that have been created in
the following project collection at the address http://myserver:8080/tfs/DefaultCollection.
c:\projects>tf workspaces /owner:* /computer:* /collection:http://myserver:8080/tfs/DefaultCollection
The following example displays detailed information about all workspaces that the current user has created in the
project collection at the address http://myserver:8080/tfs/DefaultCollection.
c:\projects>tf workspaces /computer:* /format:detailed /collection:http://myserver:8080/tfs/DefaultCollection
The following example displays detailed information including a list of workspace mappings about the workspace
"WS1," which is owned by the current user and is located on the current computer.
c:\projects>tf workspaces /format:detailed /collection:http://myserver:8080/tfs/DefaultCollection WS1
The following example removes all cached workspaces from the cache in the project collection at the address
c:\projects>tf workspaces /remove:* /collection:http://myserver:8080/tfs/DefaultCollection
See Also
Reference
Workspace Command
Workfold Command
Concepts
Other Resources
Azure Repos with Slack
If you use Slack, you can use the Azure Repos app for Slack to easily monitor your Azure repositories. You can set
up and manage subscriptions to receive notifications in your channel whenever code is pushed/checked in and
whenever a pull request (PR ) is created, updated or a merge is attempted. This app supports both Git and Team
Foundation Version Control (TFVC ) events.
Read this article to learn how to:

Add the Azure Repos app to your Slack workspace
Connect Azure Repos app to your repositories
Manage subscriptions to repository related events in your Slack channel
Using filters effectively to customize subscriptions
Get notifications in private Slack channels
Prerequisites
To create subscriptions in a Slack channel for repository-related events, you must be a member of the Azure
Project Administrators group. To get added, see Set permissions at the project or collection level.
To receive notifications, the Third-party application access via OAuth setting must be enabled for the
organization. See Change application access policies for your organization.
NOTE
Notifications are currently not supported inside direct messages.
You can only link the Azure Repos app for Slack to a project hosted on Azure DevOps Services at this time.
Add the Azure Repos app to your Slack workspace

1. Navigate to the Azure Repos Slack app to install the Azure Repos app to your Slack workspace.
2. Once added, you'll see a welcome message from the app as shown in the following image.
3. Use the /azrepos Slack handle to interact with the app. A full list of commands is provided in the Command
reference section of this article.
Connect the Azure Repos app to your repositories

1. Once the app has been installed in your Slack workspace, connect and authenticate yourself to Azure Repos
using /azrepos signin command.
2. To start monitoring a repository, use the following slash command inside a channel:
/azrepos subscribe [repository url]
The repository URL can be to any page within your repository that has your repository name.
For example, for Git repositories, use:
/azrepos subscribe https://dev.azure.com/myorg/myproject/_git/myrepository
For TFVC repositories, use:
/azrepos subscribe https://dev.azure.com/myorg/myproject/_versionControl
3. The subscribe command gets you started with a default subscription. For Git repositories, the channel is
subscribed to the Pull request created event, and for TFVC repositories, the channel is subscribed to the
Code checked in event.
Manage subscriptions
To view, add and remove subscriptions for a channel, use the subscriptions command:
/azrepos subscriptions
This command lists all the current subscriptions for the channel and allows you to add new subscriptions or
remove existing ones. When adding subscriptions, you can customize the notifications you get by using various
filters, as described in the following section.
Using filters effectively to customize subscriptions
When a user subscribes to a repository using /azrepos subscribe command, a default subscription is created.
Often, users have the need to customize these subscriptions. For example, users may want to get notified only
when PRs have a specific reviewer.
The following steps demonstrate how to customize subscriptions.
1. Run the /azrepos subscriptions command.
2. In the list of subscriptions, if there is a subscription that is unwanted or must be modified (Example: creating
noise in the channel), select the Remove button.
3. Select the Add subscription button.
4. Select the required repository and the desired event.
5. Select the appropriate filters to customize your subscription.
Example: Get notifications only when my team is in the reviewer list for a PR
Example: Tell me when merge attempts fail due to a policy violation
NOTE
All the filters are typically drop-downs. However if the drop-down were to have greater than 100 items, then users are
asked to enter the values manually.
For the TFVC Code Checked in event, the filter Under path must be of the format $/myproject/path .
Previews of pull request URLs

When a user pastes the URL of a PR, a preview is shown like the one in the following image. This helps to keep
PR -related conversations contextual and accurate.
Command reference
The following table lists all the /azrepos commands you can use in your Slack channel
SLASH COMMAND FUNCTIONALITY
/azrepos subscribe [repository url] Subscribe to a repository to receive notifications
/azrepos subscriptions Add or remove subscriptions for this channel
/azrepos signin Sign in to your Azure Repos organization
/azrepos signout Sign out from your Azure Repos organization
/azrepos feedback Report a problem or suggest a feature
Notifications in Private channels

The Azure Repos app can help you monitor the repository events in your private channels as well. You will need to
invite the bot to your private channel by using /invite @azrepos . Post that, you can set up and manage your
notifications the same way as you would for a public channel.
Troubleshooting
If you are experiencing the following errors when using the Azure Repos App for Slack, follow the procedures in
this section.
Sorry, something went wrong. Please try again.
Configuration failed. Please make sure that the organization '{organization name}' exists and that you have
sufficient permissions.
Sorry, something went wrong. Please try again.
The Azure Repos app uses the OAuth authentication protocol, and requires Third-party application access via
OAuth for the organization to be enabled. To enable this setting, navigate to Organization Settings > Security >
Policies, and set the Third-party application access via OAuth for the organization setting to On.
Configuration failed. Please make sure that the organization '{organization name }' exists and that you have
sufficient permissions.
Sign out of Azure DevOps by navigating to https://aka.ms/VsSignout using your browser.
Open an In private or incognito browser window and navigate to https://aex.dev.azure.com/me and sign in. In
the dropdown under the profile icon to the left, select the directory that contains the organization containing the
repository to which you wish to subscribe.
In the same browser, start a new tab, navigate to https://slack.com , and sign in to your work space (use web
client). Run the /azrepos signout command followed by the /azrepos signin command.
Select the Sign in button and you'll be redirected to a consent page like the one in the following example. Ensure
that the directory shown beside the email is same as what was chosen in the previous step. Accept and complete
the sign in process.
If these steps don't resolve your authentication issue, contact us at AzureDevOpsSlackApps@microsoft.com .
Related articles
Azure Boards with Slack
Azure Pipelines with Slack
Create a service hook for Azure DevOps with Slack
Launch Visual Studio via Azure DevOps
Azure DevOps Services

When you first open Visual Studio 2015, you can sign in and connect to Azure DevOps.
If you've already gone through Visual Studio sign-in, or you're using Visual Studio 2017, then learn how to connect
to Azure DevOps from the Team Explorer window.
After you're connected, you can store or share code in free, unlimited, private, cloud-based Git repositories or Team
Foundation Version Control. Organize and manage your work by using Agile tools for DevOps, continuous
integration, and continuous delivery so your team can build often, test early, and ship faster.
To set up Visual Studio without Azure DevOps, learn how to get started. To host your own server, learn how to
install and set up Azure DevOps Server.
Azure DevOps is free for up to five users with access to Basic features and for unlimited Visual Studio subscribers
and Stakeholders who can access limited features. Learn what else you get with Azure DevOps. If you want, you
can also use Azure DevOps with any IDE or code editor, like the following:
Eclipse, Android Studio, or IntelliJ
Xcode (see Git or TFVC )
Visual Studio Code
How do I set up Visual Studio 2015 for Azure DevOps during sign in?
1. Download and install Visual Studio, if you don't have the version you want already. Which versions can I use
with Azure DevOps?
If you have a Visual Studio subscription that includes the Visual Studio IDE, get the version that's available
with your subscription.
2. Start Visual Studio, and then sign in to create your profile.
This profile saves your settings and roams with you when you sign in to Visual Studio on any computer.
Why else should I sign in? If you're a Visual Studio subscriber, use the sign-in address for your subscription.
Can't sign in?
3. Enter your sign-in address, and then enter your password.
4. Add your Visual Studio profile details. You have to do this only once.
5. Give your organization a name, and confirm its location.
How can I create an organization later or change its location?

6. Create your first project to store your code, work items, backlog, builds, tests, and other assets. Name your
project, select a process to organize your work, and choose the version control to manage your code.
Not sure which to choose? Learn which process and version control (Git or Team Foundation Version
Control) work best for you.
7. If you're a new Visual Studio user, you can change your settings here, or change them later in Visual Studio
options.
These changes are saved with your profile, and your settings roam with you wherever you sign in.
8. To view your new organization, sign in to https://dev.azure.com/{yourorganization} .
Having browser problems?
Next steps
Add users to your organization
Related articles
Add code to Git or Team Foundation Version Control.
Create your backlog to organize your work, manage your process, or customize your process.
Learn how to migrate from Subversion (SVN) to Git,
including history
When moving to Git from another version control system like Subversion (SVN ), we generally recommend that
you perform a "tip migration", which migrates just the latest version of the repository contents, without including
history. However, many people want to perform a more advanced migration, including history. This guidance will
introduce a history with migration.
SVN migrations to Git can vary in complexity, depending on how old the repository is and how many branches
were created and merged, and whether you're using regular SVN or close relative like SVK.
It could be simple if:
You have a new repository
You have a standard setup of a trunk, branches, and tags directory
It's likely going to be complex if:
Your team has performed many branching and merging operations
Your repository follows a non-standard directory setup
Your directory setup has changed over time
There are several ways to migrate from SVN to Git. The approach outlined in this article is based on using git-svn,
a Git extension, which can be used to check out a Subversion repository to a local Git repository and then push
changes from the local Git repository back to the Subversion repository. These steps give a detailed overview of
the process for migrating from SVN to Git in a Windows environment, without synchronizing back to the original
SVN repository. The result will be a bare Git repository for sharing with the rest of your team.
NOTE
Before you try to migrate your source code from a centralized version control system to Git, be sure that you familiarize
yourself with the differences between centralized and distributed version control systems, and plan your team's migration.
After you've prepared, you can begin the migration.
The high-level workflow for migrating from SVN to Git is as follows:

Prepare a migration environment
Convert the source SVN repository to a local Git repository
(Optional) Synchronize the local Git repository with any changes from SVN repository while developers
continue using SVN
Push the local Git repository to a remote Git repository hosted on Azure Repos
Lock SVN repository, synchronize any remaining changes from SVN repository to local Git repository and
push final changes to the remote Git repository on Azure Repos
Developers switch to Git as main source control system
Prepare a migration environment

Configure a migration environment on a local workstation and install the following software:
Git
Subversion
git-svn utility (already part of Git)
You will also need to create a Git repository for your organization to host the converted SVN repository, you may
follow Create a new Git repo in your project
Convert the source SVN repository to a local Git repository

The goal of this step is to convert the source Subversion repository to a local bare Git repository. A bare Git
repository does not have a local working checkout of files that can be changed, instead it only contains the
repository's history and the metadata about the repository itself. This is the recommended format for sharing a Git
repository via a remote repository hosted on a service like Azure Repos.
TIP
Bare Git repositories are structured differently and given the fact that it doesn't have a working directory prevent direct
commit to the repository.
Retrieve a list of all Subversion authors

Subversion just uses the username for each commit, while Git stores both a real name and an email address. By
default, the git-svn tool will list the SVN username in the author and email fields. However, you can create a
mapping file for SVN users along with their corresponding Git names and emails.
Subversion users
Git users
To extract a list of all SVN users from the root of your local Subversion checkout, run this PowerShell command:
svn.exe log --quiet | ? { $_ -notlike '-*' } | % { "{0} = {0} <{0}>" -f ($_ -split ' \| ')[1] } | Select-Object
-Unique
This command will retrieve all the log messages, extract the usernames, eliminate any duplicate usernames, sort
the usernames, and place them into a "authors-transform.txt" file. You can then edit each line in the file to create a
mapping of SVN users to a well-formatted Git user. For example, you can map jamal = jamal <jamal> to
jamal = Jamal Hartnett <jamal@fabrikam-fiber.com> .
Clone the Subversion repository using git-svn

The following command will do the standard git-svn transformation using the authors-transform.txt file created in
the earlier step. It will place the Git repository in the c:\mytempdir folder in your local machine.
git svn clone ["SVN repo URL"] --prefix=svn/ --no-metadata --authors-file "authors-transform.txt" --stdlayout
c:\mytempdir
NOTE
The --prefix=svn/ is necessary because otherwise the tools can't tell SVN revisions from imported ones. We recommend
setting a prefix (with a trailing slash), as your SVN-tracking refs will then be located at refs/remotes/$prefix/ , which is
compatible with Git's own remote-tracking branch layout ( refs/remotes/$remote/ ).
Setting a prefix is also useful if you wish to track multiple projects that share a common repository. By default, the prefix is set
to origin/ .
If you are using the standard trunk, branches, tags layout you'll just put --stdlayout . However, if you have
something different you may have to pass the --trunk , --branches , and --tags to find what is what. For
example, if your repository structure was trunk/companydir and you branched that instead of trunk, you would
probably want --trunk=trunk/companydir --branches=branches .
git svn clone ["SVN repo URL"] --prefix=svn/ --no-metadata --trunk=/trunk --branches=/branches --tags=/tags --
authors-file "authors-transform.txt" c:\mytempdir
NOTE
This command can take a few minutes to several hours depending on the size of the SVN repository. Upon completion, you
will have a Git checkout of your repository.
Convert version control-specific configurations
If your SVN repo was using svn:ignore properties, you can convert to a .gitignore file using:
cd c:\mytempdir
git svn show-ignore > .gitignore
git add .gitignore
git commit -m 'Convert svn:ignore properties to .gitignore.'
TIP
Read more about .gitignore: Ignore file changes with Git
Push repository to a bare git repository

In this step, you will create a bare repository and make its default branch match SVN's trunk branch name.
1. Create a bare Git repository
git init --bare c:\new-bare.git

cd c:\new-bare.git
git symbolic-ref HEAD refs/heads/trunk
2. Push the local Git repository to the new bare Git repository
cd c:\mytempdir
git remote add bare c:\new-bare.git
git config remote.bare.push 'refs/remotes/*:refs/heads/*'
git push bare
3. Rename "trunk" branch to "master" Your main development branch will be named "trunk", which matches
the name it was in Subversion. You'll want to rename it to Git's standard "master" branch using:
cd c:\new-bare.git
git branch -m trunk master
4. Clean up branches and tags git-svn makes all of Subversions tags into very-short branches in Git of the
form "tags/name". You'll want to convert all those branches into actual Git tags or delete them.
Migrate SVN tags to be Git tags
cd c:\new-bare.git
git for-each-ref --format='%(refname)' refs/heads/tags | % { $_.Replace('refs/heads/tags/','') } | % { git tag
$_ "refs/heads/tags/$_"; git branch -D "tags/$_" }
Advanced migrations
Create all the SVN branches as proper Git branches
While it's easy to create all SVN branches as a proper Git branches, it's recommended that you evaluate the
following points before you continue:
If there are Feature branches: Can you wait until they integrate to the trunk before migrating?
If there are Release branches: Does it make sense to keep SVN around for servicing? If you migrate feature
branches, are you prepared to service branches out of Git?
If you still want to migrate existing branches, run the following PowerShell command:
git for-each-ref --format='%(refname)' refs/remotes | % { $_.Replace('refs/remotes/','') } | % { git branch

"$_" "refs/remotes/$_"; git branch -r -d "$_"; }
NOTE
This command can take a few minutes to several hours depending on the size of the SVN repository. Upon completion, you
will have a Git checkout of your repository.
Update your workflow

Moving from a centralized version control system to Git is more than just migrating code. Your team needs training
to understand how Git is different from your existing version control system and how these differences affect day-
to-day work. Learn more.
Learn Git
Ignore file changes with Git
Authors: Hosam Kamel, William H. Salazar | Find the origin of this article and connect with the ALM | DevOps
Rangers here

Azure Repos PDF

Загружено:

Сведения о документе

Исходное описание:

Оригинальное название

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

Azure Repos PDF

Загружено:

Авторское право:

Доступные форматы

Contents

Azure Repos Documentation

Azure Repos Documentation

Start using Azure Repos

Team Foundation version control (TFVC )

Connect your favorite development environment

Review code with pull requests

Create a pull request

Link work items to pull requests

Set up branch policies

Git branch and pull request workflows

Vote on the changes

Branch policies overview

How to configure branch policies

Pull request status overview

Create a PR status server with Node.js

Use Azure Functions to create custom branch policies

Configure a branch policy for an external service

Learn more about forks

Learn more about TFVC

Sign up with a personal Microsoft account

4. To get started with Azure DevOps, select Continue.

Sign up with a GitHub account

4. Select Authorize Microsoft corporation.

5. To get started with Azure DevOps, select Continue.

For more information about GitHub authentication, see FAQs.

2. Select Organization settings.

3. Select Users > Add new users.

4. Enter the following information:

5. When you're done, select Add to complete your invitation.

Install Git command-line tools

Get your code

Clone the repo

git clone https://dev.azure.com/contoso-ltd/MyFirstProject/_git/contoso-demo

git clone https://regius@dev.azure.com/regius/FabrikamFiber%20Web/_git/SmartHotel360

git branch users/jamal/feature1

git checkout master

git pull origin master:users/jamal/feature1

git pull origin master:users/jamal/feature1

Share your changes

git push origin users/jamal/feature1

Review and merge your changes with a pull request

Select Create to create the pull request.

git clone https://dev.azure.com/contoso-ltd/MyFirstProject/_git/contoso-demo

git checkout master

Try this next

Team Foundation Version Control (TFVC)

Authenticate with your repos

Manage your repos

Create a pull request

Link work items to pull requests

Set up branch policies

Squash merge pull requests

Git branch and pull request workflows

Get your code reviewed

Review code with pull requests

Link work items to pull requests

Give great feedback

Provide reviewer guidance with pull request templates

Vote on the changes

Branch policies overview

How to configure branch policies