1A tutorial introduction to git: part two 2======================================== 3 4You should work through link:tutorial.html[A tutorial introduction to 5git] before reading this tutorial. 6 7The goal of this tutorial is to introduce two fundamental pieces of 8git's architecture--the object database and the index file--and to 9provide the reader with everything necessary to understand the rest 10of the git documentation. 11 12The git object database 13----------------------- 14 15Let's start a new project and create a small amount of history: 16 17------------------------------------------------ 18$ mkdir test-project 19$ cd test-project 20$ git init 21Initialized empty Git repository in .git/ 22$ echo 'hello world' > file.txt 23$ git add . 24$ git commit -a -m "initial commit" 25Created initial commit 54196cc2703dc165cbd373a65a4dcf22d50ae7f7 26 create mode 100644 file.txt 27$ echo 'hello world!' >file.txt 28$ git commit -a -m "add emphasis" 29Created commit c4d59f390b9cfd4318117afde11d601c1085f241 30------------------------------------------------ 31 32What are the 40 digits of hex that git responded to the commit with? 33 34We saw in part one of the tutorial that commits have names like this. 35It turns out that every object in the git history is stored under 36such a 40-digit hex name. That name is the SHA1 hash of the object's 37contents; among other things, this ensures that git will never store 38the same data twice (since identical data is given an identical SHA1 39name), and that the contents of a git object will never change (since 40that would change the object's name as well). 41 42It is expected that the content of the commit object you created while 43following the example above generates a different SHA1 hash than 44the one shown above because the commit object records the time when 45it was created and the name of the person performing the commit. 46 47We can ask git about this particular object with the cat-file 48command. Don't copy the 40 hex digits from this example but use those 49from your own version. Note that you can shorten it to only a few 50characters to save yourself typing all 40 hex digits: 51 52------------------------------------------------ 53$ git-cat-file -t 54196cc2 54commit 55$ git-cat-file commit 54196cc2 56tree 92b8b694ffb1675e5975148e1121810081dbdffe 57author J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500 58committer J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500 59 60initial commit 61------------------------------------------------ 62 63A tree can refer to one or more "blob" objects, each corresponding to 64a file. In addition, a tree can also refer to other tree objects, 65thus creating a directory hierarchy. You can examine the contents of 66any tree using ls-tree (remember that a long enough initial portion 67of the SHA1 will also work): 68 69------------------------------------------------ 70$ git ls-tree 92b8b694 71100644 blob 3b18e512dba79e4c8300dd08aeb37f8e728b8dad file.txt 72------------------------------------------------ 73 74Thus we see that this tree has one file in it. The SHA1 hash is a 75reference to that file's data: 76 77------------------------------------------------ 78$ git cat-file -t 3b18e512 79blob 80------------------------------------------------ 81 82A "blob" is just file data, which we can also examine with cat-file: 83 84------------------------------------------------ 85$ git cat-file blob 3b18e512 86hello world 87------------------------------------------------ 88 89Note that this is the old file data; so the object that git named in 90its response to the initial tree was a tree with a snapshot of the 91directory state that was recorded by the first commit. 92 93All of these objects are stored under their SHA1 names inside the git 94directory: 95 96------------------------------------------------ 97$ find .git/objects/ 98.git/objects/ 99.git/objects/pack 100.git/objects/info 101.git/objects/3b 102.git/objects/3b/18e512dba79e4c8300dd08aeb37f8e728b8dad 103.git/objects/92 104.git/objects/92/b8b694ffb1675e5975148e1121810081dbdffe 105.git/objects/54 106.git/objects/54/196cc2703dc165cbd373a65a4dcf22d50ae7f7 107.git/objects/a0 108.git/objects/a0/423896973644771497bdc03eb99d5281615b51 109.git/objects/d0 110.git/objects/d0/492b368b66bdabf2ac1fd8c92b39d3db916e59 111.git/objects/c4 112.git/objects/c4/d59f390b9cfd4318117afde11d601c1085f241 113------------------------------------------------ 114 115and the contents of these files is just the compressed data plus a 116header identifying their length and their type. The type is either a 117blob, a tree, a commit, or a tag. 118 119The simplest commit to find is the HEAD commit, which we can find 120from .git/HEAD: 121 122------------------------------------------------ 123$ cat .git/HEAD 124ref: refs/heads/master 125------------------------------------------------ 126 127As you can see, this tells us which branch we're currently on, and it 128tells us this by naming a file under the .git directory, which itself 129contains a SHA1 name referring to a commit object, which we can 130examine with cat-file: 131 132------------------------------------------------ 133$ cat .git/refs/heads/master 134c4d59f390b9cfd4318117afde11d601c1085f241 135$ git cat-file -t c4d59f39 136commit 137$ git cat-file commit c4d59f39 138tree d0492b368b66bdabf2ac1fd8c92b39d3db916e59 139parent 54196cc2703dc165cbd373a65a4dcf22d50ae7f7 140author J. Bruce Fields <bfields@puzzle.fieldses.org> 1143418702 -0500 141committer J. Bruce Fields <bfields@puzzle.fieldses.org> 1143418702 -0500 142 143add emphasis 144------------------------------------------------ 145 146The "tree" object here refers to the new state of the tree: 147 148------------------------------------------------ 149$ git ls-tree d0492b36 150100644 blob a0423896973644771497bdc03eb99d5281615b51 file.txt 151$ git cat-file blob a0423896 152hello world! 153------------------------------------------------ 154 155and the "parent" object refers to the previous commit: 156 157------------------------------------------------ 158$ git-cat-file commit 54196cc2 159tree 92b8b694ffb1675e5975148e1121810081dbdffe 160author J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500 161committer J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500 162 163initial commit 164------------------------------------------------ 165 166The tree object is the tree we examined first, and this commit is 167unusual in that it lacks any parent. 168 169Most commits have only one parent, but it is also common for a commit 170to have multiple parents. In that case the commit represents a 171merge, with the parent references pointing to the heads of the merged 172branches. 173 174Besides blobs, trees, and commits, the only remaining type of object 175is a "tag", which we won't discuss here; refer to gitlink:git-tag[1] 176for details. 177 178So now we know how git uses the object database to represent a 179project's history: 180 181 * "commit" objects refer to "tree" objects representing the 182 snapshot of a directory tree at a particular point in the 183 history, and refer to "parent" commits to show how they're 184 connected into the project history. 185 * "tree" objects represent the state of a single directory, 186 associating directory names to "blob" objects containing file 187 data and "tree" objects containing subdirectory information. 188 * "blob" objects contain file data without any other structure. 189 * References to commit objects at the head of each branch are 190 stored in files under .git/refs/heads/. 191 * The name of the current branch is stored in .git/HEAD. 192 193Note, by the way, that lots of commands take a tree as an argument. 194But as we can see above, a tree can be referred to in many different 195ways--by the SHA1 name for that tree, by the name of a commit that 196refers to the tree, by the name of a branch whose head refers to that 197tree, etc.--and most such commands can accept any of these names. 198 199In command synopses, the word "tree-ish" is sometimes used to 200designate such an argument. 201 202The index file 203-------------- 204 205The primary tool we've been using to create commits is "git commit 206-a", which creates a commit including every change you've made to 207your working tree. But what if you want to commit changes only to 208certain files? Or only certain changes to certain files? 209 210If we look at the way commits are created under the cover, we'll see 211that there are more flexible ways creating commits. 212 213Continuing with our test-project, let's modify file.txt again: 214 215------------------------------------------------ 216$ echo "hello world, again" >>file.txt 217------------------------------------------------ 218 219but this time instead of immediately making the commit, let's take an 220intermediate step, and ask for diffs along the way to keep track of 221what's happening: 222 223------------------------------------------------ 224$ git diff 225--- a/file.txt 226+++ b/file.txt 227@@ -1 +1,2 @@ 228 hello world! 229+hello world, again 230$ git update-index file.txt 231$ git diff 232------------------------------------------------ 233 234The last diff is empty, but no new commits have been made, and the 235head still doesn't contain the new line: 236 237------------------------------------------------ 238$ git-diff HEAD 239diff --git a/file.txt b/file.txt 240index a042389..513feba 100644 241--- a/file.txt 242+++ b/file.txt 243@@ -1 +1,2 @@ 244 hello world! 245+hello world, again 246------------------------------------------------ 247 248So "git diff" is comparing against something other than the head. 249The thing that it's comparing against is actually the index file, 250which is stored in .git/index in a binary format, but whose contents 251we can examine with ls-files: 252 253------------------------------------------------ 254$ git ls-files --stage 255100644 513feba2e53ebbd2532419ded848ba19de88ba00 0 file.txt 256$ git cat-file -t 513feba2 257blob 258$ git cat-file blob 513feba2 259hello world! 260hello world, again 261------------------------------------------------ 262 263So what our "git update-index" did was store a new blob and then put 264a reference to it in the index file. If we modify the file again, 265we'll see that the new modifications are reflected in the "git-diff" 266output: 267 268------------------------------------------------ 269$ echo 'again?' >>file.txt 270$ git diff 271index 513feba..ba3da7b 100644 272--- a/file.txt 273+++ b/file.txt 274@@ -1,2 +1,3 @@ 275 hello world! 276 hello world, again 277+again? 278------------------------------------------------ 279 280With the right arguments, git diff can also show us the difference 281between the working directory and the last commit, or between the 282index and the last commit: 283 284------------------------------------------------ 285$ git diff HEAD 286diff --git a/file.txt b/file.txt 287index a042389..ba3da7b 100644 288--- a/file.txt 289+++ b/file.txt 290@@ -1 +1,3 @@ 291 hello world! 292+hello world, again 293+again? 294$ git diff --cached 295diff --git a/file.txt b/file.txt 296index a042389..513feba 100644 297--- a/file.txt 298+++ b/file.txt 299@@ -1 +1,2 @@ 300 hello world! 301+hello world, again 302------------------------------------------------ 303 304At any time, we can create a new commit using "git commit" (without 305the -a option), and verify that the state committed only includes the 306changes stored in the index file, not the additional change that is 307still only in our working tree: 308 309------------------------------------------------ 310$ git commit -m "repeat" 311$ git diff HEAD 312diff --git a/file.txt b/file.txt 313index 513feba..ba3da7b 100644 314--- a/file.txt 315+++ b/file.txt 316@@ -1,2 +1,3 @@ 317 hello world! 318 hello world, again 319+again? 320------------------------------------------------ 321 322So by default "git commit" uses the index to create the commit, not 323the working tree; the -a option to commit tells it to first update 324the index with all changes in the working tree. 325 326Finally, it's worth looking at the effect of "git add" on the index 327file: 328 329------------------------------------------------ 330$ echo "goodbye, world" >closing.txt 331$ git add closing.txt 332------------------------------------------------ 333 334The effect of the "git add" was to add one entry to the index file: 335 336------------------------------------------------ 337$ git ls-files --stage 338100644 8b9743b20d4b15be3955fc8d5cd2b09cd2336138 0 closing.txt 339100644 513feba2e53ebbd2532419ded848ba19de88ba00 0 file.txt 340------------------------------------------------ 341 342And, as you can see with cat-file, this new entry refers to the 343current contents of the file: 344 345------------------------------------------------ 346$ git cat-file blob 8b9743b2 347goodbye, world 348------------------------------------------------ 349 350The "status" command is a useful way to get a quick summary of the 351situation: 352 353------------------------------------------------ 354$ git status 355# On branch master 356# Changes to be committed: 357# (use "git reset HEAD <file>..." to unstage) 358# 359# new file: closing.txt 360# 361# Changed but not updated: 362# (use "git add <file>..." to update what will be committed) 363# 364# modified: file.txt 365# 366------------------------------------------------ 367 368Since the current state of closing.txt is cached in the index file, 369it is listed as "Changes to be committed". Since file.txt has 370changes in the working directory that aren't reflected in the index, 371it is marked "changed but not updated". At this point, running "git 372commit" would create a commit that added closing.txt (with its new 373contents), but that didn't modify file.txt. 374 375Also, note that a bare "git diff" shows the changes to file.txt, but 376not the addition of closing.txt, because the version of closing.txt 377in the index file is identical to the one in the working directory. 378 379In addition to being the staging area for new commits, the index file 380is also populated from the object database when checking out a 381branch, and is used to hold the trees involved in a merge operation. 382See the link:core-tutorial.html[core tutorial] and the relevant man 383pages for details. 384 385What next? 386---------- 387 388At this point you should know everything necessary to read the man 389pages for any of the git commands; one good place to start would be 390with the commands mentioned in link:everyday.html[Everyday git]. You 391should be able to find any unknown jargon in the 392link:glossary.html[Glossary]. 393 394The link:cvs-migration.html[CVS migration] document explains how to 395import a CVS repository into git, and shows how to use git in a 396CVS-like way. 397 398For some interesting examples of git use, see the 399link:howto-index.html[howtos]. 400 401For git developers, the link:core-tutorial.html[Core tutorial] goes 402into detail on the lower-level git mechanisms involved in, for 403example, creating a new commit.