1 Git User's Manual
2 _________________
4 This manual is designed to be readable by someone with basic unix
5 commandline skills, but no previous knowledge of git.
7 Chapter 1 gives a brief overview of git commands, without any
8 explanation; you can skip to chapter 2 on a first reading.
10 Chapters 2 and 3 explain how to fetch and study a project using
11 git--the tools you'd need to build and test a particular version of a
12 software project, to search for regressions, and so on.
14 Chapter 4 explains how to do development with git, and chapter 5 how
15 to share that development with others.
17 Further chapters cover more specialized topics.
19 Comprehensive reference documentation is available through the man
20 pages. For a command such as "git clone", just use
22 ------------------------------------------------
23 $ man git-clone
24 ------------------------------------------------
26 Git Quick Start
27 ===============
29 This is a quick summary of the major commands; the following chapters
30 will explain how these work in more detail.
32 Creating a new repository
33 -------------------------
35 From a tarball:
37 -----------------------------------------------
38 $ tar xzf project.tar.gz
39 $ cd project
40 $ git init
41 Initialized empty Git repository in .git/
42 $ git add .
43 $ git commit
44 -----------------------------------------------
46 From a remote repository:
48 -----------------------------------------------
49 $ git clone git://example.com/pub/project.git
50 $ cd project
51 -----------------------------------------------
53 Managing branches
54 -----------------
56 -----------------------------------------------
57 $ git branch # list all branches in this repo
58 $ git checkout test # switch working directory to branch "test"
59 $ git branch new # create branch "new" starting at current HEAD
60 $ git branch -d new # delete branch "new"
61 -----------------------------------------------
63 Instead of basing new branch on current HEAD (the default), use:
65 -----------------------------------------------
66 $ git branch new test # branch named "test"
67 $ git branch new v2.6.15 # tag named v2.6.15
68 $ git branch new HEAD^ # commit before the most recent
69 $ git branch new HEAD^^ # commit before that
70 $ git branch new test~10 # ten commits before tip of branch "test"
71 -----------------------------------------------
73 Create and switch to a new branch at the same time:
75 -----------------------------------------------
76 $ git checkout -b new v2.6.15
77 -----------------------------------------------
79 Update and examine branches from the repository you cloned from:
81 -----------------------------------------------
82 $ git fetch # update
83 $ git branch -r # list
84 origin/master
85 origin/next
86 ...
87 $ git branch checkout -b masterwork origin/master
88 -----------------------------------------------
90 Fetch a branch from a different repository, and give it a new
91 name in your repository:
93 -----------------------------------------------
94 $ git fetch git://example.com/project.git theirbranch:mybranch
95 $ git fetch git://example.com/project.git v2.6.15:mybranch
96 -----------------------------------------------
98 Keep a list of repositories you work with regularly:
100 -----------------------------------------------
101 $ git remote add example git://example.com/project.git
102 $ git remote # list remote repositories
103 example
104 origin
105 $ git remote show example # get details
106 * remote example
107 URL: git://example.com/project.git
108 Tracked remote branches
109 master next ...
110 $ git fetch example # update branches from example
111 $ git branch -r # list all remote branches
112 -----------------------------------------------
115 Exploring history
116 -----------------
118 -----------------------------------------------
119 $ gitk # visualize and browse history
120 $ git log # list all commits
121 $ git log src/ # ...modifying src/
122 $ git log v2.6.15..v2.6.16 # ...in v2.6.16, not in v2.6.15
123 $ git log master..test # ...in branch test, not in branch master
124 $ git log test..master # ...in branch master, but not in test
125 $ git log test...master # ...in one branch, not in both
126 $ git log -S'foo()' # ...where difference contain "foo()"
127 $ git log --since="2 weeks ago"
128 $ git log -p # show patches as well
129 $ git show # most recent commit
130 $ git diff v2.6.15..v2.6.16 # diff between two tagged versions
131 $ git diff v2.6.15..HEAD # diff with current head
132 $ git grep "foo()" # search working directory for "foo()"
133 $ git grep v2.6.15 "foo()" # search old tree for "foo()"
134 $ git show v2.6.15:a.txt # look at old version of a.txt
135 -----------------------------------------------
137 Searching for regressions:
139 -----------------------------------------------
140 $ git bisect start
141 $ git bisect bad # current version is bad
142 $ git bisect good v2.6.13-rc2 # last known good revision
143 Bisecting: 675 revisions left to test after this
144 # test here, then:
145 $ git bisect good # if this revision is good, or
146 $ git bisect bad # if this revision is bad.
147 # repeat until done.
148 -----------------------------------------------
150 Making changes
151 --------------
153 Make sure git knows who to blame:
155 ------------------------------------------------
156 $ cat >~/.gitconfig <<\EOF
157 [user]
158 name = Your Name Comes Here
159 email = you@yourdomain.example.com
160 EOF
161 ------------------------------------------------
163 Select file contents to include in the next commit, then make the
164 commit:
166 -----------------------------------------------
167 $ git add a.txt # updated file
168 $ git add b.txt # new file
169 $ git rm c.txt # old file
170 $ git commit
171 -----------------------------------------------
173 Or, prepare and create the commit in one step:
175 -----------------------------------------------
176 $ git commit d.txt # use latest content of d.txt
177 $ git commit -a # use latest content of all tracked files
178 -----------------------------------------------
180 Merging
181 -------
183 -----------------------------------------------
184 $ git merge test # merge branch "test" into the current branch
185 $ git pull git://example.com/project.git master
186 # fetch and merge in remote branch
187 $ git pull . test # equivalent to git merge test
188 -----------------------------------------------
190 Sharing your changes
191 --------------------
193 Importing or exporting patches:
195 -----------------------------------------------
196 $ git format-patch origin..HEAD # format a patch for each commit
197 # in HEAD but not in origin
198 $ git-am mbox # import patches from the mailbox "mbox"
199 -----------------------------------------------
201 Fetch a branch in a different git repository, then merge into the
202 current branch:
204 -----------------------------------------------
205 $ git pull git://example.com/project.git theirbranch
206 -----------------------------------------------
208 Store the fetched branch into a local branch before merging into the
209 current branch:
211 -----------------------------------------------
212 $ git pull git://example.com/project.git theirbranch:mybranch
213 -----------------------------------------------
215 After creating commits on a local branch, update the remote
216 branch with your commits:
218 -----------------------------------------------
219 $ git push ssh://example.com/project.git mybranch:theirbranch
220 -----------------------------------------------
222 When remote and local branch are both named "test":
224 -----------------------------------------------
225 $ git push ssh://example.com/project.git test
226 -----------------------------------------------
228 Shortcut version for a frequently used remote repository:
230 -----------------------------------------------
231 $ git remote add example ssh://example.com/project.git
232 $ git push example test
233 -----------------------------------------------
235 Repositories and Branches
236 =========================
238 How to get a git repository
239 ---------------------------
241 It will be useful to have a git repository to experiment with as you
242 read this manual.
244 The best way to get one is by using the gitlink:git-clone[1] command
245 to download a copy of an existing repository for a project that you
246 are interested in. If you don't already have a project in mind, here
247 are some interesting examples:
249 ------------------------------------------------
250 # git itself (approx. 10MB download):
251 $ git clone git://git.kernel.org/pub/scm/git/git.git
252 # the linux kernel (approx. 150MB download):
253 $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git
254 ------------------------------------------------
256 The initial clone may be time-consuming for a large project, but you
257 will only need to clone once.
259 The clone command creates a new directory named after the project
260 ("git" or "linux-2.6" in the examples above). After you cd into this
261 directory, you will see that it contains a copy of the project files,
262 together with a special top-level directory named ".git", which
263 contains all the information about the history of the project.
265 In most of the following, examples will be taken from one of the two
266 repositories above.
268 How to check out a different version of a project
269 -------------------------------------------------
271 Git is best thought of as a tool for storing the history of a
272 collection of files. It stores the history as a compressed
273 collection of interrelated snapshots (versions) of the project's
274 contents.
276 A single git repository may contain multiple branches. Each branch
277 is a bookmark referencing a particular point in the project history.
278 The gitlink:git-branch[1] command shows you the list of branches:
280 ------------------------------------------------
281 $ git branch
282 * master
283 ------------------------------------------------
285 A freshly cloned repository contains a single branch, named "master",
286 and the working directory contains the version of the project
287 referred to by the master branch.
289 Most projects also use tags. Tags, like branches, are references
290 into the project's history, and can be listed using the
291 gitlink:git-tag[1] command:
293 ------------------------------------------------
294 $ git tag -l
295 v2.6.11
296 v2.6.11-tree
297 v2.6.12
298 v2.6.12-rc2
299 v2.6.12-rc3
300 v2.6.12-rc4
301 v2.6.12-rc5
302 v2.6.12-rc6
303 v2.6.13
304 ...
305 ------------------------------------------------
307 Tags are expected to always point at the same version of a project,
308 while branches are expected to advance as development progresses.
310 Create a new branch pointing to one of these versions and check it
311 out using gitlink:git-checkout[1]:
313 ------------------------------------------------
314 $ git checkout -b new v2.6.13
315 ------------------------------------------------
317 The working directory then reflects the contents that the project had
318 when it was tagged v2.6.13, and gitlink:git-branch[1] shows two
319 branches, with an asterisk marking the currently checked-out branch:
321 ------------------------------------------------
322 $ git branch
323 master
324 * new
325 ------------------------------------------------
327 If you decide that you'd rather see version 2.6.17, you can modify
328 the current branch to point at v2.6.17 instead, with
330 ------------------------------------------------
331 $ git reset --hard v2.6.17
332 ------------------------------------------------
334 Note that if the current branch was your only reference to a
335 particular point in history, then resetting that branch may leave you
336 with no way to find the history it used to point to; so use this
337 command carefully.
339 Understanding History: Commits
340 ------------------------------
342 Every change in the history of a project is represented by a commit.
343 The gitlink:git-show[1] command shows the most recent commit on the
344 current branch:
346 ------------------------------------------------
347 $ git show
348 commit 2b5f6dcce5bf94b9b119e9ed8d537098ec61c3d2
349 Author: Jamal Hadi Salim <hadi@cyberus.ca>
350 Date: Sat Dec 2 22:22:25 2006 -0800
352 [XFRM]: Fix aevent structuring to be more complete.
354 aevents can not uniquely identify an SA. We break the ABI with this
355 patch, but consensus is that since it is not yet utilized by any
356 (known) application then it is fine (better do it now than later).
358 Signed-off-by: Jamal Hadi Salim <hadi@cyberus.ca>
359 Signed-off-by: David S. Miller <davem@davemloft.net>
361 diff --git a/Documentation/networking/xfrm_sync.txt b/Documentation/networking/xfrm_sync.txt
362 index 8be626f..d7aac9d 100644
363 --- a/Documentation/networking/xfrm_sync.txt
364 +++ b/Documentation/networking/xfrm_sync.txt
365 @@ -47,10 +47,13 @@ aevent_id structure looks like:
367 struct xfrm_aevent_id {
368 struct xfrm_usersa_id sa_id;
369 + xfrm_address_t saddr;
370 __u32 flags;
371 + __u32 reqid;
372 };
373 ...
374 ------------------------------------------------
376 As you can see, a commit shows who made the latest change, what they
377 did, and why.
379 Every commit has a 40-hexdigit id, sometimes called the "SHA1 id", shown
380 on the first line of the "git show" output. You can usually refer to
381 a commit by a shorter name, such as a tag or a branch name, but this
382 longer id can also be useful. In particular, it is a globally unique
383 name for this commit: so if you tell somebody else the SHA1 id (for
384 example in email), then you are guaranteed they will see the same
385 commit in their repository that you do in yours.
387 Understanding history: commits, parents, and reachability
388 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
390 Every commit (except the very first commit in a project) also has a
391 parent commit which shows what happened before this commit.
392 Following the chain of parents will eventually take you back to the
393 beginning of the project.
395 However, the commits do not form a simple list; git allows lines of
396 development to diverge and then reconverge, and the point where two
397 lines of development reconverge is called a "merge". The commit
398 representing a merge can therefore have more than one parent, with
399 each parent representing the most recent commit on one of the lines
400 of development leading to that point.
402 The best way to see how this works is using the gitlink:gitk[1]
403 command; running gitk now on a git repository and looking for merge
404 commits will help understand how the git organizes history.
406 In the following, we say that commit X is "reachable" from commit Y
407 if commit X is an ancestor of commit Y. Equivalently, you could say
408 that Y is a descendent of X, or that there is a chain of parents
409 leading from commit Y to commit X.
411 Undestanding history: History diagrams
412 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
414 We will sometimes represent git history using diagrams like the one
415 below. Commits are shown as "o", and the links between them with
416 lines drawn with - / and \. Time goes left to right:
418 o--o--o <-- Branch A
419 /
420 o--o--o <-- master
421 \
422 o--o--o <-- Branch B
424 If we need to talk about a particular commit, the character "o" may
425 be replaced with another letter or number.
427 Understanding history: What is a branch?
428 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
430 Though we've been using the word "branch" to mean a kind of reference
431 to a particular commit, the word branch is also commonly used to
432 refer to the line of commits leading up to that point. In the
433 example above, git may think of the branch named "A" as just a
434 pointer to one particular commit, but we may refer informally to the
435 line of three commits leading up to that point as all being part of
436 "branch A".
438 If we need to make it clear that we're just talking about the most
439 recent commit on the branch, we may refer to that commit as the
440 "head" of the branch.
442 Manipulating branches
443 ---------------------
445 Creating, deleting, and modifying branches is quick and easy; here's
446 a summary of the commands:
448 git branch::
449 list all branches
450 git branch <branch>::
451 create a new branch named <branch>, referencing the same
452 point in history as the current branch
453 git branch <branch> <start-point>::
454 create a new branch named <branch>, referencing
455 <start-point>, which may be specified any way you like,
456 including using a branch name or a tag name
457 git branch -d <branch>::
458 delete the branch <branch>; if the branch you are deleting
459 points to a commit which is not reachable from this branch,
460 this command will fail with a warning.
461 git branch -D <branch>::
462 even if the branch points to a commit not reachable
463 from the current branch, you may know that that commit
464 is still reachable from some other branch or tag. In that
465 case it is safe to use this command to force git to delete
466 the branch.
467 git checkout <branch>::
468 make the current branch <branch>, updating the working
469 directory to reflect the version referenced by <branch>
470 git checkout -b <new> <start-point>::
471 create a new branch <new> referencing <start-point>, and
472 check it out.
474 It is also useful to know that the special symbol "HEAD" can always
475 be used to refer to the current branch.
477 Examining branches from a remote repository
478 -------------------------------------------
480 The "master" branch that was created at the time you cloned is a copy
481 of the HEAD in the repository that you cloned from. That repository
482 may also have had other branches, though, and your local repository
483 keeps branches which track each of those remote branches, which you
484 can view using the "-r" option to gitlink:git-branch[1]:
486 ------------------------------------------------
487 $ git branch -r
488 origin/HEAD
489 origin/html
490 origin/maint
491 origin/man
492 origin/master
493 origin/next
494 origin/pu
495 origin/todo
496 ------------------------------------------------
498 You cannot check out these remote-tracking branches, but you can
499 examine them on a branch of your own, just as you would a tag:
501 ------------------------------------------------
502 $ git checkout -b my-todo-copy origin/todo
503 ------------------------------------------------
505 Note that the name "origin" is just the name that git uses by default
506 to refer to the repository that you cloned from.
508 [[how-git-stores-references]]
509 Naming branches, tags, and other references
510 -------------------------------------------
512 Branches, remote-tracking branches, and tags are all references to
513 commits. All references are named with a slash-separated path name
514 starting with "refs"; the names we've been using so far are actually
515 shorthand:
517 - The branch "test" is short for "refs/heads/test".
518 - The tag "v2.6.18" is short for "refs/tags/v2.6.18".
519 - "origin/master" is short for "refs/remotes/origin/master".
521 The full name is occasionally useful if, for example, there ever
522 exists a tag and a branch with the same name.
524 As another useful shortcut, if the repository "origin" posesses only
525 a single branch, you can refer to that branch as just "origin".
527 More generally, if you have defined a remote repository named
528 "example", you can refer to the branch in that repository as
529 "example". And for a repository with multiple branches, this will
530 refer to the branch designated as the "HEAD" branch.
532 For the complete list of paths which git checks for references, and
533 the order it uses to decide which to choose when there are multiple
534 references with the same shorthand name, see the "SPECIFYING
535 REVISIONS" section of gitlink:git-rev-parse[1].
537 [[Updating-a-repository-with-git-fetch]]
538 Updating a repository with git fetch
539 ------------------------------------
541 Eventually the developer cloned from will do additional work in her
542 repository, creating new commits and advancing the branches to point
543 at the new commits.
545 The command "git fetch", with no arguments, will update all of the
546 remote-tracking branches to the latest version found in her
547 repository. It will not touch any of your own branches--not even the
548 "master" branch that was created for you on clone.
550 Fetching branches from other repositories
551 -----------------------------------------
553 You can also track branches from repositories other than the one you
554 cloned from, using gitlink:git-remote[1]:
556 -------------------------------------------------
557 $ git remote add linux-nfs git://linux-nfs.org/pub/nfs-2.6.git
558 $ git fetch
559 * refs/remotes/linux-nfs/master: storing branch 'master' ...
560 commit: bf81b46
561 -------------------------------------------------
563 New remote-tracking branches will be stored under the shorthand name
564 that you gave "git remote add", in this case linux-nfs:
566 -------------------------------------------------
567 $ git branch -r
568 linux-nfs/master
569 origin/master
570 -------------------------------------------------
572 If you run "git fetch <remote>" later, the tracking branches for the
573 named <remote> will be updated.
575 If you examine the file .git/config, you will see that git has added
576 a new stanza:
578 -------------------------------------------------
579 $ cat .git/config
580 ...
581 [remote "linux-nfs"]
582 url = git://linux-nfs.org/~bfields/git.git
583 fetch = +refs/heads/*:refs/remotes/linux-nfs-read/*
584 ...
585 -------------------------------------------------
587 This is what causes git to track the remote's branches; you may
588 modify or delete these configuration options by editing .git/config
589 with a text editor.
591 Fetching individual branches
592 ----------------------------
594 TODO: find another home for this, later on:
596 You can also choose to update just one branch at a time:
598 -------------------------------------------------
599 $ git fetch origin todo:refs/remotes/origin/todo
600 -------------------------------------------------
602 The first argument, "origin", just tells git to fetch from the
603 repository you originally cloned from. The second argument tells git
604 to fetch the branch named "todo" from the remote repository, and to
605 store it locally under the name refs/remotes/origin/todo; as we saw
606 above, remote-tracking branches are stored under
607 refs/remotes/<name-of-repository>/<name-of-branch>.
609 You can also fetch branches from other repositories; so
611 -------------------------------------------------
612 $ git fetch git://example.com/proj.git master:refs/remotes/example/master
613 -------------------------------------------------
615 will create a new reference named "refs/remotes/example/master" and
616 store in it the branch named "master" from the repository at the
617 given URL. If you already have a branch named
618 "refs/remotes/example/master", it will attempt to "fast-forward" to
619 the commit given by example.com's master branch. So next we explain
620 what a fast-forward is:
622 [[fast-forwards]]
623 Understanding git history: fast-forwards
624 ----------------------------------------
626 In the previous example, when updating an existing branch, "git
627 fetch" checks to make sure that the most recent commit on the remote
628 branch is a descendant of the most recent commit on your copy of the
629 branch before updating your copy of the branch to point at the new
630 commit. Git calls this process a "fast forward".
632 A fast forward looks something like this:
634 o--o--o--o <-- old head of the branch
635 \
636 o--o--o <-- new head of the branch
639 In some cases it is possible that the new head will *not* actually be
640 a descendant of the old head. For example, the developer may have
641 realized she made a serious mistake, and decided to backtrack,
642 resulting in a situation like:
644 o--o--o--o--a--b <-- old head of the branch
645 \
646 o--o--o <-- new head of the branch
650 In this case, "git fetch" will fail, and print out a warning.
652 In that case, you can still force git to update to the new head, as
653 described in the following section. However, note that in the
654 situation above this may mean losing the commits labeled "a" and "b",
655 unless you've already created a reference of your own pointing to
656 them.
658 Forcing git fetch to do non-fast-forward updates
659 ------------------------------------------------
661 If git fetch fails because the new head of a branch is not a
662 descendant of the old head, you may force the update with:
664 -------------------------------------------------
665 $ git fetch git://example.com/proj.git +master:refs/remotes/example/master
666 -------------------------------------------------
668 Note the addition of the "+" sign. Be aware that commits which the
669 old version of example/master pointed at may be lost, as we saw in
670 the previous section.
672 Configuring remote branches
673 ---------------------------
675 We saw above that "origin" is just a shortcut to refer to the
676 repository which you originally cloned from. This information is
677 stored in git configuration variables, which you can see using
678 gitlink:git-repo-config[1]:
680 -------------------------------------------------
681 $ git-repo-config -l
682 core.repositoryformatversion=0
683 core.filemode=true
684 core.logallrefupdates=true
685 remote.origin.url=git://git.kernel.org/pub/scm/git/git.git
686 remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
687 branch.master.remote=origin
688 branch.master.merge=refs/heads/master
689 -------------------------------------------------
691 If there are other repositories that you also use frequently, you can
692 create similar configuration options to save typing; for example,
693 after
695 -------------------------------------------------
696 $ git repo-config remote.example.url git://example.com/proj.git
697 -------------------------------------------------
699 then the following two commands will do the same thing:
701 -------------------------------------------------
702 $ git fetch git://example.com/proj.git master:refs/remotes/example/master
703 $ git fetch example master:refs/remotes/example/master
704 -------------------------------------------------
706 Even better, if you add one more option:
708 -------------------------------------------------
709 $ git repo-config remote.example.fetch master:refs/remotes/example/master
710 -------------------------------------------------
712 then the following commands will all do the same thing:
714 -------------------------------------------------
715 $ git fetch git://example.com/proj.git master:ref/remotes/example/master
716 $ git fetch example master:ref/remotes/example/master
717 $ git fetch example example/master
718 $ git fetch example
719 -------------------------------------------------
721 You can also add a "+" to force the update each time:
723 -------------------------------------------------
724 $ git repo-config remote.example.fetch +master:ref/remotes/example/master
725 -------------------------------------------------
727 Don't do this unless you're sure you won't mind "git fetch" possibly
728 throwing away commits on mybranch.
730 Also note that all of the above configuration can be performed by
731 directly editing the file .git/config instead of using
732 gitlink:git-repo-config[1].
734 See gitlink:git-repo-config[1] for more details on the configuration
735 options mentioned above.
737 Exploring git history
738 =====================
740 Git is best thought of as a tool for storing the history of a
741 collection of files. It does this by storing compressed snapshots of
742 the contents of a file heirarchy, together with "commits" which show
743 the relationships between these snapshots.
745 Git provides extremely flexible and fast tools for exploring the
746 history of a project.
748 We start with one specialized tool which is useful for finding the
749 commit that introduced a bug into a project.
751 How to use bisect to find a regression
752 --------------------------------------
754 Suppose version 2.6.18 of your project worked, but the version at
755 "master" crashes. Sometimes the best way to find the cause of such a
756 regression is to perform a brute-force search through the project's
757 history to find the particular commit that caused the problem. The
758 gitlink:git-bisect[1] command can help you do this:
760 -------------------------------------------------
761 $ git bisect start
762 $ git bisect good v2.6.18
763 $ git bisect bad master
764 Bisecting: 3537 revisions left to test after this
765 [65934a9a028b88e83e2b0f8b36618fe503349f8e] BLOCK: Make USB storage depend on SCSI rather than selecting it [try #6]
766 -------------------------------------------------
768 If you run "git branch" at this point, you'll see that git has
769 temporarily moved you to a new branch named "bisect". This branch
770 points to a commit (with commit id 65934...) that is reachable from
771 v2.6.19 but not from v2.6.18. Compile and test it, and see whether
772 it crashes. Assume it does crash. Then:
774 -------------------------------------------------
775 $ git bisect bad
776 Bisecting: 1769 revisions left to test after this
777 [7eff82c8b1511017ae605f0c99ac275a7e21b867] i2c-core: Drop useless bitmaskings
778 -------------------------------------------------
780 checks out an older version. Continue like this, telling git at each
781 stage whether the version it gives you is good or bad, and notice
782 that the number of revisions left to test is cut approximately in
783 half each time.
785 After about 13 tests (in this case), it will output the commit id of
786 the guilty commit. You can then examine the commit with
787 gitlink:git-show[1], find out who wrote it, and mail them your bug
788 report with the commit id. Finally, run
790 -------------------------------------------------
791 $ git bisect reset
792 -------------------------------------------------
794 to return you to the branch you were on before and delete the
795 temporary "bisect" branch.
797 Note that the version which git-bisect checks out for you at each
798 point is just a suggestion, and you're free to try a different
799 version if you think it would be a good idea. For example,
800 occasionally you may land on a commit that broke something unrelated;
801 run
803 -------------------------------------------------
804 $ git bisect-visualize
805 -------------------------------------------------
807 which will run gitk and label the commit it chose with a marker that
808 says "bisect". Chose a safe-looking commit nearby, note its commit
809 id, and check it out with:
811 -------------------------------------------------
812 $ git reset --hard fb47ddb2db...
813 -------------------------------------------------
815 then test, run "bisect good" or "bisect bad" as appropriate, and
816 continue.
818 Naming commits
819 --------------
821 We have seen several ways of naming commits already:
823 - 40-hexdigit SHA1 id
824 - branch name: refers to the commit at the head of the given
825 branch
826 - tag name: refers to the commit pointed to by the given tag
827 (we've seen branches and tags are special cases of
828 <<how-git-stores-references,references>>).
829 - HEAD: refers to the head of the current branch
831 There are many more; see the "SPECIFYING REVISIONS" section of the
832 gitlink:git-rev-parse[1] man page for the complete list of ways to
833 name revisions. Some examples:
835 -------------------------------------------------
836 $ git show fb47ddb2 # the first few characters of the SHA1 id
837 # are usually enough to specify it uniquely
838 $ git show HEAD^ # the parent of the HEAD commit
839 $ git show HEAD^^ # the grandparent
840 $ git show HEAD~4 # the great-great-grandparent
841 -------------------------------------------------
843 Recall that merge commits may have more than one parent; by default,
844 ^ and ~ follow the first parent listed in the commit, but you can
845 also choose:
847 -------------------------------------------------
848 $ git show HEAD^1 # show the first parent of HEAD
849 $ git show HEAD^2 # show the second parent of HEAD
850 -------------------------------------------------
852 In addition to HEAD, there are several other special names for
853 commits:
855 Merges (to be discussed later), as well as operations such as
856 git-reset, which change the currently checked-out commit, generally
857 set ORIG_HEAD to the value HEAD had before the current operation.
859 The git-fetch operation always stores the head of the last fetched
860 branch in FETCH_HEAD. For example, if you run git fetch without
861 specifying a local branch as the target of the operation
863 -------------------------------------------------
864 $ git fetch git://example.com/proj.git theirbranch
865 -------------------------------------------------
867 the fetched commits will still be available from FETCH_HEAD.
869 When we discuss merges we'll also see the special name MERGE_HEAD,
870 which refers to the other branch that we're merging in to the current
871 branch.
873 The gitlink:git-rev-parse[1] command is a low-level command that is
874 occasionally useful for translating some name for a commit to the SHA1 id for
875 that commit:
877 -------------------------------------------------
878 $ git rev-parse origin
879 e05db0fd4f31dde7005f075a84f96b360d05984b
880 -------------------------------------------------
882 Creating tags
883 -------------
885 We can also create a tag to refer to a particular commit; after
886 running
888 -------------------------------------------------
889 $ git-tag stable-1 1b2e1d63ff
890 -------------------------------------------------
892 You can use stable-1 to refer to the commit 1b2e1d63ff.
894 This creates a "lightweight" tag. If the tag is a tag you wish to
895 share with others, and possibly sign cryptographically, then you
896 should create a tag object instead; see the gitlink:git-tag[1] man
897 page for details.
899 Browsing revisions
900 ------------------
902 The gitlink:git-log[1] command can show lists of commits. On its
903 own, it shows all commits reachable from the parent commit; but you
904 can also make more specific requests:
906 -------------------------------------------------
907 $ git log v2.5.. # commits since (not reachable from) v2.5
908 $ git log test..master # commits reachable from master but not test
909 $ git log master..test # ...reachable from test but not master
910 $ git log master...test # ...reachable from either test or master,
911 # but not both
912 $ git log --since="2 weeks ago" # commits from the last 2 weeks
913 $ git log Makefile # commits which modify Makefile
914 $ git log fs/ # ... which modify any file under fs/
915 $ git log -S'foo()' # commits which add or remove any file data
916 # matching the string 'foo()'
917 -------------------------------------------------
919 And of course you can combine all of these; the following finds
920 commits since v2.5 which touch the Makefile or any file under fs:
922 -------------------------------------------------
923 $ git log v2.5.. Makefile fs/
924 -------------------------------------------------
926 You can also ask git log to show patches:
928 -------------------------------------------------
929 $ git log -p
930 -------------------------------------------------
932 See the "--pretty" option in the gitlink:git-log[1] man page for more
933 display options.
935 Note that git log starts with the most recent commit and works
936 backwards through the parents; however, since git history can contain
937 multiple independant lines of development, the particular order that
938 commits are listed in may be somewhat arbitrary.
940 Generating diffs
941 ----------------
943 You can generate diffs between any two versions using
944 gitlink:git-diff[1]:
946 -------------------------------------------------
947 $ git diff master..test
948 -------------------------------------------------
950 Sometimes what you want instead is a set of patches:
952 -------------------------------------------------
953 $ git format-patch master..test
954 -------------------------------------------------
956 will generate a file with a patch for each commit reachable from test
957 but not from master. Note that if master also has commits which are
958 not reachable from test, then the combined result of these patches
959 will not be the same as the diff produced by the git-diff example.
961 Viewing old file versions
962 -------------------------
964 You can always view an old version of a file by just checking out the
965 correct revision first. But sometimes it is more convenient to be
966 able to view an old version of a single file without checking
967 anything out; this command does that:
969 -------------------------------------------------
970 $ git show v2.5:fs/locks.c
971 -------------------------------------------------
973 Before the colon may be anything that names a commit, and after it
974 may be any path to a file tracked by git.
976 Examples
977 --------
979 Check whether two branches point at the same history
980 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
982 Suppose you want to check whether two branches point at the same point
983 in history.
985 -------------------------------------------------
986 $ git diff origin..master
987 -------------------------------------------------
989 will tell you whether the contents of the project are the same at the
990 two branches; in theory, however, it's possible that the same project
991 contents could have been arrived at by two different historical
992 routes. You could compare the SHA1 id's:
994 -------------------------------------------------
995 $ git rev-list origin
996 e05db0fd4f31dde7005f075a84f96b360d05984b
997 $ git rev-list master
998 e05db0fd4f31dde7005f075a84f96b360d05984b
999 -------------------------------------------------
1001 Or you could recall that the ... operator selects all commits
1002 contained reachable from either one reference or the other but not
1003 both: so
1005 -------------------------------------------------
1006 $ git log origin...master
1007 -------------------------------------------------
1009 will return no commits when the two branches are equal.
1011 Check which tagged version a given fix was first included in
1012 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1014 Suppose you know that the commit e05db0fd fixed a certain problem.
1015 You'd like to find the earliest tagged release that contains that
1016 fix.
1018 Of course, there may be more than one answer--if the history branched
1019 after commit e05db0fd, then there could be multiple "earliest" tagged
1020 releases.
1022 You could just visually inspect the commits since e05db0fd:
1024 -------------------------------------------------
1025 $ gitk e05db0fd..
1026 -------------------------------------------------
1028 ...
1030 Developing with git
1031 ===================
1033 Telling git your name
1034 ---------------------
1036 Before creating any commits, you should introduce yourself to git. The
1037 easiest way to do so is:
1039 ------------------------------------------------
1040 $ cat >~/.gitconfig <<\EOF
1041 [user]
1042 name = Your Name Comes Here
1043 email = you@yourdomain.example.com
1044 EOF
1045 ------------------------------------------------
1048 Creating a new repository
1049 -------------------------
1051 Creating a new repository from scratch is very easy:
1053 -------------------------------------------------
1054 $ mkdir project
1055 $ cd project
1056 $ git init
1057 -------------------------------------------------
1059 If you have some initial content (say, a tarball):
1061 -------------------------------------------------
1062 $ tar -xzvf project.tar.gz
1063 $ cd project
1064 $ git init
1065 $ git add . # include everything below ./ in the first commit:
1066 $ git commit
1067 -------------------------------------------------
1069 [[how-to-make-a-commit]]
1070 how to make a commit
1071 --------------------
1073 Creating a new commit takes three steps:
1075 1. Making some changes to the working directory using your
1076 favorite editor.
1077 2. Telling git about your changes.
1078 3. Creating the commit using the content you told git about
1079 in step 2.
1081 In practice, you can interleave and repeat steps 1 and 2 as many
1082 times as you want: in order to keep track of what you want committed
1083 at step 3, git maintains a snapshot of the tree's contents in a
1084 special staging area called "the index."
1086 At the beginning, the content of the index will be identical to
1087 that of the HEAD. The command "git diff --cached", which shows
1088 the difference between the HEAD and the index, should therefore
1089 produce no output at that point.
1091 Modifying the index is easy:
1093 To update the index with the new contents of a modified file, use
1095 -------------------------------------------------
1096 $ git add path/to/file
1097 -------------------------------------------------
1099 To add the contents of a new file to the index, use
1101 -------------------------------------------------
1102 $ git add path/to/file
1103 -------------------------------------------------
1105 To remove a file from the index and from the working tree,
1107 -------------------------------------------------
1108 $ git rm path/to/file
1109 -------------------------------------------------
1111 After each step you can verify that
1113 -------------------------------------------------
1114 $ git diff --cached
1115 -------------------------------------------------
1117 always shows the difference between the HEAD and the index file--this
1118 is what you'd commit if you created the commit now--and that
1120 -------------------------------------------------
1121 $ git diff
1122 -------------------------------------------------
1124 shows the difference between the working tree and the index file.
1126 Note that "git add" always adds just the current contents of a file
1127 to the index; further changes to the same file will be ignored unless
1128 you run git-add on the file again.
1130 When you're ready, just run
1132 -------------------------------------------------
1133 $ git commit
1134 -------------------------------------------------
1136 and git will prompt you for a commit message and then create the new
1137 commmit. Check to make sure it looks like what you expected with
1139 -------------------------------------------------
1140 $ git show
1141 -------------------------------------------------
1143 As a special shortcut,
1145 -------------------------------------------------
1146 $ git commit -a
1147 -------------------------------------------------
1149 will update the index with any files that you've modified or removed
1150 and create a commit, all in one step.
1152 A number of commands are useful for keeping track of what you're
1153 about to commit:
1155 -------------------------------------------------
1156 $ git diff --cached # difference between HEAD and the index; what
1157 # would be commited if you ran "commit" now.
1158 $ git diff # difference between the index file and your
1159 # working directory; changes that would not
1160 # be included if you ran "commit" now.
1161 $ git status # a brief per-file summary of the above.
1162 -------------------------------------------------
1164 creating good commit messages
1165 -----------------------------
1167 Though not required, it's a good idea to begin the commit message
1168 with a single short (less than 50 character) line summarizing the
1169 change, followed by a blank line and then a more thorough
1170 description. Tools that turn commits into email, for example, use
1171 the first line on the Subject line and the rest of the commit in the
1172 body.
1174 how to merge
1175 ------------
1177 You can rejoin two diverging branches of development using
1178 gitlink:git-merge[1]:
1180 -------------------------------------------------
1181 $ git merge branchname
1182 -------------------------------------------------
1184 merges the development in the branch "branchname" into the current
1185 branch. If there are conflicts--for example, if the same file is
1186 modified in two different ways in the remote branch and the local
1187 branch--then you are warned; the output may look something like this:
1189 -------------------------------------------------
1190 $ git pull . next
1191 Trying really trivial in-index merge...
1192 fatal: Merge requires file-level merging
1193 Nope.
1194 Merging HEAD with 77976da35a11db4580b80ae27e8d65caf5208086
1195 Merging:
1196 15e2162 world
1197 77976da goodbye
1198 found 1 common ancestor(s):
1199 d122ed4 initial
1200 Auto-merging file.txt
1201 CONFLICT (content): Merge conflict in file.txt
1202 Automatic merge failed; fix conflicts and then commit the result.
1203 -------------------------------------------------
1205 Conflict markers are left in the problematic files, and after
1206 you resolve the conflicts manually, you can update the index
1207 with the contents and run git commit, as you normally would when
1208 creating a new file.
1210 If you examine the resulting commit using gitk, you will see that it
1211 has two parents, one pointing to the top of the current branch, and
1212 one to the top of the other branch.
1214 In more detail:
1216 [[resolving-a-merge]]
1217 Resolving a merge
1218 -----------------
1220 When a merge isn't resolved automatically, git leaves the index and
1221 the working tree in a special state that gives you all the
1222 information you need to help resolve the merge.
1224 Files with conflicts are marked specially in the index, so until you
1225 resolve the problem and update the index, git commit will fail:
1227 -------------------------------------------------
1228 $ git commit
1229 file.txt: needs merge
1230 -------------------------------------------------
1232 Also, git status will list those files as "unmerged".
1234 All of the changes that git was able to merge automatically are
1235 already added to the index file, so gitlink:git-diff[1] shows only
1236 the conflicts. Also, it uses a somewhat unusual syntax:
1238 -------------------------------------------------
1239 $ git diff
1240 diff --cc file.txt
1241 index 802992c,2b60207..0000000
1242 --- a/file.txt
1243 +++ b/file.txt
1244 @@@ -1,1 -1,1 +1,5 @@@
1245 ++<<<<<<< HEAD:file.txt
1246 +Hello world
1247 ++=======
1248 + Goodbye
1249 ++>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
1250 -------------------------------------------------
1252 Recall that the commit which will be commited after we resolve this
1253 conflict will have two parents instead of the usual one: one parent
1254 will be HEAD, the tip of the current branch; the other will be the
1255 tip of the other branch, which is stored temporarily in MERGE_HEAD.
1257 The diff above shows the differences between the working-tree version
1258 of file.txt and two previous version: one version from HEAD, and one
1259 from MERGE_HEAD. So instead of preceding each line by a single "+"
1260 or "-", it now uses two columns: the first column is used for
1261 differences between the first parent and the working directory copy,
1262 and the second for differences between the second parent and the
1263 working directory copy. Thus after resolving the conflict in the
1264 obvious way, the diff will look like:
1266 -------------------------------------------------
1267 $ git diff
1268 diff --cc file.txt
1269 index 802992c,2b60207..0000000
1270 --- a/file.txt
1271 +++ b/file.txt
1272 @@@ -1,1 -1,1 +1,1 @@@
1273 - Hello world
1274 -Goodbye
1275 ++Goodbye world
1276 -------------------------------------------------
1278 This shows that our resolved version deleted "Hello world" from the
1279 first parent, deleted "Goodbye" from the second parent, and added
1280 "Goodbye world", which was previously absent from both.
1282 The gitlink:git-log[1] command also provides special help for merges:
1284 -------------------------------------------------
1285 $ git log --merge
1286 -------------------------------------------------
1288 This will list all commits which exist only on HEAD or on MERGE_HEAD,
1289 and which touch an unmerged file.
1291 We can now add the resolved version to the index and commit:
1293 -------------------------------------------------
1294 $ git add file.txt
1295 $ git commit
1296 -------------------------------------------------
1298 Note that the commit message will already be filled in for you with
1299 some information about the merge. Normally you can just use this
1300 default message unchanged, but you may add additional commentary of
1301 your own if desired.
1303 [[undoing-a-merge]]
1304 undoing a merge
1305 ---------------
1307 If you get stuck and decide to just give up and throw the whole mess
1308 away, you can always return to the pre-merge state with
1310 -------------------------------------------------
1311 $ git reset --hard HEAD
1312 -------------------------------------------------
1314 Or, if you've already commited the merge that you want to throw away,
1316 -------------------------------------------------
1317 $ git reset --hard HEAD^
1318 -------------------------------------------------
1320 However, this last command can be dangerous in some cases--never
1321 throw away a commit you have already committed if that commit may
1322 itself have been merged into another branch, as doing so may confuse
1323 further merges.
1325 Fast-forward merges
1326 -------------------
1328 There is one special case not mentioned above, which is treated
1329 differently. Normally, a merge results in a merge commit, with two
1330 parents, one pointing at each of the two lines of development that
1331 were merged.
1333 However, if one of the two lines of development is completely
1334 contained within the other--so every commit present in the one is
1335 already contained in the other--then git just performs a
1336 <<fast-forwards,fast forward>>; the head of the current branch is
1337 moved forward to point at the head of the merged-in branch, without
1338 any new commits being created.
1340 Fixing mistakes
1341 ---------------
1343 If you've messed up the working tree, but haven't yet committed your
1344 mistake, you can return the entire working tree to the last committed
1345 state with
1347 -------------------------------------------------
1348 $ git reset --hard HEAD
1349 -------------------------------------------------
1351 If you make a commit that you later wish you hadn't, there are two
1352 fundamentally different ways to fix the problem:
1354 1. You can create a new commit that undoes whatever was done
1355 by the previous commit. This is the correct thing if your
1356 mistake has already been made public.
1358 2. You can go back and modify the old commit. You should
1359 never do this if you have already made the history public;
1360 git does not normally expect the "history" of a project to
1361 change, and cannot correctly perform repeated merges from
1362 a branch that has had its history changed.
1364 Fixing a mistake with a new commit
1365 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1367 Creating a new commit that reverts an earlier change is very easy;
1368 just pass the gitlink:git-revert[1] command a reference to the bad
1369 commit; for example, to revert the most recent commit:
1371 -------------------------------------------------
1372 $ git revert HEAD
1373 -------------------------------------------------
1375 This will create a new commit which undoes the change in HEAD. You
1376 will be given a chance to edit the commit message for the new commit.
1378 You can also revert an earlier change, for example, the next-to-last:
1380 -------------------------------------------------
1381 $ git revert HEAD^
1382 -------------------------------------------------
1384 In this case git will attempt to undo the old change while leaving
1385 intact any changes made since then. If more recent changes overlap
1386 with the changes to be reverted, then you will be asked to fix
1387 conflicts manually, just as in the case of <<resolving-a-merge,
1388 resolving a merge>>.
1390 Fixing a mistake by editing history
1391 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1393 If the problematic commit is the most recent commit, and you have not
1394 yet made that commit public, then you may just
1395 <<undoing-a-merge,destroy it using git-reset>>.
1397 Alternatively, you
1398 can edit the working directory and update the index to fix your
1399 mistake, just as if you were going to <<how-to-make-a-commit,create a
1400 new commit>>, then run
1402 -------------------------------------------------
1403 $ git commit --amend
1404 -------------------------------------------------
1406 which will replace the old commit by a new commit incorporating your
1407 changes, giving you a chance to edit the old commit message first.
1409 Again, you should never do this to a commit that may already have
1410 been merged into another branch; use gitlink:git-revert[1] instead in
1411 that case.
1413 It is also possible to edit commits further back in the history, but
1414 this is an advanced topic to be left for
1415 <<cleaning-up-history,another chapter>>.
1417 Checking out an old version of a file
1418 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1420 In the process of undoing a previous bad change, you may find it
1421 useful to check out an older version of a particular file using
1422 gitlink:git-checkout[1]. We've used git checkout before to switch
1423 branches, but it has quite different behavior if it is given a path
1424 name: the command
1426 -------------------------------------------------
1427 $ git checkout HEAD^ path/to/file
1428 -------------------------------------------------
1430 replaces path/to/file by the contents it had in the commit HEAD^, and
1431 also updates the index to match. It does not change branches.
1433 If you just want to look at an old version of the file, without
1434 modifying the working directory, you can do that with
1435 gitlink:git-show[1]:
1437 -------------------------------------------------
1438 $ git show HEAD^ path/to/file
1439 -------------------------------------------------
1441 which will display the given version of the file.
1443 Ensuring good performance
1444 -------------------------
1446 On large repositories, git depends on compression to keep the history
1447 information from taking up to much space on disk or in memory.
1449 This compression is not performed automatically. Therefore you
1450 should occasionally run
1452 -------------------------------------------------
1453 $ git gc
1454 -------------------------------------------------
1456 to recompress the archive and to prune any commits which are no
1457 longer referred to anywhere. This can be very time-consuming, and
1458 you should not modify the repository while it is working, so you
1459 should run it while you are not working.
1461 Sharing development with others
1462 ===============================
1464 [[getting-updates-with-git-pull]]
1465 Getting updates with git pull
1466 -----------------------------
1468 After you clone a repository and make a few changes of your own, you
1469 may wish to check the original repository for updates and merge them
1470 into your own work.
1472 We have already seen <<Updating-a-repository-with-git-fetch,how to
1473 keep remote tracking branches up to date>> with gitlink:git-fetch[1],
1474 and how to merge two branches. So you can merge in changes from the
1475 original repository's master branch with:
1477 -------------------------------------------------
1478 $ git fetch
1479 $ git merge origin/master
1480 -------------------------------------------------
1482 However, the gitlink:git-pull[1] command provides a way to do this in
1483 one step:
1485 -------------------------------------------------
1486 $ git pull origin master
1487 -------------------------------------------------
1489 In fact, "origin" is normally the default repository to pull from,
1490 and the default branch is normally the HEAD of the remote repository,
1491 so often you can accomplish the above with just
1493 -------------------------------------------------
1494 $ git pull
1495 -------------------------------------------------
1497 See the descriptions of the branch.<name>.remote and
1498 branch.<name>.merge options in gitlink:git-repo-config[1] to learn
1499 how to control these defaults depending on the current branch.
1501 In addition to saving you keystrokes, "git pull" also helps you by
1502 producing a default commit message documenting the branch and
1503 repository that you pulled from.
1505 (But note that no such commit will be created in the case of a
1506 <<fast-forwards,fast forward>>; instead, your branch will just be
1507 updated to point to the latest commit from the upstream branch).
1509 The git-pull command can also be given "." as the "remote" repository, in
1510 which case it just merges in a branch from the current repository; so
1511 the commands
1513 -------------------------------------------------
1514 $ git pull . branch
1515 $ git merge branch
1516 -------------------------------------------------
1518 are roughly equivalent. The former is actually very commonly used.
1520 Submitting patches to a project
1521 -------------------------------
1523 If you just have a few changes, the simplest way to submit them may
1524 just be to send them as patches in email:
1526 First, use gitlink:git-format-patches[1]; for example:
1528 -------------------------------------------------
1529 $ git format-patch origin
1530 -------------------------------------------------
1532 will produce a numbered series of files in the current directory, one
1533 for each patch in the current branch but not in origin/HEAD.
1535 You can then import these into your mail client and send them by
1536 hand. However, if you have a lot to send at once, you may prefer to
1537 use the gitlink:git-send-email[1] script to automate the process.
1538 Consult the mailing list for your project first to determine how they
1539 prefer such patches be handled.
1541 Importing patches to a project
1542 ------------------------------
1544 Git also provides a tool called gitlink:git-am[1] (am stands for
1545 "apply mailbox"), for importing such an emailed series of patches.
1546 Just save all of the patch-containing messages, in order, into a
1547 single mailbox file, say "patches.mbox", then run
1549 -------------------------------------------------
1550 $ git am -3 patches.mbox
1551 -------------------------------------------------
1553 Git will apply each patch in order; if any conflicts are found, it
1554 will stop, and you can fix the conflicts as described in
1555 "<<resolving-a-merge,Resolving a merge>>". (The "-3" option tells
1556 git to perform a merge; if you would prefer it just to abort and
1557 leave your tree and index untouched, you may omit that option.)
1559 Once the index is updated with the results of the conflict
1560 resolution, instead of creating a new commit, just run
1562 -------------------------------------------------
1563 $ git am --resolved
1564 -------------------------------------------------
1566 and git will create the commit for you and continue applying the
1567 remaining patches from the mailbox.
1569 The final result will be a series of commits, one for each patch in
1570 the original mailbox, with authorship and commit log message each
1571 taken from the message containing each patch.
1573 [[setting-up-a-public-repository]]
1574 Setting up a public repository
1575 ------------------------------
1577 Another way to submit changes to a project is to simply tell the
1578 maintainer of that project to pull from your repository, exactly as
1579 you did in the section "<<getting-updates-with-git-pull, Getting
1580 updates with git pull>>".
1582 If you and maintainer both have accounts on the same machine, then
1583 then you can just pull changes from each other's repositories
1584 directly; note that all of the command (gitlink:git-clone[1],
1585 git-fetch[1], git-pull[1], etc.) which accept a URL as an argument
1586 will also accept a local file patch; so, for example, you can
1587 use
1589 -------------------------------------------------
1590 $ git clone /path/to/repository
1591 $ git pull /path/to/other/repository
1592 -------------------------------------------------
1594 If this sort of setup is inconvenient or impossible, another (more
1595 common) option is to set up a public repository on a public server.
1596 This also allows you to cleanly separate private work in progress
1597 from publicly visible work.
1599 You will continue to do your day-to-day work in your personal
1600 repository, but periodically "push" changes from your personal
1601 repository into your public repository, allowing other developers to
1602 pull from that repository. So the flow of changes, in a situation
1603 where there is one other developer with a public repository, looks
1604 like this:
1606 you push
1607 your personal repo ------------------> your public repo
1608 ^ |
1609 | |
1610 | you pull | they pull
1611 | |
1612 | |
1613 | they push V
1614 their public repo <------------------- their repo
1616 Now, assume your personal repository is in the directory ~/proj. We
1617 first create a new clone of the repository:
1619 -------------------------------------------------
1620 $ git clone --bare proj-clone.git
1621 -------------------------------------------------
1623 The resulting directory proj-clone.git will contains a "bare" git
1624 repository--it is just the contents of the ".git" directory, without
1625 a checked-out copy of a working directory.
1627 Next, copy proj-clone.git to the server where you plan to host the
1628 public repository. You can use scp, rsync, or whatever is most
1629 convenient.
1631 If somebody else maintains the public server, they may already have
1632 set up a git service for you, and you may skip to the section
1633 "<<pushing-changes-to-a-public-repository,Pushing changes to a public
1634 repository>>", below.
1636 Otherwise, the following sections explain how to export your newly
1637 created public repository:
1639 [[exporting-via-http]]
1640 Exporting a git repository via http
1641 -----------------------------------
1643 The git protocol gives better performance and reliability, but on a
1644 host with a web server set up, http exports may be simpler to set up.
1646 All you need to do is place the newly created bare git repository in
1647 a directory that is exported by the web server, and make some
1648 adjustments to give web clients some extra information they need:
1650 -------------------------------------------------
1651 $ mv proj.git /home/you/public_html/proj.git
1652 $ cd proj.git
1653 $ git update-server-info
1654 $ chmod a+x hooks/post-update
1655 -------------------------------------------------
1657 (For an explanation of the last two lines, see
1658 gitlink:git-update-server-info[1], and the documentation
1659 link:hooks.txt[Hooks used by git].)
1661 Advertise the url of proj.git. Anybody else should then be able to
1662 clone or pull from that url, for example with a commandline like:
1664 -------------------------------------------------
1665 $ git clone http://yourserver.com/~you/proj.git
1666 -------------------------------------------------
1668 (See also
1669 link:howto/setup-git-server-over-http.txt[setup-git-server-over-http]
1670 for a slightly more sophisticated setup using WebDAV which also
1671 allows pushing over http.)
1673 [[exporting-via-git]]
1674 Exporting a git repository via the git protocol
1675 -----------------------------------------------
1677 This is the preferred method.
1679 For now, we refer you to the gitlink:git-daemon[1] man page for
1680 instructions. (See especially the examples section.)
1682 [[pushing-changes-to-a-public-repository]]
1683 Pushing changes to a public repository
1684 --------------------------------------
1686 Note that the two techniques outline above (exporting via
1687 <<exporting-via-http,http>> or <<exporting-via-git,git>>) allow other
1688 maintainers to fetch your latest changes, but they do not allow write
1689 access, which you will need to update the public repository with the
1690 latest changes created in your private repository.
1692 The simplest way to do this is using gitlink:git-push[1] and ssh; to
1693 update the remote branch named "master" with the latest state of your
1694 branch named "master", run
1696 -------------------------------------------------
1697 $ git push ssh://yourserver.com/~you/proj.git master:master
1698 -------------------------------------------------
1700 or just
1702 -------------------------------------------------
1703 $ git push ssh://yourserver.com/~you/proj.git master
1704 -------------------------------------------------
1706 As with git-fetch, git-push will complain if this does not result in
1707 a <<fast-forwards,fast forward>>. Normally this is a sign of
1708 something wrong. However, if you are sure you know what you're
1709 doing, you may force git-push to perform the update anyway by
1710 proceeding the branch name by a plus sign:
1712 -------------------------------------------------
1713 $ git push ssh://yourserver.com/~you/proj.git +master
1714 -------------------------------------------------
1716 As with git-fetch, you may also set up configuration options to
1717 save typing; so, for example, after
1719 -------------------------------------------------
1720 $ cat >.git/config <<EOF
1721 [remote "public-repo"]
1722 url = ssh://yourserver.com/~you/proj.git
1723 EOF
1724 -------------------------------------------------
1726 you should be able to perform the above push with just
1728 -------------------------------------------------
1729 $ git push public-repo master
1730 -------------------------------------------------
1732 See the explanations of the remote.<name>.url, branch.<name>.remote,
1733 and remote.<name>.push options in gitlink:git-repo-config[1] for
1734 details.
1736 Setting up a shared repository
1737 ------------------------------
1739 Another way to collaborate is by using a model similar to that
1740 commonly used in CVS, where several developers with special rights
1741 all push to and pull from a single shared repository. See
1742 link:cvs-migration.txt[git for CVS users] for instructions on how to
1743 set this up.
1745 Allow web browsing of a repository
1746 ----------------------------------
1748 TODO: Brief setup-instructions for gitweb
1750 Examples
1751 --------
1753 TODO: topic branches, typical roles as in everyday.txt, ?
1756 Working with other version control systems
1757 ==========================================
1759 TODO: CVS, Subversion, series-of-release-tarballs, ?
1761 [[cleaning-up-history]]
1762 Rewriting history and maintaining patch series
1763 ==============================================
1765 Normally commits are only added to a project, never taken away or
1766 replaced. Git is designed with this assumption, and violating it will
1767 cause git's merge machinery (for example) to do the wrong thing.
1769 However, there is a situation in which it can be useful to violate this
1770 assumption.
1772 Creating the perfect patch series
1773 ---------------------------------
1775 Suppose you are a contributor to a large project, and you want to add a
1776 complicated feature, and to present it to the other developers in a way
1777 that makes it easy for them to read your changes, verify that they are
1778 correct, and understand why you made each change.
1780 If you present all of your changes as a single patch (or commit), they may
1781 find it is too much to digest all at once.
1783 If you present them with the entire history of your work, complete with
1784 mistakes, corrections, and dead ends, they may be overwhelmed.
1786 So the ideal is usually to produce a series of patches such that:
1788 1. Each patch can be applied in order.
1790 2. Each patch includes a single logical change, together with a
1791 message explaining the change.
1793 3. No patch introduces a regression: after applying any initial
1794 part of the series, the resulting project still compiles and
1795 works, and has no bugs that it didn't have before.
1797 4. The complete series produces the same end result as your own
1798 (probably much messier!) development process did.
1800 We will introduce some tools that can help you do this, explain how to use
1801 them, and then explain some of the problems that can arise because you are
1802 rewriting history.
1804 Keeping a patch series up to date using git-rebase
1805 --------------------------------------------------
1807 Suppose you have a series of commits in a branch "mywork", which
1808 originally branched off from "origin".
1810 Suppose you create a branch "mywork" on a remote-tracking branch "origin",
1811 and created some commits on top of it:
1813 -------------------------------------------------
1814 $ git checkout -b mywork origin
1815 $ vi file.txt
1816 $ git commit
1817 $ vi otherfile.txt
1818 $ git commit
1819 ...
1820 -------------------------------------------------
1822 You have performed no merges into mywork, so it is just a simple linear
1823 sequence of patches on top of "origin":
1826 o--o--o <-- origin
1827 \
1828 o--o--o <-- mywork
1830 Some more interesting work has been done in the upstream project, and
1831 "origin" has advanced:
1833 o--o--O--o--o--o <-- origin
1834 \
1835 a--b--c <-- mywork
1837 At this point, you could use "pull" to merge your changes back in;
1838 the result would create a new merge commit, like this:
1841 o--o--O--o--o--o <-- origin
1842 \ \
1843 a--b--c--m <-- mywork
1845 However, if you prefer to keep the history in mywork a simple series of
1846 commits without any merges, you may instead choose to use
1847 gitlink:git-rebase[1]:
1849 -------------------------------------------------
1850 $ git checkout mywork
1851 $ git rebase origin
1852 -------------------------------------------------
1854 This will remove each of your commits from mywork, temporarily saving them
1855 as patches (in a directory named ".dotest"), update mywork to point at the
1856 latest version of origin, then apply each of the saved patches to the new
1857 mywork. The result will look like:
1860 o--o--O--o--o--o <-- origin
1861 \
1862 a'--b'--c' <-- mywork
1864 In the process, it may discover conflicts. In that case it will stop and
1865 allow you to fix the conflicts as described in
1866 "<<resolving-a-merge,Resolving a merge>>".
1868 XXX: no, maybe not: git diff doesn't produce very useful results, and there's
1869 no MERGE_HEAD.
1871 Once the index is updated with
1872 the results of the conflict resolution, instead of creating a new commit,
1873 just run
1875 -------------------------------------------------
1876 $ git rebase --continue
1877 -------------------------------------------------
1879 and git will continue applying the rest of the patches.
1881 At any point you may use the --abort option to abort this process and
1882 return mywork to the state it had before you started the rebase:
1884 -------------------------------------------------
1885 $ git rebase --abort
1886 -------------------------------------------------
1888 Reordering or selecting from a patch series
1889 -------------------------------------------
1891 Given one existing commit, the gitlink:git-cherry-pick[1] command allows
1892 you to apply the change introduced by that commit and create a new commit
1893 that records it.
1895 This can be useful for modifying a patch series.
1897 TODO: elaborate
1899 Other tools
1900 -----------
1902 There are numerous other tools, such as stgit, which exist for the purpose
1903 of maintianing a patch series. These are out of the scope of this manual.
1905 Problems with rewriting history
1906 -------------------------------
1908 The primary problem with rewriting the history of a branch has to do with
1909 merging.
1911 TODO: elaborate
1914 Git internals
1915 =============
1917 Architectural overview
1918 ----------------------
1920 TODO: Sources, README, core-tutorial, tutorial-2.txt, technical/
1922 Glossary of git terms
1923 =====================
1925 include::glossary.txt[]
1927 Notes and todo list for this manual
1928 ===================================
1930 This is a work in progress.
1932 The basic requirements:
1933 - It must be readable in order, from beginning to end, by
1934 someone intelligent with a basic grasp of the unix
1935 commandline, but without any special knowledge of git. If
1936 necessary, any other prerequisites should be specifically
1937 mentioned as they arise.
1938 - Whenever possible, section headings should clearly describe
1939 the task they explain how to do, in language that requires
1940 no more knowledge than necessary: for example, "importing
1941 patches into a project" rather than "the git-am command"
1943 Think about how to create a clear chapter dependency graph that will
1944 allow people to get to important topics without necessarily reading
1945 everything in between.
1947 Scan Documentation/ for other stuff left out; in particular:
1948 howto's
1949 README
1950 some of technical/?
1951 hooks
1952 etc.
1954 Scan email archives for other stuff left out
1956 Scan man pages to see if any assume more background than this manual
1957 provides.
1959 Simplify beginning by suggesting disconnected head instead of
1960 temporary branch creation.
1962 Explain how to refer to file stages in the "how to resolve a merge"
1963 section: diff -1, -2, -3, --ours, --theirs :1:/path notation. The
1964 "git ls-files --unmerged --stage" thing is sorta useful too,
1965 actually. And note gitk --merge. Also what's easiest way to see
1966 common merge base? Note also text where I claim rebase and am
1967 conflicts are resolved like merges isn't generally true, at least by
1968 default--fix.
1970 Add more good examples. Entire sections of just cookbook examples
1971 might be a good idea; maybe make an "advanced examples" section a
1972 standard end-of-chapter section?
1974 Include cross-references to the glossary, where appropriate.
1976 Add quickstart as first chapter.
1978 To document:
1979 reflogs, git reflog expire
1980 shallow clones?? See draft 1.5.0 release notes for some documentation.