1GITTUTORIAL-2(7)                  Git Manual                  GITTUTORIAL-2(7)
2
3
4

NAME

6       gittutorial-2 - A tutorial introduction to Git: part two
7

SYNOPSIS

9       git *
10
11

DESCRIPTION

13       You should work through gittutorial(7) before reading this tutorial.
14
15       The goal of this tutorial is to introduce two fundamental pieces of
16       Git’s architecture—the object database and the index file—and to
17       provide the reader with everything necessary to understand the rest of
18       the Git documentation.
19

THE GIT OBJECT DATABASE

21       Let’s start a new project and create a small amount of history:
22
23           $ mkdir test-project
24           $ cd test-project
25           $ git init
26           Initialized empty Git repository in .git/
27           $ echo 'hello world' > file.txt
28           $ git add .
29           $ git commit -a -m "initial commit"
30           [master (root-commit) 54196cc] initial commit
31            1 file changed, 1 insertion(+)
32            create mode 100644 file.txt
33           $ echo 'hello world!' >file.txt
34           $ git commit -a -m "add emphasis"
35           [master c4d59f3] add emphasis
36            1 file changed, 1 insertion(+), 1 deletion(-)
37
38
39       What are the 7 digits of hex that Git responded to the commit with?
40
41       We saw in part one of the tutorial that commits have names like this.
42       It turns out that every object in the Git history is stored under a
43       40-digit hex name. That name is the SHA-1 hash of the object’s
44       contents; among other things, this ensures that Git will never store
45       the same data twice (since identical data is given an identical SHA-1
46       name), and that the contents of a Git object will never change (since
47       that would change the object’s name as well). The 7 char hex strings
48       here are simply the abbreviation of such 40 character long strings.
49       Abbreviations can be used everywhere where the 40 character strings can
50       be used, so long as they are unambiguous.
51
52       It is expected that the content of the commit object you created while
53       following the example above generates a different SHA-1 hash than the
54       one shown above because the commit object records the time when it was
55       created and the name of the person performing the commit.
56
57       We can ask Git about this particular object with the cat-file command.
58       Don’t copy the 40 hex digits from this example but use those from your
59       own version. Note that you can shorten it to only a few characters to
60       save yourself typing all 40 hex digits:
61
62           $ git cat-file -t 54196cc2
63           commit
64           $ git cat-file commit 54196cc2
65           tree 92b8b694ffb1675e5975148e1121810081dbdffe
66           author J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500
67           committer J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500
68
69           initial commit
70
71
72       A tree can refer to one or more "blob" objects, each corresponding to a
73       file. In addition, a tree can also refer to other tree objects, thus
74       creating a directory hierarchy. You can examine the contents of any
75       tree using ls-tree (remember that a long enough initial portion of the
76       SHA-1 will also work):
77
78           $ git ls-tree 92b8b694
79           100644 blob 3b18e512dba79e4c8300dd08aeb37f8e728b8dad    file.txt
80
81
82       Thus we see that this tree has one file in it. The SHA-1 hash is a
83       reference to that file’s data:
84
85           $ git cat-file -t 3b18e512
86           blob
87
88
89       A "blob" is just file data, which we can also examine with cat-file:
90
91           $ git cat-file blob 3b18e512
92           hello world
93
94
95       Note that this is the old file data; so the object that Git named in
96       its response to the initial tree was a tree with a snapshot of the
97       directory state that was recorded by the first commit.
98
99       All of these objects are stored under their SHA-1 names inside the Git
100       directory:
101
102           $ find .git/objects/
103           .git/objects/
104           .git/objects/pack
105           .git/objects/info
106           .git/objects/3b
107           .git/objects/3b/18e512dba79e4c8300dd08aeb37f8e728b8dad
108           .git/objects/92
109           .git/objects/92/b8b694ffb1675e5975148e1121810081dbdffe
110           .git/objects/54
111           .git/objects/54/196cc2703dc165cbd373a65a4dcf22d50ae7f7
112           .git/objects/a0
113           .git/objects/a0/423896973644771497bdc03eb99d5281615b51
114           .git/objects/d0
115           .git/objects/d0/492b368b66bdabf2ac1fd8c92b39d3db916e59
116           .git/objects/c4
117           .git/objects/c4/d59f390b9cfd4318117afde11d601c1085f241
118
119
120       and the contents of these files is just the compressed data plus a
121       header identifying their length and their type. The type is either a
122       blob, a tree, a commit, or a tag.
123
124       The simplest commit to find is the HEAD commit, which we can find from
125       .git/HEAD:
126
127           $ cat .git/HEAD
128           ref: refs/heads/master
129
130
131       As you can see, this tells us which branch we’re currently on, and it
132       tells us this by naming a file under the .git directory, which itself
133       contains a SHA-1 name referring to a commit object, which we can
134       examine with cat-file:
135
136           $ cat .git/refs/heads/master
137           c4d59f390b9cfd4318117afde11d601c1085f241
138           $ git cat-file -t c4d59f39
139           commit
140           $ git cat-file commit c4d59f39
141           tree d0492b368b66bdabf2ac1fd8c92b39d3db916e59
142           parent 54196cc2703dc165cbd373a65a4dcf22d50ae7f7
143           author J. Bruce Fields <bfields@puzzle.fieldses.org> 1143418702 -0500
144           committer J. Bruce Fields <bfields@puzzle.fieldses.org> 1143418702 -0500
145
146           add emphasis
147
148
149       The "tree" object here refers to the new state of the tree:
150
151           $ git ls-tree d0492b36
152           100644 blob a0423896973644771497bdc03eb99d5281615b51    file.txt
153           $ git cat-file blob a0423896
154           hello world!
155
156
157       and the "parent" object refers to the previous commit:
158
159           $ git cat-file commit 54196cc2
160           tree 92b8b694ffb1675e5975148e1121810081dbdffe
161           author J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500
162           committer J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500
163
164           initial commit
165
166
167       The tree object is the tree we examined first, and this commit is
168       unusual in that it lacks any parent.
169
170       Most commits have only one parent, but it is also common for a commit
171       to have multiple parents. In that case the commit represents a merge,
172       with the parent references pointing to the heads of the merged
173       branches.
174
175       Besides blobs, trees, and commits, the only remaining type of object is
176       a "tag", which we won’t discuss here; refer to git-tag(1) for details.
177
178       So now we know how Git uses the object database to represent a
179       project’s history:
180
181       ·   "commit" objects refer to "tree" objects representing the snapshot
182           of a directory tree at a particular point in the history, and refer
183           to "parent" commits to show how they’re connected into the project
184           history.
185
186       ·   "tree" objects represent the state of a single directory,
187           associating directory names to "blob" objects containing file data
188           and "tree" objects containing subdirectory information.
189
190       ·   "blob" objects contain file data without any other structure.
191
192       ·   References to commit objects at the head of each branch are stored
193           in files under .git/refs/heads/.
194
195       ·   The name of the current branch is stored in .git/HEAD.
196
197       Note, by the way, that lots of commands take a tree as an argument. But
198       as we can see above, a tree can be referred to in many different ways—
199       by the SHA-1 name for that tree, by the name of a commit that refers to
200       the tree, by the name of a branch whose head refers to that tree,
201       etc.--and most such commands can accept any of these names.
202
203       In command synopses, the word "tree-ish" is sometimes used to designate
204       such an argument.
205

