Secret ingredients to quality software

SSW Foursquare

Rules to Better Version Control with Git - 12 Rules

Since 1990, SSW has supported the developer community by publishing all our best practices and rules for everyone to see.

If you still need help, visit Application Lifecycle Management and book in a consultant. Rules to Better Version Control with Git

  1. Source control is the backup of your code, as well as your change history to track changes.

    With the source control, we can share project code and cooperate with other team members. Using it allows us to track changes, compare code, and even roll-back if required. Moreover, it keeps our code safe that is the most important.

    Figure: Right-click a file and select Git | View History to see the changes in source control.

    Figure: We can select different changesets and compare the changes

    Figure: We can select different changesets and compare the changes. Blue = modified, Green = addition, Red = deletion

    Figure: Right click a file and select Git | Blame (Annotate) to view the history on a segment basis

    Figure: Use annotate to understand (or find the guy) to understand his thoughts before deleting/changing someone elses code

    Figure: Annotation is great, but it gets even better when clicking the commit code gives you its full details

    Don't just fix the problem, see who caused the problem and correct them. - Adam Cogan

    Using VS Code? There are 2 awesome extensions to see history:

  2. Do you know these important git commands?

    Git Reset – Discard your local changes and revert to your last Commit

    git reset 1
    Figure: When trying to undo a change you will sometimes get errors. The answer is to exit Visual Studio and use the command line

    git reset 2
    Figure: use ‘git reset --hard HEAD’ to throw away all your uncommitted changes

    Note: A common cause of Visual Studio failing to undo changes is an incomplete .gitignore file. See for more information.

  3. Do you know the best way to manage NuGet packages with Git? You can get into all sorts of trouble by including your packages in source control.

    ** Do not check packages into Git **

    The following are a few issues that are related to having your NuGet packages in source control:

    1. Over time the packages will grow to be too many and cloning the repository will be slow.
    2. You could get duplicate NuGet packages in your packages folder as new versions are updated.
    3. NuGet shows packages to update that have already been updated. This can happen if you have duplicate NuGet packages but they are different versions.
    4. It becomes harder to "clean" your solution of any unused package folders, as you need to ensure you don't delete any package folders still in use.

    Nuget will automatically restore packages with out checking them in to source control

    Beginning with NuGet 2.7, the NuGet Visual Studio extension integrates into Visual Studio's build events and restores missing packages when a build begins. This feature is enabled by default and packages.config will be automatically included in souce control.

    Here's how it works:

    1. On project or solution build, Visual Studio raises an event that a build is beginning within the solution.
    2. NuGet responds to this event and checks for packages.config files included in the solution.
    3. For each packages.config file found, its packages are enumerated and checked for existence in the solution's packages folder.
    4. Any missing packages are downloaded from the user's configured (and enabled) package sources, respecting the order of the package sources.
    5. As packages are downloaded, they are unzipped into the solution's packages folder.

    Support in legacy versions of NuGet

    It is highly recommended that you upgrade to the latest version of NuGet to to avoid having to configure your solution to not check in NuGet pagages to source control.

    You can read more here

  4. Using the Azure DevOps API you can programmatically get a list of commits from your repository with only a HTTP request.

    devops get commits
    Figure: HTTPS GET commits from your repository

    Using HTTPS with basic authentication, make a GET request to a URL as below, substituting in your project details. A JSON object will be returned. To quickly create classes from a JSON response, see the rule Do you know how to easily get classes from a JSON response?

    8 08 2014 4 24 34 PM compressor
    Figure: Using the Chrome extension Postman to execute our request with Basic Authentication

    For a C# implementation, see this blog post Getting Git Commits with the VSO REST API.

  5. Do you know The Levels to Git Mastery?

    Like most skills, it can take a little while to get your head around Git.We rate our devs and the devs that we mentor on the following scale.

    Where are you?

    ** Level 1 - Understanding the basic principles

    At this level, you need to have an understanding of the basic operations (including branching).

    Your workflow looks like this:

    • init local repository / clone
    • pull
    • <code>
    • commit
    • push

    ** Level 2 -  Working with Git on a team

    Now that you know the basic Git commands you can start working on projects with more than one developer.

    You should be using local feature branches for your work.

    Your workflow involves:

    • pull
    • merge
    • push

    ** Level 3 - Learning to use pull requests 

    Pull requests can be used for code reviews within your team, or to accept suggested changes from people outside your team.

    Pull requests should preferably be used with policies (TFS Git only  - harder with GitHub).

    ** Level 4 -  Working with a team advanced - Rebasing (harder, but worth it) 

    When working in a team, Git does a pretty good job of merging code together from different branches... but it can be very messy. True Git masters master rebasing. It lets you keep a much cleaner project history.

    Git process for Git masters:

    • pull master
    • rebase feature branch on top of remote master
    • push feature branch to remote or create pull request
  6. Do you protect your Master Branch?

    Use the VSTS Branch Policies feature. This is a super sexy feature.

    protect branch bad
    Figure: Bad example – no protection – anyone can make unreviewed changes

    protect branch good
    Figure: Good example – the branch protected

  7. Do you know to Rebase not Merge?

    When you merge a branch you end up with messy merge commits.

    Rebasing might take a bit to get your head around, but you get a much cleaner project history.

    • it eliminates the unnecessary merge commits required by git merge
    • rebasing also results in a perfectly linear project history - you can follow the tip of feature all the way to the beginning of the project without any forks.

    This makes it easier to navigate your project with commands like git log, git bisect, and gitk.

    Figure: When merging: a messy merge commit is created any time you need to incorporate upstream changes from the master branch

    Figure: Git Rebase moves your new commits to the end of the master branch. This ensure that you don't end up with messy merge commits and you have a clean linear project history

    Warning: If you don’t follow the Golden Rule of Rebasing, you could end up in a world of pain.

  8. Do you know The Golden Rule of Rebasing?

    Rebasing is great for ensuring a clean project history... but it can be dangerous in inexperienced hands.

    The golden rule of git rebase is to never use it on public branches. (ie. never rebase master).

    You should never rebase master onto a feature branch. This would move all of the commits in master onto the tip of the feature branch (not the other way around).

    Since rebasing results in brand new commits, Git will think that your master branch’s history has diverged from everybody else’s. If you were to Push this to the server... expect lots of pain to fix it up!

    Figure: Bad Example: Rebasing master onto a feature branch can cause project history to become confused.

    Figure: To get it wrong in Visual Studio you would need to change the current branch to master and then choose rebase. While this is possible, the VS team have done a good job making it hard to do the wrong thing

    Figure: Good Example - Rebase your Feature branch onto Master

  9. Do you know that remote branches on your machines are not automatically removed in most of Git clients?

    Git pro tip

    If you use console for fetching data use this command to fetch and prune remotes/origin folder at the same time!

    git fetch -p
  10. Git has become the defacto standard for version control systems. It's distributed and decentralized and promotes working disconnected as default. It also takes away the pain of branching and merging and has a built in code review system with pull requests. Everybody should be using Git, and if you're not, you should be migrating the Git using one of the below tools.

    • - Import Repository
    • Git-Tf
    • Git-Tfs (recommended) - Import Repository gives you the ability to import from a TFVC repository into a new Git repository.

    03 29 08

    Bad Example - Built in tool has several limitations

    If you don't care about source control history, then this inbuilt tool is the easiest to use. It has the limitations of:

    • 180 days of history
    • No branches

    TIP - Use this if you don't care about source control history

    Git -Tf

    Git-Tf is an open source command line tool that works cross platform and use the Java TFS SDK. This tool is useful for migration if you're not on a Windows environment. This tool is not maintained and has issues with migrating branches.

    To see how to use this to migrate see "Migrate an existing project from TFS to Git with changeset history intact" from Chris Kirby

    TIP - Use Git-Tf if you don't have a Windows environment

    Git-Tfs is an open source command line tool that uses the .NET TFS SDK to interface between Git and TFVC. It has the following advantages over the other tools:

    • Actively maintained
    • Good support for branches
    • Author mapping
    • Migrates all history

    Follow the migration guide to import from TFVC to Git and then proceed with the after migration steps. To help you do a smoother migration, you can refer to this tool.

  11. When you create a new git repository and need to push it to VSTS you need to provide login credentials.

    It isn't always clear how to do this.

    vsts alternative login
    Figure: Bad Example - Alternate Authentication Credentials should not be used. When you change the password it invalidates all projects and can't be scoped to limit access to your Team Services data

    Instead, you should use Personal Access Token. You can do this in two ways.

    The first option is to make sure your Git for Windows is up-to-date and when cloning the repository, you use Microsoft Account to log in. Personal Access Token for Git will be created for you.

    git credentials personal access token
    Figure: Good Example - Windows for Git credential manager will automatically create Personal Access Token for Git

    Option 2 is to manually create Personal Access Token and use it as a password for Git login.

    You can follow this blog post for full instructions: Using Personal Access Tokens to access Visual Studio Online.

    git credentials personal access token manual
    Figure: Good Example - You can also manually enter Personal Access Token into password section if the credential manager doesn't work

  12. After you use the right tool to migrate from TFVC to Git, there's a few more things you need to do to clean things up for a new user joining the project. By default, if there is a TFVC repository, that will become the default in the UI.

    Unfortunately, you can't kill the TFVC repository and make Git the default one, so there's a few steps you need to follow.

    2017 04 05 10 02 58

    Figure: Bad Example - Can't delete the now deprecated TFVC repository

    Delete files from TFVC

    Go into the repository, delete any existing files. Add a new document saying "". This will stop people from getting the wrong code.

    2017 04 05 10 24 52 **Figure: Clean up TFVC so developers can't accidentally get the wrong source code

    **Note : All the source code is still there, it's just flagged as being deleted.

    Lock down TFVC

    In the TFVC repository, click Security

    2017 04 05 10 43 51 Figure: Configure the security of the TFVC repository ** Then deny check-ins to **Contributors , P roject Administrators and Project Collection Administrators . This should stop anyone from committing new code to the repository.

    Update the Dashboard

    Next step is to update the dashboard to let new developers know.

    2017 04 05 10 30 43

    Figure: Good example - Let new users know that the source control is now on Git

    Suggestions for the VSTS team

    1. Give us the ability to hide a repository
    2. Give us the ability to set a repository as the default for all users
    3. Give us the ability to delete a TFVC repository

    Having any of these suggestions will avoid the confusion on this screen

    2017 04 05 10 06 12

    Figure: Bad Exmaple - This is confusing for a new dev

We open source. Powered by GitHub