The Configuration File – “Branch” Section

Commands used in this section:

• git clone
• git fetch
• git merge

The “branch” Section Of The Config File

Let’s look at the config file for the git client that did the git clone git://repohost/project1.git in theGit Remotes Behind the Scenes: “Tracking Branches” and “Remote-Tracking Branches” section.

After the git clone git://repohost/project1.git command is done, the contents of the.git/config file is created, as shown below:

$ git clone git://repohost/project1.gitInitialized empty Git repository in .../project1/.git/$ cat .git/config[core]    repositoryformatversion = 0    filemode = true    bare = false    logallrefupdates = true[remote "origin"]    url = git://repohost/project1.git    fetch = +refs/heads/*:refs/remotes/origin/*[branch "master"]    remote = origin    merge = refs/heads/master

The [remote "..."] section of the git config file was described in the previous section. We will be exploring the[branch "..."] section now.

What’s The Point Of A “branch” Section?”

It’s all about less typing and convenience: If you want to type git pull and have it automatically do agit fetch followed by git merge then you came to the right place. Or you can typegit fetch without any arguments or remote repository or branch names.

You can do a git fetch and git merge without a[branch "..."] section in your .git/config file. But, if you try agit pull without a [branch "..."] section,git will give you more advice than you got from your mother after going out in the rain without shoes, socksor a jacket.

We’ll temporarily comment-out the [branch] section and see what advicegit has for us today:

$ cat .git/config[core]    repositoryformatversion = 0    filemode = true    bare = false    logallrefupdates = true[remote "origin"]    url = git://repohost/project1.git    fetch = +refs/heads/*:refs/remotes/origin/*####[branch "master"]####    remote = origin####    merge = refs/heads/master$ git pullYou asked me to pull without telling me which branch youwant to merge with, and 'branch.master.merge' inyour configuration file does not tell me, either. Pleasespecify which branch you want to use on the command line andtry again (e.g. 'git pull  ').See git-pull(1) for details.If you often merge with the same branch, you may want touse something like the following in your configuration file:    [branch "master"]    remote =     merge =     [remote ""]    url =     fetch = See git-config(1) for details.

Now that was a lot of advice. I stopped listening to the above advice starting around the “You asked me to”.

The Branch Section: Line by Line

We’ll add the [branch "..."] section back to the .git/config file and examine each line in the[branch "..."] section.

While reading through this section, remember:

• git pull does:
  1. git fetch
  2. git merge
• The [branch "..."] configuration lines determine howgit pull calls git fetch and git merge. Specifically, the[branch "..."] section determines what arguments are used to callgit fetch and git merge.

Let’s look at the branch lines from the .git/config file:

[branch "master"]

This begins the definition of the configuration for users when their current branch is themaster branch.

The rest of the lines in this [branch "master"] section are usedonly if the user’s current branch is master.

remote = origin

This line specifies the remote repository to fetch from when doing the git fetch part of the git pull (or a git fetch) typed at the command line.

Since remote = origin, the remote repository named origin will be used in thegit fetch that is called by git pull.

The origin repository referred to here must be defined in a [remote "origin"] section elsewhere in the configuration file.

merge = refs/heads/master

This line is used to configure the git merge part of the git pull: This line specifies which branch from the remote repository (not the remote-tracking branch!) will be specified whengit pull calls git merge.

When the master branch is the current branch, git pull will callgit merge with the commit referred to in the refs/heads/master branch on theorigin remote repository.

This means when you are on the master branch and type:

$ git pull

The above [branch "master"] configuration causes the git pull to run the following commands:

$ git fetch origin$ git merge [the-commit-referred-to-on-the-remote-master-branch]

“git pull” Example

For the example, let’s start with:

• A remote repository with two commits, C1 and C2
• A local remote-tracking branch named
  origin/master and a local working branch named master that are both one commit behind the remote repository.

A digram is shown below:

The [remote "origin"] and [branch "master"] sections of the.git/config file are shown here:

[remote "origin"]    url = git://repohost/project1.git    fetch = +refs/heads/*:refs/remotes/origin/*[branch "master"]    remote = origin    merge = refs/heads/master

git pull: Step 1

Using the git pull command while on the master branch causes thegit fetch command to be run. The git fetch command is run using arguments from the[remote "origin"] section:

• The url from the [remote "origin"] section: “git://repohost/project1.git“
• The fetch from the [remote "origin"] line: “+refs/heads/*:refs/remotes/origin/*“

So git pull first does:

git fetch git://repohost/project1.git +refs/heads/*:refs/remotes/origin/*

The diagram below shows how the git fetch part of the git pull command is done, when master is your current branch.

git pull: Step 2

The second step done by the git pull command is the git merge command: Themerge line in the [branch "master"] section specifies the name of the branch on theremote repository
that we want to merge from.

Note: The [branch "..."] section’s merge line refers to the branch in theremote repository refs/heads/master rather thanrefs/remotes/origin/master. This is different than calling git merge on your own, where you list the branch name in the local repository.

Above, you can see the second step of git merge caused the master branch head to move from commit C1 to C2 as the new commit: CommitC2, was merged into the user’s current master branch.

Using “git branch –set-upstream” to track existing branches

Instead of modifying .git/config, you can use git branch to add[branch "..."] sections, as discussed briefly in Adding And Removing Remote Branches.

For example, to create a new working branch called v0, and then create the new branch on the remote repository usinggit push origin v0, you can type:

$ git checkout -b v0Switch to a new branch 'v0'$ git push origin v0Total 0 (delta 0), reused 0 (delta 0)To git:///repohost/project1.git * [new branch] v0 -> v0

At this point:

• The remote repository has the new v0 branch.
• The local repository has the new v0 working branch.
• The local repository has the new origin/v0 remote-tracking
  branch (it was created during the git push origin v0)

However, your .git/config does not have a [branch "v0"] section. Consequently, when you are on the[branch "v0"] section, typing git pull will fail:

amy$ git pullYou asked me to pull without telling me which branch youwant to merge with, and 'branch.v0.merge' ...

To fix this, if you are running git 1.7.0 or later, you can type:

$ git branch --set-upstream v0 origin/v0 Branch v0 set up to track remote branch v0 from origin.

The above command adds 3 lines, shown below, to the .git/config file:

$ cat .git/config   ...[branch "v0"]        remote = origin        merge = refs/heads/v0

The .git/config file has been configured as follows:

• If the user is on the v0 branch, then a git pull willgit fetch using the url and refspec configuration from theorigin remote configuration (which is not shown here).
• The git merge will be done with the v0 branch from the remote.

With git versions earlier than 1.7.0 that don’t have the –set-upstream flag, you can use the following instead of using the abovegit branch –set-upstream v0 origin/v0 command, which isn’t as convenient and takes even more typing than simply editing the.git/config file:

$ git config branch.v0.remote origin$ git config branch.v0.merge refs/heads/v0

Using “git branch –track” to create a local branch that tracks a remote-tracking branch

In some repositories, git remote -r may show there are other remote-tracking branches that you want to work on besides themaster branch:

$ git branch -r  origin/HEAD -> origin/master  origin/test  origin/future

To set up a “tracking” branch for the origin/test branch, you can type:

$ git branch --track test origin/testBranch test set up to track remote branch test from origin.

The above command creates a new section in your .git/config file:

$ cat .git/config[branch "test"]    remote = origin    merge = refs/heads/test

Then you can type git pull while on the test branch and thegit fetch and git merge commands will be run with the correct arguments, saving you time and trouble.