THE INDEX FILE

207       The primary tool we’ve been using to create commits is git-commit -a,
208       which creates a commit including every change you’ve made to your
209       working tree. But what if you want to commit changes only to certain
210       files? Or only certain changes to certain files?
211
212       If we look at the way commits are created under the cover, we’ll see
213       that there are more flexible ways creating commits.
214
215       Continuing with our test-project, let’s modify file.txt again:
216
217           $ echo "hello world, again" >>file.txt
218
219
220       but this time instead of immediately making the commit, let’s take an
221       intermediate step, and ask for diffs along the way to keep track of
222       what’s happening:
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 add file.txt
231           $ git diff
232
233
234       The last diff is empty, but no new commits have been made, and the head
235       still doesn’t contain the new line:
236
237           $ git diff HEAD
238           diff --git a/file.txt b/file.txt
239           index a042389..513feba 100644
240           --- a/file.txt
241           +++ b/file.txt
242           @@ -1 +1,2 @@
243            hello world!
244           +hello world, again
245
246
247       So git diff is comparing against something other than the head. The
248       thing that it’s comparing against is actually the index file, which is
249       stored in .git/index in a binary format, but whose contents we can
250       examine with ls-files:
251
252           $ git ls-files --stage
253           100644 513feba2e53ebbd2532419ded848ba19de88ba00 0       file.txt
254           $ git cat-file -t 513feba2
255           blob
256           $ git cat-file blob 513feba2
257           hello world!
258           hello world, again
259
260
261       So what our git add did was store a new blob and then put a reference
262       to it in the index file. If we modify the file again, we’ll see that
263       the new modifications are reflected in the git diff output:
264
265           $ echo 'again?' >>file.txt
266           $ git diff
267           index 513feba..ba3da7b 100644
268           --- a/file.txt
269           +++ b/file.txt
270           @@ -1,2 +1,3 @@
271            hello world!
272            hello world, again
273           +again?
274
275
276       With the right arguments, git diff can also show us the difference
277       between the working directory and the last commit, or between the index
278       and the last commit:
279
280           $ git diff HEAD
281           diff --git a/file.txt b/file.txt
282           index a042389..ba3da7b 100644
283           --- a/file.txt
284           +++ b/file.txt
285           @@ -1 +1,3 @@
286            hello world!
287           +hello world, again
288           +again?
289           $ git diff --cached
290           diff --git a/file.txt b/file.txt
291           index a042389..513feba 100644
292           --- a/file.txt
293           +++ b/file.txt
294           @@ -1 +1,2 @@
295            hello world!
296           +hello world, again
297
298
299       At any time, we can create a new commit using git commit (without the
300       "-a" option), and verify that the state committed only includes the
301       changes stored in the index file, not the additional change that is
302       still only in our working tree:
303
304           $ git commit -m "repeat"
305           $ git diff HEAD
306           diff --git a/file.txt b/file.txt
307           index 513feba..ba3da7b 100644
308           --- a/file.txt
309           +++ b/file.txt
310           @@ -1,2 +1,3 @@
311            hello world!
312            hello world, again
313           +again?
314
315
316       So by default git commit uses the index to create the commit, not the
317       working tree; the "-a" option to commit tells it to first update the
318       index with all changes in the working tree.
319
320       Finally, it’s worth looking at the effect of git add on the index file:
321
322           $ echo "goodbye, world" >closing.txt
323           $ git add closing.txt
324
325
326       The effect of the git add was to add one entry to the index file:
327
328           $ git ls-files --stage
329           100644 8b9743b20d4b15be3955fc8d5cd2b09cd2336138 0       closing.txt
330           100644 513feba2e53ebbd2532419ded848ba19de88ba00 0       file.txt
331
332
333       And, as you can see with cat-file, this new entry refers to the current
334       contents of the file:
335
336           $ git cat-file blob 8b9743b2
337           goodbye, world
338
339
340       The "status" command is a useful way to get a quick summary of the
341       situation:
342
343           $ git status
344           On branch master
345           Changes to be committed:
346             (use "git restore --staged <file>..." to unstage)
347
348                   new file:   closing.txt
349
350           Changes not staged for commit:
351             (use "git add <file>..." to update what will be committed)
352             (use "git restore <file>..." to discard changes in working directory)
353
354                   modified:   file.txt
355
356
357       Since the current state of closing.txt is cached in the index file, it
358       is listed as "Changes to be committed". Since file.txt has changes in
359       the working directory that aren’t reflected in the index, it is marked
360       "changed but not updated". At this point, running "git commit" would
361       create a commit that added closing.txt (with its new contents), but
362       that didn’t modify file.txt.
363
364       Also, note that a bare git diff shows the changes to file.txt, but not
365       the addition of closing.txt, because the version of closing.txt in the
366       index file is identical to the one in the working directory.
367
368       In addition to being the staging area for new commits, the index file
369       is also populated from the object database when checking out a branch,
370       and is used to hold the trees involved in a merge operation. See
371       gitcore-tutorial(7) and the relevant man pages for details.
372

WHAT NEXT?

374       At this point you should know everything necessary to read the man
375       pages for any of the git commands; one good place to start would be
376       with the commands mentioned in giteveryday(7). You should be able to
377       find any unknown jargon in gitglossary(7).
378
379       The Git User’s Manual[1] provides a more comprehensive introduction to
380       Git.
381
382       gitcvs-migration(7) explains how to import a CVS repository into Git,
383       and shows how to use Git in a CVS-like way.
384
385       For some interesting examples of Git use, see the howtos[2].
386
387       For Git developers, gitcore-tutorial(7) goes into detail on the
388       lower-level Git mechanisms involved in, for example, creating a new
389       commit.
390

SEE ALSO

392       gittutorial(7), gitcvs-migration(7), gitcore-tutorial(7),
393       gitglossary(7), git-help(1), giteveryday(7), The Git User’s Manual[1]
394

GIT

396       Part of the git(1) suite
397

NOTES

399        1. Git User’s Manual
400           file:///usr/share/doc/git/user-manual.html
401
402        2. howtos
403           file:///usr/share/doc/git/howto-index.html
404
405
406
407Git 2.24.1                        12/10/2019                  GITTUTORIAL-2(7)
Impressum