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