Working with Branches

An important version control concept is branches, which are different versions of the same sets of files. Branches may be organized according to the stage of development – for instance, alpha, beta, and release – or by contributors or any other useful criteria. Especially in large projects with lots of files and users, it is more useful to work with branches as collections of files rather than with individual files, because changes to one file often affect others, and you want to be sure that your changes affect only those you intend to change.

To view a list of branches in numerical and alphabetical order, enter git branch (Figure 6).The output will include a branch called master, which is the main branch created with the repository, with an asterisk beside the branch that is currently active. To create a new branch, enter:

git branch BRANCH-NAME

Figure 6: The essential element of version control is branches: related versions of the same file.

To switch to another branch, enter

git checkout BRANCH-NAME

All your changes to files will affect only the versions of the files on the current branch. Each branch can have different versions of files with the same name. You can merge the file versions of the branch you are currently in with the file versions in another branch with:

git merge BRANCH-NAME

If there are any conflicts between the two branches, you can use git diff to view and reconcile them. When all conflicts are resolved, use

git commit -a

to commit the changes (Figure 7). The command gitk will show a graphical depiction of the merge. Any branches no longer needed can be removed with:

git branch -d BRANCH-NAME

Figure 7: After working on one branch, you can merge it with another, either to transfer changes or (as here) to check your work.

If you are working with branches of repositories that are remote from each other, use

git pull URL

to copy files from one branch to another. If conflicts result, branches are not merged until problems are resolved locally. The keeper of one repository can view useful information from the other one with:

git fetch URL master
git log -p HEAD..FETCH_HEAD

FETCH_HEAD refers to the remote head.

Using Log Information

Resolving conflicts between branches is easier with information from Git's log. The command git log shows a complete history of changes, while the addition of the -p option displays diffs, and the combo of –stat and --summary gives a convenient overview (Figure 8).

Figure 8: Git's log can be a useful guide as you work.

The log in Figure 8 identifies a commit with a 40 character name consisting of letters and numbers. Mercifully, you do not need to use the entire name, but can often use only enough of the name to identify the commit as unique or use git tag to give the commit a human-friendly name. In any of these ways, you can then use

git show COMMIT

to zero in on its details. In addition, git grep offers a strong search command, while

git log INCLUDED-BRANCH..EXCLUDED-BRANCH

restricts the branches to include in a search.

Next Steps

This overview should be enough to get you started with Git. However, there are countless additional details. Once you are comfortable with the basics, start looking up the options for Git's subcommands and gradually expand your range of choices.

Take advantage, too, of Git's exhaustive man pages. Perhaps because version control is essential to development, Git is one of the most documented commands in all of Linux. Besides the man page for the command itself, the two-part gittutorial(7) is a lengthy lesson in itself. It is supported by gitcvs-migration(7), gitcore-tutorial(7), gitglossary(7), git-help(1), gitworkflows(7), giteveryday(7), and The Git User's Manual[1] – if that is not enough, each of dozens of subcommands also has its separate man page.

One potentially puzzling aspect of this documentation is that it often classifies commands into porcelain (high-level commands about managing repositories like git branch or git checkout) and plumbing (low-level commands about working with files and branches like git apply and git merge FILES). This distinction does not affect Git's various tasks, but it can puzzle newcomers.

Aside from the porcelain/plumbing distinction, Git is complex, but its complexity is due to its size rather than structure. Once you understand the different types of tasks it is designed for, Git is not that hard to learn. And when you grasp it, you will understand one of the vital tools – if not rituals – of open source development.