1
+Git User's Manual
2
+_________________
3
+
4
+This manual is designed to be readable by someone with basic unix
5
+commandline skills, but no previous knowledge of git.
6
+
7
+Comprehensive reference documentation is available through the man
8
+pages. For a command such as "git clone", just use
9
+
10
+------------------------------------------------
11
+$ man git-clone
12
+------------------------------------------------
13
+
14
+Repositories and Branches
15
+=========================
16
+
17
+How to get a git repository
18
+---------------------------
19
+
20
+It will be useful to have a git repository to experiment with as you
21
+read this manual.
22
+
23
+The best way to get one is by using the gitlink:git-clone[1] command
24
+to download a copy of an existing repository for a project that you
25
+are interested in. If you don't already have a project in mind, here
26
+are some interesting examples:
27
+
28
+------------------------------------------------
29
+ # git itself (approx. 10MB download):
30
+$ git clone git://git.kernel.org/pub/scm/git/git.git
31
+ # the linux kernel (approx. 150MB download):
32
+$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git
33
+------------------------------------------------
34
+
35
+The initial clone may be time-consuming for a large project, but you
36
+will only need to clone once.
37
+
38
+The clone command creates a new directory named after the project
39
+("git" or "linux-2.6" in the examples above). After you cd into this
40
+directory, you will see that it contains a copy of the project files,
41
+together with a special top-level directory named ".git", which
42
+contains all the information about the history of the project.
43
+
44
+In the following, examples will be taken from one of the two
45
+repositories above.
46
+
47
+How to check out a different version of a project
48
+-------------------------------------------------
49
+
50
+Git is best thought of as a tool for storing the history of a
51
+collection of files. It stores the history as a compressed
52
+collection of interrelated snapshots (versions) of the project's
53
+contents.
54
+
55
+A single git repository may contain multiple branches. Each branch
56
+is a bookmark referencing a particular point in the project history.
57
+The gitlink:git-branch[1] command shows you the list of branches:
58
+
59
+------------------------------------------------
60
+$ git branch
61
+* master
62
+------------------------------------------------
63
+
64
+A freshly cloned repository contains a single branch, named "master",
65
+and the working directory contains the version of the project
66
+referred to by the master branch.
67
+
68
+Most projects also use tags. Tags, like branches, are references
69
+into the project's history, and can be listed using the
70
+gitlink:git-tag[1] command:
71
+
72
+------------------------------------------------
73
+$ git tag -l
74
+v2.6.11
75
+v2.6.11-tree
76
+v2.6.12
77
+v2.6.12-rc2
78
+v2.6.12-rc3
79
+v2.6.12-rc4
80
+v2.6.12-rc5
81
+v2.6.12-rc6
82
+v2.6.13
83
+...
84
+------------------------------------------------
85
+
86
+Create a new branch pointing to one of these versions and check it
87
+out using gitlink:git-checkout[1]:
88
+
89
+------------------------------------------------
90
+$ git checkout -b new v2.6.13
91
+------------------------------------------------
92
+
93
+The working directory then reflects the contents that the project had
94
+when it was tagged v2.6.13, and gitlink:git-branch[1] shows two
95
+branches, with an asterisk marking the currently checked-out branch:
96
+
97
+------------------------------------------------
98
+$ git branch
99
+ master
100
+* new
101
+------------------------------------------------
102
+
103
+If you decide that you'd rather see version 2.6.17, you can modify
104
+the current branch to point at v2.6.17 instead, with
105
+
106
+------------------------------------------------
107
+$ git reset --hard v2.6.17
108
+------------------------------------------------
109
+
110
+Note that if the current branch was your only reference to a
111
+particular point in history, then resetting that branch may leave you
112
+with no way to find the history it used to point to; so use this
113
+command carefully.
114
+
115
+Understanding History: Commits
116
+------------------------------
117
+
118
+Every change in the history of a project is represented by a commit.
119
+The gitlink:git-show[1] command shows the most recent commit on the
120
+current branch:
121
+
122
+------------------------------------------------
123
+$ git show
124
+commit 2b5f6dcce5bf94b9b119e9ed8d537098ec61c3d2
125
+Author: Jamal Hadi Salim <hadi@cyberus.ca>
126
+Date: Sat Dec 2 22:22:25 2006 -0800
127
+
128
+ [XFRM]: Fix aevent structuring to be more complete.
129
+
130
+ aevents can not uniquely identify an SA. We break the ABI with this
131
+ patch, but consensus is that since it is not yet utilized by any
132
+ (known) application then it is fine (better do it now than later).
133
+
134
+ Signed-off-by: Jamal Hadi Salim <hadi@cyberus.ca>
135
+ Signed-off-by: David S. Miller <davem@davemloft.net>
136
+
137
+diff --git a/Documentation/networking/xfrm_sync.txt b/Documentation/networking/xfrm_sync.txt
138
+index 8be626f..d7aac9d 100644
139
+--- a/Documentation/networking/xfrm_sync.txt
140
++++ b/Documentation/networking/xfrm_sync.txt
141
+@@ -47,10 +47,13 @@ aevent_id structure looks like:
142
+
143
+ struct xfrm_aevent_id {
144
+ struct xfrm_usersa_id sa_id;
145
++ xfrm_address_t saddr;
146
+ __u32 flags;
147
++ __u32 reqid;
148
+ };
149
+...
150
+------------------------------------------------
151
+
152
+As you can see, a commit shows who made the latest change, what they
153
+did, and why.
154
+
155
+Every commit has a 20-digit id, sometimes called the "SHA1 id", shown
156
+on the first line of the "git show" output. You can usually refer to
157
+a commit by a shorter name, such as a tag or a branch name, but this
158
+longer id can also be useful. In particular, it is a globally unique
159
+name for this commit: so if you tell somebody else the SHA1 id (for
160
+example in email), then you are guaranteed they will see the same
161
+commit in their repository that you do in yours.
162
+
163
+Understanding history: commits, parents, and reachability
164
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
165
+
166
+Every commit (except the very first commit in a project) also has a
167
+parent commit which shows what happened before this commit.
168
+Following the chain of parents will eventually take you back to the
169
+beginning of the project.
170
+
171
+However, the commits do not form a simple list; git allows lines of
172
+development to diverge and then reconverge, and the point where two
173
+lines of development reconverge is called a "merge". The commit
174
+representing a merge can therefore have more than one parent, with
175
+each parent representing the most recent commit on one of the lines
176
+of development leading to that point.
177
+
178
+The best way to see how this works is using the gitlink:gitk[1]
179
+command; running gitk now on a git repository and looking for merge
180
+commits will help understand how the git organizes history.
181
+
182
+In the following, we say that commit X is "reachable" from commit Y
183
+if commit X is an ancestor of commit Y. Equivalently, you could say
184
+that Y is a descendent of X, or that there is a chain of parents
185
+leading from commit Y to commit X.
186
+
187
+Undestanding history: History diagrams
188
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
189
+
190
+We will sometimes represent git history using diagrams like the one
191
+below. Commits are shown as "o", and the links between them with
192
+lines drawn with - / and \. Time goes left to right:
193
+
194
+ o--o--o <-- Branch A
195
+ /
196
+ o--o--o <-- master
197
+ \
198
+ o--o--o <-- Branch B
199
+
200
+If we need to talk about a particular commit, the character "o" may
201
+be replaced with another letter or number.
202
+
203
+Understanding history: What is a branch?
204
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
205
+
206
+Though we've been using the word "branch" to mean a kind of reference
207
+to a particular commit, the word branch is also commonly used to
208
+refer to the line of commits leading up to that point. In the
209
+example above, git may think of the branch named "A" as just a
210
+pointer to one particular commit, but we may refer informally to the
211
+line of three commits leading up to that point as all being part of
212
+"branch A".
213
+
214
+If we need to make it clear that we're just talking about the most
215
+recent commit on the branch, we may refer to that commit as the
216
+"head" of the branch.
217
+
218
+Manipulating branches
219
+---------------------
220
+
221
+Creating, deleting, and modifying branches is quick and easy; here's
222
+a summary of the commands:
223
+
224
+git branch::
225
+ list all branches
226
+git branch <branch>::
227
+ create a new branch named <branch>, referencing the same
228
+ point in history as the current branch
229
+git branch <branch> <start-point>::
230
+ create a new branch named <branch>, referencing
231
+ <start-point>, which may be specified any way you like,
232
+ including using a branch name or a tag name
233
+git branch -d <branch>::
234
+ delete the branch <branch>; if the branch you are deleting
235
+ points to a commit which is not reachable from this branch,
236
+ this command will fail with a warning.
237
+git branch -D <branch>::
238
+ even if the branch points to a commit not reachable
239
+ from the current branch, you may know that that commit
240
+ is still reachable from some other branch or tag. In that
241
+ case it is safe to use this command to force git to delete
242
+ the branch.
243
+git checkout <branch>::
244
+ make the current branch <branch>, updating the working
245
+ directory to reflect the version referenced by <branch>
246
+git checkout -b <new> <start-point>::
247
+ create a new branch <new> referencing <start-point>, and
248
+ check it out.
249
+
250
+It is also useful to know that the special symbol "HEAD" can always
251
+be used to refer to the current branch.
252
+
253
+Examining branches from a remote repository
254
+-------------------------------------------
255
+
256
+The "master" branch that was created at the time you cloned is a copy
257
+of the HEAD in the repository that you cloned from. That repository
258
+may also have had other branches, though, and your local repository
259
+keeps branches which track each of those remote branches, which you
260
+can view using the "-r" option to gitlink:git-branch[1]:
261
+
262
+------------------------------------------------
263
+$ git branch -r
264
+ origin/HEAD
265
+ origin/html
266
+ origin/maint
267
+ origin/man
268
+ origin/master
269
+ origin/next
270
+ origin/pu
271
+ origin/todo
272
+------------------------------------------------
273
+
274
+You cannot check out these remote-tracking branches, but you can
275
+examine them on a branch of your own, just as you would a tag:
276
+
277
+------------------------------------------------
278
+$ git checkout -b my-todo-copy origin/todo
279
+------------------------------------------------
280
+
281
+Note that the name "origin" is just the name that git uses by default
282
+to refer to the repository that you cloned from.
283
+
284
+[[how-git-stores-references]]
285
+How git stores references
286
+-------------------------
287
+
288
+Branches, remote-tracking branches, and tags are all references to
289
+commits. Git stores these references in the ".git" directory. Most
290
+of them are stored in .git/refs/:
291
+
292
+ - branches are stored in .git/refs/heads
293
+ - tags are stored in .git/refs/tags
294
+ - remote-tracking branches for "origin" are stored in
295
+ .git/refs/remotes/origin/
296
+
297
+If you look at one of these files you will see that they usually
298
+contain just the SHA1 id of a commit:
299
+
300
+------------------------------------------------
301
+$ ls .git/refs/heads/
302
+master
303
+$ cat .git/refs/heads/master
304
+c0f982dcf188d55db9d932a39d4ea7becaa55fed
305
+------------------------------------------------
306
+
307
+You can refer to a reference by its path relative to the .git
308
+directory. However, we've seen above that git will also accept
309
+shorter names; for example, "master" is an acceptable shortcut for
310
+"refs/heads/master", and "origin/master" is a shortcut for
311
+"refs/remotes/origin/master".
312
+
313
+As another useful shortcut, you can also refer to the "HEAD" of
314
+"origin" (or any other remote), using just the name of the remote.
315
+
316
+For the complete list of paths which git checks for references, and
317
+how it decides which to choose when there are multiple references
318
+with the same name, see the "SPECIFYING REVISIONS" section of
319
+gitlink:git-rev-parse[1].
320
+
321
+[[Updating-a-repository-with-git-fetch]]
322
+Updating a repository with git fetch
323
+------------------------------------
324
+
325
+Eventually the developer cloned from will do additional work in her
326
+repository, creating new commits and advancing the branches to point
327
+at the new commits.
328
+
329
+The command "git fetch", with no arguments, will update all of the
330
+remote-tracking branches to the latest version found in her
331
+repository. It will not touch any of your own branches--not even the
332
+"master" branch that was created for you on clone.
333
+
334
+Fetching individual branches
335
+----------------------------
336
+
337
+You can also choose to update just one branch at a time:
338
+
339
+-------------------------------------------------
340
+$ git fetch origin todo:refs/remotes/origin/todo
341
+-------------------------------------------------
342
+
343
+The first argument, "origin", just tells git to fetch from the
344
+repository you originally cloned from. The second argument tells git
345
+to fetch the branch named "todo" from the remote repository, and to
346
+store it locally under the name refs/remotes/origin/todo; as we saw
347
+above, remote-tracking branches are stored under
348
+refs/remotes/<name-of-repository>/<name-of-branch>.
349
+
350
+You can also fetch branches from other repositories; so
351
+
352
+-------------------------------------------------
353
+$ git fetch git://example.com/proj.git master:refs/remotes/example/master
354
+-------------------------------------------------
355
+
356
+will create a new reference named "refs/remotes/example/master" and
357
+store in it the branch named "master" from the repository at the
358
+given URL. If you already have a branch named
359
+"refs/remotes/example/master", it will attempt to "fast-forward" to
360
+the commit given by example.com's master branch. So next we explain
361
+what a fast-forward is:
362
+
363
+[[fast-forwards]]
364
+Understanding git history: fast-forwards
365
+----------------------------------------
366
+
367
+In the previous example, when updating an existing branch, "git
368
+fetch" checks to make sure that the most recent commit on the remote
369
+branch is a descendant of the most recent commit on your copy of the
370
+branch before updating your copy of the branch to point at the new
371
+commit. Git calls this process a "fast forward".
372
+
373
+A fast forward looks something like this:
374
+
375
+ o--o--o--o <-- old head of the branch
376
+ \
377
+ o--o--o <-- new head of the branch
378
+
379
+
380
+In some cases it is possible that the new head will *not* actually be
381
+a descendant of the old head. For example, the developer may have
382
+realized she made a serious mistake, and decided to backtrack,
383
+resulting in a situation like:
384
+
385
+ o--o--o--o--a--b <-- old head of the branch
386
+ \
387
+ o--o--o <-- new head of the branch
388
+
389
+
390
+
391
+In this case, "git fetch" will fail, and print out a warning.
392
+
393
+In that case, you can still force git to update to the new head, as
394
+described in the following section. However, note that in the
395
+situation above this may mean losing the commits labeled "a" and "b",
396
+unless you've already created a reference of your own pointing to
397
+them.
398
+
399
+Forcing git fetch to do non-fast-forward updates
400
+------------------------------------------------
401
+
402
+If git fetch fails because the new head of a branch is not a
403
+descendant of the old head, you may force the update with:
404
+
405
+-------------------------------------------------
406
+$ git fetch git://example.com/proj.git +master:refs/remotes/example/master
407
+-------------------------------------------------
408
+
409
+Note the addition of the "+" sign. Be aware that commits which the
410
+old version of example/master pointed at may be lost, as we saw in
411
+the previous section.
412
+
413
+Configuring remote branches
414
+---------------------------
415
+
416
+We saw above that "origin" is just a shortcut to refer to the
417
+repository which you originally cloned from. This information is
418
+stored in git configuration variables, which you can see using
419
+gitlink:git-repo-config[1]:
420
+
421
+-------------------------------------------------
422
+$ git-repo-config -l
423
+core.repositoryformatversion=0
424
+core.filemode=true
425
+core.logallrefupdates=true
426
+remote.origin.url=git://git.kernel.org/pub/scm/git/git.git
427
+remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
428
+branch.master.remote=origin
429
+branch.master.merge=refs/heads/master
430
+-------------------------------------------------
431
+
432
+If there are other repositories that you also use frequently, you can
433
+create similar configuration options to save typing; for example,
434
+after
435
+
436
+-------------------------------------------------
437
+$ git repo-config remote.example.url=git://example.com/proj.git
438
+-------------------------------------------------
439
+
440
+then the following two commands will do the same thing:
441
+
442
+-------------------------------------------------
443
+$ git fetch git://example.com/proj.git master:refs/remotes/example/master
444
+$ git fetch example master:refs/remotes/example/master
445
+-------------------------------------------------
446
+
447
+Even better, if you add one more option:
448
+
449
+-------------------------------------------------
450
+$ git repo-config remote.example.fetch=master:refs/remotes/example/master
451
+-------------------------------------------------
452
+
453
+then the following commands will all do the same thing:
454
+
455
+-------------------------------------------------
456
+$ git fetch git://example.com/proj.git master:ref/remotes/example/master
457
+$ git fetch example master:ref/remotes/example/master
458
+$ git fetch example example/master
459
+$ git fetch example
460
+-------------------------------------------------
461
+
462
+You can also add a "+" to force the update each time:
463
+
464
+-------------------------------------------------
465
+$ git repo-config +master:ref/remotes/example/master
466
+-------------------------------------------------
467
+
468
+Don't do this unless you're sure you won't mind "git fetch" possibly
469
+throwing away commits on mybranch.
470
+
471
+Also note that all of the above configuration can be performed by
472
+directly editing the file .git/config instead of using
473
+gitlink:git-repo-config[1].
474
+
475
+See gitlink:git-repo-config[1] for more details on the configuration
476
+options mentioned above.
477
+
478
+Exploring git history
479
+=====================
480
+
481
+Git is best thought of as a tool for storing the history of a
482
+collection of files. It does this by storing compressed snapshots of
483
+the contents of a file heirarchy, together with "commits" which show
484
+the relationships between these snapshots.
485
+
486
+Git provides extremely flexible and fast tools for exploring the
487
+history of a project.
488
+
489
+We start with one specialized tool which is useful for finding the
490
+commit that introduced a bug into a project.
491
+
492
+How to use bisect to find a regression
493
+--------------------------------------
494
+
495
+Suppose version 2.6.18 of your project worked, but the version at
496
+"master" crashes. Sometimes the best way to find the cause of such a
497
+regression is to perform a brute-force search through the project's
498
+history to find the particular commit that caused the problem. The
499
+gitlink:git-bisect[1] command can help you do this:
500
+
501
+-------------------------------------------------
502
+$ git bisect start
503
+$ git bisect good v2.6.18
504
+$ git bisect bad master
505
+Bisecting: 3537 revisions left to test after this
506
+[65934a9a028b88e83e2b0f8b36618fe503349f8e] BLOCK: Make USB storage depend on SCSI rather than selecting it [try #6]
507
+-------------------------------------------------
508
+
509
+If you run "git branch" at this point, you'll see that git has
510
+temporarily moved you to a new branch named "bisect". This branch
511
+points to a commit (with commit id 65934...) that is reachable from
512
+v2.6.19 but not from v2.6.18. Compile and test it, and see whether
513
+it crashes. Assume it does crash. Then:
514
+
515
+-------------------------------------------------
516
+$ git bisect bad
517
+Bisecting: 1769 revisions left to test after this
518
+[7eff82c8b1511017ae605f0c99ac275a7e21b867] i2c-core: Drop useless bitmaskings
519
+-------------------------------------------------
520
+
521
+checks out an older version. Continue like this, telling git at each
522
+stage whether the version it gives you is good or bad, and notice
523
+that the number of revisions left to test is cut approximately in
524
+half each time.
525
+
526
+After about 13 tests (in this case), it will output the commit id of
527
+the guilty commit. You can then examine the commit with
528
+gitlink:git-show[1], find out who wrote it, and mail them your bug
529
+report with the commit id. Finally, run
530
+
531
+-------------------------------------------------
532
+$ git bisect reset
533
+-------------------------------------------------
534
+
535
+to return you to the branch you were on before and delete the
536
+temporary "bisect" branch.
537
+
538
+Note that the version which git-bisect checks out for you at each
539
+point is just a suggestion, and you're free to try a different
540
+version if you think it would be a good idea. For example,
541
+occasionally you may land on a commit that broke something unrelated;
542
+run
543
+
544
+-------------------------------------------------
545
+$ git bisect-visualize
546
+-------------------------------------------------
547
+
548
+which will run gitk and label the commit it chose with a marker that
549
+says "bisect". Chose a safe-looking commit nearby, note its commit
550
+id, and check it out with:
551
+
552
+-------------------------------------------------
553
+$ git reset --hard fb47ddb2db...
554
+-------------------------------------------------
555
+
556
+then test, run "bisect good" or "bisect bad" as appropriate, and
557
+continue.
558
+
559
+Naming commits
560
+--------------
561
+
562
+We have seen several ways of naming commits already:
563
+
564
+ - 20-digit SHA1 id
565
+ - branch name: refers to the commit at the head of the given
566
+ branch
567
+ - tag name: refers to the commit pointed to by the given tag
568
+ (we've seen branches and tags are special cases of
569
+ <<how-git-stores-references,references>>).
570
+ - HEAD: refers to the head of the current branch
571
+
572
+There are many more; see the "SPECIFYING REVISION" section of the
573
+gitlink:git-rev-list[1] man page for the complete list of ways to
574
+name revisions. Some examples:
575
+
576
+-------------------------------------------------
577
+$ git show fb47ddb2 # the first few characters of the SHA1 id
578
+ # are usually enough to specify it uniquely
579
+$ git show HEAD^ # the parent of the HEAD commit
580
+$ git show HEAD^^ # the grandparent
581
+$ git show HEAD~4 # the great-great-grandparent
582
+-------------------------------------------------
583
+
584
+Recall that merge commits may have more than one parent; by default,
585
+^ and ~ follow the first parent listed in the commit, but you can
586
+also choose:
587
+
588
+-------------------------------------------------
589
+$ git show HEAD^1 # show the first parent of HEAD
590
+$ git show HEAD^2 # show the second parent of HEAD
591
+-------------------------------------------------
592
+
593
+In addition to HEAD, there are several other special names for
594
+commits:
595
+
596
+Merges (to be discussed later), as well as operations such as
597
+git-reset, which change the currently checked-out commit, generally
598
+set ORIG_HEAD to the value HEAD had before the current operation.
599
+
600
+The git-fetch operation always stores the head of the last fetched
601
+branch in FETCH_HEAD. For example, if you run git fetch without
602
+specifying a local branch as the target of the operation
603
+
604
+-------------------------------------------------
605
+$ git fetch git://example.com/proj.git theirbranch
606
+-------------------------------------------------
607
+
608
+the fetched commits will still be available from FETCH_HEAD.
609
+
610
+When we discuss merges we'll also see the special name MERGE_HEAD,
611
+which refers to the other branch that we're merging in to the current
612
+branch.
613
+
614
+Creating tags
615
+-------------
616
+
617
+We can also create a tag to refer to a particular commit; after
618
+running
619
+
620
+-------------------------------------------------
621
+$ git-tag stable-1 1b2e1d63ff
622
+-------------------------------------------------
623
+
624
+You can use stable-1 to refer to the commit 1b2e1d63ff.
625
+
626
+This creates a "lightweight" tag. If the tag is a tag you wish to
627
+share with others, and possibly sign cryptographically, then you
628
+should create a tag object instead; see the gitlink:git-tag[1] man
629
+page for details.
630
+
631
+Browsing revisions
632
+------------------
633
+
634
+The gitlink:git-log[1] command can show lists of commits. On its
635
+own, it shows all commits reachable from the parent commit; but you
636
+can also make more specific requests:
637
+
638
+-------------------------------------------------
639
+$ git log v2.5.. # commits since (not reachable from) v2.5
640
+$ git log test..master # commits reachable from master but not test
641
+$ git log master..test # ...reachable from test but not master
642
+$ git log master...test # ...reachable from either test or master,
643
+ # but not both
644
+$ git log --since="2 weeks ago" # commits from the last 2 weeks
645
+$ git log Makefile # commits which modify Makefile
646
+$ git log fs/ # ... which modify any file under fs/
647
+$ git log -S'foo()' # commits which add or remove any file data
648
+ # matching the string 'foo()'
649
+-------------------------------------------------
650
+
651
+And of course you can combine all of these; the following finds
652
+commits since v2.5 which touch the Makefile or any file under fs:
653
+
654
+-------------------------------------------------
655
+$ git log v2.5.. Makefile fs/
656
+-------------------------------------------------
657
+
658
+You can also ask git log to show patches:
659
+
660
+-------------------------------------------------
661
+$ git log -p
662
+-------------------------------------------------
663
+
664
+See the "--pretty" option in the gitlink:git-log[1] man page for more
665
+display options.
666
+
667
+Note that git log starts with the most recent commit and works
668
+backwards through the parents; however, since git history can contain
669
+multiple independant lines of development, the particular order that
670
+commits are listed in may be somewhat arbitrary.
671
+
672
+Generating diffs
673
+----------------
674
+
675
+You can generate diffs between any two versions using
676
+gitlink:git-diff[1]:
677
+
678
+-------------------------------------------------
679
+$ git diff master..test
680
+-------------------------------------------------
681
+
682
+Sometimes what you want instead is a set of patches:
683
+
684
+-------------------------------------------------
685
+$ git format-patch master..test
686
+-------------------------------------------------
687
+
688
+will generate a file with a patch for each commit reachable from test
689
+but not from master. Note that if master also has commits which are
690
+not reachable from test, then the combined result of these patches
691
+will not be the same as the diff produced by the git-diff example.
692
+
693
+Viewing old file versions
694
+-------------------------
695
+
696
+You can always view an old version of a file by just checking out the
697
+correct revision first. But sometimes it is more convenient to be
698
+able to view an old version of a single file without checking
699
+anything out; this command does that:
700
+
701
+-------------------------------------------------
702
+$ git show v2.5:fs/locks.c
703
+-------------------------------------------------
704
+
705
+Before the colon may be anything that names a commit, and after it
706
+may be any path to a file tracked by git.
707
+
708
+Developing with git
709
+===================
710
+
711
+Telling git your name
712
+---------------------
713
+
714
+Before creating any commits, you should introduce yourself to git. The
715
+easiest way to do so is:
716
+
717
+------------------------------------------------
718
+$ cat >~/.gitconfig <<\EOF
719
+[user]
720
+ name = Your Name Comes Here
721
+ email = you@yourdomain.example.com
722
+EOF
723
+------------------------------------------------
724
+
725
+
726
+Creating a new repository
727
+-------------------------
728
+
729
+Creating a new repository from scratch is very easy:
730
+
731
+-------------------------------------------------
732
+$ mkdir project
733
+$ cd project
734
+$ git init-db
735
+-------------------------------------------------
736
+
737
+If you have some initial content (say, a tarball):
738
+
739
+-------------------------------------------------
740
+$ tar -xzvf project.tar.gz
741
+$ cd project
742
+$ git init-db
743
+$ git add . # include everything below ./ in the first commit:
744
+$ git commit
745
+-------------------------------------------------
746
+
747
+[[how-to-make-a-commit]]
748
+how to make a commit
749
+--------------------
750
+
751
+Creating a new commit takes three steps:
752
+
753
+ 1. Making some changes to the working directory using your
754
+ favorite editor.
755
+ 2. Telling git about your changes.
756
+ 3. Creating the commit using the content you told git about
757
+ in step 2.
758
+
759
+In practice, you can interleave and repeat steps 1 and 2 as many
760
+times as you want: in order to keep track of what you want committed
761
+at step 3, git maintains a snapshot of the tree's contents in a
762
+special staging area called "the index."
763
+
764
+By default, the content of the index is identical to that of the
765
+HEAD. The command "git diff --cached" shows the difference between
766
+HEAD and the index, so you should no output from that command.
767
+
768
+Modifying the index is easy:
769
+
770
+To update the index with the new contents of a modified file, use
771
+
772
+-------------------------------------------------
773
+$ git add path/to/file
774
+-------------------------------------------------
775
+
776
+To add the contents of a new file to the index, use
777
+
778
+-------------------------------------------------
779
+$ git add path/to/file
780
+-------------------------------------------------
781
+
782
+To remove a file from the index that you've removed from the working
783
+tree,
784
+
785
+-------------------------------------------------
786
+$ git rm path/to/file
787
+-------------------------------------------------
788
+
789
+After each step you can verify that
790
+
791
+-------------------------------------------------
792
+$ git diff --cached
793
+-------------------------------------------------
794
+
795
+always shows the difference between the HEAD and the index file--this
796
+is what you'd commit if you created the commit now--and that
797
+
798
+-------------------------------------------------
799
+$ git diff
800
+-------------------------------------------------
801
+
802
+shows the difference between the working tree and the index file.
803
+
804
+Note that "git add" always adds just the current contents of a file
805
+to the index; further changes to the same file will be ignored unless
806
+you run git-add on the file again.
807
+
808
+When you're ready, just run
809
+
810
+-------------------------------------------------
811
+$ git commit
812
+-------------------------------------------------
813
+
814
+and git will prompt you for a commit message and then create the new
815
+commmit. Check to make sure it looks like what you expected with
816
+
817
+-------------------------------------------------
818
+$ git show
819
+-------------------------------------------------
820
+
821
+As a special shortcut,
822
+
823
+-------------------------------------------------
824
+$ git commit -a
825
+-------------------------------------------------
826
+
827
+will update the index with any files that you've modified or removed
828
+and create a commit, all in one step.
829
+
830
+A number of commands are useful for keeping track of what you're
831
+about to commit:
832
+
833
+-------------------------------------------------
834
+$ git diff --cached # difference between HEAD and the index; what
835
+ # would be commited if you ran "commit" now.
836
+$ git diff # difference between the index file and your
837
+ # working directory; changes that would not
838
+ # be included if you ran "commit" now.
839
+$ git status # a brief per-file summary of the above.
840
+-------------------------------------------------
841
+
842
+creating good commit messages
843
+-----------------------------
844
+
845
+Though not required, it's a good idea to begin the commit message
846
+with a single short (less than 50 character) line summarizing the
847
+change, followed by a blank line and then a more thorough
848
+description. Tools that turn commits into email, for example, use
849
+the first line on the Subject line and the rest of the commit in the
850
+body.
851
+
852
+how to merge
853
+------------
854
+
855
+You can rejoin two diverging branches of development using
856
+gitlink:git-merge[1]:
857
+
858
+-------------------------------------------------
859
+$ git merge branchname
860
+-------------------------------------------------
861
+
862
+merges the development in the branch "branchname" into the current
863
+branch. If there are conflicts--for example, if the same file is
864
+modified in two different ways in the remote branch and the local
865
+branch--then you are warned; the output may look something like this:
866
+
867
+-------------------------------------------------
868
+$ git pull . next
869
+Trying really trivial in-index merge...
870
+fatal: Merge requires file-level merging
871
+Nope.
872
+Merging HEAD with 77976da35a11db4580b80ae27e8d65caf5208086
873
+Merging:
874
+15e2162 world
875
+77976da goodbye
876
+found 1 common ancestor(s):
877
+d122ed4 initial
878
+Auto-merging file.txt
879
+CONFLICT (content): Merge conflict in file.txt
880
+Automatic merge failed; fix conflicts and then commit the result.
881
+-------------------------------------------------
882
+
883
+Conflict markers are left in the problematic files, and after
884
+you resolve the conflicts manually, you can update the index
885
+with the contents and run git commit, as you normally would when
886
+creating a new file.
887
+
888
+If you examine the resulting commit using gitk, you will see that it
889
+has two parents, one pointing to the top of the current branch, and
890
+one to the top of the other branch.
891
+
892
+In more detail:
893
+
894
+[[resolving-a-merge]]
895
+Resolving a merge
896
+-----------------
897
+
898
+When a merge isn't resolved automatically, git leaves the index and
899
+the working tree in a special state that gives you all the
900
+information you need to help resolve the merge.
901
+
902
+Files with conflicts are marked specially in the index, so until you
903
+resolve the problem and update the index, git commit will fail:
904
+
905
+-------------------------------------------------
906
+$ git commit
907
+file.txt: needs merge
908
+-------------------------------------------------
909
+
910
+Also, git status will list those files as "unmerged".
911
+
912
+All of the changes that git was able to merge automatically are
913
+already added to the index file, so gitlink:git-diff[1] shows only
914
+the conflicts. Also, it uses a somewhat unusual syntax:
915
+
916
+-------------------------------------------------
917
+$ git diff
918
+diff --cc file.txt
919
+index 802992c,2b60207..0000000
920
+--- a/file.txt
921
++++ b/file.txt
922
+@@@ -1,1 -1,1 +1,5 @@@
923
+++<<<<<<< HEAD:file.txt
924
+ +Hello world
925
+++=======
926
++ Goodbye
927
+++>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
928
+-------------------------------------------------
929
+
930
+Recall that the commit which will be commited after we resolve this
931
+conflict will have two parents instead of the usual one: one parent
932
+will be HEAD, the tip of the current branch; the other will be the
933
+tip of the other branch, which is stored temporarily in MERGE_HEAD.
934
+
935
+The diff above shows the differences between the working-tree version
936
+of file.txt and two previous version: one version from HEAD, and one
937
+from MERGE_HEAD. So instead of preceding each line by a single "+"
938
+or "-", it now uses two columns: the first column is used for
939
+differences between the first parent and the working directory copy,
940
+and the second for differences between the second parent and the
941
+working directory copy. Thus after resolving the conflict in the
942
+obvious way, the diff will look like:
943
+
944
+-------------------------------------------------
945
+$ git diff
946
+diff --cc file.txt
947
+index 802992c,2b60207..0000000
948
+--- a/file.txt
949
++++ b/file.txt
950
+@@@ -1,1 -1,1 +1,1 @@@
951
+- Hello world
952
+ -Goodbye
953
+++Goodbye world
954
+-------------------------------------------------
955
+
956
+This shows that our resolved version deleted "Hello world" from the
957
+first parent, deleted "Goodbye" from the second parent, and added
958
+"Goodbye world", which was previously absent from both.
959
+
960
+The gitlink:git-log[1] command also provides special help for merges:
961
+
962
+-------------------------------------------------
963
+$ git log --merge
964
+-------------------------------------------------
965
+
966
+This will list all commits which exist only on HEAD or on MERGE_HEAD,
967
+and which touch an unmerged file.
968
+
969
+We can now add the resolved version to the index and commit:
970
+
971
+-------------------------------------------------
972
+$ git add file.txt
973
+$ git commit
974
+-------------------------------------------------
975
+
976
+Note that the commit message will already be filled in for you with
977
+some information about the merge. Normally you can just use this
978
+default message unchanged, but you may add additional commentary of
979
+your own if desired.
980
+
981
+[[undoing-a-merge]]
982
+undoing a merge
983
+---------------
984
+
985
+If you get stuck and decide to just give up and throw the whole mess
986
+away, you can always return to the pre-merge state with
987
+
988
+-------------------------------------------------
989
+$ git reset --hard HEAD
990
+-------------------------------------------------
991
+
992
+Or, if you've already commited the merge that you want to throw away,
993
+
994
+-------------------------------------------------
995
+$ git reset --hard HEAD^
996
+-------------------------------------------------
997
+
998
+However, this last command can be dangerous in some cases--never
999
+throw away a commit you have already committed if that commit may
1000
+itself have been merged into another branch, as doing so may confuse
1001
+further merges.
1002
+
1003
+Fast-forward merges
1004
+-------------------
1005
+
1006
+There is one special case not mentioned above, which is treated
1007
+differently. Normally, a merge results in a merge commit, with two
1008
+parents, one pointing at each of the two lines of development that
1009
+were merged.
1010
+
1011
+However, if one of the two lines of development is completely
1012
+contained within the other--so every commit present in the one is
1013
+already contained in the other--then git just performs a
1014
+<<fast-forwards,fast forward>>; the head of the current branch is
1015
+moved forward to point at the head of the merged-in branch, without
1016
+any new commits being created.
1017
+
1018
+Ensuring good performance
1019
+-------------------------
1020
+
1021
+On large repositories, git depends on compression to keep the history
1022
+information from taking up to much space on disk or in memory.
1023
+
1024
+This compression is not performed automatically. Therefore you
1025
+should occasionally run
1026
+
1027
+-------------------------------------------------
1028
+$ git gc
1029
+-------------------------------------------------
1030
+
1031
+to recompress the archive and to prune any commits which are no
1032
+longer referred to anywhere. This can be very time-consuming, and
1033
+you should not modify the repository while it is working, so you
1034
+should run it while you are not working.
1035
+
1036
+Sharing development with others
1037
+-------------------------------
1038
+
1039
+[[getting-updates-with-git-pull]]
1040
+Getting updates with git pull
1041
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1042
+
1043
+After you clone a repository and make a few changes of your own, you
1044
+may wish to check the original repository for updates and merge them
1045
+into your own work.
1046
+
1047
+We have already seen <<Updating-a-repository-with-git-fetch,how to
1048
+keep remote tracking branches up to date>> with gitlink:git-fetch[1],
1049
+and how to merge two branches. So you can merge in changes from the
1050
+original repository's master branch with:
1051
+
1052
+-------------------------------------------------
1053
+$ git fetch
1054
+$ git merge origin/master
1055
+-------------------------------------------------
1056
+
1057
+However, the gitlink:git-pull[1] command provides a way to do this in
1058
+one step:
1059
+
1060
+-------------------------------------------------
1061
+$ git pull origin master
1062
+-------------------------------------------------
1063
+
1064
+In fact, "origin" is normally the default repository to pull from,
1065
+and the default branch is normally the HEAD of the remote repository,
1066
+so often you can accomplish the above with just
1067
+
1068
+-------------------------------------------------
1069
+$ git pull
1070
+-------------------------------------------------
1071
+
1072
+See the descriptions of the branch.<name>.remote and
1073
+branch.<name>.merge options in gitlink:git-repo-config[1] to learn
1074
+how to control these defaults depending on the current branch.
1075
+
1076
+In addition to saving you keystrokes, "git pull" also helps you by
1077
+producing a default commit message documenting the branch and
1078
+repository that you pulled from.
1079
+
1080
+(But note that no such commit will be created in the case of a
1081
+<<fast-forwards,fast forward>>; instead, your branch will just be
1082
+updated to point to the latest commit from the upstream branch).
1083
+
1084
+Submitting patches to a project
1085
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1086
+
1087
+If you just have a few changes, the simplest way to submit them may
1088
+just be to send them as patches in email:
1089
+
1090
+First, use gitlink:git-format-patches[1]; for example:
1091
+
1092
+-------------------------------------------------
1093
+$ git format-patches origin
1094
+-------------------------------------------------
1095
+
1096
+will produce a numbered series of files in the current directory, one
1097
+for each patch in the current branch but not in origin/HEAD.
1098
+
1099
+You can then import these into your mail client and send them by
1100
+hand. However, if you have a lot to send at once, you may prefer to
1101
+use the gitlink:git-send-email[1] script to automate the process.
1102
+Consult the mailing list for your project first to determine how they
1103
+prefer such patches be handled.
1104
+
1105
+Importing patches to a project
1106
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1107
+
1108
+Git also provides a tool called gitlink:git-am[1] (am stands for
1109
+"apply mailbox"), for importing such an emailed series of patches.
1110
+Just save all of the patch-containing messages, in order, into a
1111
+single mailbox file, say "patches.mbox", then run
1112
+
1113
+-------------------------------------------------
1114
+$ git am patches.mbox
1115
+-------------------------------------------------
1116
+
1117
+Git will apply each patch in order; if any conflicts are found, it
1118
+will stop, and you can fix the conflicts as described in
1119
+"<<resolving-a-merge,Resolving a merge>>". Once the index is updated
1120
+with the results of the conflict resolution, instead of creating a
1121
+new commit, just run
1122
+
1123
+-------------------------------------------------
1124
+$ git am --resolved
1125
+-------------------------------------------------
1126
+
1127
+and git will create the commit for you and continue applying the
1128
+remaining patches from the mailbox.
1129
+
1130
+The final result will be a series of commits, one for each patch in
1131
+the original mailbox, with authorship and commit log message each
1132
+taken from the message containing each patch.
1133
+
1134
+[[setting-up-a-public-repository]]
1135
+Setting up a public repository
1136
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1137
+
1138
+Another way to submit changes to a project is to simply tell the
1139
+maintainer of that project to pull from your repository, exactly as
1140
+you did in the section "<<getting-updates-with-git-pull, Getting
1141
+updates with git pull>>".
1142
+
1143
+If you and maintainer both have accounts on the same machine, then
1144
+then you can just pull changes from each other's repositories
1145
+directly; note that all of the command (gitlink:git-clone[1],
1146
+git-fetch[1], git-pull[1], etc.) which accept a URL as an argument
1147
+will also accept a local file patch; so, for example, you can
1148
+use
1149
+
1150
+-------------------------------------------------
1151
+$ git clone /path/to/repository
1152
+$ git pull /path/to/other/repository
1153
+-------------------------------------------------
1154
+
1155
+If this sort of setup is inconvenient or impossible, another (more
1156
+common) option is to set up a public repository on a public server.
1157
+This also allows you to cleanly separate private work in progress
1158
+from publicly visible work.
1159
+
1160
+You will continue to do your day-to-day work in your personal
1161
+repository, but periodically "push" changes from your personal
1162
+repository into your public repository, allowing other developers to
1163
+pull from that repository. So the flow of changes, in a situation
1164
+where there is one other developer with a public repository, looks
1165
+like this:
1166
+
1167
+ you push
1168
+ your personal repo ------------------> your public repo
1169
+ ^ |
1170
+ | |
1171
+ | you pull | they pull
1172
+ | |
1173
+ | |
1174
+ | they push V
1175
+ their public repo <------------------- their repo
1176
+
1177
+Now, assume your personal repository is in the directory ~/proj. We
1178
+first create a new clone of the repository:
1179
+
1180
+-------------------------------------------------
1181
+$ git clone --bare proj-clone.git
1182
+-------------------------------------------------
1183
+
1184
+The resulting directory proj-clone.git will contains a "bare" git
1185
+repository--it is just the contents of the ".git" directory, without
1186
+a checked-out copy of a working directory.
1187
+
1188
+Next, copy proj-clone.git to the server where you plan to host the
1189
+public repository. You can use scp, rsync, or whatever is most
1190
+convenient.
1191
+
1192
+If somebody else maintains the public server, they may already have
1193
+set up a git service for you, and you may skip to the section
1194
+"<<pushing-changes-to-a-public-repository,Pushing changes to a public
1195
+repository>>", below.
1196
+
1197
+Otherwise, the following sections explain how to export your newly
1198
+created public repository:
1199
+
1200
+[[exporting-via-http]]
1201
+Exporting a git repository via http
1202
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1203
+
1204
+The git protocol gives better performance and reliability, but on a
1205
+host with a web server set up, http exports may be simpler to set up.
1206
+
1207
+All you need to do is place the newly created bare git repository in
1208
+a directory that is exported by the web server, and make some
1209
+adjustments to give web clients some extra information they need:
1210
+
1211
+-------------------------------------------------
1212
+$ mv proj.git /home/you/public_html/proj.git
1213
+$ cd proj.git
1214
+$ git update-server-info
1215
+$ chmod a+x hooks/post-update
1216
+-------------------------------------------------
1217
+
1218
+(For an explanation of the last two lines, see
1219
+gitlink:git-update-server-info[1], and the documentation
1220
+link:hooks.txt[Hooks used by git].)
1221
+
1222
+Advertise the url of proj.git. Anybody else should then be able to
1223
+clone or pull from that url, for example with a commandline like:
1224
+
1225
+-------------------------------------------------
1226
+$ git clone http://yourserver.com/~you/proj.git
1227
+-------------------------------------------------
1228
+
1229
+(See also
1230
+link:howto/setup-git-server-over-http.txt[setup-git-server-over-http]
1231
+for a slightly more sophisticated setup using WebDAV which also
1232
+allows pushing over http.)
1233
+
1234
+[[exporting-via-git]]
1235
+Exporting a git repository via the git protocol
1236
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1237
+
1238
+This is the preferred method.
1239
+
1240
+For now, we refer you to the gitlink:git-daemon[1] man page for
1241
+instructions. (See especially the examples section.)
1242
+
1243
+[[pushing-changes-to-a-public-repository]]
1244
+Pushing changes to a public repository
1245
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1246
+
1247
+Note that the two techniques outline above (exporting via
1248
+<<exporting-via-http,http>> or <<exporting-via-git,git>>) allow other
1249
+maintainers to fetch your latest changes, but they do not allow write
1250
+access, which you will need to update the public repository with the
1251
+latest changes created in your private repository.
1252
+
1253
+The simplest way to do this is using gitlink:git-push[1] and ssh; to
1254
+update the remote branch named "master" with the latest state of your
1255
+branch named "master", run
1256
+
1257
+-------------------------------------------------
1258
+$ git push ssh://yourserver.com/~you/proj.git master:master
1259
+-------------------------------------------------
1260
+
1261
+or just
1262
+
1263
+-------------------------------------------------
1264
+$ git push ssh://yourserver.com/~you/proj.git master
1265
+-------------------------------------------------
1266
+
1267
+As with git-fetch, git-push will complain if this does not result in
1268
+a <<fast-forwards,fast forward>>. Normally this is a sign of
1269
+something wrong. However, if you are sure you know what you're
1270
+doing, you may force git-push to perform the update anyway by
1271
+proceeding the branch name by a plus sign:
1272
+
1273
+-------------------------------------------------
1274
+$ git push ssh://yourserver.com/~you/proj.git +master
1275
+-------------------------------------------------
1276
+
1277
+As with git-fetch, you may also set up configuration options to
1278
+save typing; so, for example, after
1279
+
1280
+-------------------------------------------------
1281
+$ cat >.git/config <<EOF
1282
+[remote "public-repo"]
1283
+ url = ssh://yourserver.com/~you/proj.git
1284
+EOF
1285
+-------------------------------------------------
1286
+
1287
+you should be able to perform the above push with just
1288
+
1289
+-------------------------------------------------
1290
+$ git push public-repo master
1291
+-------------------------------------------------
1292
+
1293
+See the explanations of the remote.<name>.url, branch.<name>.remote,
1294
+and remote.<name>.push options in gitlink:git-repo-config[1] for
1295
+details.
1296
+
1297
+Setting up a shared repository
1298
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1299
+
1300
+Another way to collaborate is by using a model similar to that
1301
+commonly used in CVS, where several developers with special rights
1302
+all push to and pull from a single shared repository. See
1303
+link:cvs-migration.txt[git for CVS users] for instructions on how to
1304
+set this up.
1305
+
1306
+Fixing mistakes
1307
+---------------
1308
+
1309
+If you've messed up the working tree, but haven't yet committed your
1310
+mistake, you can return the entire working tree to the last committed
1311
+state with
1312
+
1313
+-------------------------------------------------
1314
+$ git reset --hard HEAD
1315
+-------------------------------------------------
1316
+
1317
+If you make a commit that you later wish you hadn't, there are two
1318
+fundamentally different ways to fix the problem:
1319
+
1320
+ 1. You can create a new commit that undoes whatever was done
1321
+ by the previous commit. This is the correct thing if your
1322
+ mistake has already been made public.
1323
+
1324
+ 2. You can go back and modify the old commit. You should
1325
+ never do this if you have already made the history public;
1326
+ git does not normally expect the "history" of a project to
1327
+ change, and cannot correctly perform repeated merges from
1328
+ a branch that has had its history changed.
1329
+
1330
+Fixing a mistake with a new commit
1331
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1332
+
1333
+Creating a new commit that reverts an earlier change is very easy;
1334
+just pass the gitlink:git-revert[1] command a reference to the bad
1335
+commit; for example, to revert the most recent commit:
1336
+
1337
+-------------------------------------------------
1338
+$ git revert HEAD
1339
+-------------------------------------------------
1340
+
1341
+This will create a new commit which undoes the change in HEAD. You
1342
+will be given a chance to edit the commit message for the new commit.
1343
+
1344
+You can also revert an earlier change, for example, the next-to-last:
1345
+
1346
+-------------------------------------------------
1347
+$ git revert HEAD^
1348
+-------------------------------------------------
1349
+
1350
+In this case git will attempt to undo the old change while leaving
1351
+intact any changes made since then. If more recent changes overlap
1352
+with the changes to be reverted, then you will be asked to fix
1353
+conflicts manually, just as in the case of <<resolving-a-merge,
1354
+resolving a merge>>.
1355
+
1356
+Fixing a mistake by editing history
1357
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1358
+
1359
+If the problematic commit is the most recent commit, and you have not
1360
+yet made that commit public, then you may just
1361
+<<undoing-a-merge,destroy it using git-reset>>.
1362
+
1363
+Alternatively, you
1364
+can edit the working directory and update the index to fix your
1365
+mistake, just as if you were going to <<how-to-make-a-commit,create a
1366
+new commit>>, then run
1367
+
1368
+-------------------------------------------------
1369
+$ git commit --amend
1370
+-------------------------------------------------
1371
+
1372
+which will replace the old commit by a new commit incorporating your
1373
+changes, giving you a chance to edit the old commit message first.
1374
+
1375
+Again, you should never do this to a commit that may already have
1376
+been merged into another branch; use gitlink:git-revert[1] instead in
1377
+that case.
1378
+
1379
+It is also possible to edit commits further back in the history, but
1380
+this is an advanced topic to be left for
1381
+<<cleaning-up-history,another chapter>>.
1382
+
1383
+Checking out an old version of a file
1384
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1385
+
1386
+In the process of undoing a previous bad change, you may find it
1387
+useful to check out an older version of a particular file using
1388
+gitlink:git-checkout[1]. We've used git checkout before to switch
1389
+branches, but it has quite different behavior if it is given a path
1390
+name: the command
1391
+
1392
+-------------------------------------------------
1393
+$ git checkout HEAD^ path/to/file
1394
+-------------------------------------------------
1395
+
1396
+replaces path/to/file by the contents it had in the commit HEAD^, and
1397
+also updates the index to match. It does not change branches.
1398
+
1399
+If you just want to look at an old version of the file, without
1400
+modifying the working directory, you can do that with
1401
+gitlink:git-show[1]:
1402
+
1403
+-------------------------------------------------
1404
+$ git show HEAD^ path/to/file
1405
+-------------------------------------------------
1406
+
1407
+which will display the given version of the file.
1408
+
1409
+Working with other version control systems
1410
+==========================================
1411
+
1412
+TODO: CVS, Subversion, ?
1413
+
1414
+[[cleaning-up-history]]
1415
+Cleaning up history: rebasing, cherry-picking, and patch series
1416
+===============================================================
1417
+
1418
+TODO: rebase, cherry-pick, pointers to other tools (like stgit)
1419
+
1420
+Git internals
1421
+=============
1422
+
1423
+Architectural overview
1424
+----------------------
1425
+
1426
+TODO: Sources, README, core-tutorial, tutorial-2.txt, technical/
1427
+
1428
+Glossary of git terms
1429
+=====================
1430
+
1431
+include::glossary.txt[]
1432
+
1433
+Todo list for this manual
1434
+=========================
1435
+
1436
+Scan Documentation/ for other stuff left out; in particular:
1437
+ howto's
1438
+ README
1439
+ some of technical/?
1440
+ hooks
1441
+ etc.
1442
+
1443
+Scan email archives for other stuff left out
1444
+
1445
+Scan man pages to see if any assume more background than this manual
1446
+provides.
1447
+
1448
+Mention of gitweb.
1449
+
1450
+Update git fetch discussion to use "git remote" setup. That will
1451
+make things simpler. Maybe wait till git remote is done.
1452
+
1453
+Can also simplify beginning by suggesting disconnected head instead
1454
+of temporary branch creation.
1455
+
1456
+Explain how to refer to file stages in the "how to resolve a merge"
1457
+section: diff -1, -2, -3; :1:/path notation.
1458
+
1459
+Include cross-references to the glossary, where appropriate.
1460
+