Git Handbook

This handbook is aimed at all those developers who look for a quick but quite complete introduction to this powerful version control system. The version used in all the examples is 1.7.5.3.

1 Some basic definitions

Workin directory! this is commonly your pro"ect root directory# which contains all the files you are currently workin on. The content of this workin directory can chan e when you switch on another branch. $ndex! the %it index contains all the files that will o in the next commit. The index may of course differ from the workin directory &for example for cause of new chan es you don't want to put in this commit(. ) it pro"ect is identified by the it directory# the hidden directory named *. it+ in your workin directory. This contains all the necessary information.

2 Cloning or creating a repo

) new repository can be created from existin sources &or no sources( usin a simple
$ git init

in the pro"ect root directory. This repository can be copied elsewhere on your system usin
$ git clone <path to repository>

The ori inal repository can also be located in another machine. The git-clone command allows us to obtain the repository knowin the ,-.# usin !
$ git clone <repository>

which creates a new directory with a copy of what is on the server. The remote repository's ,-. can be later chan ed with
$ git remote set-url origin <URL>

3 Basic configuration.
)ll the confi uration for a pro"ect is read from the file config in the it directory. /ou can edit this file manually or via the git-config tool. The file is divided into sections formatted like this!
[section] variable1 = value1 variable! = value!

$f we want to chan e value1 into ne"value the command is!

$ git config section#variable1 ne"value

) new variable can be added with

$ git config --a$$ section#variable value

There is also a lobal confi uration file in your home directory# called #gitconfig# that refers to all the it pro"ects. $t is modified addin the 00global option to the previous lines. The first variables you'd want to chan e are name and email in the [user] section! they will appear in your commits. There's of course a lot of sections# subsections and variables to be set in the

confi uration files! a list of those is found in the git-config&1( manpa e.

4 Everyday use.
)fter you have obtained your own copy of the remote repository# you make some chan es to the files# and you want to share them with the rest of the team. The common procedure is!
$ git status

shows you which files have been modified since the last commit. $t shows also all the untracked files &that is# the files it doesn't consider part of the pro"ect( in a different section. 1ow you want to add those file to the index# ready for the commit to take them. The command is!
$ git a$$ <filename>

if the file is untracked and you wish to add it to the pro"ect# git-a$$ does it automatically for you. )ll the files added with this command are so added to the index. 2inally!
$ git commit

creates the new commit. /ou can pass a commit messa e as a strin next to the -m option# otherwise it will open your default editor &set in the lobal confi ( so that you can write one. There's a shortcut# the option -a# which simply puts into the commit all the modified files &but leaves the untracked ones alone(. 1ote that this commit only exists locally# stored in a particular ob"ect in your it directory. $f you're sharin a remote repository with the other developers# the commit must be pushed there usin !
$ git push

which by default uses the remote ,-. found in the confi uration. $n the same way# you surely will have to update your local tree from the remote repository!
$ git pull

1ote that this involves two steps! ettin the chan es from the remote server# and mer in them into the local tree. $f you tree have diver ed from the remote one and you didn't commit your chan es# the automer e procedure can fail# leavin unsolved conflicts in some files# and you will be warned about this on the command line. $n this case# before you can o on the conflicts must be solved. 3ach conflict is si ned in its file by lines lookin like this!
<<<<<< %&'( some co$e ======= some $ifferent co$e# $ git $iff

in this situation shows all these lines for you &see the 4iff section for further explanations about this tool(. )fter solvin all the conflicts# add the files to the index and then run
$ git commit

This will create a solvin commit with a enerated messa e about the mer e.

5 Patc es.
)nother way of showin your new commit to other people is creatin and sendin a patch5 this is for example useful if you don't have permissions to push the commit onto the remote repository. )fter creatin your commit as usual# run

$ git format-patch

This command creates a patch for every commit you have made that isn't present on the remote repository. The -n option creates a patch for the topmost n commits. $f you receive a patch which you want to apply to your tree# use
$ git apply <file>

may be used to determine what chan es would the patch brin if applied &runnin a sort of simulation(. %ood options in this context are! --summary ! syntetic summary of the chan es to apply --chec)! see if the patch would be applicable# detectin errors. --cache$! apply the chan es directly in the index without touchin the workin tree.
git-apply

! "etting diffs.
This command enerally *show chan es+. .et's see some examples!
$ git $iff

shows the chan es between the index and your current workin tree. 6an be used to discover in details what git-status is talkin about.
$ git $iff branch1##branch*

7hows differences between the tips of the two branches.

# $evie%ing istory.
$ git log

shows all the commits made from the ori in of the pro"ect to the current day# with author# date and messa e. The format in which the history is created can be vary accordin to many options. 8ne useful option if you want to parse the history with other tools is --pretty=oneline# which shows each commit in one line.

& Branc es' rebasing and merging.

) sin le pro"ect can contain more than one *branch+ of development. That is# at a certain point the development can diver e in two or more different lines. The default branch is called master# while other branches can be created with the command
$ git branch <branchname>

)ll branches are listed usin

$ git branch

which also shows the branch you are currently on# marked with 9. 1ote that the new branch is ori inally set as a copy of the branch you're standin on durin the creation! this is called the upstream branch. $t's however possible to create a so0called *empty branch+# a branch that has no upstream branch and no history in common with your current development. They're usually created for enerated documentation. ) branch can exist only locally &for which the above command is sufficient( but if you want the remote repository to have it too type!
$ git remote a$$ origin <branch>

2inally# if another member of the team created the branch remotely with the previous command and you want to have it locally# use
$ git pull origin <branch>

/ou can switch between branches usin

