How To Use git

Overview

Git is a distributed Software Control Management (SCM) system. It is used by developers to keep revision history of a software project to ensure that chagnes to the code are properly logged and documented. The distributed aspect of git means that every developer has their own personal repository of source code; the source code is not tightly coupled with a centralized server.

Git's primary strength is its decentralization. It allows individual developers to have their own personal source branches to aid in the development process as well as make individual commits on their own system without having to push them back to the central repository. If the central repository goes down, every developer has their own version of it, and can continue working without issue.

While git does not have a concept of a "central repository", most git workflows include the concept of a Published tree, which is usually located on a server that is accessible by all developers. Each developer works on the code from their workstation, and at various intervals may push changes back to the published branch, or request that the maintainer of the published branch pull changes from them.

Since there are many copies of the git tree floating around, git employs a powerful merge system that can resolve conflicts between changes from multiple developers. Git treats all merges as a merge between two branches of code, so a push to the published branch is essentially a merge between the developer's personal branch, and the published branch. The history of both branches are merged in the published branch, so each developer may have very different commit histories that will be preserved in the published branch. This also means that a developer does not need to have a completely up-to-date version of the published branch in order to push changes back.

If you are already familiar with git, and want instructions for cloning a repository, see the document HOWTO Clone a Timesys Git Repository.

More basic information about git can be found on its official website.

If you need to be convinced of the powers of Git, see the website http://whygitisbetterthanx.com/

Typical workflow

A typical git workflow consists of multiple developers cloning the published branch, modifying it, creating individual commits on their workstation, and asking the project maintainer to pull these these commits back to published branch. If the development group is small enough, or have adequate channels of communication, it is possible for the individual developers to push the changes directly to the tree, although this can quickly become problematic as the size of the group increases. Developers can also pull changes from the published branch and merge them into their own tree to incorporate new changes into their development code.

Remember - every copy of the git repository is a separate, independent repository. It is only loosely coupled (via a remote tree reference) with the published tree, or the origin in git terminology. This is why you clone the tree, not check it out.

Setting up git on your host system

Procedure

1. Install Git on your host system
   • On Ubuntu 8.04 and 8.10, git is provided by the git-core package
     

     $ sudo apt-get install git-core

   • On Fedora, git is provided by the git package
     

     $ sudo yum install git

   • You can also get the most up-to-date version of git from http://git.or.cz/#download and build it from source.
2. Set up environment variables using git-config. This will add values to your global git config, typically located at ~/.gitconfig
   • User Name
     

     $ git config --global user.name "First Last"

   • E-mail Address
     

     $ git config --global user.email "foo@gmail.com"

   • Default text editor
     

     $ git config --global core.editor vi

   • Add syntax highlighting for diff generation and other common commands (if you like)
     

     $ git config --global color.diff auto
     $ git config --global color.status auto
     $ git config --global color.branch auto
     $ git config --global color.interactive auto
     

Cloning from the Timesys Git Repository

• HOWTO Clone a Timesys Git Repository

Quick Start Guides

The following guides will get you started in git.

Git Tutorial - Official git tutorial
Git for SVN Users - Guide for SVN users learning Git
Git for the Lazy - Straightforward, no-nonsense guide for using git.

Common Git Practices

Cloning a published tree

To get a working copy of the published git tree, you must use the git clone command. This creates a copy of the repository on your workstation, and registers the published tree as your default origin location. It will also populate the git directory with the source code from the master branch of the published tree.

$ git clone <repository location> <local repository name>

Example

In the following example, we are cloning the Kernel.org git tree and putting it in the directory linux-2.6

$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git linux-2.6

We can also clone the tree using other protocols, such as ssh. In this case, we can authenticate with a server, which may give us permission to push changes back at a later time.

$ git clone ssh://username@url/var/pub/git/gitreponame.git gitreponame

Commiting changes to your local repository

Once a tree is cloned, you can modify the source code, and commit the changes to your local repository. This is done with the git add and git commit commands. The git add command is used to specify which files are to be added to the new commit, and the git commit command is used to actually commit those changes to the repository.

$ git add <filename>
$ git commit

You can also commit all modified files using the -a flag. This will not add new files, however. Those must be manually added with git add.

$ git commit -a

Example

$ git add file.c
$ git commit

The editor of your choice (see Setting up git, above) will now open, allowing you to specify a commit message. When you finish, write out the file and quit the editor, and the commit will be added to your repository.

For style details about commits in git, see the git documentation

Pulling changes from the published tree

Use the git pull command to pull changes from the published tree. This will fetch all references from the specified repository, and merge them into your current branch. If everything merges cleanly, then git will perform a fast forward and simply add the new commits to your current history.

Tagging commits

Special commits, such as released versions, can be tagged using the git tag command. Using the -a option will allow you to annotate your tag, which is typically a prerequisite for published branches.

$ git tag -a <tag name> -m "<tag message>"

Switching to a different branch

You can switch between different branches in your working tree by using the git checkout command. The following command will check out the branch <branch name> and set the head of that branch as your current head. It will also replace the working directory with the source code from the given branch.

$ git checkout <branch name>

Creating a new branch

You can create a new branch using either the git checkout or git branch commands. Both commands are identical, except that checkout will create a new branch and switch your working tree to it, while branch will simply create the branch without modifying anything else. The following commands will create a new branch with name <new branch name> with the head at <starting point>. <starting point> can be a tagged version, a given commit, or even the head of another branch. The new branch will share the same history as the old one up until that point.

$ git checkout -b <new branch name> <starting point>

$ git branch <new branch name> <starting point>

Adding a new remote repository

If you wish to track an additional remote repository besides the origin (in the case of the kernel, you may wish to track both your corporate repository as well as the official Kernel.org tree), you can use the git remote command.

$ git remote add <local alias> <remote url>

The following example will create a remote repository called mainline that will point to the kernel.org git tree:

$ git remote add mainline git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git

This remote repository can be treated just like the origin: you can fetch references, pull from it, and possibly push information back to it, if you have the proper permission.

Applying a patch from a mailing list

If you find a patch from a mailing list, you can apply it directly to your git tree while preserving a good deal of the metadata. This is accomplished using the git am command. You can use your mail client to save the message in plain text. Once the file is in your file system, you can use the following command to apply all patches in the given directory:

$ git am <patch directory>

Each patch will be applied and committed individually, and the subject line, message body, date, and from line will be added to the commit message.

Setting a single file to a specific version

Sometimes, you may wish to revert a single file to a specific version. Perhaps you've modified it and decided to revert the changes back. In this case, you can use the git checkout command.

$ git checkout [<revision>] <path to file>

The previous command will replace your working copy of the given file to the state it was in at the given revision. If a revision isn't specified, it will choose the current head.

External Docs

Git Tutorial - Official git tutorial
Git User Guide - Official git user guide
Git Website - Official website for git
Git for SVN Users - Guide for SVN users learning Git