2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
10 <sect1 id="Git_Community_Boo"><title>Git Community Book</title>
11 <sect2 id=""><title></title>
12 <para>The open Git resource pulled together by the whole
15 </sect2><sect2 id="Author"><title>Authors</title>
17 <para>Alecs King (alecsk@gmail.com), Amos Waterland
18 (apw@rossby.metr.ou.edu), Andrew Ruder (andy@aeruder.net), Andy
19 Parkins (andyparkins@gmail.com), Arjen Laarhoven (arjen@yaph.org),
20 Brian Hetro (whee@smaertness.net), Carl Worth (cworth@cworth.org),
21 Christian Meder (chris@absolutegiganten.org), Dan McGee
22 (dpmcgee@gmail.com), David Kastrup (dak@gnu.org), Dmitry V. Levin
23 (ldv@altlinux.org), Francis Daly (francis@daoine.org), Gerrit Pape
24 (pape@smarden.org), Greg Louis (glouis@dynamicro.ca), Gustaf
25 Hendeby (hendeby@isy.liu.se), Horst H. von Brand
26 (vonbrand@inf.utfsm.cl), J. Bruce Fields (bfields@fieldses.org),
27 Jakub Narebski (jnareb@gmail.com), Jim Meyering (jim@meyering.net),
28 Johan Herland (johan@herland.net), Johannes Schindelin
29 (Johannes.Schindelin@gmx.de), Jon Loeliger (jdl@freescale.org),
30 Josh Triplett (josh@freedesktop.org), Junio C Hamano
31 (gitster@pobox.com), Linus Torvalds (torvalds@osdl.org), Lukas
32 Sandström (lukass@etek.chalmers.se), Marcus Fritzsch
33 (m@fritschy.de), Michael Coleman (tutufan@gmail.com), Michael Smith
34 (msmith@cbnco.com), Mike Coleman (tutufan@gmail.com), Miklos Vajna
35 (vmiklos@frugalware.org), Nicolas Pitre (nico@cam.org), Oliver
36 Steele (steele@osteele.com), Paolo Ciarrocchi
37 (paolo.ciarrocchi@gmail.com), Pavel Roskin (proski@gnu.org), Ralf
38 Wildenhues (Ralf.Wildenhues@gmx.de), Robin Rosenberg
39 (robin.rosenberg.lists@dewire.com), Santi Béjar
40 (sbejar@gmail.com), Scott Chacon (schacon@gmail.com), Sergei
41 Organov (osv@javad.com), Shawn Bohrer (shawn.bohrer@gmail.com),
42 Shawn O. Pearce (spearce@spearce.org), Steffen Prohaska
43 (prohaska@zib.de), Tom Prince (tom.prince@ualberta.net), William
44 Pursell (bill.pursell@gmail.com), Yasushi SHOJI
45 (yashi@atmark-techno.com)</para>
46 </sect2><sect2 id="Maintainer___Edito"><title>Maintainer /
49 <para>Scott Chacon (schacon@gmail.com)</para>
51 </sect2></sect1><sect1 id="Introductio"><title>Introduction</title>
52 <sect2 id="Welcome_to_Gi"><title>Welcome to Git</title>
53 <para>Welcome to Git - the fast, distributed version control
55 <para>This book is meant to be a starting point for people new to
56 Git to learn it as quickly and easily as possible.</para>
57 <para>This book will start out by introducing you to the way Git
58 stores data, to give you the context for why it is different than
59 other VCS tools. This is meant to take you about 20 minutes.</para>
60 <para>Next we will cover <emphasis>Basic Git Usage</emphasis> - the
61 commands you will be using 90% of the time. These should give you a
62 good basis to use Git comfortably for most of what you're going to
63 use it for. This section should take you about 30 minutes to read
65 <para>Next we will go over <emphasis>Intermediate Git
66 Usage</emphasis> - things that are slightly more complex, but may
67 replace some of the basic commands you learned in the first
68 section. This will mostly be tricks and commands that will feel
69 more comfortable after you know the basic commands.</para>
70 <para>After you have all of that mastered, we will cover
71 <emphasis>Advanced Git</emphasis> - commands that most people
72 probably don't use very often, but can be very helpful in certain
73 situations. Learning these commands should round out your
74 day-to-day git knowledge; you will be a master of the Git!</para>
75 <para>Now that you know Git, we will then cover <emphasis>Working
76 with Git</emphasis>. Here we will go over how to use Git in
77 scripts, with deployment tools, with editors and more. These
78 sections are meant to help you integrate Git into your
80 <para>Lastly, we will have a series of articles on
81 <emphasis>low-level documentation</emphasis> that may help the Git
82 hackers who want to learn how the actual internals and protocols
84 <sect3 id="Feedback_and_Contributin"><title>Feedback and
86 <para>At any point, if you see a mistake or want to contribute to
87 the book, you can send me an email at
88 <ulink url="mailto:schacon@gmail.com">schacon@gmail.com</ulink>, or
89 you can clone the source of this book at
90 <ulink url="http://github.com/schacon/gitbook">http://github.com/schacon/gitbook</ulink>
91 and send me a patch or a pull-request.</para>
92 </sect3><sect3 id="Reference"><title>References</title>
93 <para>Much of this book is pulled together from different sources
94 and then added to.If you would like to read some of the original
95 articles or resources, please visit them and thank the
98 <listitem><ulink url="http://www.kernel.org/pub/software/scm/git/docs/user-manual.html">Git
99 User Manual</ulink></listitem>
100 <listitem><ulink url="http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html">The
101 Git Tutorial</ulink></listitem>
102 <listitem><ulink url="http://www.kernel.org/pub/software/scm/git/docs/gittutorial-2.html">The
103 Git Tutorial pt 2</ulink></listitem>
104 <listitem><ulink url="http://osteele.com/archives/2008/05/my-git-workflow">"My
105 Git Workflow" blog post</ulink></listitem>
107 </sect3></sect2><sect2 id="The_Git_Object_Mode"><title>The Git
109 <sect3 id="The_SH"><title>The SHA</title>
110 <para>All the information needed to represent the history of a
111 project is stored in files referenced by a 40-digit "object name"
112 that looks something like this:</para>
114 <literal>6ff87c4664981e4397625791c8ea3bbb5f2279a3
118 <para>You will see these 40-character strings all over the place in
119 Git. In each case the name is calculated by taking the SHA1 hash of
120 the contents of the object. The SHA1 hash is a cryptographic hash
121 function. What that means to us is that it is virtually impossible
122 to find two different objects with the same name. This has a number
123 of advantages; among others:</para>
125 <listitem>Git can quickly determine whether two objects are
126 identical or not, just by comparing names.</listitem>
127 <listitem>Since object names are computed the same way in every
128 repository, the same content stored in two repositories will always
129 be stored under the same name.</listitem>
130 <listitem>Git can detect errors when it reads an object, by
131 checking that the object's name is still the SHA1 hash of its
134 </sect3><sect3 id="The_Object"><title>The Objects</title>
135 <para>Every object consists of three things - a
136 <emphasis>type</emphasis>, a <emphasis>size</emphasis> and
137 <emphasis>content</emphasis>. The <emphasis>size</emphasis> is
138 simply the size of the contents, the contents depend on what type
139 of object it is, and there are four different types of objects:
140 "blob", "tree", "commit", and "tag".</para>
142 <listitem>A <para><emphasis>"blob"</emphasis></para> is used to
143 store file data - it is generally a file.</listitem>
144 <listitem>A <para><emphasis>"tree"</emphasis></para> is basically
145 like a directory - it references a bunch of other trees and/or
146 blobs (i.e. files and sub-directories)</listitem>
147 <listitem>A <para><emphasis>"commit"</emphasis></para> points to a
148 single tree, marking it as what the project looked like at a
149 certain point in time. It contains meta-information about that
150 point in time, such as a timestamp, the author of the changes since
151 the last commit, a pointer to the previous commit(s),
153 <listitem>A <para><emphasis>"tag"</emphasis></para> is a way to
154 mark a specific commit as special in some way. It is normally used
155 to tag certain commits as specific releases or something along
156 those lines.</listitem>
158 <para>Almost all of Git is built around manipulating this simple
159 structure of four different object types. It is sort of its own
160 little filesystem that sits on top of your machine's
162 </sect3><sect3 id="Different_from_SV"><title>Different from
164 <para>It is important to note that this is very different from most
165 SCM systems that you may be familiar with. Subversion, CVS,
166 Perforce, Mercurial and the like all use <emphasis>Delta
167 Storage</emphasis> systems - they store the differences between one
168 commit and the next. Git does not do this - it stores a snapshot of
169 what all the files in your project look like in this tree structure
170 each time you commit. This is a very important concept to
171 understand when using Git.</para>
172 </sect3><sect3 id="Blob_Objec"><title>Blob Object</title>
173 <para>A blob generally stores the contents of a file.</para>
174 <inlinemediaobject><imageobject>
175 <imagedata fileref="images/object-blob.png"/>
176 </imageobject></inlinemediaobject>
180 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-show.html">git
181 show</ulink> to examine the contents of any blob. Assuming we have
182 the SHA for a blob, we can examine its contents like this:</para>
184 <literal>$ git show 6ff87c4664
186 Note that the only valid version of the GPL as far as this project
187 is concerned is _this_ particular version of the license (ie v2, not
188 v2.2 or v3.x or whatever), unless explicitly otherwise stated.
193 <para>A "blob" object is nothing but a chunk of binary data. It
194 doesn't refer to anything else or have attributes of any kind, not
195 even a file name.</para>
196 <para>Since the blob is entirely defined by its data, if two files
197 in a directory tree (or in multiple different versions of the
198 repository) have the same contents, they will share the same blob
199 object. The object is totally independent of its location in the
200 directory tree, and renaming a file does not change the object that
201 file is associated with.</para>
202 </sect3><sect3 id="Tree_Objec"><title>Tree Object</title>
203 <para>A tree is a simple object that has a bunch of pointers to
204 blobs and other trees - it generally represents the contents of a
205 directory or subdirectory.</para>
206 <inlinemediaobject><imageobject>
207 <imagedata fileref="images/object-tree.png"/>
208 </imageobject></inlinemediaobject>
211 <para>The ever-versatile
212 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-show.html">git
213 show</ulink> command can also be used to examine tree objects, but
214 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-ls-tree.html">git
215 ls-tree</ulink> will give you more details. Assuming we have the
216 SHA for a tree, we can examine it like this:</para>
218 <literal>$ git ls-tree fb3a8bdd0ce
219 100644 blob 63c918c667fa005ff12ad89437f2fdc80926e21c .gitignore
220 100644 blob 5529b198e8d14decbe4ad99db3f7fb632de0439d .mailmap
221 100644 blob 6ff87c4664981e4397625791c8ea3bbb5f2279a3 COPYING
222 040000 tree 2fb783e477100ce076f6bf57e4a6f026013dc745 Documentation
223 100755 blob 3c0032cec592a765692234f1cba47dfdcc3a9200 GIT-VERSION-GEN
224 100644 blob 289b046a443c0647624607d471289b2c7dcd470b INSTALL
225 100644 blob 4eb463797adc693dc168b926b6932ff53f17d0b1 Makefile
226 100644 blob 548142c327a6790ff8821d67c2ee1eff7a656b52 README
231 <para>As you can see, a tree object contains a list of entries,
232 each with a mode, object type, SHA1 name, and name, sorted by name.
233 It represents the contents of a single directory tree.</para>
234 <para>An object referenced by a tree may be blob, representing the
235 contents of a file, or another tree, representing the contents of a
236 subdirectory. Since trees and blobs, like all other objects, are
237 named by the SHA1 hash of their contents, two trees have the same
238 SHA1 name if and only if their contents (including, recursively,
239 the contents of all subdirectories) are identical. This allows git
240 to quickly determine the differences between two related tree
241 objects, since it can ignore any entries with identical object
243 <para>(Note: in the presence of submodules, trees may also have
244 commits as entries. See the <emphasis>Submodules</emphasis>
246 <para>Note that the files all have mode 644 or 755: git actually
247 only pays attention to the executable bit.</para>
248 </sect3><sect3 id="Commit_Objec"><title>Commit Object</title>
249 <para>The "commit" object links a physical state of a tree with a
250 description of how we got there and why.</para>
251 <inlinemediaobject><imageobject>
252 <imagedata fileref="images/object-commit.png"/>
253 </imageobject></inlinemediaobject>
256 <para>You can use the --pretty=raw option to
257 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-show.html">git
259 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-log.html">git
260 log</ulink> to examine your favorite commit:</para>
262 <literal>$ git show -s --pretty=raw 2be7fcb476
263 commit 2be7fcb4764f2dbcee52635b91fedb1b3dcf7ab4
264 tree fb3a8bdd0ceddd019615af4d57a53f43d8cee2bf
265 parent 257a84d9d02e90447b149af58b271c19405edb6a
266 author Dave Watson <dwatson@mimvista.com> 1187576872 -0400
267 committer Junio C Hamano <gitster@pobox.com> 1187591163 -0700
269 Fix misspelling of 'suppress' in docs
271 Signed-off-by: Junio C Hamano <gitster@pobox.com>
275 <para>As you can see, a commit is defined by:</para>
277 <listitem>a <para><emphasis>tree</emphasis></para>: The SHA1 name
278 of a tree object (as defined below), representing the contents of a
279 directory at a certain point in time.</listitem>
280 <listitem><para><emphasis>parent(s)</emphasis></para>: The SHA1
281 name of some number of commits which represent the immediately
282 previous step(s) in the history of the project. The example above
283 has one parent; merge commits may have more than one. A commit with
284 no parents is called a "root" commit, and represents the initial
285 revision of a project. Each project must have at least one root. A
286 project can also have multiple roots, though that isn't common (or
287 necessarily a good idea).</listitem>
288 <listitem>an <para><emphasis>author</emphasis></para>: The name of
289 the person responsible for this change, together with its
291 <listitem>a <para><emphasis>committer</emphasis></para>: The name
292 of the person who actually created the commit, with the date it was
293 done. This may be different from the author; for example, if the
294 author wrote a patch and emailed it to another person who used the
295 patch to create the commit.</listitem>
296 <listitem>a <para><emphasis>comment</emphasis></para> describing
297 this commit.</listitem>
299 <para>Note that a commit does not itself contain any information
300 about what actually changed; all changes are calculated by
301 comparing the contents of the tree referred to by this commit with
302 the trees associated with its parents. In particular, git does not
303 attempt to record file renames explicitly, though it can identify
304 cases where the existence of the same file data at changing paths
305 suggests a rename. (See, for example, the -M option to
306 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-diff.html">git
307 diff</ulink>).</para>
308 <para>A commit is usually created by
309 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-commit.html">git
310 commit</ulink>, which creates a commit whose parent is normally the
311 current HEAD, and whose tree is taken from the content currently
312 stored in the index.</para>
313 </sect3><sect3 id="The_Object_Mode"><title>The Object Model</title>
314 <para>So, now that we've looked at the 3 main object types (blob,
315 tree and commit), let's take a quick look at how they all fit
317 <para>If we had a simple project with the following directory
328 2 directories, 3 files
332 <para>And we committed this to a Git repository, it would be
333 represented like this:</para>
334 <inlinemediaobject><imageobject>
335 <imagedata fileref="images/objects-example.png"/>
336 </imageobject></inlinemediaobject>
339 <para>You can see that we have created a <emphasis>tree</emphasis>
340 object for each directory (including the root) and a
341 <emphasis>blob</emphasis> object for each file. Then we have a
342 <emphasis>commit</emphasis> object to point to the root, so we can
343 track what our project looked like when it was committed.</para>
344 </sect3><sect3 id="Tag_Objec"><title>Tag Object</title>
345 <inlinemediaobject><imageobject>
346 <imagedata fileref="images/object-tag.png"/>
347 </imageobject></inlinemediaobject>
350 <para>A tag object contains an object name (called simply
351 'object'), object type, tag name, the name of the person ("tagger")
352 who created the tag, and a message, which may contain a signature,
354 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-cat-file.html">git
355 cat-file</ulink>:</para>
357 <literal>$ git cat-file tag v1.5.0
358 object 437b1b20df4b356c9342dac8d38849f24ef44f27
361 tagger Junio C Hamano <junkio@cox.net> 1171411200 +0000
364 -----BEGIN PGP SIGNATURE-----
365 Version: GnuPG v1.4.6 (GNU/Linux)
367 iD8DBQBF0lGqwMbZpPMRm5oRAuRiAJ9ohBLd7s2kqjkKlq1qqC57SbnmzQCdG4ui
368 nLE/L9aUXdWeTFPron96DLA=
370 -----END PGP SIGNATURE-----
375 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-tag.html">git
376 tag</ulink> command to learn how to create and verify tag objects.
378 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-tag.html">git
379 tag</ulink> can also be used to create "lightweight tags", which
380 are not tag objects at all, but just simple references whose names
381 begin with "refs/tags/").</para>
382 </sect3></sect2><sect2 id="Git_Directory_and_Working_Director"><title>Git
383 Directory and Working Directory</title>
384 <sect3 id="The_Git_Director"><title>The Git Directory</title>
385 <para>The 'git directory' is the directory that stores all Git's
386 history and meta information for your project - including all of
387 the objects (commits, trees, blobs, tags), all of the pointers to
388 where different branches are and more.</para>
389 <para>There is only one Git Directory per project (as opposed to
390 one per subdirectory like with SVN or CVS), and that directory is
391 (by default, though not necessarily) '.git' in the root of your
392 project. If you look at the contents of that directory, you can see
393 all of your important files:</para>
395 <literal>$>tree -L 1
397 |-- HEAD # pointer to your current branch
398 |-- config # your configuration preferences
399 |-- description # description of your project
400 |-- hooks/ # pre/post action hooks
401 |-- index # index file (see next section)
402 |-- logs/ # a history of where your branches have been
403 |-- objects/ # your objects (commits, trees, blobs, tags)
404 `-- refs/ # pointers to your branches
408 <para>(there may be some other files/directories in there as well,
409 but they are not important for now)</para>
410 </sect3><sect3 id="The_Working_Director"><title>The Working
412 <para>The Git 'working directory' is the directory that holds the
413 current checkout of the files you are working on. Files in this
414 directory are often removed or replaced by Git as you switch
415 branches - this is normal. All your history is stored in the Git
416 Directory; the working directory is simply a temporary checkout
417 place where you can modify the files until your next commit.</para>
418 </sect3></sect2><sect2 id="The_Git_Inde"><title>The Git
420 <para>The Git index is used as a staging area between your working
421 directory and your repository. You can use the index to build up a
422 set of changes that you want to commit together. When you create a
423 commit, what is committed is what is currently in the index, not
424 what is in your working directory.</para>
425 <sect3 id="Looking_at_the_Inde"><title>Looking at the Index</title>
426 <para>The easiest way to see what is in the index is with the
427 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-status.html">git
428 status</ulink> command. When you run git status, you can see which
429 files are staged (currently in your index), which are modified but
430 not yet staged, and which are completely untracked.</para>
432 <literal>$>git status
434 # Your branch is behind 'origin/master' by 11 commits, and can be fast-forwarded.
436 # Changes to be committed:
437 # (use "git reset HEAD <file>..." to unstage)
441 # Changed but not updated:
442 # (use "git add <file>..." to update what will be committed)
448 # (use "git add <file>..." to include in what will be committed)
456 <para>If you blow the index away entirely, you generally haven't
457 lost any information as long as you have the name of the tree that
459 <para>And with that, you should have a pretty good understanding of
460 the basics of what Git is doing behind the scenes, and why it is a
461 bit different than most other SCM systems. Don't worry if you don't
462 totally understand it all right now; we'll revisit all of these
463 topics in the next sections. Now we're ready to move on to
464 installing, configuring and using Git.</para>
465 </sect3></sect2></sect1><sect1 id="First_Tim"><title>First
467 <sect2 id="Installing_Gi"><title>Installing Git</title>
468 <sect3 id="Installing_from_Sourc"><title>Installing from
470 <para>In short, on a Unix-based system, you can download the Git
471 source code from the <ulink url="http://git-scm.com/download">Git
472 Download Page</ulink>, and then run something along the lines of
475 <literal>$ make prefix=/usr all ;# as yourself
476 $ make prefix=/usr install ;# as root
480 <para>You will need the
481 <ulink url="http://expat.sourceforge.net/">expat</ulink>,
482 <ulink url="http://curl.linux-mirror.org">curl</ulink>,
483 <ulink url="http://www.zlib.net">zlib</ulink>, and
484 <ulink url="http://www.openssl.org">openssl</ulink> libraries
485 installed - though with the possible exception of
486 <emphasis>expat</emphasis>, these will normally already be
488 </sect3><sect3 id="Linu"><title>Linux</title>
489 <para>If you are running Linux, you can likely install Git easily
490 via your native package management system:</para>
492 <literal>$ yum install git-core
494 $ apt-get install git-core
498 <para>If that doesn't work, you can download the .deb or .rpm
499 packages from here:</para>
500 <para><ulink url="http://kernel.org/pub/software/scm/git/RPMS/">RPM
501 Packages</ulink></para>
502 <para><ulink url="http://www.backports.org/debian/pool/main/g/git-core/">Stable
504 <para>If you prefer to install from source on a Linux system, this
505 article may be helpful:</para>
506 <para><ulink url="http://chrisolsen.org/2008/03/10/installing-git-on-ubuntu/">Article:
507 Installing Git on Ubuntu</ulink></para>
508 </sect3><sect3 id="Mac_10."><title>Mac 10.4</title>
509 <para>In both Mac 10.4 and 10.5, you can install Git via
510 <ulink url="http://www.macports.org/">MacPorts</ulink>, if you have
511 that installed. If not, you can install it from
512 <ulink url="http://www.macports.org/install.php">here</ulink>.</para>
513 <para>Once MacPorts is installed, all you should have to do
516 <literal>$ sudo port install git-core
520 <para>If you prefer to install from source, these articles may be
522 <para><ulink url="http://rails.wincent.com/wiki/Installing_Git_1.5.2.3_on_Mac_OS_X_Tiger">Article:
523 Installing Git on Tiger</ulink></para>
524 <para><ulink url="http://larrytheliquid.com/2007/12/29/compiling-git-and-git-svn-on-osx-tiger/">Article:
525 Installing Git and git-svn on Tiger from source</ulink></para>
526 </sect3><sect3 id="Mac_10."><title>Mac 10.5</title>
527 <para>With Leopard, you can also install via MacPorts, but here you
528 have the additional option of using a nice installer, which you can
530 <ulink url="http://code.google.com/p/git-osx-installer/downloads/list?can=3">Git
531 OSX Installer</ulink></para>
532 <para>If you prefer to install it from source, these guides may be
533 particularly helpful to you :</para>
534 <para><ulink url="http://solutions.treypiepmeier.com/2008/02/25/installing-git-on-os-x-leopard/">Article:
535 Installing Git on OSX Leopard</ulink></para>
536 <para><ulink url="http://dysinger.net/2007/12/30/installing-git-on-mac-os-x-105-leopard/">Article:
537 Installing Git on OS 10.5</ulink></para>
538 </sect3><sect3 id="Window"><title>Windows</title>
539 <para>On Windows, installing Git is pretty easy. Simply download
541 <ulink url="http://code.google.com/p/msysgit/downloads/list">msysGit</ulink>
543 <para>See the <emphasis>Git on Windows</emphasis> chapter for a
544 screencast demonstrating installing and using Git on
546 </sect3></sect2><sect2 id="Setup_and_Initializatio"><title>Setup
547 and Initialization</title>
548 <sect3 id="Git_Confi"><title>Git Config</title>
549 <para>The first thing you're going to want to do is set up your
550 name and email address for Git to use to sign your commits.</para>
552 <literal>$ git config --global user.name "Scott Chacon"
553 $ git config --global user.email "schacon@gmail.com"
557 <para>That will set up a file in your home directory which may be
558 used by any of your projects. By default that file is
559 <emphasis>~/.gitconfig</emphasis> and the contents will look like
564 email = schacon@gmail.com
568 <para>If you want to override those values for a specific project
569 (to use a work email address, for example), you can run the
570 <emphasis>git config</emphasis> command without the
571 <emphasis>--global</emphasis> option while in that project. This
572 will add a [user] section like the one shown above to the
573 <emphasis>.git/config</emphasis> file in your project's root
575 </sect3></sect2></sect1><sect1 id="Basic_Usag"><title>Basic
577 <sect2 id="Getting_a_Git_Repositor"><title>Getting a Git
579 <para>So now that we're all set up, we need a Git repository. We
580 can do this one of two ways - we can <emphasis>clone</emphasis> one
581 that already exists, or we can <emphasis>initialize</emphasis> one
582 either from existing files that aren't in source control yet, or
583 from an empty directory.</para>
584 <sect3 id="Cloning_a_Repositor"><title>Cloning a Repository</title>
585 <para>In order to get a copy of a project, you will need to know
586 the project's Git URL - the location of the repository. Git can
587 operate over many different protocols, so it may begin with ssh://,
588 http(s)://, git://, or just a username (in which case git will
589 assume ssh). Some repositories may be accessed over more than one
590 protocol. For example, the source code to Git itself can be cloned
591 either over the git:// protocol:</para>
593 <literal>git clone git://git.kernel.org/pub/scm/git/git.git
597 <para>or over http:</para>
599 <literal>git clone http://www.kernel.org/pub/scm/git/git.git
603 <para>The git:// protocol is faster and more efficient, but
604 sometimes it is necessary to use http when behind corporate
605 firewalls or what have you. In either case you should then have a
606 new directory named 'git' that contains all the Git source code and
607 history - it is basically a complete copy of what was on the
609 <para>By default, Git will name the new directory it has checked
610 out your cloned code into after whatever comes directly before the
611 '.git' in the path of the cloned project. (ie. <emphasis>git clone
612 http://git.kernel.org/linux/kernel/git/torvalds/linux-2.6.git</emphasis>
613 will result in a new directory named 'linux-2.6')</para>
614 </sect3><sect3 id="Initializing_a_New_Repositor"><title>Initializing
615 a New Repository</title>
616 <para>Assume you have a tarball named project.tar.gz with your
617 initial work. You can place it under git revision control as
620 <literal>$ tar xzf project.tar.gz
626 <para>Git will reply</para>
628 <literal>Initialized empty Git repository in .git/
632 <para>You've now initialized the working directory--you may notice
633 a new directory created, named ".git".</para>
634 </sect3></sect2><sect2 id="Normal_Workflo"><title>Normal
636 <para>Modify some files, then add their updated contents to the
639 <literal>$ git add file1 file2 file3
643 <para>You are now ready to commit. You can see what is about to be
645 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-diff.html">git
646 diff</ulink> with the --cached option:</para>
648 <literal>$ git diff --cached
652 <para>(Without --cached,
653 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-diff.html">git
654 diff</ulink> will show you any changes that you've made but not yet
655 added to the index.) You can also get a brief summary of the
657 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-status.html">git
658 status</ulink>:</para>
660 <literal>$ git status
662 # Changes to be committed:
663 # (use "git reset HEAD <file>..." to unstage)
672 <para>If you need to make any further adjustments, do so now, and
673 then add any newly modified content to the index. Finally, commit
674 your changes with:</para>
676 <literal>$ git commit
680 <para>This will again prompt you for a message describing the
681 change, and then record a new version of the project.</para>
682 <para>Alternatively, instead of running <literal>git add</literal>
683 beforehand, you can use</para>
685 <literal>$ git commit -a
689 <para>which will automatically notice any modified (but not new)
690 files, add them to the index, and commit, all in one step.</para>
691 <para>A note on commit messages: Though not required, it's a good
692 idea to begin the commit message with a single short (less than 50
693 character) line summarizing the change, followed by a blank line
694 and then a more thorough description. Tools that turn commits into
695 email, for example, use the first line on the Subject: line and the
696 rest of the commit message in the body.</para>
697 <sect4 id="Git_tracks_content_not_file"><title>Git tracks content
699 <para>Many revision control systems provide an "add" command that
700 tells the system to start tracking changes to a new file. Git's
701 "add" command does something simpler and more powerful:
702 <literal>git add</literal> is used both for new and newly modified
703 files, and in both cases it takes a snapshot of the given files and
704 stages that content in the index, ready for inclusion in the next
706 </sect4></sect2><sect2 id="Basic_Branching_and_Mergin"><title>Basic
707 Branching and Merging</title>
708 <para>A single git repository can maintain multiple branches of
709 development. To create a new branch named "experimental",
712 <literal>$ git branch experimental
716 <para>If you now run</para>
718 <literal>$ git branch
722 <para>you'll get a list of all existing branches:</para>
724 <literal> experimental
729 <para>The "experimental" branch is the one you just created, and
730 the "master" branch is a default branch that was created for you
731 automatically. The asterisk marks the branch you are currently on;
734 <literal>$ git checkout experimental
738 <para>to switch to the experimental branch. Now edit a file, commit
739 the change, and switch back to the master branch:</para>
743 $ git checkout master
747 <para>Check that the change you made is no longer visible, since it
748 was made on the experimental branch and you're back on the master
750 <para>You can make a different change on the master branch:</para>
757 <para>at this point the two branches have diverged, with different
758 changes made in each. To merge the changes made in experimental
759 into master, run</para>
761 <literal>$ git merge experimental
765 <para>If the changes don't conflict, you're done. If there are
766 conflicts, markers will be left in the problematic files showing
773 <para>will show this. Once you've edited the files to resolve the
776 <literal>$ git commit -a
780 <para>will commit the result of the merge. Finally,</para>
786 <para>will show a nice graphical representation of the resulting
788 <para>At this point you could delete the experimental branch
791 <literal>$ git branch -d experimental
795 <para>This command ensures that the changes in the experimental
796 branch are already in the current branch.</para>
797 <para>If you develop on a branch crazy-idea, then regret it, you
798 can always delete the branch with</para>
800 <literal>$ git branch -D crazy-idea
804 <para>Branches are cheap and easy, so this is a good way to try
805 something out.</para>
806 <sect3 id="How_to_merg"><title>How to merge</title>
807 <para>You can rejoin two diverging branches of development using
808 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-merge.html">git
809 merge</ulink>:</para>
811 <literal>$ git merge branchname
815 <para>merges the changes made in the branch "branchname" into the
816 current branch. If there are conflicts--for example, if the same
817 file is modified in two different ways in the remote branch and the
818 local branch--then you are warned; the output may look something
821 <literal>$ git merge next
824 CONFLICT (content): Merge conflict in file.txt
825 Automatic merge failed; fix conflicts and then commit the result.
829 <para>Conflict markers are left in the problematic files, and after
830 you resolve the conflicts manually, you can update the index with
831 the contents and run git commit, as you normally would when
832 modifying a file.</para>
833 <para>If you examine the resulting commit using gitk, you will see
834 that it has two parents: one pointing to the top of the current
835 branch, and one to the top of the other branch.</para>
836 </sect3><sect3 id="Resolving_a_merg"><title>Resolving a
838 <para>When a merge isn't resolved automatically, git leaves the
839 index and the working tree in a special state that gives you all
840 the information you need to help resolve the merge.</para>
841 <para>Files with conflicts are marked specially in the index, so
842 until you resolve the problem and update the index,
843 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-commit.html">git
844 commit</ulink> will fail:</para>
846 <literal>$ git commit
847 file.txt: needs merge
852 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-status.html">git
853 status</ulink> will list those files as "unmerged", and the files
854 with conflicts will have conflict markers added, like this:</para>
856 <literal><<<<<<< HEAD:file.txt
860 >>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
864 <para>All you need to do is edit the files to resolve the
865 conflicts, and then</para>
867 <literal>$ git add file.txt
872 <para>Note that the commit message will already be filled in for
873 you with some information about the merge. Normally you can just
874 use this default message unchanged, but you may add additional
875 commentary of your own if desired.</para>
876 <para>The above is all you need to know to resolve a simple merge.
877 But git also provides more information to help resolve
879 </sect3><sect3 id="Undoing_a_merg"><title>Undoing a merge</title>
880 <para>If you get stuck and decide to just give up and throw the
881 whole mess away, you can always return to the pre-merge state
884 <literal>$ git reset --hard HEAD
888 <para>Or, if you've already committed the merge that you want to
891 <literal>$ git reset --hard ORIG_HEAD
895 <para>However, this last command can be dangerous in some
896 cases--never throw away a commit if that commit may itself have
897 been merged into another branch, as doing so may confuse further
899 </sect3><sect3 id="Fast-forward_merge"><title>Fast-forward
901 <para>There is one special case not mentioned above, which is
902 treated differently. Normally, a merge results in a merge commit
903 with two parents, one for each of the two lines of development that
905 <para>However, if the current branch has not diverged from the
906 other--so every commit present in the current branch is already
907 contained in the other--then git just performs a "fast forward";
908 the head of the current branch is moved forward to point at the
909 head of the merged-in branch, without any new commits being
911 </sect3></sect2><sect2 id="Reviewing_History_-_Git_Lo"><title>Reviewing
912 History - Git Log</title>
914 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-log.html">git
915 log</ulink> command can show lists of commits. On its own, it shows
916 all commits reachable from the parent commit; but you can also make
917 more specific requests:</para>
919 <literal>$ git log v2.5.. # commits since (not reachable from) v2.5
920 $ git log test..master # commits reachable from master but not test
921 $ git log master..test # commits reachable from test but not master
922 $ git log master...test # commits reachable from either test or
923 # master, but not both
924 $ git log --since="2 weeks ago" # commits from the last 2 weeks
925 $ git log Makefile # commits that modify Makefile
926 $ git log fs/ # commits that modify any file under fs/
927 $ git log -S'foo()' # commits that add or remove any file data
928 # matching the string 'foo()'
929 $ git log --no-merges # dont show merge commits
933 <para>And of course you can combine all of these; the following
934 finds commits since v2.5 which touch the Makefile or any file under
937 <literal>$ git log v2.5.. Makefile fs/
941 <para>Git log will show a listing of each commit, with the most
942 recent commits first, that match the arguments given to the log
945 <literal>commit f491239170cb1463c7c3cd970862d6de636ba787
946 Author: Matt McCutchen <matt@mattmccutchen.net>
947 Date: Thu Aug 14 13:37:41 2008 -0400
949 git format-patch documentation: clarify what --cover-letter does
951 commit 7950659dc9ef7f2b50b18010622299c508bfdfc3
952 Author: Eric Raible <raible@gmail.com>
953 Date: Thu Aug 14 10:12:54 2008 -0700
955 bash completion: 'git apply' should use 'fix' not 'strip'
956 Bring completion up to date with the man page.
960 <para>You can also ask git log to show patches:</para>
962 <literal>$ git log -p
964 commit da9973c6f9600d90e64aac647f3ed22dfd692f70
965 Author: Robert Schiele <rschiele@gmail.com>
966 Date: Mon Aug 18 16:17:04 2008 +0200
968 adapt git-cvsserver manpage to dash-free syntax
970 diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt
971 index c2d3c90..785779e 100644
972 --- a/Documentation/git-cvsserver.txt
973 +++ b/Documentation/git-cvsserver.txt
974 @@ -11,7 +11,7 @@ SYNOPSIS
978 -export CVS_SERVER=git-cvsserver
979 +export CVS_SERVER="git cvsserver"
980 'cvs' -d :ext:user@server/path/repo.git co <HEAD_name>
982 pserver (/etc/inetd.conf):
986 <sect3 id="Log_Stat"><title>Log Stats</title>
987 <para>If you pass the <literal>--stat</literal> option to 'git
988 log', it will show you which files have changed in that commit and
989 how many lines were added and removed from each.</para>
991 <literal>$ git log --stat
993 commit dba9194a49452b5f093b96872e19c91b50e526aa
994 Author: Junio C Hamano <gitster@pobox.com>
995 Date: Sun Aug 17 15:44:11 2008 -0700
997 Start 1.6.0.X maintenance series
999 Documentation/RelNotes-1.6.0.1.txt | 15 +++++++++++++++
1001 2 files changed, 16 insertions(+), 1 deletions(-)
1005 </sect3><sect3 id="Formatting_the_Lo"><title>Formatting the
1007 <para>You can also format the log output almost however you want.
1008 The '--pretty' option can take a number of preset formats, such as
1011 <literal>$ git log --pretty=oneline
1012 a6b444f570558a5f31ab508dc2a24dc34773825f dammit, this is the second time this has reverted
1013 49d77f72783e4e9f12d1bbcacc45e7a15c800240 modified index to create refs/heads if it is not
1014 9764edd90cf9a423c9698a2f1e814f16f0111238 Add diff-lcs dependency
1015 e1ba1e3ca83d53a2f16b39c453fad33380f8d1cc Add dependency for Open4
1016 0f87b4d9020fff756c18323106b3fd4e2f422135 merged recent changes: * accepts relative alt pat
1017 f0ce7d5979dfb0f415799d086e14a8d2f9653300 updated the Manifest file
1021 <para>or you can do 'short' format:</para>
1023 <literal>$ git log --pretty=short
1024 commit a6b444f570558a5f31ab508dc2a24dc34773825f
1025 Author: Scott Chacon <schacon@gmail.com>
1027 dammit, this is the second time this has reverted
1029 commit 49d77f72783e4e9f12d1bbcacc45e7a15c800240
1030 Author: Scott Chacon <schacon@gmail.com>
1032 modified index to create refs/heads if it is not there
1034 commit 9764edd90cf9a423c9698a2f1e814f16f0111238
1035 Author: Hans Engel <engel@engel.uk.to>
1037 Add diff-lcs dependency
1041 <para>You can also use 'medium', 'full', 'fuller', 'email' or
1042 'raw'. If those formats aren't exactly what you need, you can also
1043 create your own format with the '--pretty=format' option (see the
1044 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-log.html">git
1045 log</ulink> docs for all the formatting options).</para>
1047 <literal>$ git log --pretty=format:'%h was %an, %ar, message: %s'
1048 a6b444f was Scott Chacon, 5 days ago, message: dammit, this is the second time this has re
1049 49d77f7 was Scott Chacon, 8 days ago, message: modified index to create refs/heads if it i
1050 9764edd was Hans Engel, 11 days ago, message: Add diff-lcs dependency
1051 e1ba1e3 was Hans Engel, 11 days ago, message: Add dependency for Open4
1052 0f87b4d was Scott Chacon, 12 days ago, message: merged recent changes:
1056 <para>Another interesting thing you can do is visualize the commit
1057 graph with the '--graph' option, like so:</para>
1059 <literal>$ git log --pretty=format:'%h : %s' --graph
1060 * 2d3acf9 : ignore errors from SIGCHLD on trap
1061 * 5e3ee11 : Merge branch 'master' of git://github.com/dustin/grit
1063 | * 420eac9 : Added a method for getting the current branch.
1064 * | 30e367c : timeout code and tests
1065 * | 5a09431 : add timeout protection to grit
1066 * | e1193f8 : support for heads with slashes in them
1068 * d6016bc : require time for xmlschema
1072 <para>It will give a pretty nice ASCII representation of the commit
1073 history lines.</para>
1074 </sect3><sect3 id="Ordering_the_Lo"><title>Ordering the Log</title>
1075 <para>You can also view the log entries in a few different orders.
1076 Note that git log starts with the most recent commit and works
1077 backwards through the parents; however, since git history can
1078 contain multiple independent lines of development, the particular
1079 order that commits are listed in may be somewhat arbitrary.</para>
1080 <para>If you want to specify a certain order, you can add an
1081 ordering option to the git log command.</para>
1082 <para>By default, the commits are shown in reverse chronological
1084 <para>However, you can also specify '--topo-order', which makes the
1085 commits appear in topological order (i.e. descendant commits are
1086 shown before their parents). If we view the git log for the Grit
1087 repo in topo-order, you can see that the development lines are all
1088 grouped together.</para>
1090 <literal>$ git log --pretty=format:'%h : %s' --topo-order --graph
1091 * 4a904d7 : Merge branch 'idx2'
1093 | * dfeffce : merged in bryces changes and fixed some testing issues
1095 | | * 23f4ecf : Clarify how to get a full count out of Repo#commits
1096 | | * 9d6d250 : Appropriate time-zone test fix from halorgium
1098 | | | * cec36f7 : Fix the to_hash test to run in US/Pacific time
1099 | | * | decfe7b : fixed manifest and grit.rb to make correct gemspec
1100 | | * | cd27d57 : added lib/grit/commit_stats.rb to the big list o' files
1101 | | * | 823a9d9 : cleared out errors by adding in Grit::Git#run method
1102 | | * | 4eb3bf0 : resolved merge conflicts, hopefully amicably
1104 | | | * | d065e76 : empty commit to push project to runcoderun
1105 | | | * | 3fa3284 : whitespace
1106 | | | * | d01cffd : whitespace
1107 | | | * | 7c74272 : oops, update version here too
1108 | | | * | 13f8cc3 : push 0.8.3
1109 | | | * | 06bae5a : capture stderr and log it if debug is true when running commands
1110 | | | * | 0b5bedf : update history
1111 | | | * | d40e1f0 : some docs
1112 | | | * | ef8a23c : update gemspec to include the newly added files to manifest
1113 | | | * | 15dd347 : add missing files to manifest; add grit test
1114 | | | * | 3dabb6a : allow sending debug messages to a user defined logger if provided; tes
1115 | | | * | eac1c37 : pull out the date in this assertion and compare as xmlschemaw, to avoi
1116 | | | * | 0a7d387 : Removed debug print.
1117 | | | * | 4d6b69c : Fixed to close opened file description.
1121 <para>You can also use '--date-order', which orders the commits
1122 primarily by commit date. This option is similar to --topo-order in
1123 the sense that no parent comes before all of its children, but
1124 otherwise things are still ordered in the commit timestamp order.
1125 You can see that development lines are not grouped together here,
1126 that they jump around as parallel development occurred:</para>
1128 <literal>$ git log --pretty=format:'%h : %s' --date-order --graph
1129 * 4a904d7 : Merge branch 'idx2'
1131 * | 81a3e0d : updated packfile code to recognize index v2
1132 | * dfeffce : merged in bryces changes and fixed some testing issues
1134 | * | c615d80 : fixed a log issue
1136 | * 23f4ecf : Clarify how to get a full count out of Repo#commits
1137 | * 9d6d250 : Appropriate time-zone test fix from halorgium
1139 | * | decfe7b : fixed manifest and grit.rb to make correct gemspec
1140 | * | cd27d57 : added lib/grit/commit_stats.rb to the big list o' file
1141 | * | 823a9d9 : cleared out errors by adding in Grit::Git#run method
1142 | * | 4eb3bf0 : resolved merge conflicts, hopefully amicably
1144 | * | | ba23640 : Fix CommitDb errors in test (was this the right fix?
1145 | * | | 4d8873e : test_commit no longer fails if you're not in PDT
1146 | * | | b3285ad : Use the appropriate method to find a first occurrenc
1147 | * | | 44dda6c : more cleanly accept separate options for initializin
1148 | * | | 839ba9f : needed to be able to ask Repo.new to work with a bar
1149 | | * | d065e76 : empty commit to push project to runcoderun
1150 * | | | 791ec6b : updated grit gemspec
1151 * | | | 756a947 : including code from github updates
1152 | | * | 3fa3284 : whitespace
1153 | | * | d01cffd : whitespace
1154 | * | | a0e4a3d : updated grit gemspec
1155 | * | | 7569d0d : including code from github updates
1159 <para>Lastly, you can reverse the order of the log with the
1160 '--reverse' option.</para>
1161 </sect3></sect2><sect2 id="Comparing_Commits_-_Git_Dif"><title>Comparing
1162 Commits - Git Diff</title>
1163 <para>You can generate diffs between any two versions of your
1165 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-diff.html">git
1166 diff</ulink>:</para>
1168 <literal>$ git diff master..test
1172 <para>That will produce the diff between the tips of the two
1173 branches. If you'd prefer to find the diff from their common
1174 ancestor to test, you can use three dots instead of two:</para>
1176 <literal>$ git diff master...test
1180 <para><ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-diff.html">git
1181 diff</ulink> is an incredibly useful tool for figuring out what has
1182 changed between any two points in your project's history, or to see
1183 what people are trying to introduce in new branches, etc.</para>
1184 <sect3 id="What_you_will_commi"><title>What you will commit</title>
1185 <para>You will commonly use
1186 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-diff.html">git
1187 diff</ulink> for figuring out differences between your last commit,
1188 your index, and your current working directory. A common use is to
1195 <para>which will show you changes in the working directory that are
1196 not yet staged for the next commit. If you want to see what
1197 <emphasis>is</emphasis> staged for the next commit, you can
1200 <literal>$ git diff --cached
1204 <para>which will show you the difference between the index and your
1205 last commit; what you would be committing if you run "git commit"
1206 without the "-a" option. Lastly, you can run</para>
1208 <literal>$ git diff HEAD
1212 <para>which shows changes in the working directory since your last
1213 commit; what you would be committing if you run "git commit
1215 </sect3><sect3 id="More_Diff_Option"><title>More Diff
1217 <para>If you want to see how your current working directory differs
1218 from the state of the project in another branch, you can run
1219 something like</para>
1221 <literal>$ git diff test
1225 <para>This will show you what is different between your current
1226 working directory and the snapshot on the 'test' branch. You can
1227 also limit the comparison to a specific file or subdirectory by
1228 adding a <emphasis>path limiter</emphasis>:</para>
1230 <literal>$ git diff HEAD -- ./lib
1234 <para>That command will show the changes between your current
1235 working directory and the last commit (or, more accurately, the tip
1236 of the current branch), limiting the comparison to files in the
1237 'lib' subdirectory.</para>
1238 <para>If you don't want to see the whole patch, you can add the
1239 '--stat' option, which will limit the output to the files that have
1240 changed along with a little text graph depicting how many lines
1241 changed in each file.</para>
1243 <literal>$>git diff --stat
1244 layout/book_index_template.html | 8 ++-
1245 text/05_Installing_Git/0_Source.markdown | 14 ++++++
1246 text/05_Installing_Git/1_Linux.markdown | 17 +++++++
1247 text/05_Installing_Git/2_Mac_104.markdown | 11 +++++
1248 text/05_Installing_Git/3_Mac_105.markdown | 8 ++++
1249 text/05_Installing_Git/4_Windows.markdown | 7 +++
1250 .../1_Getting_a_Git_Repo.markdown | 7 +++-
1251 .../0_ Comparing_Commits_Git_Diff.markdown | 45 +++++++++++++++++++-
1252 .../0_ Hosting_Git_gitweb_repoorcz_github.markdown | 4 +-
1253 9 files changed, 115 insertions(+), 6 deletions(-)
1257 <para>Sometimes that makes it easier to see overall what has
1258 changed, to jog your memory.</para>
1259 </sect3></sect2><sect2 id="Distributed_Workflow"><title>Distributed
1261 <para>Suppose that Alice has started a new project with a git
1262 repository in /home/alice/project, and that Bob, who has a home
1263 directory on the same machine, wants to contribute.</para>
1264 <para>Bob begins with:</para>
1266 <literal>$ git clone /home/alice/project myrepo
1270 <para>This creates a new directory "myrepo" containing a clone of
1271 Alice's repository. The clone is on an equal footing with the
1272 original project, possessing its own copy of the original project's
1274 <para>Bob then makes some changes and commits them:</para>
1276 <literal>(edit files)
1278 (repeat as necessary)
1282 <para>When he's ready, he tells Alice to pull changes from the
1283 repository at /home/bob/myrepo. She does this with:</para>
1285 <literal>$ cd /home/alice/project
1286 $ git pull /home/bob/myrepo master
1290 <para>This merges the changes from Bob's "master" branch into
1291 Alice's current branch. If Alice has made her own changes in the
1292 meantime, then she may need to manually fix any conflicts. (Note
1293 that the "master" argument in the above command is actually
1294 unnecessary, as it is the default.)</para>
1295 <para>The "pull" command thus performs two operations: it fetches
1296 changes from a remote branch, then merges them into the current
1298 <para>When you are working in a small closely knit group, it is not
1299 unusual to interact with the same repository over and over again.
1300 By defining 'remote' repository shorthand, you can make it
1303 <literal>$ git remote add bob /home/bob/myrepo
1307 <para>With this, Alice can perform the first operation alone using
1308 the "git fetch" command without merging them with her own branch,
1311 <literal>$ git fetch bob
1315 <para>Unlike the longhand form, when Alice fetches from Bob using a
1316 remote repository shorthand set up with <literal>git
1317 remote</literal>, what was fetched is stored in a remote tracking
1318 branch, in this case <literal>bob/master</literal>. So after
1321 <literal>$ git log -p master..bob/master
1325 <para>shows a list of all the changes that Bob made since he
1326 branched from Alice's master branch.</para>
1327 <para>After examining those changes, Alice could merge the changes
1328 into her master branch:</para>
1330 <literal>$ git merge bob/master
1334 <para>This <literal>merge</literal> can also be done by 'pulling
1335 from her own remote tracking branch', like this:</para>
1337 <literal>$ git pull . remotes/bob/master
1341 <para>Note that git pull always merges into the current branch,
1342 regardless of what else is given on the command line.</para>
1343 <para>Later, Bob can update his repo with Alice's latest changes
1350 <para>Note that he doesn't need to give the path to Alice's
1351 repository; when Bob cloned Alice's repository, git stored the
1352 location of her repository in the repository configuration, and
1353 that location is used for pulls:</para>
1355 <literal>$ git config --get remote.origin.url
1360 <para>(The complete configuration created by git-clone is visible
1361 using "git config -l", and the
1362 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-config.html">git
1363 config</ulink> man page explains the meaning of each
1365 <para>Git also keeps a pristine copy of Alice's master branch under
1366 the name "origin/master":</para>
1368 <literal>$ git branch -r
1373 <para>If Bob later decides to work from a different host, he can
1374 still perform clones and pulls using the ssh protocol:</para>
1376 <literal>$ git clone alice.org:/home/alice/project myrepo
1380 <para>Alternatively, git has a native protocol, or can use rsync or
1382 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-pull.html">git
1383 pull</ulink> for details.</para>
1384 <para>Git can also be used in a CVS-like mode, with a central
1385 repository that various users push changes to; see
1386 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-push.html">git
1388 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/gitcvs-migration.html">gitcvs-migration</ulink>.</para>
1389 <sect3 id="Public_git_repositorie"><title>Public git
1390 repositories</title>
1391 <para>Another way to submit changes to a project is to tell the
1392 maintainer of that project to pull the changes from your repository
1394 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-pull.html">git
1395 pull</ulink>. This is a way to get updates from the "main"
1396 repository, but it works just as well in the other
1398 <para>If you and the maintainer both have accounts on the same
1399 machine, then you can just pull changes from each other's
1400 repositories directly; commands that accept repository URLs as
1401 arguments will also accept a local directory name:</para>
1403 <literal>$ git clone /path/to/repository
1404 $ git pull /path/to/other/repository
1408 <para>or an ssh URL:</para>
1410 <literal>$ git clone ssh://yourhost/~you/repository
1414 <para>For projects with few developers, or for synchronizing a few
1415 private repositories, this may be all you need.</para>
1416 <para>However, the more common way to do this is to maintain a
1417 separate public repository (usually on a different host) for others
1418 to pull changes from. This is usually more convenient, and allows
1419 you to cleanly separate private work in progress from publicly
1420 visible work.</para>
1421 <para>You will continue to do your day-to-day work in your personal
1422 repository, but periodically "push" changes from your personal
1423 repository into your public repository, allowing other developers
1424 to pull from that repository. So the flow of changes, in a
1425 situation where there is one other developer with a public
1426 repository, looks like this:</para>
1429 your personal repo ------------------> your public repo
1432 | you pull | they pull
1436 their public repo <------------------- their repo
1440 </sect3><sect3 id="Pushing_changes_to_a_public_repositor"><title>Pushing
1441 changes to a public repository</title>
1442 <para>Note that exporting via http or git allow other maintainers
1443 to fetch your latest changes, but they do not allow write access.
1444 For this, you will need to update the public repository with the
1445 latest changes created in your private repository.</para>
1446 <para>The simplest way to do this is using
1447 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-push.html">git
1448 push</ulink> and ssh; to update the remote branch named "master"
1449 with the latest state of your branch named "master", run</para>
1451 <literal>$ git push ssh://yourserver.com/~you/proj.git master:master
1455 <para>or just</para>
1457 <literal>$ git push ssh://yourserver.com/~you/proj.git master
1461 <para>As with git-fetch, git-push will complain if this does not
1462 result in a fast forward; see the following section for details on
1463 handling this case.</para>
1464 <para>Note that the target of a "push" is normally a bare
1465 repository. You can also push to a repository that has a
1466 checked-out working tree, but the working tree will not be updated
1467 by the push. This may lead to unexpected results if the branch you
1468 push to is the currently checked-out branch!</para>
1469 <para>As with git-fetch, you may also set up configuration options
1470 to save typing; so, for example, after</para>
1472 <literal>$ cat >>.git/config <<EOF
1473 [remote "public-repo"]
1474 url = ssh://yourserver.com/~you/proj.git
1479 <para>you should be able to perform the above push with just</para>
1481 <literal>$ git push public-repo master
1485 <para>See the explanations of the remote..url, branch..remote, and
1486 remote..push options in
1487 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-config.html">git
1488 config</ulink> for details.</para>
1489 </sect3><sect3 id="What_to_do_when_a_push_fail"><title>What to do
1490 when a push fails</title>
1491 <para>If a push would not result in a fast forward of the remote
1492 branch, then it will fail with an error like:</para>
1494 <literal>error: remote 'refs/heads/master' is not an ancestor of
1495 local 'refs/heads/master'.
1496 Maybe you are not up-to-date and need to pull first?
1497 error: failed to push to 'ssh://yourserver.com/~you/proj.git'
1501 <para>This can happen, for example, if you:</para>
1503 <literal>- use `git-reset --hard` to remove already-published commits, or
1504 - use `git-commit --amend` to replace already-published commits, or
1505 - use `git-rebase` to rebase any already-published commits.
1509 <para>You may force git-push to perform the update anyway by
1510 preceding the branch name with a plus sign:</para>
1512 <literal>$ git push ssh://yourserver.com/~you/proj.git +master
1516 <para>Normally whenever a branch head in a public repository is
1517 modified, it is modified to point to a descendant of the commit
1518 that it pointed to before. By forcing a push in this situation, you
1519 break that convention.</para>
1520 <para>Nevertheless, this is a common practice for people that need
1521 a simple way to publish a work-in-progress patch series, and it is
1522 an acceptable compromise as long as you warn other developers that
1523 this is how you intend to manage the branch.</para>
1524 <para>It's also possible for a push to fail in this way when other
1525 people have the right to push to the same repository. In that case,
1526 the correct solution is to retry the push after first updating your
1527 work: either by a pull, or by a fetch followed by a rebase; see the
1529 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/gitcvs-migration.html">gitcvs-migration</ulink>
1531 </sect3></sect2><sect2 id="Git_Ta"><title>Git Tag</title>
1532 <sect3 id="Lightweight_Tag"><title>Lightweight Tags</title>
1533 <para>We can create a tag to refer to a particular commit by
1535 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-tag.html">git
1536 tag</ulink> with no arguments.</para>
1538 <literal>$ git tag stable-1 1b2e1d63ff
1542 <para>After that, we can use stable-1 to refer to the commit
1544 <para>This creates a "lightweight" tag, basically a branch that
1545 never moves. If you would also like to include a comment with the
1546 tag, and possibly sign it cryptographically, then we can create a
1547 <emphasis>tag object</emphasis> instead.</para>
1548 </sect3><sect3 id="Tag_Object"><title>Tag Objects</title>
1549 <para>If one of <emphasis>-a</emphasis>, <emphasis>-s</emphasis>,
1550 or <emphasis>-u <key-id></emphasis> is passed, the command
1551 creates a tag object, and requires the tag message. Unless -m or
1552 -F is given, an editor is started for the user to type in the tag
1554 <para>When this happens, a new object is added to the Git object
1555 database and the tag ref points to that <emphasis>tag
1556 object</emphasis>, rather than the commit itself. The strength of
1557 this is that you can sign the tag, so you can verify that it is the
1558 correct commit later. You can create a tag object like this:</para>
1560 <literal>$ git tag -a stable-1 1b2e1d63ff
1564 <para>It is actually possible to tag any object, but tagging commit
1565 objects is the most common. (In the Linux kernel source, the first
1566 tag object references a tree, rather than a commit)</para>
1567 </sect3><sect3 id="Signed_Tag"><title>Signed Tags</title>
1568 <para>If you have a GPG key setup, you can create signed tags
1569 fairly easily. First, you will probably want to setup your key id
1570 in your <emphasis>.git/config</emphasis> or
1571 <emphasis>~.gitconfig</emphasis> file.</para>
1574 signingkey = <gpg-key-id>
1578 <para>You can also set that with</para>
1580 <literal>$ git config (--global) user.signingkey <gpg-key-id>
1584 <para>Now you can create a signed tag simply by replacing the
1585 <emphasis>-a</emphasis> with a <emphasis>-s</emphasis>.</para>
1587 <literal>$ git tag -s stable-1 1b2e1d63ff
1591 <para>If you don't have your GPG key in your config file, you can
1592 accomplish the same thing this way:</para>
1594 <literal>$ git tag -u <gpg-key-id> stable-1 1b2e1d63ff
1598 </sect3></sect2></sect1><sect1 id="Intermediate_Usag"><title>Intermediate
1600 <sect2 id="Ignoring_file"><title>Ignoring files</title>
1601 <para>A project will often generate files that you do 'not' want to
1602 track with git. This typically includes files generated by a build
1603 process or temporary backup files made by your editor. Of course,
1604 'not' tracking files with git is just a matter of 'not' calling
1605 "<literal>git-add</literal>" on them. But it quickly becomes
1606 annoying to have these untracked files lying around; e.g. they make
1607 "<literal>git add .</literal>" and "<literal>git commit
1608 -a</literal>" practically useless, and they keep showing up in the
1609 output of "<literal>git status</literal>".</para>
1610 <para>You can tell git to ignore certain files by creating a file
1611 called .gitignore in the top level of your working directory, with
1612 contents such as:</para>
1614 <literal># Lines starting with '#' are considered comments.
1615 # Ignore any file named foo.txt.
1617 # Ignore (generated) html files,
1619 # except foo.html which is maintained by hand.
1621 # Ignore objects and archives.
1627 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/gitignore.html">gitignore</ulink>
1628 for a detailed explanation of the syntax. You can also place
1629 .gitignore files in other directories in your working tree, and
1630 they will apply to those directories and their subdirectories. The
1631 <literal>.gitignore</literal> files can be added to your repository
1632 like any other files (just run <literal>git add
1633 .gitignore</literal> and <literal>git commit</literal>, as usual),
1634 which is convenient when the exclude patterns (such as patterns
1635 matching build output files) would also make sense for other users
1636 who clone your repository.</para>
1637 <para>If you wish the exclude patterns to affect only certain
1638 repositories (instead of every repository for a given project), you
1639 may instead put them in a file in your repository named
1640 .git/info/exclude, or in any file specified by the
1641 <literal>core.excludesfile</literal> configuration variable. Some
1642 git commands can also take exclude patterns directly on the command
1644 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/gitignore.html">gitignore</ulink>
1645 for the details.</para>
1646 </sect2><sect2 id="Rebasin"><title>Rebasing</title>
1647 <para>Suppose that you create a branch "mywork" on a
1648 remote-tracking branch "origin".</para>
1650 <literal>$ git checkout -b mywork origin
1654 <inlinemediaobject><imageobject>
1655 <imagedata fileref="images/rebase0.png"/>
1656 </imageobject></inlinemediaobject>
1659 <para>Now you do some work, creating two new commits.</para>
1661 <literal>$ vi file.txt
1669 <para>Meanwhile, someone else does some work creating two new
1670 commits on the origin branch too. This means both 'origin' and
1671 'mywork' has advanced, which means the work has diverged.</para>
1672 <inlinemediaobject><imageobject>
1673 <imagedata fileref="images/rebase1.png"/>
1674 </imageobject></inlinemediaobject>
1677 <para>At this point, you could use "pull" to merge your changes
1678 back in; the result would create a new merge commit, like
1680 <inlinemediaobject><imageobject>
1681 <imagedata fileref="images/rebase2.png"/>
1682 </imageobject></inlinemediaobject>
1685 <para>However, if you prefer to keep the history in mywork a simple
1686 series of commits without any merges, you may instead choose to use
1687 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-rebase.html">git
1688 rebase</ulink>:</para>
1690 <literal>$ git checkout mywork
1695 <para>This will remove each of your commits from mywork,
1696 temporarily saving them as patches (in a directory named
1697 ".git/rebase"), update mywork to point at the latest version of
1698 origin, then apply each of the saved patches to the new
1700 <inlinemediaobject><imageobject>
1701 <imagedata fileref="images/rebase3.png"/>
1702 </imageobject></inlinemediaobject>
1705 <para>Once the ref ('mywork') is updated to point to the newly
1706 created commit objects, your older commits will be abandoned. They
1707 will likely be removed if you run a pruning garbage collection.
1709 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-gc.html">git
1711 <inlinemediaobject><imageobject>
1712 <imagedata fileref="images/rebase4.png"/>
1713 </imageobject></inlinemediaobject>
1716 <para>So now we can look at the difference in our history between
1717 running a merge and running a rebase:</para>
1718 <inlinemediaobject><imageobject>
1719 <imagedata fileref="images/rebase5.png"/>
1720 </imageobject></inlinemediaobject>
1723 <para>In the process of the rebase, it may discover conflicts. In
1724 that case it will stop and allow you to fix the conflicts; after
1725 fixing conflicts, use "git-add" to update the index with those
1726 contents, and then, instead of running git-commit, just run</para>
1728 <literal>$ git rebase --continue
1732 <para>and git will continue applying the rest of the
1734 <para>At any point you may use the <literal>--abort</literal>
1735 option to abort this process and return mywork to the state it had
1736 before you started the rebase:</para>
1738 <literal>$ git rebase --abort
1742 </sect2><sect2 id="Interactive_Rebasin"><title>Interactive
1744 <para>You can also rebase interactively. This is often used to
1745 re-write your own commit objects before pusing them somewhere. It
1746 is an easy way to split, merge or re-order commits before sharing
1747 them with others. You can also use it to clean up commits you've
1748 pulled from someone when applying them locally.</para>
1749 <para>If you have a number of commits that you would like to
1750 somehow modify during the rebase, you can invoke interactive mode
1751 by passing a '-i' or '--interactive' to the 'git rebase'
1754 <literal>$ git rebase -i origin/master
1758 <para>This will invoke interactive rebase mode on all the commits
1759 you have made since the last time you have pushed (or merged from
1760 the origin repository).</para>
1761 <para>To see what commits those are beforehand, you can run log
1764 <literal>$ git log github/master..
1768 <para>Once you run the 'rebase -i' command, you will be thrown into
1769 your editor of choice with something that looks like this:</para>
1771 <literal>pick fc62e55 added file_size
1772 pick 9824bf4 fixed little thing
1773 pick 21d80a5 added number to log
1774 pick 76b9da6 added the apply command
1775 pick c264051 Revert "added file_size" - not implemented correctly
1777 # Rebase f408319..b04dc3d onto f408319
1780 # p, pick = use commit
1781 # e, edit = use commit, but stop for amending
1782 # s, squash = use commit, but meld into previous commit
1784 # If you remove a line here THAT COMMIT WILL BE LOST.
1785 # However, if you remove everything, the rebase will be aborted.
1790 <para>This means that there are 5 commits since you last pushed and
1791 it gives you one line per commit with the following format:</para>
1793 <literal>(action) (partial-sha) (short commit message)
1797 <para>Now, you can change the action (which is by default 'pick')
1798 to either 'edit' or 'squash', or just leave it as 'pick'. You can
1799 also reorder the commits just by moving the lines around however
1800 you want. Then, when you exit the editor, git will try to apply the
1801 commits however they are now arranged and do the action
1803 <para>If 'pick' is specified, it will simply try to apply the patch
1804 and save the commit with the same message as before.</para>
1805 <para>If 'squash' is specified, it will combine that commit with
1806 the previous one to create a new commit. This will drop you into
1807 your editor again to merge the commit messages of the two commits
1808 it is now squashing together. So, if you exit the editor with
1811 <literal>pick fc62e55 added file_size
1812 squash 9824bf4 fixed little thing
1813 squash 21d80a5 added number to log
1814 squash 76b9da6 added the apply command
1815 squash c264051 Revert "added file_size" - not implemented correctly
1819 <para>Then you will have to create a single commit message from
1822 <literal># This is a combination of 5 commits.
1823 # The first commit's message is:
1826 # This is the 2nd commit message:
1830 # This is the 3rd commit message:
1834 # This is the 4th commit message:
1836 added the apply command
1838 # This is the 5th commit message:
1840 Revert "added file_size" - not implemented correctly
1842 This reverts commit fc62e5543b195f18391886b9f663d5a7eca38e84.
1846 <para>Once you have edited that down into once commit message and
1847 exit the editor, the commit will be saved with your new
1849 <para>If 'edit' is specified, it will do the same thing, but then
1850 pause before moving on to the next one and drop you into the
1851 command line so you can amend the commit, or change the commit
1852 contents somehow.</para>
1853 <para>If you wanted to split a commit, for instance, you would
1854 specify 'edit' for that commit:</para>
1856 <literal>pick fc62e55 added file_size
1857 pick 9824bf4 fixed little thing
1858 edit 21d80a5 added number to log
1859 pick 76b9da6 added the apply command
1860 pick c264051 Revert "added file_size" - not implemented correctly
1864 <para>And then when you get to the command line, you revert that
1865 commit and create two (or more) new ones. Lets say 21d80a5 modified
1866 two files, file1 and file2, and you wanted to split them into
1867 seperate commits. You could do this after the rebase dropped you to
1868 the command line :</para>
1870 <literal>$ git reset HEAD^
1872 $ git commit 'first part of split commit'
1874 $ git commit 'second part of split commit'
1875 $ git rebase --continue
1879 <para>And now instead of 5 commits, you would have 6.</para>
1880 <para>The last useful thing that interactive rebase can do is drop
1881 commits for you. If instead of choosing 'pick', 'squash' or 'edit'
1882 for the commit line, you simply remove the line, it will remove the
1883 commit from the history.</para>
1884 </sect2><sect2 id="Interactive_Addin"><title>Interactive
1886 <para>Interactive Adding is a really nice way of working with and
1887 visualizing the Git index. To start it up, simply type 'git add
1888 -i'. Git will show you all the modified files you have and their
1891 <literal>$>git add -i
1892 staged unstaged path
1893 1: unchanged +4/-0 assets/stylesheets/style.css
1894 2: unchanged +23/-11 layout/book_index_template.html
1895 3: unchanged +7/-7 layout/chapter_template.html
1896 4: unchanged +3/-3 script/pdf.rb
1897 5: unchanged +121/-0 text/14_Interactive_Rebasing/0_ Interactive_Rebasing.markdown
1900 1: status 2: update 3: revert 4: add untracked
1901 5: patch 6: diff 7: quit 8: help
1906 <para>In this case, we can see that there are 5 modified files that
1907 have not been added to our index yet (unstaged), and even how many
1908 lines have been added to or removed from each. It then shows us an
1909 interactive menu of what we can do in this mode.</para>
1910 <para>If we want to stage the files, we can type '2' or 'u' for the
1911 update mode. Then I can specify which files I want to stage (add to
1912 the index) by typing in the numbers of the files (in this case,
1915 <literal>What now> 2
1916 staged unstaged path
1917 1: unchanged +4/-0 assets/stylesheets/style.css
1918 2: unchanged +23/-11 layout/book_index_template.html
1919 3: unchanged +7/-7 layout/chapter_template.html
1920 4: unchanged +3/-3 script/pdf.rb
1921 5: unchanged +121/-0 text/14_Interactive_Rebasing/0_ Interactive_Rebasing.markdown
1923 staged unstaged path
1924 * 1: unchanged +4/-0 assets/stylesheets/style.css
1925 * 2: unchanged +23/-11 layout/book_index_template.html
1926 * 3: unchanged +7/-7 layout/chapter_template.html
1927 * 4: unchanged +3/-3 script/pdf.rb
1928 5: unchanged +121/-0 text/14_Interactive_Rebasing/0_ Interactive_Rebasing.markdown
1933 <para>If I hit enter, I will be taken back to the main menu where I
1934 can see that the file status has changed:</para>
1936 <literal>What now> status
1937 staged unstaged path
1938 1: +4/-0 nothing assets/stylesheets/style.css
1939 2: +23/-11 nothing layout/book_index_template.html
1940 3: +7/-7 nothing layout/chapter_template.html
1941 4: +3/-3 nothing script/pdf.rb
1942 5: unchanged +121/-0 text/14_Interactive_Rebasing/0_ Interactive_Rebasing.markdown
1946 <para>Now we can see the first four files are staged and the last
1947 one is still not. This is basically a compressed way to see the
1948 same information we see when we run 'git status' from the command
1951 <literal>$ git status
1953 # Changes to be committed:
1954 # (use "git reset HEAD <file>..." to unstage)
1956 # modified: assets/stylesheets/style.css
1957 # modified: layout/book_index_template.html
1958 # modified: layout/chapter_template.html
1959 # modified: script/pdf.rb
1961 # Changed but not updated:
1962 # (use "git add <file>..." to update what will be committed)
1964 # modified: text/14_Interactive_Rebasing/0_ Interactive_Rebasing.markdown
1969 <para>There are a number of useful things we can do, including
1970 unstaging files (3: revert), adding untracked files (4: add
1971 untracked), and viewing diffs (6: diff). Those are all pretty
1972 straightforward. However, there is one command that is pretty cool
1973 here, which is staging patches (5: patch).</para>
1974 <para>If you type '5' or 'p' in the menu, git will show you your
1975 diff patch by patch (or hunk by hunk) and ask if you want to stage
1976 each one. That way you can actually stage for a commit a part of a
1977 file edit. If you've edited a file and want to only commit part of
1978 it and not an unfinished part, or commit documentation or
1979 whitespace changes seperate from substantive changes, you can use
1980 'git add -i' to do so relatively easily.</para>
1981 <para>Here I've staged some changes to the book_index_template.html
1982 file, but not all of them:</para>
1984 <literal> staged unstaged path
1985 1: +4/-0 nothing assets/stylesheets/style.css
1986 2: +20/-7 +3/-4 layout/book_index_template.html
1987 3: +7/-7 nothing layout/chapter_template.html
1988 4: +3/-3 nothing script/pdf.rb
1989 5: unchanged +121/-0 text/14_Interactive_Rebasing/0_ Interactive_Rebasing.markdown
1990 6: unchanged +85/-0 text/15_Interactive_Adding/0_ Interactive_Adding.markdown
1994 <para>When you are done making changes to your index through 'git
1995 add -i', you simply quit (7: quit) and then run 'git commit' to
1996 commit the staged changes. Remember <emphasis>not</emphasis> to run
1997 'git commit -a', which will blow away all the careful changes
1998 you've just made and simply commit everything.</para>
1999 </sect2><sect2 id="Stashin"><title>Stashing</title>
2000 <para>While you are in the middle of working on something
2001 complicated, you find an unrelated but obvious and trivial bug. You
2002 would like to fix it before continuing. You can use
2003 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-stash.html">git
2004 stash</ulink> to save the current state of your work, and after
2005 fixing the bug (or, optionally after doing so on a different branch
2006 and then coming back), unstash the work-in-progress changes.</para>
2008 <literal>$ git stash "work in progress for foo feature"
2012 <para>This command will save your changes away to the
2013 <literal>stash</literal>, and reset your working tree and the index
2014 to match the tip of your current branch. Then you can make your fix
2017 <literal>... edit and test ...
2018 $ git commit -a -m "blorpl: typofix"
2022 <para>After that, you can go back to what you were working on with
2023 <literal>git stash apply</literal>:</para>
2025 <literal>$ git stash apply
2029 <sect3 id="Stash_Queu"><title>Stash Queue</title>
2030 <para>You can also use stashing to queue up stashed changes.If you
2031 run 'git stash list' you can see which stashes you have
2034 <literal>$>git stash list
2035 stash@{0}: WIP on book: 51bea1d... fixed images
2036 stash@{1}: WIP on master: 9705ae6... changed the browse code to the official repo
2040 <para>Then you can apply them individually with 'git stash apply
2041 stash@{1}'. You can clear out the list with 'git stash
2043 </sect3></sect2><sect2 id="Git_Treeishe"><title>Git
2045 <para>There are a number of ways to refer to a particular commit or
2046 tree other than spelling out the entire 40-character sha. In Git,
2047 these are referred to as a 'treeish'.</para>
2048 <sect3 id="Partial_Sh"><title>Partial Sha</title>
2049 <para>If your commit sha is
2050 '<literal>980e3ccdaac54a0d4de358f3fe5d718027d96aae</literal>', git
2051 will recognize any of the following identically:</para>
2053 <literal>980e3ccdaac54a0d4de358f3fe5d718027d96aae
2059 <para>As long as the partial sha is unique - it can't be confused
2060 with another (which is incredibly unlikely if you use at least 5
2061 characters), git will expand a partial sha for you.</para>
2062 </sect3><sect3 id="Branch,_Remote_or_Tag_Nam"><title>Branch, Remote
2064 <para>You can always use a branch, remote or tag name instead of a
2065 sha, since they are simply pointers anyhow. If your master branch
2066 is on the 980e3 commit and you've pushed it to origin and have
2067 tagged it 'v1.0', then all of the following are equivalent:</para>
2069 <literal>980e3ccdaac54a0d4de358f3fe5d718027d96aae
2071 refs/remotes/origin/master
2079 <para>Which means the following will give you identical
2082 <literal>$ git log master
2084 $ git log refs/tags/v1.0
2088 </sect3><sect3 id="Date_Spe"><title>Date Spec</title>
2089 <para>The Ref Log that git keeps will allow you to do some relative
2090 stuff locally, such as:</para>
2092 <literal>master@{yesterday}
2094 master@{1 month ago}
2098 <para>Which is shorthand for 'where the master branch head was
2099 yesterday', etc. Note that this format can result in different shas
2100 on different computers, even if the master branch is currently
2101 pointing to the same place.</para>
2102 </sect3><sect3 id="Ordinal_Spe"><title>Ordinal Spec</title>
2103 <para>This format will give you the Nth previous value of a
2104 particular reference. For example:</para>
2110 <para>will give you the 5th prior value of the master head
2112 </sect3><sect3 id="Carrot_Paren"><title>Carrot Parent</title>
2113 <para>This will give you the Nth parent of a particular commit.
2114 This format is only useful on merge commits - commit objects that
2115 have more than one direct parent.</para>
2121 </sect3><sect3 id="Tilde_Spe"><title>Tilde Spec</title>
2122 <para>The tilde spec will give you the Nth grandparent of a commit
2123 object. For example,</para>
2129 <para>will give us the first parent of the first parent of the
2130 commit that master points to. It is equivalent to:</para>
2136 <para>You can keep doing this, too. The following specs will point
2137 to the same commit:</para>
2139 <literal>master^^^^^^
2145 </sect3><sect3 id="Tree_Pointe"><title>Tree Pointer</title>
2146 <para>This disambiguates a commit from the tree that it points to.
2147 If you want the sha that a commit points to, you can add the
2148 '^{tree}' spec to the end of it.</para>
2150 <literal>master^{tree}
2154 </sect3><sect3 id="Blob_Spe"><title>Blob Spec</title>
2155 <para>If you want the sha of a particular blob, you can add the
2156 blob path at the end of the treeish, like so:</para>
2158 <literal>master:/path/to/file
2162 </sect3><sect3 id="Rang"><title>Range</title>
2163 <para>Finally, you can specify a range of commits with the range
2164 spec. This will give you all the commits between 7b593b5 and 51bea1
2165 (where 51bea1 is most recent), excluding 7b593b5 but including
2168 <literal>7b593b5..51bea1
2172 <para>This will include every commit <emphasis>since</emphasis>
2179 </sect3></sect2><sect2 id="Tracking_Branche"><title>Tracking
2181 <para>A 'tracking branch' in Git is a local branch that is
2182 connected to a remote branch. When you push and pull on that
2183 branch, it automatically pushes and pulls to the remote branch that
2184 it is connected with.</para>
2185 <para>Use this if you always pull from the same upstream branch
2186 into the new branch, and if you don't want to use "git pull "
2188 <para>The 'git clone' command automatically sets up a 'master'
2189 branch that is a tracking branch for 'origin/master' - the master
2190 branch on the cloned repository.</para>
2191 <para>You can create a tracking branch manually by adding the
2192 '--track' option to the 'branch' command in Git.</para>
2194 <literal>git branch --track experimental origin/experimental
2198 <para>Then when you run:</para>
2200 <literal>$ git pull experimental
2204 <para>It will automatically fetch from 'origin' and merge
2205 'origin/experimental' into your local 'experimental' branch.</para>
2206 <para>Likewise, when you push to origin, it will push what your
2207 'experimental' points to to origins 'experimental', without having
2208 to specify it.</para>
2209 </sect2><sect2 id="Finding_with_Git_Gre"><title>Finding with Git
2211 <para>Finding files with words or phrases in Git is really easy
2213 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-grep.html">git
2214 grep</ulink> command. It is possible to do this with the normal
2215 unix 'grep' command, but with 'git grep' you can also search
2216 through previous versions of the project without having to check
2218 <para>For example, if I wanted to see every place that used the
2219 'xmmap' call in my git.git repository, I could run this:</para>
2221 <literal>$ git grep xmmap
2222 config.c: contents = xmmap(NULL, contents_sz, PROT_READ,
2223 diff.c: s->data = xmmap(NULL, s->size, PROT_READ, MAP_PRIVATE, fd, 0);
2224 git-compat-util.h:extern void *xmmap(void *start, size_t length, int prot, int fla
2225 read-cache.c: mmap = xmmap(NULL, mmap_size, PROT_READ | PROT_WRITE, MAP_PRIVATE,
2226 refs.c: log_mapped = xmmap(NULL, mapsz, PROT_READ, MAP_PRIVATE, logfd, 0);
2227 sha1_file.c: map = xmmap(NULL, mapsz, PROT_READ, MAP_PRIVATE, fd, 0);
2228 sha1_file.c: idx_map = xmmap(NULL, idx_size, PROT_READ, MAP_PRIVATE, fd, 0);
2229 sha1_file.c: win->base = xmmap(NULL, win->len,
2230 sha1_file.c: map = xmmap(NULL, *size, PROT_READ, MAP_PRIVATE, f
2231 sha1_file.c: buf = xmmap(NULL, size, PROT_READ, MAP_PRIVATE, fd, 0);
2232 wrapper.c:void *xmmap(void *start, size_t length,
2236 <para>If I wanted to see the line number of each match as well, I
2237 can add the '-n' option:</para>
2239 <literal>$>git grep -n xmmap
2240 config.c:1016: contents = xmmap(NULL, contents_sz, PROT_READ,
2241 diff.c:1833: s->data = xmmap(NULL, s->size, PROT_READ, MAP_PRIVATE, fd,
2242 git-compat-util.h:291:extern void *xmmap(void *start, size_t length, int prot, int
2243 read-cache.c:1178: mmap = xmmap(NULL, mmap_size, PROT_READ | PROT_WRITE, MAP_
2244 refs.c:1345: log_mapped = xmmap(NULL, mapsz, PROT_READ, MAP_PRIVATE, logfd, 0);
2245 sha1_file.c:377: map = xmmap(NULL, mapsz, PROT_READ, MAP_PRIVATE, fd, 0);
2246 sha1_file.c:479: idx_map = xmmap(NULL, idx_size, PROT_READ, MAP_PRIVATE, fd
2247 sha1_file.c:780: win->base = xmmap(NULL, win->len,
2248 sha1_file.c:1076: map = xmmap(NULL, *size, PROT_READ, MAP_PR
2249 sha1_file.c:2393: buf = xmmap(NULL, size, PROT_READ, MAP_PRIVATE, fd
2250 wrapper.c:89:void *xmmap(void *start, size_t length,
2254 <para>If we're only interested in the filename, we can pass the
2255 '--name-only' option:</para>
2257 <literal>$>git grep --name-only xmmap
2268 <para>We could also see how many line matches we have in each file
2269 with the '-c' option:</para>
2271 <literal>$>git grep -c xmmap
2282 <para>Now, if I wanted to see where that was used in a specific
2283 version of git, I could add the tag reference to the end, like
2286 <literal>$ git grep xmmap v1.5.0
2287 v1.5.0:config.c: contents = xmmap(NULL, st.st_size, PROT_READ,
2288 v1.5.0:diff.c: s->data = xmmap(NULL, s->size, PROT_READ, MAP_PRIVATE, fd,
2289 v1.5.0:git-compat-util.h:static inline void *xmmap(void *start, size_t length,
2290 v1.5.0:read-cache.c: cache_mmap = xmmap(NULL, cache_mmap_size,
2291 v1.5.0:refs.c: log_mapped = xmmap(NULL, st.st_size, PROT_READ, MAP_PRIVATE, logfd
2292 v1.5.0:sha1_file.c: map = xmmap(NULL, st.st_size, PROT_READ, MAP_PRIVATE, fd,
2293 v1.5.0:sha1_file.c: idx_map = xmmap(NULL, idx_size, PROT_READ, MAP_PRIVATE, fd
2294 v1.5.0:sha1_file.c: win->base = xmmap(NULL, win->len,
2295 v1.5.0:sha1_file.c: map = xmmap(NULL, st.st_size, PROT_READ, MAP_PRIVATE, fd,
2296 v1.5.0:sha1_file.c: buf = xmmap(NULL, size, PROT_READ, MAP_PRIVATE, fd
2300 <para>We can see that there are some differences between the
2301 current lines and these lines in version 1.5.0, one of which is
2302 that xmmap is now used in wrapper.c where it was not back in
2304 <para>We can also combine search terms in grep. Say we wanted to
2305 search for where SORT_DIRENT is defined in our repository:</para>
2307 <literal>$ git grep -e '#define' --and -e SORT_DIRENT
2308 builtin-fsck.c:#define SORT_DIRENT 0
2309 builtin-fsck.c:#define SORT_DIRENT 1
2313 <para>We can also search for every file that has
2314 <emphasis>both</emphasis> search terms, but display each line that
2315 has <emphasis>either</emphasis> of the terms in those files:</para>
2317 <literal>$ git grep --all-match -e '#define' -e SORT_DIRENT
2318 builtin-fsck.c:#define REACHABLE 0x0001
2319 builtin-fsck.c:#define SEEN 0x0002
2320 builtin-fsck.c:#define ERROR_OBJECT 01
2321 builtin-fsck.c:#define ERROR_REACHABLE 02
2322 builtin-fsck.c:#define SORT_DIRENT 0
2323 builtin-fsck.c:#define DIRENT_SORT_HINT(de) 0
2324 builtin-fsck.c:#define SORT_DIRENT 1
2325 builtin-fsck.c:#define DIRENT_SORT_HINT(de) ((de)->d_ino)
2326 builtin-fsck.c:#define MAX_SHA1_ENTRIES (1024)
2327 builtin-fsck.c: if (SORT_DIRENT)
2331 <para>We can also search for lines that have one term and either of
2332 two other terms, for example, if we wanted to see where we defined
2333 constants that had either PATH or MAX in the name:</para>
2335 <literal>$ git grep -e '#define' --and \( -e PATH -e MAX \)
2336 abspath.c:#define MAXDEPTH 5
2337 builtin-blame.c:#define MORE_THAN_ONE_PATH (1u<<13)
2338 builtin-blame.c:#define MAXSG 16
2339 builtin-describe.c:#define MAX_TAGS (FLAG_BITS - 1)
2340 builtin-fetch-pack.c:#define MAX_IN_VAIN 256
2341 builtin-fsck.c:#define MAX_SHA1_ENTRIES (1024)
2346 </sect2><sect2 id="Undoing_in_Git_-_Reset,_Checkout_and_Rever"><title>Undoing
2347 in Git - Reset, Checkout and Revert</title>
2348 <para>Git provides multiple methods for fixing up mistakes as you
2349 are developing. Selecting an appropriate method depends on whether
2350 or not you have committed the mistake, and if you have committed
2351 the mistake, whether you have shared the erroneous commit with
2353 <sect3 id="Fixing_un-committed_mistake"><title>Fixing un-committed
2355 <para>If you've messed up the working tree, but haven't yet
2356 committed your mistake, you can return the entire working tree to
2357 the last committed state with</para>
2359 <literal>$ git reset --hard HEAD
2363 <para>This will throw away any changes you may have added to the
2364 git index and as well as any outstanding changes you have in your
2365 working tree. In other words, it causes the results of "git diff"
2366 and "git diff --cached" to both be empty.</para>
2367 <para>If you just want to restore just one file, say your hello.rb,
2369 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-checkout.html">git
2370 checkout</ulink> instead</para>
2372 <literal>$ git checkout -- hello.rb
2373 $ git checkout HEAD hello.rb
2377 <para>The first command restores hello.rb to the version in the
2378 index, so that "git diff hello.rb" returns no differences. The
2379 second command will restore hello.rb to the version in the HEAD
2380 revision, so that both "git diff hello.rb" and "git diff --cached
2381 hello.rb" return no differences.</para>
2382 </sect3><sect3 id="Fixing_committed_mistake"><title>Fixing
2383 committed mistakes</title>
2384 <para>If you make a commit that you later wish you hadn't, there
2385 are two fundamentally different ways to fix the problem:</para>
2388 <para>You can create a new commit that undoes whatever was done by
2389 the old commit. This is the correct thing if your mistake has
2390 already been made public.</para>
2393 <para>You can go back and modify the old commit. You should never
2394 do this if you have already made the history public; git does not
2395 normally expect the "history" of a project to change, and cannot
2396 correctly perform repeated merges from a branch that has had its
2397 history changed.</para>
2401 <sect4 id="Fixing_a_mistake_with_a_new_commi"><title>Fixing a
2402 mistake with a new commit</title>
2403 <para>Creating a new commit that reverts an earlier change is very
2405 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-revert.html">git
2406 revert</ulink> command a reference to the bad commit; for example,
2407 to revert the most recent commit:</para>
2409 <literal>$ git revert HEAD
2413 <para>This will create a new commit which undoes the change in
2414 HEAD. You will be given a chance to edit the commit message for the
2416 <para>You can also revert an earlier change, for example, the
2417 next-to-last:</para>
2419 <literal>$ git revert HEAD^
2423 <para>In this case git will attempt to undo the old change while
2424 leaving intact any changes made since then. If more recent changes
2425 overlap with the changes to be reverted, then you will be asked to
2426 fix conflicts manually, just as in the case of resolving a
2428 </sect4><sect4 id="Fixing_a_mistake_by_modifying_a_commi"><title>Fixing
2429 a mistake by modifying a commit</title>
2430 <para>If you have just committed something but realize you need to
2431 fix up that commit, recent versions of
2432 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-commit.html">git
2433 commit</ulink> support an <emphasis>--amend</emphasis> flag which
2434 instructs git to replace the HEAD commit with a new one, based on
2435 the current contents of the index. This gives you an opportunity to
2436 add files that you forgot to add or correct typos in a commit
2437 message, prior to pushing the change out for the world to
2439 <para>If you find a mistake in an older commit, but still one that
2440 you have not yet published to the world, you use
2441 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-rebase.html">git
2442 rebase</ulink> in interactive mode, with "git rebase -i" marking
2443 the change that requires correction with <emphasis>edit</emphasis>.
2444 This will allow you to amend the commit during the rebasing
2446 </sect4></sect3></sect2><sect2 id="Maintaining_Gi"><title>Maintaining
2448 <sect3 id="Ensuring_good_performanc"><title>Ensuring good
2450 <para>On large repositories, git depends on compression to keep the
2451 history information from taking up too much space on disk or in
2453 <para>This compression is not performed automatically. Therefore
2454 you should occasionally run
2455 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-gc.html">git
2462 <para>to recompress the archive. This can be very time-consuming,
2463 so you may prefer to run git-gc when you are not doing other
2465 </sect3><sect3 id="Ensuring_reliabilit"><title>Ensuring
2468 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-fsck.html">git
2469 fsck</ulink> command runs a number of self-consistency checks on
2470 the repository, and reports on any problems. This may take some
2471 time. The most common warning by far is about "dangling"
2475 dangling commit 7281251ddd2a61e38657c827739c57015671a6b3
2476 dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a63
2477 dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b5
2478 dangling blob 218761f9d90712d37a9c5e36f406f92202db07eb
2479 dangling commit bf093535a34a4d35731aa2bd90fe6b176302f14f
2480 dangling commit 8e4bec7f2ddaa268bef999853c25755452100f8e
2481 dangling tree d50bb86186bf27b681d25af89d3b5b68382e4085
2482 dangling tree b24c2473f1fd3d91352a624795be026d64c8841f
2487 <para>Dangling objects are not a problem. At worst they may take up
2488 a little extra disk space. They can sometimes provide a last-resort
2489 method for recovering lost work.</para>
2490 </sect3></sect2><sect2 id="Setting_Up_A_Public_Repositor"><title>Setting
2491 Up A Public Repository</title>
2492 <para>Assume your personal repository is in the directory ~/proj.
2493 We first create a new clone of the repository and tell git-daemon
2494 that it is meant to be public:</para>
2496 <literal>$ git clone --bare ~/proj proj.git
2497 $ touch proj.git/git-daemon-export-ok
2501 <para>The resulting directory proj.git contains a "bare" git
2502 repository--it is just the contents of the ".git" directory,
2503 without any files checked out around it.</para>
2504 <para>Next, copy proj.git to the server where you plan to host the
2505 public repository. You can use scp, rsync, or whatever is most
2507 <sect3 id="Exporting_a_git_repository_via_the_git_proto"><title>Exporting
2508 a git repository via the git protocol</title>
2509 <para>This is the preferred method.</para>
2510 <para>If someone else administers the server, they should tell you
2511 what directory to put the repository in, and what git:// URL it
2512 will appear at.</para>
2513 <para>Otherwise, all you need to do is start
2514 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-daemon.html">git
2515 daemon</ulink>; it will listen on port 9418. By default, it will
2516 allow access to any directory that looks like a git directory and
2517 contains the magic file git-daemon-export-ok. Passing some
2518 directory paths as git-daemon arguments will further restrict the
2519 exports to those paths.</para>
2520 <para>You can also run git-daemon as an inetd service; see the
2521 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-daemon.html">git
2522 daemon</ulink> man page for details. (See especially the examples
2524 </sect3><sect3 id="Exporting_a_git_repository_via_htt"><title>Exporting
2525 a git repository via http</title>
2526 <para>The git protocol gives better performance and reliability,
2527 but on a host with a web server set up, http exports may be simpler
2529 <para>All you need to do is place the newly created bare git
2530 repository in a directory that is exported by the web server, and
2531 make some adjustments to give web clients some extra information
2534 <literal>$ mv proj.git /home/you/public_html/proj.git
2536 $ git --bare update-server-info
2537 $ chmod a+x hooks/post-update
2541 <para>(For an explanation of the last two lines, see
2542 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-update-server-info.html">git
2543 update-server-info</ulink> and
2544 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/githooks.html">githooks</ulink>.)</para>
2545 <para>Advertise the URL of proj.git. Anybody else should then be
2546 able to clone or pull from that URL, for example with a command
2549 <literal>$ git clone http://yourserver.com/~you/proj.git
2553 </sect3></sect2><sect2 id="Setting_Up_a_Private_Repositor"><title>Setting
2554 Up a Private Repository</title>
2555 <para>If you need to setup a private repository and want to do so
2556 locally, rather than using a hosted solution, you have a number of
2558 <sect3 id="Repo_Access_over_SS"><title>Repo Access over SSH</title>
2559 <para>Generally, the easiest solution is to simply use Git over
2560 SSH. If users already have ssh accounts on a machine, you can put
2561 the git repository anywhere on the box that they have access to and
2562 let them access it over normal ssh logins. For example, say you
2563 have a repository you want to host. You can export it as a bare
2564 repo and then scp it onto your server like so:</para>
2566 <literal>$ git clone --bare /home/user/myrepo/.git /tmp/myrepo.git
2567 $ scp -r /tmp/myrepo.git myserver.com:/opt/git/myrepo.git
2571 <para>Then someone else with an ssh account on myserver.com can
2574 <literal>$ git clone myserver.com:/opt/git/myrepo.git
2578 <para>Which will simply prompt them for thier ssh password or use
2579 thier public key, however they have ssh authentication
2581 </sect3><sect3 id="Multiple_User_Access_using_Gitosi"><title>Multiple
2582 User Access using Gitosis</title>
2583 <para>If you don't want to setup seperate accounts for every user,
2584 you can use a tool called Gitosis. In gitosis, there is an
2585 authorized_keys file that contains the public keys of everyone
2586 authorized to access the repository, and then everyone uses the
2587 'git' user to do pushes and pulls.</para>
2588 <para><ulink url="http://www.urbanpuddle.com/articles/2008/07/11/installing-git-on-a-server-ubuntu-or-debian">Installing
2589 and Setting up Gitosis</ulink></para>
2590 </sect3></sect2></sect1><sect1 id="Advanced_Gi"><title>Advanced
2592 <sect2 id="Creating_New_Empty_Branche"><title>Creating New Empty
2594 <para>Ocasionally, you may want to keep branches in your repository
2595 that do not share an ancestor with your normal code. Some examples
2596 of this might be generated documentation or something along those
2597 lines. If you want to create a new branch head that does not use
2598 your current codebase as a parent, you can create an empty branch
2601 <literal>git symbolic-ref HEAD refs/heads/newbranch
2606 git commit -m 'Initial commit'
2610 </sect2><sect2 id="Modifying_your_Histor"><title>Modifying your
2612 <para>Interactive rebasing is a good way to modify individual
2614 <para><ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-filter-branch.html">git
2615 filter-branch</ulink> is a good way to edit commits en
2617 </sect2><sect2 id="Advanced_Branching_And_Mergin"><title>Advanced
2618 Branching And Merging</title>
2619 <sect3 id="Getting_conflict-resolution_help_during_a_me"><title>Getting
2620 conflict-resolution help during a merge</title>
2621 <para>All of the changes that git was able to merge automatically
2622 are already added to the index file, so
2623 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-diff.html">git
2624 diff</ulink> shows only the conflicts. It uses an unusual
2629 index 802992c,2b60207..0000000
2632 @@@ -1,1 -1,1 +1,5 @@@
2633 ++<<<<<<< HEAD:file.txt
2637 ++>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
2641 <para>Recall that the commit which will be committed after we
2642 resolve this conflict will have two parents instead of the usual
2643 one: one parent will be HEAD, the tip of the current branch; the
2644 other will be the tip of the other branch, which is stored
2645 temporarily in MERGE_HEAD.</para>
2646 <para>During the merge, the index holds three versions of each
2647 file. Each of these three "file stages" represents a different
2648 version of the file:</para>
2650 <literal>$ git show :1:file.txt # the file in a common ancestor of both branches
2651 $ git show :2:file.txt # the version from HEAD.
2652 $ git show :3:file.txt # the version from MERGE_HEAD.
2657 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-diff.html">git
2658 diff</ulink> to show the conflicts, it runs a three-way diff
2659 between the conflicted merge results in the work tree with stages 2
2660 and 3 to show only hunks whose contents come from both sides, mixed
2661 (in other words, when a hunk's merge results come only from stage
2662 2, that part is not conflicting and is not shown. Same for stage
2664 <para>The diff above shows the differences between the working-tree
2665 version of file.txt and the stage 2 and stage 3 versions. So
2666 instead of preceding each line by a single "+" or "-", it now uses
2667 two columns: the first column is used for differences between the
2668 first parent and the working directory copy, and the second for
2669 differences between the second parent and the working directory
2670 copy. (See the "COMBINED DIFF FORMAT" section of
2671 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-diff-files.html">git
2672 diff-files</ulink> for a details of the format.)</para>
2673 <para>After resolving the conflict in the obvious way (but before
2674 updating the index), the diff will look like:</para>
2678 index 802992c,2b60207..0000000
2681 @@@ -1,1 -1,1 +1,1 @@@
2688 <para>This shows that our resolved version deleted "Hello world"
2689 from the first parent, deleted "Goodbye" from the second parent,
2690 and added "Goodbye world", which was previously absent from
2692 <para>Some special diff options allow diffing the working directory
2693 against any of these stages:</para>
2695 <literal>$ git diff -1 file.txt # diff against stage 1
2696 $ git diff --base file.txt # same as the above
2697 $ git diff -2 file.txt # diff against stage 2
2698 $ git diff --ours file.txt # same as the above
2699 $ git diff -3 file.txt # diff against stage 3
2700 $ git diff --theirs file.txt # same as the above.
2705 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-log.html">git
2707 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/gitk.html">gitk</ulink>
2708 commands also provide special help for merges:</para>
2710 <literal>$ git log --merge
2715 <para>These will display all commits which exist only on HEAD or on
2716 MERGE_HEAD, and which touch an unmerged file.</para>
2717 <para>You may also use
2718 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-mergetool.html">git
2719 mergetool</ulink>, which lets you merge the unmerged files using
2720 external tools such as emacs or kdiff3.</para>
2721 <para>Each time you resolve the conflicts in a file and update the
2724 <literal>$ git add file.txt
2728 <para>the different stages of that file will be "collapsed", after
2729 which git-diff will (by default) no longer show diffs for that
2731 </sect3><sect3 id="Multiway_Merg"><title>Multiway Merge</title>
2732 <para>You can merge several heads at one time by simply listing
2734 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-merge.html">git
2735 merge</ulink> command. For instance,</para>
2737 <literal>$ git merge scott/master rick/master tom/master
2741 <para>is the equivalent of:</para>
2743 <literal>$ git merge scott/master
2744 $ git merge rick/master
2745 $ git merge tom/master
2749 </sect3><sect3 id="Subtre"><title>Subtree</title>
2750 <para>There are situations where you want to include contents in
2751 your project from an independently developed project. You can just
2752 pull from the other project as long as there are no conflicting
2754 <para>The problematic case is when there are conflicting files.
2755 Potential candidates are Makefiles and other standard filenames.
2756 You could merge these files but probably you do not want to. A
2757 better solution for this problem can be to merge the project as its
2758 own subdirectory. This is not supported by the recursive merge
2759 strategy, so just pulling won't work.</para>
2760 <para>What you want is the subtree merge strategy, which helps you
2761 in such a situation.</para>
2762 <para>In this example, let's say you have the repository at
2763 /path/to/B (but it can be an URL as well, if you want). You want to
2764 merge the master branch of that repository to the dir-B
2765 subdirectory in your current branch.</para>
2766 <para>Here is the command sequence you need:</para>
2768 <literal>$ git remote add -f Bproject /path/to/B (1)
2769 $ git merge -s ours --no-commit Bproject/master (2)
2770 $ git read-tree --prefix=dir-B/ -u Bproject/master (3)
2771 $ git commit -m "Merge B project as our subdirectory" (4)
2772 $ git pull -s subtree Bproject master (5)
2776 <para>The benefit of using subtree merge is that it requires less
2777 administrative burden from the users of your repository. It works
2778 with older (before Git v1.5.2) clients and you have the code right
2780 <para>However if you use submodules then you can choose not to
2781 transfer the submodule objects. This may be a problem with the
2782 subtree merge.</para>
2783 <para>Also, in case you make changes to the other project, it is
2784 easier to submit changes if you just use submodules.</para>
2786 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/howto/using-merge-subtree.html">Using
2787 Subtree Merge</ulink>)</para>
2788 </sect3></sect2><sect2 id="Finding_Issues_-_Git_Bisec"><title>Finding
2789 Issues - Git Bisect</title>
2790 <para>Suppose version 2.6.18 of your project worked, but the
2791 version at "master" crashes. Sometimes the best way to find the
2792 cause of such a regression is to perform a brute-force search
2793 through the project's history to find the particular commit that
2794 caused the problem. The
2795 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-bisect.html">git
2796 bisect</ulink> command can help you do this:</para>
2798 <literal>$ git bisect start
2799 $ git bisect good v2.6.18
2800 $ git bisect bad master
2801 Bisecting: 3537 revisions left to test after this
2802 [65934a9a028b88e83e2b0f8b36618fe503349f8e] BLOCK: Make USB storage depend on SCSI rather than selecting it [try #6]
2806 <para>If you run "git branch" at this point, you'll see that git
2807 has temporarily moved you to a new branch named "bisect". This
2808 branch points to a commit (with commit id 65934...) that is
2809 reachable from "master" but not from v2.6.18. Compile and test it,
2810 and see whether it crashes. Assume it does crash. Then:</para>
2812 <literal>$ git bisect bad
2813 Bisecting: 1769 revisions left to test after this
2814 [7eff82c8b1511017ae605f0c99ac275a7e21b867] i2c-core: Drop useless bitmaskings
2818 <para>checks out an older version. Continue like this, telling git
2819 at each stage whether the version it gives you is good or bad, and
2820 notice that the number of revisions left to test is cut
2821 approximately in half each time.</para>
2822 <para>After about 13 tests (in this case), it will output the
2823 commit id of the guilty commit. You can then examine the commit
2825 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-show.html">git
2826 show</ulink>, find out who wrote it, and mail them your bug report
2827 with the commit id. Finally, run</para>
2829 <literal>$ git bisect reset
2833 <para>to return you to the branch you were on before and delete the
2834 temporary "bisect" branch.</para>
2835 <para>Note that the version which git-bisect checks out for you at
2836 each point is just a suggestion, and you're free to try a different
2837 version if you think it would be a good idea. For example,
2838 occasionally you may land on a commit that broke something
2839 unrelated; run</para>
2841 <literal>$ git bisect visualize
2845 <para>which will run gitk and label the commit it chose with a
2846 marker that says "bisect". Choose a safe-looking commit nearby,
2847 note its commit id, and check it out with:</para>
2849 <literal>$ git reset --hard fb47ddb2db...
2853 <para>then test, run "bisect good" or "bisect bad" as appropriate,
2854 and continue.</para>
2855 </sect2><sect2 id="Finding_Issues_-_Git_Blam"><title>Finding Issues
2858 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-blame.html">git
2859 blame</ulink> command is really helpful for figuring out who
2860 changed which sections of a file. If you simple run 'git blame
2861 [filename]' you'll get an output of the entire file with the last
2862 commit sha, date and author for every line in the file.</para>
2864 <literal>$ git blame sha1_file.c
2866 0fcfd160 (Linus Torvalds 2005-04-18 13:04:43 -0700 8) */
2867 0fcfd160 (Linus Torvalds 2005-04-18 13:04:43 -0700 9) #include "cache.h"
2868 1f688557 (Junio C Hamano 2005-06-27 03:35:33 -0700 10) #include "delta.h"
2869 a733cb60 (Linus Torvalds 2005-06-28 14:21:02 -0700 11) #include "pack.h"
2870 8e440259 (Peter Eriksen 2006-04-02 14:44:09 +0200 12) #include "blob.h"
2871 8e440259 (Peter Eriksen 2006-04-02 14:44:09 +0200 13) #include "commit.h"
2872 8e440259 (Peter Eriksen 2006-04-02 14:44:09 +0200 14) #include "tag.h"
2873 8e440259 (Peter Eriksen 2006-04-02 14:44:09 +0200 15) #include "tree.h"
2874 f35a6d3b (Linus Torvalds 2007-04-09 21:20:29 -0700 16) #include "refs.h"
2875 70f5d5d3 (Nicolas Pitre 2008-02-28 00:25:19 -0500 17) #include "pack-revindex.h"628522ec (Junio C Hamano 2007-12-29 02:05:47 -0800 18) #include "sha1-lookup.h"
2880 <para>This is often helpful if a file had a line reverted or a
2881 mistake that broke the build to help you see who changed that line
2883 <para>You can also specify a start and end line for the
2886 <literal>$>git blame -L 160,+10 sha1_file.c
2887 ace1534d (Junio C Hamano 2005-05-07 00:38:04 -0700 160)}
2888 ace1534d (Junio C Hamano 2005-05-07 00:38:04 -0700 161)
2889 0fcfd160 (Linus Torvalds 2005-04-18 13:04:43 -0700 162)/*
2890 0fcfd160 (Linus Torvalds 2005-04-18 13:04:43 -0700 163) * NOTE! This returns a statically allocate
2891 790296fd (Jim Meyering 2008-01-03 15:18:07 +0100 164) * careful about using it. Do an "xstrdup()
2892 0fcfd160 (Linus Torvalds 2005-04-18 13:04:43 -0700 165) * filename.
2893 ace1534d (Junio C Hamano 2005-05-07 00:38:04 -0700 166) *
2894 ace1534d (Junio C Hamano 2005-05-07 00:38:04 -0700 167) * Also note that this returns the location
2895 ace1534d (Junio C Hamano 2005-05-07 00:38:04 -0700 168) * SHA1 file can happen from any alternate
2896 d19938ab (Junio C Hamano 2005-05-09 17:57:56 -0700 169) * DB_ENVIRONMENT environment variable if i
2900 </sect2><sect2 id="Git_and_Emai"><title>Git and Email</title>
2901 <sect3 id="Submitting_patches_to_a_projec"><title>Submitting
2902 patches to a project</title>
2903 <para>If you just have a few changes, the simplest way to submit
2904 them may just be to send them as patches in email:</para>
2906 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-format-patch.html">git
2907 format-patch</ulink>; for example:</para>
2909 <literal>$ git format-patch origin
2913 <para>will produce a numbered series of files in the current
2914 directory, one for each patch in the current branch but not in
2916 <para>You can then import these into your mail client and send them
2917 by hand. However, if you have a lot to send at once, you may prefer
2919 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-send-email.html">git
2920 send-email</ulink> script to automate the process. Consult the
2921 mailing list for your project first to determine how they prefer
2922 such patches be handled.</para>
2923 </sect3><sect3 id="Importing_patches_to_a_projec"><title>Importing
2924 patches to a project</title>
2925 <para>Git also provides a tool called
2926 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-am.html">git
2927 am</ulink> (am stands for "apply mailbox"), for importing such an
2928 emailed series of patches. Just save all of the patch-containing
2929 messages, in order, into a single mailbox file, say "patches.mbox",
2932 <literal>$ git am -3 patches.mbox
2936 <para>Git will apply each patch in order; if any conflicts are
2937 found, it will stop, and you can manually fix the conflicts and
2938 resolve the merge. (The "-3" option tells git to perform a merge;
2939 if you would prefer it just to abort and leave your tree and index
2940 untouched, you may omit that option.)</para>
2941 <para>Once the index is updated with the results of the conflict
2942 resolution, instead of creating a new commit, just run</para>
2944 <literal>$ git am --resolved
2948 <para>and git will create the commit for you and continue applying
2949 the remaining patches from the mailbox.</para>
2950 <para>The final result will be a series of commits, one for each
2951 patch in the original mailbox, with authorship and commit log
2952 message each taken from the message containing each patch.</para>
2953 </sect3></sect2><sect2 id="Customizing_Gi"><title>Customizing
2955 <para><ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-config.html">git
2956 config</ulink></para>
2957 <sect3 id="Changing_your_Edito"><title>Changing your Editor</title>
2959 <literal>$ git config --global core.editor emacs
2963 </sect3><sect3 id="Adding_Aliase"><title>Adding Aliases</title>
2965 <literal>$ git config --global alias.last 'cat-file commit HEAD'
2968 tree c85fbd1996b8e7e5eda1288b56042c0cdb91836b
2969 parent cdc9a0a28173b6ba4aca00eb34f5aabb39980735
2970 author Scott Chacon <schacon@gmail.com> 1220473867 -0700
2971 committer Scott Chacon <schacon@gmail.com> 1220473867 -0700
2973 fixed a weird formatting problem
2975 $ git cat-file commit HEAD
2976 tree c85fbd1996b8e7e5eda1288b56042c0cdb91836b
2977 parent cdc9a0a28173b6ba4aca00eb34f5aabb39980735
2978 author Scott Chacon <schacon@gmail.com> 1220473867 -0700
2979 committer Scott Chacon <schacon@gmail.com> 1220473867 -0700
2981 fixed a weird formatting problem
2985 </sect3><sect3 id="Adding_Colo"><title>Adding Color</title>
2986 <para>See all color.* options in the
2987 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-config.html">git
2988 config</ulink> docs</para>
2990 <literal>$ git config color.branch auto
2991 $ git config color.diff auto
2992 $ git config color.interactive auto
2993 $ git config color.status auto
2997 <para>Or, you can set all of them on with the color.ui
3000 <literal>$ git config color.ui true
3004 </sect3><sect3 id="Commit_Templat"><title>Commit Template</title>
3006 <literal>$ git config commit.template '/etc/git-commit-template'
3010 </sect3><sect3 id="Log_Forma"><title>Log Format</title>
3012 <literal>$ git config format.pretty oneline
3016 </sect3><sect3 id="Other_Config_Option"><title>Other Config
3018 <para>There are also a number of interesting options for packing,
3019 gc-ing, merging, remotes, branches, http transport, diffs, paging,
3020 whitespace and more. If you want to tweak these, check out the
3021 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-config.html">git
3022 config</ulink> docs.</para>
3023 </sect3></sect2><sect2 id="Git_Hook"><title>Git Hooks</title>
3024 <para>Hooks are little scripts you can place in $GIT_DIR/hooks
3025 directory to trigger action at certain points. When git-init is
3026 run, a handful example hooks are copied in the hooks directory of
3027 the new repository, but by default they are all disabled. To enable
3028 a hook, rename it by removing its .sample suffix.</para>
3029 <sect3 id="applypatch-ms"><title>applypatch-msg</title>
3031 <literal>GIT_DIR/hooks/applypatch-msg
3035 <para>This hook is invoked by git-am script. It takes a single
3036 parameter, the name of the file that holds the proposed commit log
3037 message. Exiting with non-zero status causes git-am to abort before
3038 applying the patch.</para>
3039 <para>The hook is allowed to edit the message file in place, and
3040 can be used to normalize the message into some project standard
3041 format (if the project has one). It can also be used to refuse the
3042 commit after inspecting the message file. The default
3043 applypatch-msg hook, when enabled, runs the commit-msg hook, if the
3044 latter is enabled.</para>
3045 </sect3><sect3 id="pre-applypatc"><title>pre-applypatch</title>
3047 <literal>GIT_DIR/hooks/pre-applypatch
3051 <para>This hook is invoked by git-am. It takes no parameter, and is
3052 invoked after the patch is applied, but before a commit is made. If
3053 it exits with non-zero status, then the working tree will not be
3054 committed after applying the patch.</para>
3055 <para>It can be used to inspect the current working tree and refuse
3056 to make a commit if it does not pass certain test. The default
3057 pre-applypatch hook, when enabled, runs the pre-commit hook, if the
3058 latter is enabled.</para>
3059 </sect3><sect3 id="post-applypatc"><title>post-applypatch</title>
3061 <literal>GIT_DIR/hooks/post-applypatch
3065 <para>This hook is invoked by 'git-am'. It takes no parameter, and
3066 is invoked after the patch is applied and a commit is made.</para>
3067 <para>This hook is meant primarily for notification, and cannot
3068 affect the outcome of 'git-am'.</para>
3069 </sect3><sect3 id="pre-commi"><title>pre-commit</title>
3071 <literal>GIT_DIR/hooks/pre-commit
3075 <para>This hook is invoked by 'git-commit', and can be bypassed
3076 with <literal>\--no-verify</literal> option. It takes no parameter,
3077 and is invoked before obtaining the proposed commit log message and
3078 making a commit. Exiting with non-zero status from this script
3079 causes the 'git-commit' to abort.</para>
3080 <para>The default 'pre-commit' hook, when enabled, catches
3081 introduction of lines with trailing whitespaces and aborts the
3082 commit when such a line is found.</para>
3083 <para>All the 'git-commit' hooks are invoked with the environment
3084 variable <literal>GIT_EDITOR=:</literal> if the command will not
3085 bring up an editor to modify the commit message.</para>
3086 <para>Here is an example of a Ruby script that runs RSpec tests
3087 before allowing a commit.</para>
3090 html_path = "spec_results.html"
3091 `spec -f h:#{html_path} -f p spec` # run the spec. send progress to screen. save html results to html_path
3093 # find out how many errors were found
3094 html = open(html_path).read
3095 examples = html.match(/(\d+) examples/)[0].to_i rescue 0
3096 failures = html.match(/(\d+) failures/)[0].to_i rescue 0
3097 pending = html.match(/(\d+) pending/)[0].to_i rescue 0
3100 puts "0 failures! #{examples} run, #{pending} pending"
3102 puts "\aDID NOT COMMIT YOUR FILES!"
3103 puts "View spec results at #{File.expand_path(html_path)}"
3105 puts "#{failures} failures! #{examples} run, #{pending} pending"
3110 </sect3><sect3 id="prepare-commit-ms"><title>prepare-commit-msg</title>
3112 <literal>GIT_DIR/hooks/prepare-commit-msg
3116 <para>This hook is invoked by 'git-commit' right after preparing
3117 the default log message, and before the editor is started.</para>
3118 <para>It takes one to three parameters. The first is the name of
3119 the file that the commit log message. The second is the source of
3120 the commit message, and can be: <literal>message</literal> (if a
3121 <literal>-m</literal> or <literal>-F</literal> option was given);
3122 <literal>template</literal> (if a <literal>-t</literal> option was
3123 given or the configuration option
3124 <literal>commit.template</literal> is set);
3125 <literal>merge</literal> (if the commit is a merge or a
3126 <literal>.git/MERGE_MSG</literal> file exists);
3127 <literal>squash</literal> (if a <literal>.git/SQUASH_MSG</literal>
3128 file exists); or <literal>commit</literal>, followed by a commit
3129 SHA1 (if a <literal>-c</literal>, <literal>-C</literal> or
3130 <literal>\--amend</literal> option was given).</para>
3131 <para>If the exit status is non-zero, 'git-commit' will
3133 <para>The purpose of the hook is to edit the message file in place,
3134 and it is not suppressed by the <literal>\--no-verify</literal>
3135 option. A non-zero exit means a failure of the hook and aborts the
3136 commit. It should not be used as replacement for pre-commit
3138 <para>The sample <literal>prepare-commit-msg</literal> hook that
3139 comes with git comments out the <literal>Conflicts:</literal> part
3140 of a merge's commit message.</para>
3141 </sect3><sect3 id="commit-ms"><title>commit-msg</title>
3143 <literal>GIT_DIR/hooks/commit-msg
3147 <para>This hook is invoked by 'git-commit', and can be bypassed
3148 with <literal>\--no-verify</literal> option. It takes a single
3149 parameter, the name of the file that holds the proposed commit log
3150 message. Exiting with non-zero status causes the 'git-commit' to
3152 <para>The hook is allowed to edit the message file in place, and
3153 can be used to normalize the message into some project standard
3154 format (if the project has one). It can also be used to refuse the
3155 commit after inspecting the message file.</para>
3156 <para>The default 'commit-msg' hook, when enabled, detects
3157 duplicate "Signed-off-by" lines, and aborts the commit if one is
3159 </sect3><sect3 id="post-commi"><title>post-commit</title>
3161 <literal>GIT_DIR/hooks/post-commit
3165 <para>This hook is invoked by 'git-commit'. It takes no parameter,
3166 and is invoked after a commit is made.</para>
3167 <para>This hook is meant primarily for notification, and cannot
3168 affect the outcome of 'git-commit'.</para>
3169 </sect3><sect3 id="pre-rebas"><title>pre-rebase</title>
3171 <literal>GIT_DIR/hooks/pre-rebase
3175 <para>This hook is called by 'git-rebase' and can be used to
3176 prevent a branch from getting rebased.</para>
3177 </sect3><sect3 id="post-checkou"><title>post-checkout</title>
3179 <literal>GIT_DIR/hooks/post-checkout
3183 <para>This hook is invoked when a 'git-checkout' is run after
3184 having updated the worktree. The hook is given three parameters:
3185 the ref of the previous HEAD, the ref of the new HEAD (which may or
3186 may not have changed), and a flag indicating whether the checkout
3187 was a branch checkout (changing branches, flag=1) or a file
3188 checkout (retrieving a file from the index, flag=0). This hook
3189 cannot affect the outcome of 'git-checkout'.</para>
3190 <para>This hook can be used to perform repository validity checks,
3191 auto-display differences from the previous HEAD if different, or
3192 set working dir metadata properties.</para>
3193 </sect3><sect3 id="post-merg"><title>post-merge</title>
3195 <literal>GIT_DIR/hooks/post-merge
3199 <para>This hook is invoked by 'git-merge', which happens when a
3200 'git-pull' is done on a local repository. The hook takes a single
3201 parameter, a status flag specifying whether or not the merge being
3202 done was a squash merge. This hook cannot affect the outcome of
3203 'git-merge' and is not executed, if the merge failed due to
3205 <para>This hook can be used in conjunction with a corresponding
3206 pre-commit hook to save and restore any form of metadata associated
3207 with the working tree (eg: permissions/ownership, ACLS, etc). See
3208 contrib/hooks/setgitperms.perl for an example of how to do
3210 </sect3><sect3 id="pre-receiv"><title>pre-receive</title>
3212 <literal>GIT_DIR/hooks/pre-receive
3216 <para>This hook is invoked by 'git-receive-pack' on the remote
3217 repository, which happens when a 'git-push' is done on a local
3218 repository. Just before starting to update refs on the remote
3219 repository, the pre-receive hook is invoked. Its exit status
3220 determines the success or failure of the update.</para>
3221 <para>This hook executes once for the receive operation. It takes
3222 no arguments, but for each ref to be updated it receives on
3223 standard input a line of the format:</para>
3224 <para><old-value> SP <new-value> SP <ref-name>
3226 <para>where <literal><old-value></literal> is the old object
3227 name stored in the ref, <literal><new-value></literal> is the
3228 new object name to be stored in the ref and
3229 <literal><ref-name></literal> is the full name of the ref.
3230 When creating a new ref, <literal><old-value></literal> is 40
3231 <literal>0</literal>.</para>
3232 <para>If the hook exits with non-zero status, none of the refs will
3233 be updated. If the hook exits with zero, updating of individual
3234 refs can still be prevented by the <<update,'update'>>
3236 <para>Both standard output and standard error output are forwarded
3237 to 'git-send-pack' on the other end, so you can simply
3238 <literal>echo</literal> messages for the user.</para>
3239 <para>If you wrote it in Ruby, you might get the args this
3242 rev_old, rev_new, ref = STDIN.read.split(" ")
3245 <para>Or in a bash script, something like this would work:</para>
3248 # <oldrev> <newrev> <refname>
3249 # update a blame tree
3250 while read oldrev newrev ref
3252 echo "STARTING [$oldrev $newrev $ref]"
3253 for path in `git diff-tree -r $oldrev..$newrev | awk '{print $6}'`
3255 echo "git update-ref refs/blametree/$ref/$path $newrev"
3256 `git update-ref refs/blametree/$ref/$path $newrev`
3262 </sect3><sect3 id="updat"><title>update</title>
3264 <literal>GIT_DIR/hooks/update
3268 <para>This hook is invoked by 'git-receive-pack' on the remote
3269 repository, which happens when a 'git-push' is done on a local
3270 repository. Just before updating the ref on the remote repository,
3271 the update hook is invoked. Its exit status determines the success
3272 or failure of the ref update.</para>
3273 <para>The hook executes once for each ref to be updated, and takes
3274 three parameters:</para>
3276 <listitem>the name of the ref being updated,</listitem>
3277 <listitem>the old object name stored in the ref,</listitem>
3278 <listitem>and the new objectname to be stored in the
3281 <para>A zero exit from the update hook allows the ref to be
3282 updated. Exiting with a non-zero status prevents 'git-receive-pack'
3283 from updating that ref.</para>
3284 <para>This hook can be used to prevent 'forced' update on certain
3285 refs by making sure that the object name is a commit object that is
3286 a descendant of the commit object named by the old object name.
3287 That is, to enforce a "fast forward only" policy.</para>
3288 <para>It could also be used to log the old..new status. However, it
3289 does not know the entire set of branches, so it would end up firing
3290 one e-mail per ref when used naively, though. The
3291 <<post-receive,'post-receive'>> hook is more suited to
3293 <para>Another use suggested on the mailing list is to use this hook
3294 to implement access control which is finer grained than the one
3295 based on filesystem group.</para>
3296 <para>Both standard output and standard error output are forwarded
3297 to 'git-send-pack' on the other end, so you can simply
3298 <literal>echo</literal> messages for the user.</para>
3299 <para>The default 'update' hook, when enabled--and with
3300 <literal>hooks.allowunannotated</literal> config option turned
3301 on--prevents unannotated tags to be pushed.</para>
3302 </sect3><sect3 id="post-receiv"><title>post-receive</title>
3304 <literal>GIT_DIR/hooks/post-receive
3308 <para>This hook is invoked by 'git-receive-pack' on the remote
3309 repository, which happens when a 'git-push' is done on a local
3310 repository. It executes on the remote repository once after all the
3311 refs have been updated.</para>
3312 <para>This hook executes once for the receive operation. It takes
3313 no arguments, but gets the same information as the
3314 <<pre-receive,'pre-receive'>> hook does on its standard
3316 <para>This hook does not affect the outcome of 'git-receive-pack',
3317 as it is called after the real work is done.</para>
3318 <para>This supersedes the <<post-update,'post-update'>>
3319 hook in that it gets both old and new values of all the refs in
3320 addition to their names.</para>
3321 <para>Both standard output and standard error output are forwarded
3322 to 'git-send-pack' on the other end, so you can simply
3323 <literal>echo</literal> messages for the user.</para>
3324 <para>The default 'post-receive' hook is empty, but there is a
3325 sample script <literal>post-receive-email</literal> provided in the
3326 <literal>contrib/hooks</literal> directory in git distribution,
3327 which implements sending commit emails.</para>
3328 </sect3><sect3 id="post-updat"><title>post-update</title>
3330 <literal>GIT_DIR/hooks/post-update
3334 <para>This hook is invoked by 'git-receive-pack' on the remote
3335 repository, which happens when a 'git-push' is done on a local
3336 repository. It executes on the remote repository once after all the
3337 refs have been updated.</para>
3338 <para>It takes a variable number of parameters, each of which is
3339 the name of ref that was actually updated.</para>
3340 <para>This hook is meant primarily for notification, and cannot
3341 affect the outcome of 'git-receive-pack'.</para>
3342 <para>The 'post-update' hook can tell what are the heads that were
3343 pushed, but it does not know what their original and updated values
3344 are, so it is a poor place to do log old..new. The
3345 <<post-receive,'post-receive'>> hook does get both
3346 original and updated values of the refs. You might consider it
3347 instead if you need them.</para>
3348 <para>When enabled, the default 'post-update' hook runs
3349 'git-update-server-info' to keep the information used by dumb
3350 transports (e.g., HTTP) up-to-date. If you are publishing a git
3351 repository that is accessible via HTTP, you should probably enable
3353 <para>Both standard output and standard error output are forwarded
3354 to 'git-send-pack' on the other end, so you can simply
3355 <literal>echo</literal> messages for the user.</para>
3356 </sect3><sect3 id="pre-auto-g"><title>pre-auto-gc</title>
3358 <literal>GIT_DIR/hooks/pre-auto-gc
3362 <para>This hook is invoked by 'git-gc --auto'. It takes no
3363 parameter, and exiting with non-zero status from this script causes
3364 the 'git-gc --auto' to abort.</para>
3365 </sect3><sect3 id="Reference"><title>References</title>
3366 <para><ulink url="http://www.kernel.org/pub/software/scm/git/docs/githooks.html">Git
3368 http://probablycorey.wordpress.com/2008/03/07/git-hooks-make-me-giddy/</para>
3369 </sect3></sect2><sect2 id="Recovering_Corrupted_Object"><title>Recovering
3370 Corrupted Objects</title>
3371 <para><ulink url="http://programblings.com/2008/06/07/the-illustrated-guide-to-recovering-lost-commits-with-git">Recovering
3372 Lost Commits Blog Post</ulink></para>
3373 <para><ulink url="http://www.kernel.org/pub/software/scm/git/docs/howto/recover-corrupted-blob-object.txt">Recovering
3374 Corrupted Blobs by Linus</ulink></para>
3375 </sect2><sect2 id="Submodule"><title>Submodules</title>
3376 <para>Large projects are often composed of smaller, self-contained
3377 modules. For example, an embedded Linux distribution's source tree
3378 would include every piece of software in the distribution with some
3379 local modifications; a movie player might need to build against a
3380 specific, known-working version of a decompression library; several
3381 independent programs might all share the same build scripts.</para>
3382 <para>With centralized revision control systems this is often
3383 accomplished by including every module in one single repository.
3384 Developers can check out all modules or only the modules they need
3385 to work with. They can even modify files across several modules in
3386 a single commit while moving things around or updating APIs and
3387 translations.</para>
3388 <para>Git does not allow partial checkouts, so duplicating this
3389 approach in Git would force developers to keep a local copy of
3390 modules they are not interested in touching. Commits in an enormous
3391 checkout would be slower than you'd expect as Git would have to
3392 scan every directory for changes. If modules have a lot of local
3393 history, clones would take forever.</para>
3394 <para>On the plus side, distributed revision control systems can
3395 much better integrate with external sources. In a centralized
3396 model, a single arbitrary snapshot of the external project is
3397 exported from its own revision control and then imported into the
3398 local revision control on a vendor branch. All the history is
3399 hidden. With distributed revision control you can clone the entire
3400 external history and much more easily follow development and
3401 re-merge local changes.</para>
3402 <para>Git's submodule support allows a repository to contain, as a
3403 subdirectory, a checkout of an external project. Submodules
3404 maintain their own identity; the submodule support just stores the
3405 submodule repository location and commit ID, so other developers
3406 who clone the containing project ("superproject") can easily clone
3407 all the submodules at the same revision. Partial checkouts of the
3408 superproject are possible: you can tell Git to clone none, some or
3409 all of the submodules.</para>
3411 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-submodule.html">git
3412 submodule</ulink> command is available since Git 1.5.3. Users with
3413 Git 1.5.2 can look up the submodule commits in the repository and
3414 manually check them out; earlier versions won't recognize the
3415 submodules at all.</para>
3416 <para>To see how submodule support works, create (for example) four
3417 example repositories that can be used later as a submodule:</para>
3419 <literal>$ mkdir ~/git
3426 echo "module $i" > $i.txt
3428 git commit -m "Initial commit, submodule $i"
3434 <para>Now create the superproject and add all the
3437 <literal>$ mkdir super
3442 git submodule add ~/git/$i $i
3447 <para>NOTE: Do not use local URLs here if you plan to publish your
3448 superproject!</para>
3449 <para>See what files <literal>git-submodule</literal>
3453 . .. .git .gitmodules a b c d
3457 <para>The <literal>git-submodule add</literal> command does a
3458 couple of things:</para>
3460 <listitem>It clones the submodule under the current directory and
3461 by default checks out the master branch.</listitem>
3462 <listitem>It adds the submodule's clone path to the
3463 <para><ulink url="http://www.kernel.org/pub/software/scm/git/docs/gitmodules.html">gitmodules</ulink></para>
3464 file and adds this file to the index, ready to be
3465 committed.</listitem>
3466 <listitem>It adds the submodule's current commit ID to the index,
3467 ready to be committed.</listitem>
3469 <para>Commit the superproject:</para>
3471 <literal>$ git commit -m "Add submodules a, b, c and d."
3475 <para>Now clone the superproject:</para>
3478 $ git clone super cloned
3483 <para>The submodule directories are there, but they're
3488 $ git submodule status
3489 -d266b9873ad50488163457f025db7cdd9683d88b a
3490 -e81d457da15309b4fef4249aba9b50187999670d b
3491 -c1536a972b9affea0f16e0680ba87332dc059146 c
3492 -d96249ff5d57de5de093e6baff9e0aafa5276a74 d
3496 <para>NOTE: The commit object names shown above would be different
3497 for you, but they should match the HEAD commit object names of your
3498 repositories. You can check it by running <literal>git ls-remote
3499 ../git/a</literal>.</para>
3500 <para>Pulling down the submodules is a two-step process. First run
3501 <literal>git submodule init</literal> to add the submodule
3502 repository URLs to <literal>.git/config</literal>:</para>
3504 <literal>$ git submodule init
3508 <para>Now use <literal>git-submodule update</literal> to clone the
3509 repositories and check out the commits specified in the
3510 superproject:</para>
3512 <literal>$ git submodule update
3519 <para>One major difference between <literal>git-submodule
3520 update</literal> and <literal>git-submodule add</literal> is that
3521 <literal>git-submodule update</literal> checks out a specific
3522 commit, rather than the tip of a branch. It's like checking out a
3523 tag: the head is detached, so you're not working on a
3526 <literal>$ git branch
3532 <para>If you want to make a change within a submodule and you have
3533 a detached head, then you should create or checkout a branch, make
3534 your changes, publish the change within the submodule, and then
3535 update the superproject to reference the new commit:</para>
3537 <literal>$ git checkout master
3543 <literal>$ git checkout -b fix-up
3549 <literal>$ echo "adding a line again" >> a.txt
3550 $ git commit -a -m "Updated the submodule from within the superproject."
3555 index d266b98..261dfac 160000
3559 -Subproject commit d266b9873ad50488163457f025db7cdd9683d88b
3560 +Subproject commit 261dfac35cb99d380eb966e102c1197139f7fa24
3562 $ git commit -m "Updated submodule a."
3567 <para>You have to run <literal>git submodule update</literal> after
3568 <literal>git pull</literal> if you want to update submodules,
3570 <sect3 id="Pitfalls_with_submodule"><title>Pitfalls with
3572 <para>Always publish the submodule change before publishing the
3573 change to the superproject that references it. If you forget to
3574 publish the submodule change, others won't be able to clone the
3577 <literal>$ cd ~/git/super/a
3578 $ echo i added another line to this file >> a.txt
3579 $ git commit -a -m "doing it wrong this time"
3582 $ git commit -m "Updated submodule a again."
3586 $ git submodule update
3587 error: pathspec '261dfac35cb99d380eb966e102c1197139f7fa24' did not match any file(s) known to git.
3588 Did you forget to 'git add'?
3589 Unable to checkout '261dfac35cb99d380eb966e102c1197139f7fa24' in submodule path 'a'
3593 <para>If you are staging an updated submodule for commit manually,
3594 be careful to not add a trailing slash when specifying the path.
3595 With the slash appended, Git will assume you are removing the
3596 submodule and checking that directory's contents into the
3597 containing repository.</para>
3599 <literal>$ cd ~/git/super/a
3600 $ echo i added another line to this file >> a.txt
3601 $ git commit -a -m "doing it wrong this time"
3606 # Changes to be committed:
3607 # (use "git reset HEAD <file>..." to unstage)
3612 # Modified submodules:
3614 # * a aa5c351...0000000 (1):
3615 # < Initial commit, submodule a
3620 <para>To fix the index after performing this operation, reset the
3621 changes and then add the submodule without the trailing
3624 <literal>$ git reset HEAD A
3628 # Changes to be committed:
3629 # (use "git reset HEAD <file>..." to unstage)
3633 # Modified submodules:
3635 # * a aa5c351...8d3ba36 (1):
3636 # > doing it wrong this time
3641 <para>You also should not rewind branches in a submodule beyond
3642 commits that were ever recorded in any superproject.</para>
3643 <para>It's not safe to run <literal>git submodule update</literal>
3644 if you've made and committed changes within a submodule without
3645 checking out a branch first. They will be silently
3648 <literal>$ cat a.txt
3650 $ echo line added from private2 >> a.txt
3651 $ git commit -a -m "line added inside private2"
3653 $ git submodule update
3654 Submodule path 'a': checked out 'd266b9873ad50488163457f025db7cdd9683d88b'
3661 <para>NOTE: The changes are still visible in the submodule's
3663 <para>This is not the case if you did not commit your
3665 </sect3></sect2></sect1><sect1 id="Working_with_Gi"><title>Working
3667 <sect2 id="Git_on_Window"><title>Git on Windows</title>
3668 <para>(mSysGit)</para>
3669 </sect2><sect2 id="Deploying_with_Gi"><title>Deploying with
3671 <sect3 id="Capistrano_and_Gi"><title>Capistrano and Git</title>
3672 <para><ulink url="http://github.com/guides/deploying-with-capistrano">GitHub
3673 Guide on Deploying with Cap</ulink></para>
3674 <para><ulink url="http://www.vimeo.com/369095">Git and Capistrano
3675 Screencast</ulink></para>
3676 </sect3></sect2><sect2 id="Subversion_Integratio"><title>Subversion
3678 </sect2><sect2 id="SCM_Migratio"><title>SCM Migration</title>
3679 <para>So you've made the decision to move away from your existing
3680 system and convert your whole project to Git. How can you do that
3682 <sect3 id="Importing_Subversio"><title>Importing Subversion</title>
3683 <para>Git comes with a script called git-svn that has a clone
3684 command that will import a subversion repository into a new git
3685 repository. There is also a free tool on the GitHub service that
3686 will do this for you.</para>
3688 <literal>$ git-svn clone http://my-project.googlecode.com/svn/trunk new-project
3692 <para>This will give you a new Git repository with all the history
3693 of the original Subversion repo. This takes a pretty good amount of
3694 time, generally, since it starts with version 1 and checks out and
3695 commits locally every single revision one by one.</para>
3696 </sect3><sect3 id="Importing_Perforc"><title>Importing
3698 <para>In contrib/fast-import you will find the git-p4 script, which
3699 is a Python script that will import a Perforce repository for
3702 <literal>$ ~/git.git/contrib/fast-import/git-p4 clone //depot/project/main@all myproject
3706 </sect3><sect3 id="Importing_Other"><title>Importing Others</title>
3707 <para>These are other SCMs that listed high on the Git Survey,
3708 should find import docs for them. !!TODO!!</para>
3710 <listitem>CVS</listitem>
3712 <para>Mercurial (hg)</para>
3715 <para>Bazaar-NG</para>
3717 <listitem>Darcs</listitem>
3718 <listitem>ClearCase</listitem>
3720 </sect3></sect2><sect2 id="Graphical_Gi"><title>Graphical
3722 <para>Git has a couple of fairly popular Graphial User Interfaces
3723 that can read and/or maniplulate Git repositories.</para>
3724 <sect3 id="Bundled_GUI"><title>Bundled GUIs</title>
3725 <para>Git comes with two major GUI programs written in Tcl/Tk. Gitk
3726 is a repository browser and commit history visualization
3728 <para><ulink url="http://www.kernel.org/pub/software/scm/git/docs/gitk.html">gitk</ulink></para>
3729 <para><ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-gui.html">git
3730 gui</ulink> is a tool that helps you visualize the index
3731 operations, like add, remove and commit. It won't do everything you
3732 can do on the command line, but for many of the basic operations,
3733 it's pretty good.</para>
3734 <para><ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-gui.html">git
3736 </sect3><sect3 id="Third_Party_Project"><title>Third Party
3738 <para>For Mac users, there are
3739 <ulink url="http://gitx.frim.nl/">GitX</ulink> and
3740 <ulink url="http://github.com/Caged/gitnub/wikis">GitNub</ulink></para>
3741 <para>For Linux or other Qt users, there is
3742 <ulink url="http://digilander.libero.it/mcostalba/">QGit</ulink></para>
3743 </sect3></sect2><sect2 id="Hosted_Gi"><title>Hosted Git</title>
3745 <para>repoorcz</para>
3746 </sect2><sect2 id="Alternative_Use"><title>Alternative Uses</title>
3747 <para>ContentDistribution</para>
3749 </sect2><sect2 id="Scripting_and_Gi"><title>Scripting and
3751 <sect3 id="Ruby_and_Gi"><title>Ruby and Git</title>
3753 <para>jgit + jruby</para>
3754 </sect3><sect3 id="PHP_and_Gi"><title>PHP and Git</title>
3755 </sect3><sect3 id="Python_and_Gi"><title>Python and Git</title>
3757 </sect3><sect3 id="Perl_and_Gi"><title>Perl and Git</title>
3758 <para>perlgit</para>
3759 </sect3></sect2><sect2 id="Git_and_Editor"><title>Git and
3761 <para>textmate</para>
3762 <para>eclipse</para>
3763 <para>netbeans</para>
3764 </sect2></sect1><sect1 id="Internals_and_Plumbin"><title>Internals
3765 and Plumbing</title>
3766 <sect2 id="How_Git_Stores_Object"><title>How Git Stores
3768 <para>This chapter goes into detail about how Git physically stores
3770 <para>All objects are stored as compressed contents by their sha
3771 values. They contain the object type, size and contents in a
3772 gzipped format.</para>
3773 <para>There are two formats that Git keeps objects in - loose
3774 objects and packed objects.</para>
3775 <sect3 id="Loose_Object"><title>Loose Objects</title>
3776 <para>Loose objects are the simpler format. It is simply the
3777 compressed data stored in a single file on disk. Every object
3778 written to a seperate file.</para>
3779 <para>If the sha of your object is
3780 <literal>ab04d884140f7b0cf8bbf86d6883869f16a46f65</literal>, then
3781 the file will be stored in the following path:</para>
3783 <literal>GIT_DIR/objects/ab/04d884140f7b0cf8bbf86d6883869f16a46f65
3787 <para>It pulls the first two characters off and uses that as the
3788 subdirectory, so that there are never too many objects in one
3789 directory. The actual file name is the remaining 38
3791 <para>The easiest way to describe exactly how the object data is
3792 stored is this Ruby implementation of object storage:</para>
3794 def put_raw_object(content, type)
3795 size = content.length.to_s
3797 header = "#{type} #{size}\0" # type(space)size(null byte)
3798 store = header + content
3800 sha1 = Digest::SHA1.hexdigest(store)
3801 path = @git_dir + '/' + sha1[0...2] + '/' + sha1[2..40]
3803 if !File.exists?(path)
3804 content = Zlib::Deflate.deflate(store)
3806 FileUtils.mkdir_p(@directory+'/'+sha1[0...2])
3807 File.open(path, 'w') do |f|
3815 </sect3><sect3 id="Packed_Object"><title>Packed Objects</title>
3816 <para>The other format for object storage is the packfile. Since
3817 Git stores each version of each file as a seperate object, it can
3818 get pretty inefficient. Imagine having a file several thousand
3819 lines long and changing a single line. Git will store the second
3820 file in it's entirety, which is a great big waste of space.</para>
3821 <para>In order to save that space, Git utilizes the packfile. This
3822 is a format where Git will only save the part that has changed in
3823 the second file, with a pointer to the file it is similar
3825 <para>When objects are written to disk, it is often in the loose
3826 format, since that format is less expensive to access. However,
3827 eventually you'll want to save the space by packing up the objects
3828 - this is done with the
3829 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-gc.html">git
3830 gc</ulink> command. It will use a rather complicated heuristic to
3831 determine which files are likely most similar and base the deltas
3832 off that analysis. There can be multiple packfiles, they can be
3833 repacked if neccesary
3834 (<ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-repack.html">git
3835 repack</ulink>) or unpacked back into loose files
3836 (<ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-unpack-objects.html">git
3837 unpack-objects</ulink>) relatively easily.</para>
3838 <para>Git will also write out an index file for each packfile that
3839 is much smaller and contains offsets into the packfile to more
3840 quickly find specific objects by sha.</para>
3841 <para>The actual details of the packfile implementation are found
3842 in the Packfile chapter a little later on.</para>
3843 </sect3></sect2><sect2 id="Browsing_Git_Object"><title>Browsing Git
3845 <para>We can ask git about particular objects with the cat-file
3846 command. Note that you can shorten the shas to only a few
3847 characters to save yourself typing all 40 hex digits:</para>
3849 <literal>$ git-cat-file -t 54196cc2
3851 $ git-cat-file commit 54196cc2
3852 tree 92b8b694ffb1675e5975148e1121810081dbdffe
3853 author J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500
3854 committer J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500
3860 <para>A tree can refer to one or more "blob" objects, each
3861 corresponding to a file. In addition, a tree can also refer to
3862 other tree objects, thus creating a directory hierarchy. You can
3863 examine the contents of any tree using ls-tree (remember that a
3864 long enough initial portion of the SHA1 will also work):</para>
3866 <literal>$ git ls-tree 92b8b694
3867 100644 blob 3b18e512dba79e4c8300dd08aeb37f8e728b8dad file.txt
3871 <para>Thus we see that this tree has one file in it. The SHA1 hash
3872 is a reference to that file's data:</para>
3874 <literal>$ git cat-file -t 3b18e512
3879 <para>A "blob" is just file data, which we can also examine with
3882 <literal>$ git cat-file blob 3b18e512
3887 <para>Note that this is the old file data; so the object that git
3888 named in its response to the initial tree was a tree with a
3889 snapshot of the directory state that was recorded by the first
3891 <para>All of these objects are stored under their SHA1 names inside
3892 the git directory:</para>
3894 <literal>$ find .git/objects/
3899 .git/objects/3b/18e512dba79e4c8300dd08aeb37f8e728b8dad
3901 .git/objects/92/b8b694ffb1675e5975148e1121810081dbdffe
3903 .git/objects/54/196cc2703dc165cbd373a65a4dcf22d50ae7f7
3905 .git/objects/a0/423896973644771497bdc03eb99d5281615b51
3907 .git/objects/d0/492b368b66bdabf2ac1fd8c92b39d3db916e59
3909 .git/objects/c4/d59f390b9cfd4318117afde11d601c1085f241
3913 <para>and the contents of these files is just the compressed data
3914 plus a header identifying their length and their type. The type is
3915 either a blob, a tree, a commit, or a tag.</para>
3916 <para>The simplest commit to find is the HEAD commit, which we can
3917 find from .git/HEAD:</para>
3919 <literal>$ cat .git/HEAD
3920 ref: refs/heads/master
3924 <para>As you can see, this tells us which branch we're currently
3925 on, and it tells us this by naming a file under the .git directory,
3926 which itself contains a SHA1 name referring to a commit object,
3927 which we can examine with cat-file:</para>
3929 <literal>$ cat .git/refs/heads/master
3930 c4d59f390b9cfd4318117afde11d601c1085f241
3931 $ git cat-file -t c4d59f39
3933 $ git cat-file commit c4d59f39
3934 tree d0492b368b66bdabf2ac1fd8c92b39d3db916e59
3935 parent 54196cc2703dc165cbd373a65a4dcf22d50ae7f7
3936 author J. Bruce Fields <bfields@puzzle.fieldses.org> 1143418702 -0500
3937 committer J. Bruce Fields <bfields@puzzle.fieldses.org> 1143418702 -0500
3943 <para>The "tree" object here refers to the new state of the
3946 <literal>$ git ls-tree d0492b36
3947 100644 blob a0423896973644771497bdc03eb99d5281615b51 file.txt
3948 $ git cat-file blob a0423896
3953 <para>and the "parent" object refers to the previous commit:</para>
3955 <literal>$ git-cat-file commit 54196cc2
3956 tree 92b8b694ffb1675e5975148e1121810081dbdffe
3957 author J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500
3958 committer J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500
3962 </sect2><sect2 id="Git_Reference"><title>Git References</title>
3963 <para>Branches, remote-tracking branches, and tags are all
3964 references to commits. All references are named with a
3965 slash-separated path name starting with "refs"; the names we've
3966 been using so far are actually shorthand:</para>
3968 <literal>- The branch "test" is short for "refs/heads/test".
3969 - The tag "v2.6.18" is short for "refs/tags/v2.6.18".
3970 - "origin/master" is short for "refs/remotes/origin/master".
3974 <para>The full name is occasionally useful if, for example, there
3975 ever exists a tag and a branch with the same name.</para>
3976 <para>(Newly created refs are actually stored in the .git/refs
3977 directory, under the path given by their name. However, for
3978 efficiency reasons they may also be packed together in a single
3980 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-pack-refs.html">git
3981 pack-refs</ulink>).</para>
3982 <para>As another useful shortcut, the "HEAD" of a repository can be
3983 referred to just using the name of that repository. So, for
3984 example, "origin" is usually a shortcut for the HEAD branch in the
3985 repository "origin".</para>
3986 <para>For the complete list of paths which git checks for
3987 references, and the order it uses to decide which to choose when
3988 there are multiple references with the same shorthand name, see the
3989 "SPECIFYING REVISIONS" section of
3990 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-rev-parse.html">git
3991 rev-parse</ulink>.</para>
3992 <sect3 id="Showing_commits_unique_to_a_given_branc"><title>Showing
3993 commits unique to a given branch</title>
3994 <para>Suppose you would like to see all the commits reachable from
3995 the branch head named "master" but not from any other head in your
3997 <para>We can list all the heads in this repository with
3998 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-show-ref.html">git
3999 show-ref</ulink>:</para>
4001 <literal>$ git show-ref --heads
4002 bf62196b5e363d73353a9dcf094c59595f3153b7 refs/heads/core-tutorial
4003 db768d5504c1bb46f63ee9d6e1772bd047e05bf9 refs/heads/maint
4004 a07157ac624b2524a059a3414e99f6f44bebc1e7 refs/heads/master
4005 24dbc180ea14dc1aebe09f14c8ecf32010690627 refs/heads/tutorial-2
4006 1e87486ae06626c2f31eaa63d26fc0fd646c8af2 refs/heads/tutorial-fixes
4010 <para>We can get just the branch-head names, and remove "master",
4011 with the help of the standard utilities cut and grep:</para>
4013 <literal>$ git show-ref --heads | cut -d' ' -f2 | grep -v '^refs/heads/master'
4014 refs/heads/core-tutorial
4016 refs/heads/tutorial-2
4017 refs/heads/tutorial-fixes
4021 <para>And then we can ask to see all the commits reachable from
4022 master but not from these other heads:</para>
4024 <literal>$ gitk master --not $( git show-ref --heads | cut -d' ' -f2 |
4025 grep -v '^refs/heads/master' )
4029 <para>Obviously, endless variations are possible; for example, to
4030 see all commits reachable from some head but not from any tag in
4031 the repository:</para>
4033 <literal>$ gitk $( git show-ref --heads ) --not $( git show-ref --tags )
4038 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-rev-parse.html">git
4039 rev-parse</ulink> for explanations of commit-selecting syntax such
4040 as <literal>--not</literal>.)</para>
4041 <para>(!!update-ref!!)</para>
4042 </sect3></sect2><sect2 id="The_Git_Inde"><title>The Git
4044 <para>The index is a binary file (generally kept in .git/index)
4045 containing a sorted list of path names, each with permissions and
4046 the SHA1 of a blob object;
4047 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-ls-files.html">git
4048 ls-files</ulink> can show you the contents of the index:</para>
4050 <literal>$ git ls-files --stage
4051 100644 63c918c667fa005ff12ad89437f2fdc80926e21c 0 .gitignore
4052 100644 5529b198e8d14decbe4ad99db3f7fb632de0439d 0 .mailmap
4053 100644 6ff87c4664981e4397625791c8ea3bbb5f2279a3 0 COPYING
4054 100644 a37b2152bd26be2c2289e1f57a292534a51a93c7 0 Documentation/.gitignore
4055 100644 fbefe9a45b00a54b58d94d06eca48b03d40a50e0 0 Documentation/Makefile
4057 100644 2511aef8d89ab52be5ec6a5e46236b4b6bcd07ea 0 xdiff/xtypes.h
4058 100644 2ade97b2574a9f77e7ae4002a4e07a6a38e46d07 0 xdiff/xutils.c
4059 100644 d5de8292e05e7c36c4b68857c1cf9855e3d2f70a 0 xdiff/xutils.h
4063 <para>Note that in older documentation you may see the index called
4064 the "current directory cache" or just the "cache". It has three
4065 important properties:</para>
4068 <para>The index contains all the information necessary to generate
4069 a single (uniquely determined) tree object.</para>
4070 <para>For example, running
4071 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-commit.html">git
4072 commit</ulink> generates this tree object from the index, stores it
4073 in the object database, and uses it as the tree object associated
4074 with the new commit.</para>
4077 <para>The index enables fast comparisons between the tree object it
4078 defines and the working tree.</para>
4079 <para>It does this by storing some additional data for each entry
4080 (such as the last modified time). This data is not displayed above,
4081 and is not stored in the created tree object, but it can be used to
4082 determine quickly which files in the working directory differ from
4083 what was stored in the index, and thus save git from having to read
4084 all of the data from such files to look for changes.</para>
4087 <para>It can efficiently represent information about merge
4088 conflicts between different tree objects, allowing each pathname to
4089 be associated with sufficient information about the trees involved
4090 that you can create a three-way merge between them.</para>
4091 <para>During a merge, the index can store multiple versions of a
4092 single file (called "stages"). The third column in the
4093 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-ls-files.html">git
4094 ls-files</ulink> output above is the stage number, and will take on
4095 values other than 0 for files with merge conflicts.</para>
4099 <para>The index is thus a sort of temporary staging area, which is
4100 filled with a tree which you are in the process of working
4102 </sect2><sect2 id="The_Packfil"><title>The Packfile</title>
4103 <para>This chapter explains in detail, down to the bits, how the
4104 packfile and pack index files are formatted.</para>
4105 <sect3 id="The_Packfile_Inde"><title>The Packfile Index</title>
4106 <para>First off, we have the packfile index, which is basically
4107 just a series of bookmarks into a packfile.</para>
4108 <para>There are two versions of the packfile index - version one,
4109 which is the default in versions of Git earlier than 1.6, and
4110 version two, which is the default from 1.6 forward, but which can
4111 be read by Git versions going back to 1.5.2, and has been further
4112 backported to 1.4.4.5 if you are still on the 1.4 series.</para>
4113 <para>Version 2 also includes a CRC checksum of each object so
4114 compressed data can be copied directly from pack to pack during
4115 repacking without undetected data corruption. Version 2 indexes can
4116 also handle packfiles larger than 4 Gb.</para>
4117 <inlinemediaobject><imageobject>
4118 <imagedata fileref="images/packfile-index.png"/>
4119 </imageobject></inlinemediaobject>
4122 <para>In both formats, the fanout table is simply a way to find the
4123 offset of a particular sha faster within the index file. The
4124 offset/sha1[] tables are sorted by sha1[] values (this is to allow
4125 binary search of this table), and fanout[] table points at the
4126 offset/sha1[] table in a specific way (so that part of the latter
4127 table that covers all hashes that start with a given byte can be
4128 found to avoid 8 iterations of the binary search).</para>
4129 <para>In version 1, the offsets and shas are in the same space,
4130 where in version two, there are seperate tables for the shas, crc
4131 checksums and offsets. At the end of both files are checksum shas
4132 for both the index file and the packfile it references.</para>
4133 <para>Importantly, packfile indexes are <emphasis>not</emphasis>
4134 neccesary to extract objects from a packfile, they are simply used
4135 to <emphasis>quickly</emphasis> retrieve individual objects from a
4136 pack. The packfile format is used in upload-pack and receieve-pack
4137 programs (push and fetch protocols) to transfer objects and there
4138 is no index used then - it can be built after the fact by scanning
4139 the packfile.</para>
4140 </sect3><sect3 id="The_Packfile_Forma"><title>The Packfile
4142 <para>The packfile itself is a very simple format. There is a
4143 header, a series of packed objects (each with it's own header and
4144 body) and then a checksum trailer. The first four bytes is the
4145 string 'PACK', which is sort of used to make sure you're getting
4146 the start of the packfile correctly. This is followed by a 4-byte
4147 packfile version number and then a 4-byte number of entries in that
4148 file. In Ruby, you might read the header data like this:</para>
4150 def read_pack_header
4151 sig = @session.recv(4)
4152 ver = @session.recv(4).unpack("N")[0]
4153 entries = @session.recv(4).unpack("N")[0]
4158 <para>After that, you get a series of packed objects, in order of
4159 thier SHAs which each consist of an object header and object
4160 contents. At the end of the packfile is a 20-byte SHA1 sum of all
4161 the shas (in sorted order) in that packfile.</para>
4162 <inlinemediaobject><imageobject>
4163 <imagedata fileref="images/packfile-format.png"/>
4164 </imageobject></inlinemediaobject>
4167 <para>The object header is a series of one or more 1 byte (8 bit)
4168 hunks that specify the type of object the following data is, and
4169 the size of the data when expanded. Each byte is really 7 bits of
4170 data, with the first bit being used to say if that hunk is the last
4171 one or not before the data starts. If the first bit is a 1, you
4172 will read another byte, otherwise the data starts next. The first 3
4173 bits in the first byte specifies the type of data, according to the
4175 <para>(Currently, of the 8 values that can be expressed with 3 bits
4176 (0-7), 0 (000) is 'undefined' and 5 (101) is not yet used.)</para>
4177 <para>Here, we can see an example of a header of two bytes, where
4178 the first specifies that the following data is a commit, and the
4179 remainder of the first and the last 7 bits of the second specifies
4180 that the data will be 144 bytes when expanded.</para>
4181 <inlinemediaobject><imageobject>
4182 <imagedata fileref="images/packfile-logic.png"/>
4183 </imageobject></inlinemediaobject>
4186 <para>It is important to note that the size specified in the header
4187 data is not the size of the data that actually follows, but the
4188 size of that data <emphasis>when expanded</emphasis>. This is why
4189 the offsets in the packfile index are so useful, otherwise you have
4190 to expand every object just to tell when the next header
4192 <para>The data part is just zlib stream for non-delta object types;
4193 for the two delta object representations, the data portion contains
4194 something that identifies which base object this delta
4195 representation depends on, and the delta to apply on the base
4196 object to resurrect this object. <literal>ref-delta</literal> uses
4197 20-byte hash of the base object at the beginning of data, while
4198 <literal>ofs-delta</literal> stores an offset within the same
4199 packfile to identify the base object. In either case, two important
4200 constraints a reimplementor must adhere to are:</para>
4203 <para>delta representation must be based on some other object
4204 within the same packfile;</para>
4207 <para>the base object must be of the same underlying type (blob,
4208 tree, commit or tag);</para>
4212 <sect2 id="Raw_Gi"><title>Raw Git</title>
4213 <para>Here we will take a look at how to manipulate git at a more
4214 raw level, in case you would like to write a tool that generates
4215 new blobs, trees or commits in a more artificial way. If you want
4216 to write a script that uses more low-level git plumbing to do
4217 something new, here are some of the tools you'll need.</para>
4218 <sect3 id="Creating_Blob"><title>Creating Blobs</title>
4219 <para>Creating a blob in your Git repository and getting a SHA back
4221 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-hash-object.html">git
4222 hash-object</ulink> command is all you'll need. To create a blob
4223 object from an existing file, just run it with the '-w' option
4224 (which tells it to write the blob, not just compute the
4227 <literal>$ git hash-object -w myfile.txt
4228 6ff87c4664981e4397625791c8ea3bbb5f2279a3
4230 $ git hash-object -w myfile2.txt
4231 3bb0e8592a41ae3185ee32266c860714980dbed7
4235 <para>The STDOUT output of the command will the the SHA of the blob
4236 that was created.</para>
4237 </sect3><sect3 id="Creating_Tree"><title>Creating Trees</title>
4238 <para>Now lets say you want to create a tree from your new objects.
4240 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-mktree.html">git
4241 mktree</ulink> command makes it pretty simple to generate new tree
4243 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-ls-tree.html">git
4244 ls-tree</ulink> formatted output. For example, if you write the
4245 following to a file named '/tmp/tree.txt' :</para>
4247 <literal>100644 blob 6ff87c4664981e4397625791c8ea3bbb5f2279a3 file1
4248 100644 blob 3bb0e8592a41ae3185ee32266c860714980dbed7 file2
4252 <para>and then piped that through the
4253 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-mktree.html">git
4254 mktree</ulink> command, Git will write a new tree to the object
4255 database and give you back the new sha of that tree.</para>
4257 <literal>$ cat /tmp/tree.txt | git mk-tree
4258 f66a66ab6a7bfe86d52a66516ace212efa00fe1f
4262 <para>Then, we can take that and make it a subdirectory of yet
4263 another tree, and so on. If we wanted to create a new tree with
4264 that one as a subtree, we just create a new file (/tmp/newtree.txt)
4265 with our new SHA as a tree in it:</para>
4267 <literal>100644 blob 6ff87c4664981e4397625791c8ea3bbb5f2279a3 file1-copy
4268 040000 tree f66a66ab6a7bfe86d52a66516ace212efa00fe1f our_files
4273 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-mk-tree.html">git
4274 mk-tree</ulink> again:</para>
4276 <literal>$ cat /tmp/newtree.txt | git mk-tree
4277 5bac6559179bd543a024d6d187692343e2d8ae83
4281 <para>And we now have an artificial directory structure in Git that
4282 looks like this:</para>
4290 1 directory, 3 files
4294 <para>without that structure ever having actually existed on disk.
4295 Plus, we have a SHA (<literal>5bac6559</literal>) that points to
4297 </sect3><sect3 id="Rearranging_Tree"><title>Rearranging
4299 <para>We can also do tree manipulation by combining trees into new
4300 structures using the index file. As a simple example, let's take
4301 the tree we just created and make a new tree that has two copies of
4302 our <literal>5bac6559</literal> tree in it using a temporary index
4303 file. (You can do this by resetting the GIT_INDEX_FILE environment
4304 variable or on the command line)</para>
4305 <para>First, we read the tree into our index file under a new
4307 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-read-tree.html">git
4308 read-tree</ulink> command, and then write the index contents as a
4310 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-write-tree.html">git
4311 write-tree</ulink> command:</para>
4313 <literal>$ export GIT_INDEX_FILE=/tmp/index
4314 $ git read-tree --prefix=copy1/ 5bac6559
4315 $ git read-tree --prefix=copy2/ 5bac6559
4317 bb2fa6de7625322322382215d9ea78cfe76508c1
4319 $>git ls-tree bb2fa
4320 040000 tree 5bac6559179bd543a024d6d187692343e2d8ae83 copy1
4321 040000 tree 5bac6559179bd543a024d6d187692343e2d8ae83 copy2
4325 <para>So now we can see that we've created a new tree just from
4326 index manipulation. You can also do interesting merge operations
4327 and such in a temporary index this way - see the
4328 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-read-tree.html">git
4329 read-tree</ulink> docs for more information.</para>
4330 </sect3><sect3 id="Creating_Commit"><title>Creating Commits</title>
4331 <para>Now that we have a tree SHA, we can create a commit object
4332 that points to it. We can do this using the
4333 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-commit-tree.html">git
4334 commit-tree</ulink> command. Most of the data that goes into the
4335 commit has to be set as environment variables, so you'll want to
4336 set the following:</para>
4338 <literal>GIT_AUTHOR_NAME
4347 <para>Then you will need to write your commit message to a file or
4348 somehow pipe it into the command through STDIN. Then, you can
4349 create your commit object based on the tree sha we have.</para>
4351 <literal>$ git commit-tree bb2fa < /tmp/message
4352 a5f85ba5875917319471dfd98dfc636c1dc65650
4356 <para>If you want to specify one or more parent commits, simply add
4357 the shas on the command line with a '-p' option before each. The
4358 SHA of the new commit object will be returned via STDOUT.</para>
4359 </sect3><sect3 id="Updating_a_Branch_Re"><title>Updating a Branch
4361 <para>Now that we have a new commit object SHA, we can update a
4362 branch to point to it if we want to. Lets say we want to update our
4363 'master' branch to point to the new commit we just created - we
4365 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-update-ref.html">git
4366 update-ref</ulink> command:</para>
4368 <literal>$ git update-ref refs/heads/master a5f85ba5875917319471dfd98dfc636c1dc65650
4372 </sect3></sect2><sect2 id="Transfer_Protocol"><title>Transfer
4374 <para>Here we will go over how clients and servers talk to each
4375 other to transfer Git data around.</para>
4376 <sect3 id="Fetching_Data_over_HTT"><title>Fetching Data over
4378 <para>Fetching over an http/s URL will make Git use a slightly
4379 dumber protocol. In this case, all of the logic is entirely on the
4380 client side. The server requires no special setup - any static
4381 webserver will work fine if the git directory you are fetching from
4382 is in the webserver path.</para>
4383 <para>In order for this to work, you do need to run a single
4384 command on the server repo everytime anything is updated, though -
4385 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-update-server-info.html">git
4386 update-server-info</ulink>, which updates the objects/info/packs
4387 and info/refs files to list which refs and packfiles are available,
4388 since you can't do a listing over http. When that command is run,
4389 the objects/info/packs file looks something like this:</para>
4391 <literal>P pack-ce2bd34abc3d8ebc5922dc81b2e1f30bf17c10cc.pack
4392 P pack-7ad5f5d05f5e20025898c95296fe4b9c861246d8.pack
4396 <para>So that if the fetch can't find a loose file, it can try
4397 these packfiles. The info/refs file will look something like
4400 <literal>184063c9b594f8968d61a686b2f6052779551613 refs/heads/development
4401 32aae7aef7a412d62192f710f2130302997ec883 refs/heads/master
4405 <para>Then when you fetch from this repo, it will start with these
4406 refs and walk the commit objects until the client has all the
4407 objects that it needs.</para>
4408 <para>For instance, if you ask to fetch the master branch, it will
4409 see that master is pointing to <literal>32aae7ae</literal> and that
4410 your master is pointing to <literal>ab04d88</literal>, so you need
4411 <literal>32aae7ae</literal>. You fetch that object</para>
4413 <literal>CONNECT http://myserver.com
4414 GET /git/myproject.git/objects/32/aae7aef7a412d62192f710f2130302997ec883 - 200
4418 <para>and it looks like this:</para>
4420 <literal>tree aa176fb83a47d00386be237b450fb9dfb5be251a
4421 parent bd71cad2d597d0f1827d4a3f67bb96a646f02889
4422 author Scott Chacon <schacon@gmail.com> 1220463037 -0700
4423 committer Scott Chacon <schacon@gmail.com> 1220463037 -0700
4425 added chapters on private repo setup, scm migration, raw git
4429 <para>So now it fetches the tree
4430 <literal>aa176fb8</literal>:</para>
4432 <literal>GET /git/myproject.git/objects/aa/176fb83a47d00386be237b450fb9dfb5be251a - 200
4436 <para>which looks like this:</para>
4438 <literal>100644 blob 6ff87c4664981e4397625791c8ea3bbb5f2279a3 COPYING
4439 100644 blob 97b51a6d3685b093cfb345c9e79516e5099a13fb README
4440 100644 blob 9d1b23b8660817e4a74006f15fae86e2a508c573 Rakefile
4444 <para>So then it fetches those objects:</para>
4446 <literal>GET /git/myproject.git/objects/6f/f87c4664981e4397625791c8ea3bbb5f2279a3 - 200
4447 GET /git/myproject.git/objects/97/b51a6d3685b093cfb345c9e79516e5099a13fb - 200
4448 GET /git/myproject.git/objects/9d/1b23b8660817e4a74006f15fae86e2a508c573 - 200
4452 <para>It actually does this with Curl, and can open up multiple
4453 parallel threads to speed up this process. When it's done recursing
4454 the tree pointed to by the commit, it fetches the next
4457 <literal>GET /git/myproject.git/objects/bd/71cad2d597d0f1827d4a3f67bb96a646f02889 - 200
4461 <para>Now in this case, the commit that comes back looks like
4464 <literal>tree b4cc00cf8546edd4fcf29defc3aec14de53e6cf8
4465 parent ab04d884140f7b0cf8bbf86d6883869f16a46f65
4466 author Scott Chacon <schacon@gmail.com> 1220421161 -0700
4467 committer Scott Chacon <schacon@gmail.com> 1220421161 -0700
4469 added chapters on the packfile and how git stores objects
4473 <para>and we can see that the parent, <literal>ab04d88</literal> is
4474 where our master branch is currently pointing. So, we recursively
4475 fetch this tree and then stop, since we know we have everything
4476 before this point. You can force Git to double check that we have
4477 everything with the '--recover' option. See
4478 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-http-fetch.html">git
4479 http-fetch</ulink> for more information.</para>
4480 <para>If one of the loose object fetches fails, Git will download
4481 the packfile indexes looking for the sha that it needs, then
4482 download that packfile.</para>
4483 <para>It is important if you are running a git server that serves
4484 repos this way to implement a post-receive hook that runs the 'git
4485 update-server-info' command each time or there will be
4487 </sect3><sect3 id="Fetching_Data_with_Upload_Pac"><title>Fetching
4488 Data with Upload Pack</title>
4489 <para>For the smarter protocols, fetching objects is much more
4490 efficient. A socket is opened, either over ssh or over port 9418
4491 (in the case of the git:// protocol), and the
4492 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-fetch-pack.html">git
4493 fetch-pack</ulink> command on the client begins communicating with
4495 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-upload-pack.html">git
4496 upload-pack</ulink> process on the server.</para>
4497 <para>Then the server will tell the client which SHAs it has for
4498 each ref, and the client figures out what it needs and responds
4499 with a list of SHAs it wants and already has.</para>
4500 <para>At this point, the server will generate a packfile with all
4501 the objects that the client needs and begin streaming it down to
4503 <para>Let's look at an example.</para>
4504 <para>The client connects and sends the request header. The clone
4507 <literal>$ git clone git://myserver.com/project.git
4511 <para>produces the following request:</para>
4513 <literal>0032git-upload-pack /project.git\000host=myserver.com\000
4517 <para>The first four bytes contain the hex length of the line
4518 (including 4 byte line length and trailing newline if present).
4519 Following are the command and arguments. This is followed by a null
4520 byte and then the host information. The request is terminated by a
4522 <para>The request is processed and turned into a call to
4523 git-upload-pack:</para>
4525 <literal>$ git-upload-pack /path/to/repos/project.git
4529 <para>This immediately returns information of the repo:</para>
4531 <literal>007c74730d410fcb6603ace96f1dc55ea6196122532d HEAD\000multi_ack thin-pack side-band side-band-64k ofs-delta shallow no-progress
4532 003e7d1665144a3a975c05f1f43902ddaf084e784dbe refs/heads/debug
4533 003d5a3f6be755bbb7deae50065988cbfa1ffa9ab68a refs/heads/dist
4534 003e7e47fe2bd8d01d481f44d7af0531bd93d3b21c01 refs/heads/local
4535 003f74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/master
4540 <para>Each line starts with a four byte line length declaration in
4541 hex. The section is terminated by a line length declaration of
4543 <para>This is sent back to the client verbatim. The client responds
4544 with another request:</para>
4546 <literal>0054want 74730d410fcb6603ace96f1dc55ea6196122532d multi_ack side-band-64k ofs-delta
4547 0032want 7d1665144a3a975c05f1f43902ddaf084e784dbe
4548 0032want 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a
4549 0032want 7e47fe2bd8d01d481f44d7af0531bd93d3b21c01
4550 0032want 74730d410fcb6603ace96f1dc55ea6196122532d
4555 <para>The is sent to the open git-upload-pack process which then
4556 streams out the final response:</para>
4558 <literal>"0008NAK\n"
4559 "0023\002Counting objects: 2797, done.\n"
4560 "002b\002Compressing objects: 0% (1/1177) \r"
4561 "002c\002Compressing objects: 1% (12/1177) \r"
4562 "002c\002Compressing objects: 2% (24/1177) \r"
4563 "002c\002Compressing objects: 3% (36/1177) \r"
4564 "002c\002Compressing objects: 4% (48/1177) \r"
4565 "002c\002Compressing objects: 5% (59/1177) \r"
4566 "002c\002Compressing objects: 6% (71/1177) \r"
4567 "0053\002Compressing objects: 7% (83/1177) \rCompressing objects: 8% (95/1177) \r"
4569 "005b\002Compressing objects: 100% (1177/1177) \rCompressing objects: 100% (1177/1177), done.\n"
4570 "2004\001PACK\000\000\000\002\000\000\n\355\225\017x\234\235\216K\n\302"...
4571 "2005\001\360\204{\225\376\330\345]z2673"...
4573 "0037\002Total 2797 (delta 1799), reused 2360 (delta 1529)\n"
4575 "<\276\255L\273s\005\001w0006\001[0000"
4579 <para>See the Packfile chapter previously for the actual format of
4580 the packfile data in the response.</para>
4581 </sect3><sect3 id="Pushing_Dat"><title>Pushing Data</title>
4582 <para>Pushing data over the git and ssh protocols is similar, but
4583 simpler. Basically what happens is the client requests a
4584 receive-pack instance, which is started up if the client has
4585 access, then the server returns all the ref head shas it has again
4586 and the client generates a packfile of everything the server needs
4587 (generally only if what is on the server is a direct ancestor of
4588 what it is pushing) and sends that packfile upstream, where the
4589 server either stores it on disk and builds an index for it, or
4590 unpacks it (if there aren't many objects in it)</para>
4591 <para>This entire process is accomplished through the
4592 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-send-pack.html">git
4593 send-pack</ulink> command on the client, which is invoked by
4594 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-push.html">git
4595 push</ulink> and the
4596 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-receive-pack.html">git
4597 receive-pack</ulink> command on the server side, which is invoked
4598 by the ssh connect process or git daemon (if it's an open push
4600 </sect3></sect2><sect2 id="Glossar"><title>Glossary</title>
4601 <para>Here we have the meanings of some terms used into Git
4602 context.These terms were entirely copied from
4603 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/gitglossary.html">Git
4604 Glossary</ulink>.</para>
4605 <para><emphasis>alternate object database</emphasis></para>
4607 <para>Via the alternates mechanism, a repository</para>
4609 <literal>can inherit part of its object database
4610 from another object database, which is called "alternate".
4614 <para><emphasis>bare repository</emphasis></para>
4616 <para>A bare repository is normally an appropriately</para>
4618 <literal>named directory with a `.git` suffix that does not
4619 have a locally checked-out copy of any of the files under
4620 revision control. That is, all of the `git`
4621 administrative and control files that would normally be present in the
4622 hidden `.git` sub-directory are directly present in the
4623 `repository.git` directory instead,
4624 and no other files are present and checked out. Usually publishers of
4625 public repositories make bare repositories available.
4629 <para><emphasis>blob object</emphasis></para>
4631 <para>Untyped object, e.g. the contents of a file.</para>
4633 <para><emphasis>branch</emphasis></para>
4635 <para>A "branch" is an active line of development. The most
4638 <literal>commit on a branch is referred to as the tip of
4639 that branch. The tip of the branch is referenced by a branch
4640 head, which moves forward as additional development
4641 is done on the branch. A single git
4642 repository can track an arbitrary number of
4643 branches, but your working tree is
4644 associated with just one of them (the "current" or "checked out"
4645 branch), and HEAD points to that branch.
4649 <para><emphasis>cache</emphasis></para>
4651 <para>Obsolete for: index.</para>
4653 <para><emphasis>chain</emphasis></para>
4655 <para>A list of objects, where each object in the list
4658 <literal>a reference to its successor (for example, the successor of a
4659 commit could be one of its parents).
4663 <para><emphasis>changeset</emphasis></para>
4665 <para>BitKeeper/cvsps speak for "commit". Since git does not</para>
4667 <literal>store changes, but states, it really does not make sense to use the term
4668 "changesets" with git.
4672 <para><emphasis>checkout</emphasis></para>
4674 <para>The action of updating all or part of the</para>
4676 <literal>working tree with a tree object
4678 object database, and updating the
4679 index and HEAD if the whole working tree has
4680 been pointed at a new branch.
4684 <para><emphasis>cherry-picking</emphasis></para>
4686 <para>In SCM jargon, "cherry pick" means to choose a subset
4689 <literal>changes out of a series of changes (typically commits) and record them
4690 as a new series of changes on top of a different codebase. In GIT, this is
4691 performed by the "git cherry-pick" command to extract the change introduced
4692 by an existing commit and to record it based on the tip
4693 of the current branch as a new commit.
4697 <para><emphasis>clean</emphasis></para>
4699 <para>A working tree is clean, if it</para>
4701 <literal>corresponds to the revision referenced by the current
4702 head. Also see "dirty".
4706 <para><emphasis>commit</emphasis></para>
4708 <para>As a noun: A single point in the</para>
4710 <literal>git history; the entire history of a project is represented as a
4711 set of interrelated commits. The word "commit" is often
4712 used by git in the same places other revision control systems
4713 use the words "revision" or "version". Also used as a short
4714 hand for commit object.
4718 <para>As a verb: The action of storing a new snapshot of the
4721 <literal>state in the git history, by creating a new commit representing the current
4722 state of the index and advancing HEAD
4723 to point at the new commit.
4727 <para><emphasis>commit object</emphasis></para>
4729 <para>An object which contains the information about a</para>
4731 <literal>particular revision, such as parents, committer,
4732 author, date and the tree object which corresponds
4733 to the top directory of the stored
4738 <para><emphasis>core git</emphasis></para>
4740 <para>Fundamental data structures and utilities of git. Exposes
4743 <literal>source code management tools.
4747 <para><emphasis>DAG</emphasis></para>
4749 <para>Directed acyclic graph. The commit objects form a</para>
4751 <literal>directed acyclic graph, because they have parents (directed), and the
4752 graph of commit objects is acyclic (there is no chain
4753 which begins and ends with the same object).
4757 <para><emphasis>dangling object</emphasis></para>
4759 <para>An unreachable object which is not</para>
4761 <literal>reachable even from other unreachable objects; a
4762 dangling object has no references to it from any
4763 reference or object in the repository.
4767 <para><emphasis>detached HEAD</emphasis></para>
4769 <para>Normally the HEAD stores the name of a</para>
4771 <literal>branch. However, git also allows you to check out
4772 an arbitrary commit that isn't necessarily the tip of any
4773 particular branch. In this case HEAD is said to be "detached".
4777 <para><emphasis>dircache</emphasis></para>
4779 <para>You are <emphasis>waaaaay</emphasis> behind. See
4782 <para><emphasis>directory</emphasis></para>
4784 <para>The list you get with "ls" :-)</para>
4786 <para><emphasis>dirty</emphasis></para>
4788 <para>A working tree is said to be "dirty" if</para>
4790 <literal>it contains modifications which have not been committed to the current
4795 <para><emphasis>ent</emphasis></para>
4797 <para>Favorite synonym to "tree-ish" by some total geeks.
4800 <literal>`http://en.wikipedia.org/wiki/Ent_(Middle-earth)` for an in-depth
4801 explanation. Avoid this term, not to confuse people.
4805 <para><emphasis>evil merge</emphasis></para>
4807 <para>An evil merge is a merge that introduces changes that</para>
4809 <literal>do not appear in any parent.
4813 <para><emphasis>fast forward</emphasis></para>
4815 <para>A fast-forward is a special type of merge where you have
4818 <literal>revision and you are "merging" another
4819 branch's changes that happen to be a descendant of what
4820 you have. In such these cases, you do not make a new merge
4821 commit but instead just update to his
4822 revision. This will happen frequently on a
4823 tracking branch of a remote
4828 <para><emphasis>fetch</emphasis></para>
4830 <para>Fetching a branch means to get the</para>
4832 <literal>branch's head ref from a remote
4833 repository, to find out which objects are
4834 missing from the local object database,
4835 and to get them, too. See also <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-fetch.html">git fetch</ulink>.
4839 <para><emphasis>file system</emphasis></para>
4841 <para>Linus Torvalds originally designed git to be a user space
4844 <literal>i.e. the infrastructure to hold files and directories. That ensured the
4845 efficiency and speed of git.
4849 <para><emphasis>git archive</emphasis></para>
4851 <para>Synonym for repository (for arch people).</para>
4853 <para><emphasis>grafts</emphasis></para>
4855 <para>Grafts enables two otherwise different lines of development
4858 <literal>together by recording fake ancestry information for commits. This way
4859 you can make git pretend the set of parents a commit has
4860 is different from what was recorded when the commit was
4861 created. Configured via the `.git/info/grafts` file.
4865 <para><emphasis>hash</emphasis></para>
4867 <para>In git's context, synonym to object name.</para>
4869 <para><emphasis>head</emphasis></para>
4871 <para>A named reference to the commit at the tip of a</para>
4873 <literal>branch. Heads are stored in
4874 `$GIT_DIR/refs/heads/`, except when using packed refs. (See
4875 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-pack-refs.html">git pack-refs</ulink>.)
4879 <para><emphasis>HEAD</emphasis></para>
4881 <para>The current branch. In more detail: Your working tree is
4882 normally derived</para>
4884 <literal>from the state of the tree referred to by HEAD. HEAD is a reference to one
4885 of the heads in your repository, except when using a detached HEAD, in which
4886 case it may reference an arbitrary commit.
4890 <para><emphasis>head ref</emphasis></para>
4892 <para>A synonym for head.</para>
4894 <para><emphasis>hook</emphasis></para>
4896 <para>During the normal execution of several git commands,
4897 call-outs are made</para>
4899 <literal>to optional scripts that allow a developer to add functionality or
4900 checking. Typically, the hooks allow for a command to be pre-verified
4901 and potentially aborted, and allow for a post-notification after the
4902 operation is done. The hook scripts are found in the
4903 `$GIT_DIR/hooks/` directory, and are enabled by simply
4904 removing the `.sample` suffix from the filename. In earlier versions
4905 of git you had to make them executable.
4909 <para><emphasis>index</emphasis></para>
4911 <para>A collection of files with stat information, whose contents
4914 <literal>as objects. The index is a stored version of your
4915 working tree. Truth be told, it can also contain a second, and even
4916 a third version of a working tree, which are used
4921 <para><emphasis>index entry</emphasis></para>
4923 <para>The information regarding a particular file, stored in
4926 <literal>index. An index entry can be unmerged, if a
4927 merge was started, but not yet finished (i.e. if
4928 the index contains multiple versions of that file).
4932 <para><emphasis>master</emphasis></para>
4934 <para>The default development branch. Whenever you</para>
4936 <literal>create a git repository, a branch named
4937 "master" is created, and becomes the active branch. In most
4938 cases, this contains the local development, though that is
4939 purely by convention and is not required.
4943 <para><emphasis>merge</emphasis></para>
4945 <para>As a verb: To bring the contents of another</para>
4947 <literal>branch (possibly from an external
4948 repository) into the current branch. In the
4949 case where the merged-in branch is from a different repository,
4950 this is done by first fetching the remote branch
4951 and then merging the result into the current branch. This
4952 combination of fetch and merge operations is called a
4953 pull. Merging is performed by an automatic process
4954 that identifies changes made since the branches diverged, and
4955 then applies all those changes together. In cases where changes
4956 conflict, manual intervention may be required to complete the
4961 <para>As a noun: unless it is a fast forward, a</para>
4963 <literal>successful merge results in the creation of a new commit
4964 representing the result of the merge, and having as
4965 parents the tips of the merged branches.
4966 This commit is referred to as a "merge commit", or sometimes just a
4971 <para><emphasis>object</emphasis></para>
4973 <para>The unit of storage in git. It is uniquely identified by
4976 <literal>SHA1> of its contents. Consequently, an
4977 object can not be changed.
4981 <para><emphasis>object database</emphasis></para>
4983 <para>Stores a set of "objects", and an individual object is</para>
4985 <literal>identified by its object name. The objects usually
4986 live in `$GIT_DIR/objects/`.
4990 <para><emphasis>object identifier</emphasis></para>
4992 <para>Synonym for object name.</para>
4994 <para><emphasis>object name</emphasis></para>
4996 <para>The unique identifier of an object. The hash</para>
4998 <literal>of the object's contents using the Secure Hash Algorithm
4999 1 and usually represented by the 40 character hexadecimal encoding of
5000 the hash of the object.
5004 <para><emphasis>object type</emphasis></para>
5006 <para>One of the identifiers "commit", "tree", "tag" or "blob"
5007 describing the</para>
5009 <literal>type of an object.
5013 <para><emphasis>octopus</emphasis></para>
5015 <para>To merge more than two branches. Also denotes an</para>
5017 <literal>intelligent predator.
5021 <para><emphasis>origin</emphasis></para>
5023 <para>The default upstream repository. Most projects have</para>
5025 <literal>at least one upstream project which they track. By default
5026 'origin' is used for that purpose. New upstream updates
5027 will be fetched into remote tracking branches named
5028 origin/name-of-upstream-branch, which you can see using
5033 <para><emphasis>pack</emphasis></para>
5035 <para>A set of objects which have been compressed into one file (to
5038 <literal>or to transmit them efficiently).
5042 <para><emphasis>pack index</emphasis></para>
5044 <para>The list of identifiers, and other information, of the
5047 <literal>pack, to assist in efficiently accessing the contents of a
5052 <para><emphasis>parent</emphasis></para>
5054 <para>A commit object contains a (possibly empty) list</para>
5056 <literal>of the logical predecessor(s) in the line of development, i.e. its
5061 <para><emphasis>pickaxe</emphasis></para>
5063 <para>The term pickaxe refers to an option to the diffcore</para>
5065 <literal>routines that help select changes that add or delete a given text
5066 string. With the `--pickaxe-all` option, it can be used to view the full
5067 changeset that introduced or removed, say, a
5068 particular line of text. See <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-diff.html">git diff</ulink>.
5072 <para><emphasis>plumbing</emphasis></para>
5074 <para>Cute name for core git.</para>
5076 <para><emphasis>porcelain</emphasis></para>
5078 <para>Cute name for programs and program suites depending on</para>
5080 <literal>core git, presenting a high level access to
5081 core git. Porcelains expose more of a SCM
5082 interface than the plumbing.
5086 <para><emphasis>pull</emphasis></para>
5088 <para>Pulling a branch means to fetch it and</para>
5090 <literal>merge it. See also <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-pull.html">git pull</ulink>.
5094 <para><emphasis>push</emphasis></para>
5096 <para>Pushing a branch means to get the branch's</para>
5098 <literal>head ref from a remote repository,
5099 find out if it is a direct ancestor to the branch's local
5100 head ref, and in that case, putting all
5101 objects, which are reachable from the local
5102 head ref, and which are missing from the remote
5103 repository, into the remote
5104 object database, and updating the remote
5105 head ref. If the remote head is not an
5106 ancestor to the local head, the push fails.
5110 <para><emphasis>reachable</emphasis></para>
5112 <para>All of the ancestors of a given commit are said to be</para>
5114 <literal>"reachable" from that commit. More
5115 generally, one object is reachable from
5116 another if we can reach the one from the other by a chain
5117 that follows tags to whatever they tag,
5118 commits to their parents or trees, and
5119 trees to the trees or blobs
5124 <para><emphasis>rebase</emphasis></para>
5126 <para>To reapply a series of changes from a branch to a</para>
5128 <literal>different base, and reset the head of that branch
5133 <para><emphasis>ref</emphasis></para>
5135 <para>A 40-byte hex representation of a SHA1 or a name that</para>
5137 <literal>denotes a particular object. These may be stored in
5142 <para><emphasis>reflog</emphasis></para>
5144 <para>A reflog shows the local "history" of a ref. In other
5147 <literal>it can tell you what the 3rd last revision in _this_ repository
5148 was, and what was the current state in _this_ repository,
5149 yesterday 9:14pm. See <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-reflog.html">git reflog</ulink> for details.
5153 <para><emphasis>refspec</emphasis></para>
5155 <para>A "refspec" is used by fetch and</para>
5157 <literal>push to describe the mapping between remote
5158 ref and local ref. They are combined with a colon in
5159 the format <src>:<dst>, preceded by an optional plus sign, +.
5160 For example: `git fetch $URL
5161 refs/heads/master:refs/heads/origin` means "grab the master
5162 branch head from the $URL and store
5163 it as my origin branch head". And `git push
5164 $URL refs/heads/master:refs/heads/to-upstream` means "publish my
5165 master branch head as to-upstream branch at $URL". See also
5166 <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-push.html">git push</ulink>.
5170 <para><emphasis>repository</emphasis></para>
5172 <para>A collection of refs together with an</para>
5174 <literal>object database containing all objects
5175 which are reachable from the refs, possibly
5176 accompanied by meta data from one or more porcelains. A
5177 repository can share an object database with other repositories
5178 via alternates mechanism.
5182 <para><emphasis>resolve</emphasis></para>
5184 <para>The action of fixing up manually what a failed
5187 <literal>merge left behind.
5191 <para><emphasis>revision</emphasis></para>
5193 <para>A particular state of files and directories which was stored
5196 <literal>object database. It is referenced by a
5201 <para><emphasis>rewind</emphasis></para>
5203 <para>To throw away part of the development, i.e. to assign
5206 <literal>head to an earlier revision.
5210 <para><emphasis>SCM</emphasis></para>
5212 <para>Source code management (tool).</para>
5214 <para><emphasis>SHA1</emphasis></para>
5216 <para>Synonym for object name.</para>
5218 <para><emphasis>shallow repository</emphasis></para>
5220 <para>A shallow repository has an incomplete</para>
5222 <literal>history some of whose commits have parents cauterized away (in other
5223 words, git is told to pretend that these commits do not have the
5224 parents, even though they are recorded in the commit
5225 object). This is sometimes useful when you are interested only in the
5226 recent history of a project even though the real history recorded in the
5227 upstream is much larger. A shallow repository
5228 is created by giving the `--depth` option to <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-clone.html">git clone</ulink>, and
5229 its history can be later deepened with <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-fetch.html">git fetch</ulink>.
5233 <para><emphasis>symref</emphasis></para>
5235 <para>Symbolic reference: instead of containing the SHA1</para>
5237 <literal>id itself, it is of the format 'ref: refs/some/thing' and when
5238 referenced, it recursively dereferences to this reference.
5239 'HEAD' is a prime example of a symref. Symbolic
5240 references are manipulated with the <ulink url="http://www.kernel.org/pub/software/scm/git/docs/git-symbolic-ref.html">git symbolic-ref</ulink>
5245 <para><emphasis>tag</emphasis></para>
5247 <para>A ref pointing to a tag or</para>
5249 <literal>commit object. In contrast to a head,
5250 a tag is not changed by a commit. Tags (not
5251 tag objects) are stored in `$GIT_DIR/refs/tags/`. A
5252 git tag has nothing to do with a Lisp tag (which would be
5253 called an object type in git's context). A
5254 tag is most typically used to mark a particular point in the
5255 commit ancestry chain.
5259 <para><emphasis>tag object</emphasis></para>
5261 <para>An object containing a ref pointing to</para>
5263 <literal>another object, which can contain a message just like a
5264 commit object. It can also contain a (PGP)
5265 signature, in which case it is called a "signed tag object".
5269 <para><emphasis>topic branch</emphasis></para>
5271 <para>A regular git branch that is used by a developer to</para>
5273 <literal>identify a conceptual line of development. Since branches are very easy
5274 and inexpensive, it is often desirable to have several small branches
5275 that each contain very well defined concepts or small incremental yet
5280 <para><emphasis>tracking branch</emphasis></para>
5282 <para>A regular git branch that is used to follow changes
5285 <literal>another repository. A tracking
5286 branch should not contain direct modifications or have local commits
5287 made to it. A tracking branch can usually be
5288 identified as the right-hand-side ref in a Pull:
5293 <para><emphasis>tree</emphasis></para>
5295 <para>Either a working tree, or a tree object together with the
5298 <literal>blob and tree objects (i.e. a stored representation of a working tree).
5302 <para><emphasis>tree object</emphasis></para>
5304 <para>An object containing a list of file names and modes
5307 <literal>with refs to the associated blob and/or tree objects. A
5308 tree is equivalent to a directory.
5312 <para><emphasis>tree-ish</emphasis></para>
5314 <para>A ref pointing to either a commit object, a tree object, or a
5317 <literal>object pointing to a tag or commit or tree object.
5321 <para><emphasis>unmerged index</emphasis></para>
5323 <para>An index which contains unmerged</para>
5325 <literal>index entries.
5329 <para><emphasis>unreachable object</emphasis></para>
5331 <para>An object which is not reachable from a</para>
5333 <literal>branch, tag, or any other reference.
5337 <para><emphasis>working tree</emphasis></para>
5339 <para>The tree of actual checked out files. The working tree
5342 <literal>normally equal to the HEAD plus any local changes
5343 that you have made but not yet committed.
5352 </sect2></sect1></article>
OSDN Git Service