$ git chec)out <branch>

This will fail if the current branch has some chan es not still committed that would be overwritten by the files in the other branch. To solve this problem# either make the requested commit or read the stashin section below. To delete a branch# use
$ git branch -$ <branch>

This command issues an error if the newbranch isn't fully mer ed to its upstream# while -( always deletes it. 8k# now you can start developin and committin on the new branch while your team developers continue their work on the master one. )fter some commits# the history of the two branches have surely diver ed. 7o# how do you mer e them back into one development branch without messin everythin up: The situation! we have two diver in branches named master and experimental &of course the experimental's upstream branch is master(. The simplest way is to run# while on master
$ git merge e+perimental

)ny conflict will be si nalled the same way it's done durin a pull5 you solve it and then commit the result5 then the branch can be deleted# and you have a new mer e commit reflectin a *mix+ of the two development branches. ;ut if you prefer to keep the history of your pro"ect as a series of normal commits# you can choose to do a rebase instead!
$ git chec)out e+perimental $ git rebase origin

This will remove each commit from experimental &savin them in a temporary hidden directory(# apply all the diver ed commits from master# and then your commits a ain. This process# as the mer e does# can discover lots of conflicts in different files. The command will then stop warnin you about the files it couldn't automer e. )fter you solved the conflicts# run
$ git rebase --continue

to start the process a ain or

$ git rebase --abort

to stop it. )fter the rebase# you run the mer e as above and there won't be any conflict.

( $everting c anges or commits.

)t any point durin your development you can delete all the chan es you made so that the workin tree reflects the last commit# usin
$ git reset --har$ %&'(

this will delete even the chan es you already added to the index. This can be done also for a sin le file!
$ git chec)out -- <filename>

takes it back to the version currently in the index# while

$ git chec)out %&'( <filename>

to the last commit status. $f you already committed what you re ret and want to undo# there's two main ways! if the chan es already went on the remote repository# you have to create a new commit to fix them. $f the chan es are only on a local commit# there's a command that does this for you!
$ git revert %&'(

$f you want to modify the current commit without havin to create a new one
$ git commit --amen$

corrects the commit based on the current state of the index.

1) Stas ing.
7ay you are switchin branches but git-chec)out is failin because some chan es in the current branch would be overwritten# or you have to do a pull and the mer e fails because of new chan es. /ou're not ready for a commit yet# but you don't want to lose those chan es# "ust put them somewhere until you can work on them a ain. %it0stash comes in your aid in these situations. <ust run
$ git stash ,optional $escription-

/our chan es will be saved and the workin tree reverted back at the last commit status. /ou can see the list of stashes with
$ git stash list stash./01 branch ,$escription1stash./11 branch ,$escription*-

$ git stash sho" <stashname>

&where stashname is for example stash./01( shows the diff between what is recorded in the stash and the current workin tree. This command takes all the format options valid for git-$iff.
$ git stash pop <stashname>

applies the iven stash to the top of the workin tree. The workin tree must match the index. )n empty stashname by default means stash=>?@. The stash is removed from the list after pop! if you want to keep it# use apply instead of pop. )pplyin the stash can of course fail with conflicts. $n this case the stash is never removed from the list and you have to solve the conflicts manually.
$ git stash $rop <stashname>

The stash is deleted without bein applied. The same rules for stash names are valid here.
$ git stash clear

deletes all the entries in the stash list.

11 Some advanced topics

11.1 $egular e*pressions %it git+grep
git-grep

is a tool to search thorou h your entire pro"ect for some pattern. ,nlike the ,1$A rep# it rep is also able to search in previous versions on the code without havin to check them out.

$ git grep <rege+p-pattern>

is the simplest use. 7ome useful options are!

--no-in$e+! searches

also the untracked files. --ignore-case! enables a case insensitive search. --invert-match! shows non0matchin lines. --line-number! shows the line numbers too. --count! shows only the number of matchin lines.

11.2 Searc ing an entire istory.

The git-bisect tool helps in those situations where a previous commit broke down somethin in the pro"ect# but you don't know the specific commit. This tool performs a binary search to speed up the search.
$ git bisect start

starts the procedure. 1ow you need to mark the bad version &normally the current one(
$ git bisect ba$

and the last ood one you're sure about

$ git bisect goo$ v#2

this means version A is the last tested one you're sure is ood. $nstead of version numbers# you can use the commit 7B). 3very commit is identified by a unique C?0di it 7B) number! you can read it from git-log. The tool now prints somethin like!
3isecting4 2 revisions left to test after this#

)t this point you're moved into a temporary branch as the tool checks out different versions &warnin you about rou hly how many revisions are left to check(5 you test them and tell it if they're ood or bad with
$ git bisect goo$5ba$

)fter a certain number of tests &based on how the A number printed before( it will print all the information &author# messa e# etc.( about the commit which caused the error. )t any point of your search#
$ git bisect visuali6e

shows how much revisions are left to test. )t the end!

$ git bisect reset

takes you back on your normal workin branch.

11.3 Blaming people ,$ git blame <filename>

prints out all the lines in the filename preceded by the author's name and the first di its of the 7B) identifier of the commit which *caused+ that line &or *1ot committed yet+(5 iven the uniqueness of the 7B) hashes# those di its are often enou h to identify the commit.

11 Conclusion.
%it is a very powerful system for mana in a bi pro"ect5 the topics covered here are merely an introduction that will help you usin it for day0to0day work without too much problems. 8f course# each manual pa e can navi ate you throu h a much more complete knowled e of the possibilities of the tool you're oin to use. shainer Dshainer=chakra0pro"ect.or E