Using Git

This document is only intended to provide enough information to perform the simple tasks you need to get started. There are many other good tutorials on the web, so I do not need to reproduce that information here.

Config

Before starting to use Git, you should use the git config command to tell Git your name and email address. The commands below initialize this information globally, so it will be used for all your projects. It will be saved in the file ~/.gitconfig. This information is used to identify you in the log when you make a change.

$ git config --global user.name "Your Name"

$ git config --global user.email youremail@domain

Copying a Git Source Tree

To make a copy of a source tree for the first time using Git, you use the git clone command, and pass it a URL that points to the source tree you want to copy. You can find most of the Git source trees used for developing the Linux kernel at the git.kernel.org web page or look in the MAINTAINERS file at the top of the kernel source tree.

To copy the current, official Linux kernel source code (Linus Torvalds’ Git tree), use the following command.

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

This will create a subdirectory named linux-2.6 that contains the complete copy of the source code from the server including the revision history and any other source management information maintained by Git.

Git supports many protocols that you can use with the git clone command to copy the source code, but you will probably use the git protocol (that is, git://) most of the time because is very efficient.

Updating the Source Tree

If you are using a clone of a standard tree, you will periodically want to update your tree so it has the most recent changes. The git pull command without any parameters will update your tree from the location where it was originally cloned.

$ cd linux-2.6

$ git pull

The git pull command will get and merge files from another repository into the current branch of the current source tree.

Starting a New Project

As a Linux kernel developer, you will do not need to know how to start a new project and manage it with Git, but you can use Git to manage projects other than the Linux kernel. You may find it useful to use Git to manage small source projects of your own. Since Git is fast and easy to use, using it to track changes to small, personal projects is a good way to get familiar with Git. It can be easier to understand what is happening when you try something new on a small project rather than a project as large as the Linux kernel.

You can start a new Git project with the git init command. If project is new and does not have any files yet, you can use the commands below to initialize a new, empty project directory.

$ mkdir myproj

$ cd myproj

$ git init

To use Git to manage an existing project, you can initialize the project as shown below.

$ tar –xvf myproj.tar

$ cd myproj

$ git init

$ git add .

$ git commit

Recording Changes

The files in the project directory are the working files. Git keeps all of the information it uses to manage the project and its copies of the files in the subdirectory .git at the top of the project directory. To make a change to a file, edit the file in the project directory. When you are satisfied with the changes, use the git add command. This will copy the file to a staging area, or the index as it is called in Git. Edit any other files and add them to the index too. If you make more changes to a file that you have already added to the index, you will need to add it again.

Once you are satisfied that all your changes have been made and added to the index, use the git commit command to record the changes in Git’s repository. The git commit command records all the changes in the index.

$ git add fileName

$ git commit

You can also commit a changes without first adding it to the index by using the –a option with the git commit command.

$ git commit -a fileName

Status

You can use the git status command to list the files in the index and the files in the working directory that have been modified but not added to the index. The following command shows that the README file has been changed but not added to the index, and there are no changed files in the index waiting to be committed.

$ git status

# On branch master

# Changed but not updated:

# (use "git add <file>..." to update what will be committed)

#

# modified: README

#

no changes added to commit (use "git add" and/or "git commit -a")

History

You can use the git log command to print information about the revision history. Log entries are created when a change is committed, but the git log command can provide much more interesting information than just a list of commit records.

Blah, blah, blah...

Branches

The git branch command without any parameters will list the current branches in the project. The default branch (which is created for you when the project is initialized) is named “master”. The branch with an asterisk next to its name is the branch you are currently on.

$ git branch

* master

You can also create a new branch with the git branch command.

$ git branch experimental

To change to a different branch, use the git checkout command.

$ git checkout experimental

Now you can switch back and forth between branches with a simple command (git branch branchName), and you can edit files and commit changes in whichever branch you are on. Any changes you make will not affect the other branch(es).

Merge Branches

You can create a separate branch to do development without affecting the files in the master branch, but when you are finished, you will want to merge your changes back into the main branch when you are done. You can do this by going to the master branch and using the git merge command to merge the changes from the development branch into the current branch.

$ git checkout master

$ git merge experimental

If there are no conflicts, you are done; otherwise, you can use the git diff command to see the conflicts.

$ git diff

You will need to edit the files and resolve the conflicts. Then use git add and git commit to commit the final changes.

If the experimental branch is no longer needed, you can delete the branch with the –d option to the git branch command.

$ git branch -d experimental

Example

First, create a simple project, initialize it with Git, and add three files to the project.

$ mkdir myproj

$ cd myproj

$ git init

Initialized empty Git repository in /home/bruce/myproj/.git/

The following commands create three simple files, adds them to the Git index (git add), and moves them to the Git repository (git commit).

$ echo “This is file1” >file1

$ echo “This is file2” >file2

$ echo “This is file3” >file3

$ git add .

$ git commit –m “Initial commit.”

Created initial commit 5e3615f: Initial commit

3 files changed, 3 insertions(+), 0 deletions(-)

create mode 100644 file1

create mode 100644 file2

create mode 100644 file3

At this point, the three files are in both the current directory (the working directory) and the Git repository. The Git index is empty.

$ git status

# On branch master

nothing to commit (working directory clean)

Now, create a new branch named “experimental”, so there is a place to make a change without affecting the master branch.

$ git branch experimental

The new branch is created. Switch to that branch and make a change to one of the files.

$ git checkout experimental

Switched to branch "experimental"

$ cat file1 | sed "s/This is/THIS IS/" >tmp

$ mv tmp file1

$ git add file1

$ git commit -m "Upshift message."

Created commit f48b66d: Upshift message.

1 files changed, 1 insertions(+), 1 deletions(-)

Check the file to verify it has been changed.

$ cat file1

THIS IS file1

Switch back to the master branch and make a change to the same file so that there will be a conflict when they are merged.

$ git checkout master

Switched to branch "master"

$ cat file1 | sed "s/This is/this is/" >tmp

$ mv tmp file1

$ git add file1

$ git commit -m "Downshift message."

Created commit 951fda1: Downshift message.

1 files changed, 1 insertions(+), 1 deletions(-)

Check the file to verify it has been changed.

$ cat file1

this is file1

At this point, the current branch is the master branch and file1 has been changed in both branches. Now, merge the experimental branch into the current branch.

$ git merge experimental

Auto-merged file1

CONFLICT (content): Merge conflict in file1

Automatic merge failed; fix conflicts and then commit the result.

Look at the contents of file1. You can see that the git merge command marked the conflicting line(s) so they are easy to find.

$ cat file1

<<<<<<< HEAD:file1

this is file1

=======

THIS IS file1

>>>>>>> experimental:file1

Edit the file to resolve the conflict, and then add the results to the Git index. Files that were successfully merged will have added to the Git index automatically.

$ cat file1 | grep "THIS IS" >tmp

$ mv tmp file1

$ git add file1

When you are satisfied that the merge is successful, commit the changes to the Git repository.

$ git commit -m "Merge from experimental branch."

Created commit 81851bc: Merge from experimental branch.