013e46fe3c5e04ff93d257e9d43382d7b54fef0a
   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
   7Chapters 1 and 2 explain how to fetch and study a project using
   8git--the tools you'd need to build and test a particular version of a
   9software project, to search for regressions, and so on.
  10
  11Chapter 3 explains how to do development with git, and chapter 4 how
  12to share that development with others.
  13
  14Further chapters cover more specialized topics.
  15
  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 most of 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 branches from other repositories
 344-----------------------------------------
 345
 346You can also track branches from repositories other than the one you
 347cloned from, using gitlink:git-remote[1]:
 348
 349-------------------------------------------------
 350$ git remote add linux-nfs git://linux-nfs.org/pub/nfs-2.6.git
 351$ git fetch
 352* refs/remotes/linux-nfs/master: storing branch 'master' ...
 353  commit: bf81b46
 354-------------------------------------------------
 355
 356New remote-tracking branches will be stored under the shorthand name
 357that you gave "git remote add", in this case linux-nfs:
 358
 359-------------------------------------------------
 360$ git branch -r
 361linux-nfs/master
 362origin/master
 363-------------------------------------------------
 364
 365If you run "git fetch <remote>" later, the tracking branches for the
 366named <remote> will be updated.
 367
 368If you examine the file .git/config, you will see that git has added
 369a new stanza:
 370
 371-------------------------------------------------
 372$ cat .git/config
 373...
 374[remote "linux-nfs"]
 375        url = git://linux-nfs.org/~bfields/git.git
 376        fetch = +refs/heads/*:refs/remotes/linux-nfs-read/*
 377...
 378-------------------------------------------------
 379
 380This is what causes git to track the remote's branches; you may
 381modify or delete these configuration options by editing .git/config
 382with a text editor.
 383
 384Fetching individual branches
 385----------------------------
 386
 387TODO: find another home for this, later on:
 388
 389You can also choose to update just one branch at a time:
 390
 391-------------------------------------------------
 392$ git fetch origin todo:refs/remotes/origin/todo
 393-------------------------------------------------
 394
 395The first argument, "origin", just tells git to fetch from the
 396repository you originally cloned from.  The second argument tells git
 397to fetch the branch named "todo" from the remote repository, and to
 398store it locally under the name refs/remotes/origin/todo; as we saw
 399above, remote-tracking branches are stored under
 400refs/remotes/<name-of-repository>/<name-of-branch>.
 401
 402You can also fetch branches from other repositories; so
 403
 404-------------------------------------------------
 405$ git fetch git://example.com/proj.git master:refs/remotes/example/master
 406-------------------------------------------------
 407
 408will create a new reference named "refs/remotes/example/master" and
 409store in it the branch named "master" from the repository at the
 410given URL.  If you already have a branch named
 411"refs/remotes/example/master", it will attempt to "fast-forward" to
 412the commit given by example.com's master branch.  So next we explain
 413what a fast-forward is:
 414
 415[[fast-forwards]]
 416Understanding git history: fast-forwards
 417----------------------------------------
 418
 419In the previous example, when updating an existing branch, "git
 420fetch" checks to make sure that the most recent commit on the remote
 421branch is a descendant of the most recent commit on your copy of the
 422branch before updating your copy of the branch to point at the new
 423commit.  Git calls this process a "fast forward".
 424
 425A fast forward looks something like this:
 426
 427 o--o--o--o <-- old head of the branch
 428           \
 429            o--o--o <-- new head of the branch
 430
 431
 432In some cases it is possible that the new head will *not* actually be
 433a descendant of the old head.  For example, the developer may have
 434realized she made a serious mistake, and decided to backtrack,
 435resulting in a situation like:
 436
 437 o--o--o--o--a--b <-- old head of the branch
 438           \
 439            o--o--o <-- new head of the branch
 440
 441
 442
 443In this case, "git fetch" will fail, and print out a warning.
 444
 445In that case, you can still force git to update to the new head, as
 446described in the following section.  However, note that in the
 447situation above this may mean losing the commits labeled "a" and "b",
 448unless you've already created a reference of your own pointing to
 449them.
 450
 451Forcing git fetch to do non-fast-forward updates
 452------------------------------------------------
 453
 454If git fetch fails because the new head of a branch is not a
 455descendant of the old head, you may force the update with:
 456
 457-------------------------------------------------
 458$ git fetch git://example.com/proj.git +master:refs/remotes/example/master
 459-------------------------------------------------
 460
 461Note the addition of the "+" sign.  Be aware that commits which the
 462old version of example/master pointed at may be lost, as we saw in
 463the previous section.
 464
 465Configuring remote branches
 466---------------------------
 467
 468We saw above that "origin" is just a shortcut to refer to the
 469repository which you originally cloned from.  This information is
 470stored in git configuration variables, which you can see using
 471gitlink:git-repo-config[1]:
 472
 473-------------------------------------------------
 474$ git-repo-config -l
 475core.repositoryformatversion=0
 476core.filemode=true
 477core.logallrefupdates=true
 478remote.origin.url=git://git.kernel.org/pub/scm/git/git.git
 479remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
 480branch.master.remote=origin
 481branch.master.merge=refs/heads/master
 482-------------------------------------------------
 483
 484If there are other repositories that you also use frequently, you can
 485create similar configuration options to save typing; for example,
 486after
 487
 488-------------------------------------------------
 489$ git repo-config remote.example.url=git://example.com/proj.git
 490-------------------------------------------------
 491
 492then the following two commands will do the same thing:
 493
 494-------------------------------------------------
 495$ git fetch git://example.com/proj.git master:refs/remotes/example/master
 496$ git fetch example master:refs/remotes/example/master
 497-------------------------------------------------
 498
 499Even better, if you add one more option:
 500
 501-------------------------------------------------
 502$ git repo-config remote.example.fetch=master:refs/remotes/example/master
 503-------------------------------------------------
 504
 505then the following commands will all do the same thing:
 506
 507-------------------------------------------------
 508$ git fetch git://example.com/proj.git master:ref/remotes/example/master
 509$ git fetch example master:ref/remotes/example/master
 510$ git fetch example example/master
 511$ git fetch example
 512-------------------------------------------------
 513
 514You can also add a "+" to force the update each time:
 515
 516-------------------------------------------------
 517$ git repo-config +master:ref/remotes/example/master
 518-------------------------------------------------
 519
 520Don't do this unless you're sure you won't mind "git fetch" possibly
 521throwing away commits on mybranch.
 522
 523Also note that all of the above configuration can be performed by
 524directly editing the file .git/config instead of using
 525gitlink:git-repo-config[1].
 526
 527See gitlink:git-repo-config[1] for more details on the configuration
 528options mentioned above.
 529
 530Exploring git history
 531=====================
 532
 533Git is best thought of as a tool for storing the history of a
 534collection of files.  It does this by storing compressed snapshots of
 535the contents of a file heirarchy, together with "commits" which show
 536the relationships between these snapshots.
 537
 538Git provides extremely flexible and fast tools for exploring the
 539history of a project.
 540
 541We start with one specialized tool which is useful for finding the
 542commit that introduced a bug into a project.
 543
 544How to use bisect to find a regression
 545--------------------------------------
 546
 547Suppose version 2.6.18 of your project worked, but the version at
 548"master" crashes.  Sometimes the best way to find the cause of such a
 549regression is to perform a brute-force search through the project's
 550history to find the particular commit that caused the problem.  The
 551gitlink:git-bisect[1] command can help you do this:
 552
 553-------------------------------------------------
 554$ git bisect start
 555$ git bisect good v2.6.18
 556$ git bisect bad master
 557Bisecting: 3537 revisions left to test after this
 558[65934a9a028b88e83e2b0f8b36618fe503349f8e] BLOCK: Make USB storage depend on SCSI rather than selecting it [try #6]
 559-------------------------------------------------
 560
 561If you run "git branch" at this point, you'll see that git has
 562temporarily moved you to a new branch named "bisect".  This branch
 563points to a commit (with commit id 65934...) that is reachable from
 564v2.6.19 but not from v2.6.18.  Compile and test it, and see whether
 565it crashes.  Assume it does crash.  Then:
 566
 567-------------------------------------------------
 568$ git bisect bad
 569Bisecting: 1769 revisions left to test after this
 570[7eff82c8b1511017ae605f0c99ac275a7e21b867] i2c-core: Drop useless bitmaskings
 571-------------------------------------------------
 572
 573checks out an older version.  Continue like this, telling git at each
 574stage whether the version it gives you is good or bad, and notice
 575that the number of revisions left to test is cut approximately in
 576half each time.
 577
 578After about 13 tests (in this case), it will output the commit id of
 579the guilty commit.  You can then examine the commit with
 580gitlink:git-show[1], find out who wrote it, and mail them your bug
 581report with the commit id.  Finally, run
 582
 583-------------------------------------------------
 584$ git bisect reset
 585-------------------------------------------------
 586
 587to return you to the branch you were on before and delete the
 588temporary "bisect" branch.
 589
 590Note that the version which git-bisect checks out for you at each
 591point is just a suggestion, and you're free to try a different
 592version if you think it would be a good idea.  For example,
 593occasionally you may land on a commit that broke something unrelated;
 594run
 595
 596-------------------------------------------------
 597$ git bisect-visualize
 598-------------------------------------------------
 599
 600which will run gitk and label the commit it chose with a marker that
 601says "bisect".  Chose a safe-looking commit nearby, note its commit
 602id, and check it out with:
 603
 604-------------------------------------------------
 605$ git reset --hard fb47ddb2db...
 606-------------------------------------------------
 607
 608then test, run "bisect good" or "bisect bad" as appropriate, and
 609continue.
 610
 611Naming commits
 612--------------
 613
 614We have seen several ways of naming commits already:
 615
 616        - 20-digit SHA1 id
 617        - branch name: refers to the commit at the head of the given
 618          branch
 619        - tag name: refers to the commit pointed to by the given tag
 620          (we've seen branches and tags are special cases of
 621          <<how-git-stores-references,references>>).
 622        - HEAD: refers to the head of the current branch
 623
 624There are many more; see the "SPECIFYING REVISION" section of the
 625gitlink:git-rev-parse[1] man page for the complete list of ways to
 626name revisions.  Some examples:
 627
 628-------------------------------------------------
 629$ git show fb47ddb2 # the first few characters of the SHA1 id
 630                    # are usually enough to specify it uniquely
 631$ git show HEAD^    # the parent of the HEAD commit
 632$ git show HEAD^^   # the grandparent
 633$ git show HEAD~4   # the great-great-grandparent
 634-------------------------------------------------
 635
 636Recall that merge commits may have more than one parent; by default,
 637^ and ~ follow the first parent listed in the commit, but you can
 638also choose:
 639
 640-------------------------------------------------
 641$ git show HEAD^1   # show the first parent of HEAD
 642$ git show HEAD^2   # show the second parent of HEAD
 643-------------------------------------------------
 644
 645In addition to HEAD, there are several other special names for
 646commits:
 647
 648Merges (to be discussed later), as well as operations such as
 649git-reset, which change the currently checked-out commit, generally
 650set ORIG_HEAD to the value HEAD had before the current operation.
 651
 652The git-fetch operation always stores the head of the last fetched
 653branch in FETCH_HEAD.  For example, if you run git fetch without
 654specifying a local branch as the target of the operation
 655
 656-------------------------------------------------
 657$ git fetch git://example.com/proj.git theirbranch
 658-------------------------------------------------
 659
 660the fetched commits will still be available from FETCH_HEAD.
 661
 662When we discuss merges we'll also see the special name MERGE_HEAD,
 663which refers to the other branch that we're merging in to the current
 664branch.
 665
 666The gitlink:git-rev-parse[1] command is a low-level command that is
 667occasionally useful for translating some name for a commit to the SHA1 id for
 668that commit:
 669
 670-------------------------------------------------
 671$ git rev-parse origin
 672e05db0fd4f31dde7005f075a84f96b360d05984b
 673-------------------------------------------------
 674
 675Creating tags
 676-------------
 677
 678We can also create a tag to refer to a particular commit; after
 679running
 680
 681-------------------------------------------------
 682$ git-tag stable-1 1b2e1d63ff
 683-------------------------------------------------
 684
 685You can use stable-1 to refer to the commit 1b2e1d63ff.
 686
 687This creates a "lightweight" tag.  If the tag is a tag you wish to
 688share with others, and possibly sign cryptographically, then you
 689should create a tag object instead; see the gitlink:git-tag[1] man
 690page for details.
 691
 692Browsing revisions
 693------------------
 694
 695The gitlink:git-log[1] command can show lists of commits.  On its
 696own, it shows all commits reachable from the parent commit; but you
 697can also make more specific requests:
 698
 699-------------------------------------------------
 700$ git log v2.5..        # commits since (not reachable from) v2.5
 701$ git log test..master  # commits reachable from master but not test
 702$ git log master..test  # ...reachable from test but not master
 703$ git log master...test # ...reachable from either test or master,
 704                        #    but not both
 705$ git log --since="2 weeks ago" # commits from the last 2 weeks
 706$ git log Makefile      # commits which modify Makefile
 707$ git log fs/           # ... which modify any file under fs/
 708$ git log -S'foo()'     # commits which add or remove any file data
 709                        # matching the string 'foo()'
 710-------------------------------------------------
 711
 712And of course you can combine all of these; the following finds
 713commits since v2.5 which touch the Makefile or any file under fs:
 714
 715-------------------------------------------------
 716$ git log v2.5.. Makefile fs/
 717-------------------------------------------------
 718
 719You can also ask git log to show patches:
 720
 721-------------------------------------------------
 722$ git log -p
 723-------------------------------------------------
 724
 725See the "--pretty" option in the gitlink:git-log[1] man page for more
 726display options.
 727
 728Note that git log starts with the most recent commit and works
 729backwards through the parents; however, since git history can contain
 730multiple independant lines of development, the particular order that
 731commits are listed in may be somewhat arbitrary.
 732
 733Generating diffs
 734----------------
 735
 736You can generate diffs between any two versions using
 737gitlink:git-diff[1]:
 738
 739-------------------------------------------------
 740$ git diff master..test
 741-------------------------------------------------
 742
 743Sometimes what you want instead is a set of patches:
 744
 745-------------------------------------------------
 746$ git format-patch master..test
 747-------------------------------------------------
 748
 749will generate a file with a patch for each commit reachable from test
 750but not from master.  Note that if master also has commits which are
 751not reachable from test, then the combined result of these patches
 752will not be the same as the diff produced by the git-diff example.
 753
 754Viewing old file versions
 755-------------------------
 756
 757You can always view an old version of a file by just checking out the
 758correct revision first.  But sometimes it is more convenient to be
 759able to view an old version of a single file without checking
 760anything out; this command does that:
 761
 762-------------------------------------------------
 763$ git show v2.5:fs/locks.c
 764-------------------------------------------------
 765
 766Before the colon may be anything that names a commit, and after it
 767may be any path to a file tracked by git.
 768
 769Examples
 770--------
 771
 772Check whether two branches point at the same history
 773----------------------------------------------------
 774
 775Suppose you want to check whether two branches point at the same point
 776in history.
 777
 778-------------------------------------------------
 779$ git diff origin..master
 780-------------------------------------------------
 781
 782will tell you whether the contents of the project are the same at the two
 783branches; in theory, however, it's possible that the same project contents
 784could have been arrived at by two different historical routes.  You could
 785compare the SHA1 id's:
 786
 787-------------------------------------------------
 788$ git rev-list origin
 789e05db0fd4f31dde7005f075a84f96b360d05984b
 790$ git rev-list master
 791e05db0fd4f31dde7005f075a84f96b360d05984b
 792-------------------------------------------------
 793
 794Or you could recall that the ... operator selects all commits contained
 795reachable from either one reference or the other but not both: so
 796
 797-------------------------------------------------
 798$ git log origin...master
 799-------------------------------------------------
 800
 801will return no commits when the two branches are equal.
 802
 803Check which tagged version a given fix was first included in
 804------------------------------------------------------------
 805
 806Suppose you know that a critical fix made it into the linux kernel with commit
 807e05db0fd...  You'd like to find which kernel version that commit first made it
 808into.
 809
 810Developing with git
 811===================
 812
 813Telling git your name
 814---------------------
 815
 816Before creating any commits, you should introduce yourself to git.  The
 817easiest way to do so is:
 818
 819------------------------------------------------
 820$ cat >~/.gitconfig <<\EOF
 821[user]
 822        name = Your Name Comes Here
 823        email = you@yourdomain.example.com
 824EOF
 825------------------------------------------------
 826
 827
 828Creating a new repository
 829-------------------------
 830
 831Creating a new repository from scratch is very easy:
 832
 833-------------------------------------------------
 834$ mkdir project
 835$ cd project
 836$ git init-db
 837-------------------------------------------------
 838
 839If you have some initial content (say, a tarball):
 840
 841-------------------------------------------------
 842$ tar -xzvf project.tar.gz
 843$ cd project
 844$ git init-db
 845$ git add . # include everything below ./ in the first commit:
 846$ git commit
 847-------------------------------------------------
 848
 849[[how-to-make-a-commit]]
 850how to make a commit
 851--------------------
 852
 853Creating a new commit takes three steps:
 854
 855        1. Making some changes to the working directory using your
 856           favorite editor.
 857        2. Telling git about your changes.
 858        3. Creating the commit using the content you told git about
 859           in step 2.
 860
 861In practice, you can interleave and repeat steps 1 and 2 as many
 862times as you want: in order to keep track of what you want committed
 863at step 3, git maintains a snapshot of the tree's contents in a
 864special staging area called "the index."
 865
 866By default, the content of the index is identical to that of the
 867HEAD.  The command "git diff --cached" shows the difference between
 868HEAD and the index, so you should no output from that command.
 869
 870Modifying the index is easy:
 871
 872To update the index with the new contents of a modified file, use
 873
 874-------------------------------------------------
 875$ git add path/to/file
 876-------------------------------------------------
 877
 878To add the contents of a new file to the index, use
 879
 880-------------------------------------------------
 881$ git add path/to/file
 882-------------------------------------------------
 883
 884To remove a file from the index that you've removed from the working
 885tree,
 886
 887-------------------------------------------------
 888$ git rm path/to/file
 889-------------------------------------------------
 890
 891After each step you can verify that
 892
 893-------------------------------------------------
 894$ git diff --cached
 895-------------------------------------------------
 896
 897always shows the difference between the HEAD and the index file--this
 898is what you'd commit if you created the commit now--and that
 899
 900-------------------------------------------------
 901$ git diff
 902-------------------------------------------------
 903
 904shows the difference between the working tree and the index file.
 905
 906Note that "git add" always adds just the current contents of a file
 907to the index; further changes to the same file will be ignored unless
 908you run git-add on the file again.
 909
 910When you're ready, just run
 911
 912-------------------------------------------------
 913$ git commit
 914-------------------------------------------------
 915
 916and git will prompt you for a commit message and then create the new
 917commmit.  Check to make sure it looks like what you expected with
 918
 919-------------------------------------------------
 920$ git show
 921-------------------------------------------------
 922
 923As a special shortcut,
 924                
 925-------------------------------------------------
 926$ git commit -a
 927-------------------------------------------------
 928
 929will update the index with any files that you've modified or removed
 930and create a commit, all in one step.
 931
 932A number of commands are useful for keeping track of what you're
 933about to commit:
 934
 935-------------------------------------------------
 936$ git diff --cached # difference between HEAD and the index; what
 937                    # would be commited if you ran "commit" now.
 938$ git diff          # difference between the index file and your
 939                    # working directory; changes that would not
 940                    # be included if you ran "commit" now.
 941$ git status        # a brief per-file summary of the above.
 942-------------------------------------------------
 943
 944creating good commit messages
 945-----------------------------
 946
 947Though not required, it's a good idea to begin the commit message
 948with a single short (less than 50 character) line summarizing the
 949change, followed by a blank line and then a more thorough
 950description.  Tools that turn commits into email, for example, use
 951the first line on the Subject line and the rest of the commit in the
 952body.
 953
 954how to merge
 955------------
 956
 957You can rejoin two diverging branches of development using
 958gitlink:git-merge[1]:
 959
 960-------------------------------------------------
 961$ git merge branchname
 962-------------------------------------------------
 963
 964merges the development in the branch "branchname" into the current
 965branch.  If there are conflicts--for example, if the same file is
 966modified in two different ways in the remote branch and the local
 967branch--then you are warned; the output may look something like this:
 968
 969-------------------------------------------------
 970$ git pull . next
 971Trying really trivial in-index merge...
 972fatal: Merge requires file-level merging
 973Nope.
 974Merging HEAD with 77976da35a11db4580b80ae27e8d65caf5208086
 975Merging:
 97615e2162 world
 97777976da goodbye
 978found 1 common ancestor(s):
 979d122ed4 initial
 980Auto-merging file.txt
 981CONFLICT (content): Merge conflict in file.txt
 982Automatic merge failed; fix conflicts and then commit the result.
 983-------------------------------------------------
 984
 985Conflict markers are left in the problematic files, and after
 986you resolve the conflicts manually, you can update the index
 987with the contents and run git commit, as you normally would when
 988creating a new file.
 989
 990If you examine the resulting commit using gitk, you will see that it
 991has two parents, one pointing to the top of the current branch, and
 992one to the top of the other branch.
 993
 994In more detail:
 995
 996[[resolving-a-merge]]
 997Resolving a merge
 998-----------------
 999
1000When a merge isn't resolved automatically, git leaves the index and
1001the working tree in a special state that gives you all the
1002information you need to help resolve the merge.
1003
1004Files with conflicts are marked specially in the index, so until you
1005resolve the problem and update the index, git commit will fail:
1006
1007-------------------------------------------------
1008$ git commit
1009file.txt: needs merge
1010-------------------------------------------------
1011
1012Also, git status will list those files as "unmerged".
1013
1014All of the changes that git was able to merge automatically are
1015already added to the index file, so gitlink:git-diff[1] shows only
1016the conflicts.  Also, it uses a somewhat unusual syntax:
1017
1018-------------------------------------------------
1019$ git diff
1020diff --cc file.txt
1021index 802992c,2b60207..0000000
1022--- a/file.txt
1023+++ b/file.txt
1024@@@ -1,1 -1,1 +1,5 @@@
1025++<<<<<<< HEAD:file.txt
1026 +Hello world
1027++=======
1028+ Goodbye
1029++>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
1030-------------------------------------------------
1031
1032Recall that the commit which will be commited after we resolve this
1033conflict will have two parents instead of the usual one: one parent
1034will be HEAD, the tip of the current branch; the other will be the
1035tip of the other branch, which is stored temporarily in MERGE_HEAD.
1036
1037The diff above shows the differences between the working-tree version
1038of file.txt and two previous version: one version from HEAD, and one
1039from MERGE_HEAD.  So instead of preceding each line by a single "+"
1040or "-", it now uses two columns: the first column is used for
1041differences between the first parent and the working directory copy,
1042and the second for differences between the second parent and the
1043working directory copy.  Thus after resolving the conflict in the
1044obvious way, the diff will look like:
1045
1046-------------------------------------------------
1047$ git diff
1048diff --cc file.txt
1049index 802992c,2b60207..0000000
1050--- a/file.txt
1051+++ b/file.txt
1052@@@ -1,1 -1,1 +1,1 @@@
1053- Hello world
1054 -Goodbye
1055++Goodbye world
1056-------------------------------------------------
1057
1058This shows that our resolved version deleted "Hello world" from the
1059first parent, deleted "Goodbye" from the second parent, and added
1060"Goodbye world", which was previously absent from both.
1061
1062The gitlink:git-log[1] command also provides special help for merges:
1063
1064-------------------------------------------------
1065$ git log --merge
1066-------------------------------------------------
1067
1068This will list all commits which exist only on HEAD or on MERGE_HEAD,
1069and which touch an unmerged file.
1070
1071We can now add the resolved version to the index and commit:
1072
1073-------------------------------------------------
1074$ git add file.txt
1075$ git commit
1076-------------------------------------------------
1077
1078Note that the commit message will already be filled in for you with
1079some information about the merge.  Normally you can just use this
1080default message unchanged, but you may add additional commentary of
1081your own if desired.
1082
1083[[undoing-a-merge]]
1084undoing a merge
1085---------------
1086
1087If you get stuck and decide to just give up and throw the whole mess
1088away, you can always return to the pre-merge state with
1089
1090-------------------------------------------------
1091$ git reset --hard HEAD
1092-------------------------------------------------
1093
1094Or, if you've already commited the merge that you want to throw away,
1095
1096-------------------------------------------------
1097$ git reset --hard HEAD^
1098-------------------------------------------------
1099
1100However, this last command can be dangerous in some cases--never
1101throw away a commit you have already committed if that commit may
1102itself have been merged into another branch, as doing so may confuse
1103further merges.
1104
1105Fast-forward merges
1106-------------------
1107
1108There is one special case not mentioned above, which is treated
1109differently.  Normally, a merge results in a merge commit, with two
1110parents, one pointing at each of the two lines of development that
1111were merged.
1112
1113However, if one of the two lines of development is completely
1114contained within the other--so every commit present in the one is
1115already contained in the other--then git just performs a
1116<<fast-forwards,fast forward>>; the head of the current branch is
1117moved forward to point at the head of the merged-in branch, without
1118any new commits being created.
1119
1120Fixing mistakes
1121---------------
1122
1123If you've messed up the working tree, but haven't yet committed your
1124mistake, you can return the entire working tree to the last committed
1125state with
1126
1127-------------------------------------------------
1128$ git reset --hard HEAD
1129-------------------------------------------------
1130
1131If you make a commit that you later wish you hadn't, there are two
1132fundamentally different ways to fix the problem:
1133
1134        1. You can create a new commit that undoes whatever was done
1135        by the previous commit.  This is the correct thing if your
1136        mistake has already been made public.
1137
1138        2. You can go back and modify the old commit.  You should
1139        never do this if you have already made the history public;
1140        git does not normally expect the "history" of a project to
1141        change, and cannot correctly perform repeated merges from
1142        a branch that has had its history changed.
1143
1144Fixing a mistake with a new commit
1145~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1146
1147Creating a new commit that reverts an earlier change is very easy;
1148just pass the gitlink:git-revert[1] command a reference to the bad
1149commit; for example, to revert the most recent commit:
1150
1151-------------------------------------------------
1152$ git revert HEAD
1153-------------------------------------------------
1154
1155This will create a new commit which undoes the change in HEAD.  You
1156will be given a chance to edit the commit message for the new commit.
1157
1158You can also revert an earlier change, for example, the next-to-last:
1159
1160-------------------------------------------------
1161$ git revert HEAD^
1162-------------------------------------------------
1163
1164In this case git will attempt to undo the old change while leaving
1165intact any changes made since then.  If more recent changes overlap
1166with the changes to be reverted, then you will be asked to fix
1167conflicts manually, just as in the case of <<resolving-a-merge,
1168resolving a merge>>.
1169
1170Fixing a mistake by editing history
1171~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1172
1173If the problematic commit is the most recent commit, and you have not
1174yet made that commit public, then you may just
1175<<undoing-a-merge,destroy it using git-reset>>.
1176
1177Alternatively, you
1178can edit the working directory and update the index to fix your
1179mistake, just as if you were going to <<how-to-make-a-commit,create a
1180new commit>>, then run
1181
1182-------------------------------------------------
1183$ git commit --amend
1184-------------------------------------------------
1185
1186which will replace the old commit by a new commit incorporating your
1187changes, giving you a chance to edit the old commit message first.
1188
1189Again, you should never do this to a commit that may already have
1190been merged into another branch; use gitlink:git-revert[1] instead in
1191that case.
1192
1193It is also possible to edit commits further back in the history, but
1194this is an advanced topic to be left for
1195<<cleaning-up-history,another chapter>>.
1196
1197Checking out an old version of a file
1198~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1199
1200In the process of undoing a previous bad change, you may find it
1201useful to check out an older version of a particular file using
1202gitlink:git-checkout[1].  We've used git checkout before to switch
1203branches, but it has quite different behavior if it is given a path
1204name: the command
1205
1206-------------------------------------------------
1207$ git checkout HEAD^ path/to/file
1208-------------------------------------------------
1209
1210replaces path/to/file by the contents it had in the commit HEAD^, and
1211also updates the index to match.  It does not change branches.
1212
1213If you just want to look at an old version of the file, without
1214modifying the working directory, you can do that with
1215gitlink:git-show[1]:
1216
1217-------------------------------------------------
1218$ git show HEAD^ path/to/file
1219-------------------------------------------------
1220
1221which will display the given version of the file.
1222
1223Ensuring good performance
1224-------------------------
1225
1226On large repositories, git depends on compression to keep the history
1227information from taking up to much space on disk or in memory.
1228
1229This compression is not performed automatically.  Therefore you
1230should occasionally run
1231
1232-------------------------------------------------
1233$ git gc
1234-------------------------------------------------
1235
1236to recompress the archive and to prune any commits which are no
1237longer referred to anywhere.  This can be very time-consuming, and
1238you should not modify the repository while it is working, so you
1239should run it while you are not working.
1240
1241Sharing development with others
1242===============================
1243
1244[[getting-updates-with-git-pull]]
1245Getting updates with git pull
1246-----------------------------
1247
1248After you clone a repository and make a few changes of your own, you
1249may wish to check the original repository for updates and merge them
1250into your own work.
1251
1252We have already seen <<Updating-a-repository-with-git-fetch,how to
1253keep remote tracking branches up to date>> with gitlink:git-fetch[1],
1254and how to merge two branches.  So you can merge in changes from the
1255original repository's master branch with:
1256
1257-------------------------------------------------
1258$ git fetch
1259$ git merge origin/master
1260-------------------------------------------------
1261
1262However, the gitlink:git-pull[1] command provides a way to do this in
1263one step:
1264
1265-------------------------------------------------
1266$ git pull origin master
1267-------------------------------------------------
1268
1269In fact, "origin" is normally the default repository to pull from,
1270and the default branch is normally the HEAD of the remote repository,
1271so often you can accomplish the above with just
1272
1273-------------------------------------------------
1274$ git pull
1275-------------------------------------------------
1276
1277See the descriptions of the branch.<name>.remote and
1278branch.<name>.merge options in gitlink:git-repo-config[1] to learn
1279how to control these defaults depending on the current branch.
1280
1281In addition to saving you keystrokes, "git pull" also helps you by
1282producing a default commit message documenting the branch and
1283repository that you pulled from.
1284
1285(But note that no such commit will be created in the case of a
1286<<fast-forwards,fast forward>>; instead, your branch will just be
1287updated to point to the latest commit from the upstream branch).
1288
1289The git-pull command can also be given "." as the "remote" repository, in
1290which case it just merges in a branch from the current repository; so
1291the commands
1292
1293-------------------------------------------------
1294$ git pull . branch
1295$ git merge branch
1296-------------------------------------------------
1297
1298are roughly equivalent.  The former is actually very commonly used.
1299
1300Submitting patches to a project
1301-------------------------------
1302
1303If you just have a few changes, the simplest way to submit them may
1304just be to send them as patches in email:
1305
1306First, use gitlink:git-format-patches[1]; for example:
1307
1308-------------------------------------------------
1309$ git format-patches origin
1310-------------------------------------------------
1311
1312will produce a numbered series of files in the current directory, one
1313for each patch in the current branch but not in origin/HEAD.
1314
1315You can then import these into your mail client and send them by
1316hand.  However, if you have a lot to send at once, you may prefer to
1317use the gitlink:git-send-email[1] script to automate the process.
1318Consult the mailing list for your project first to determine how they
1319prefer such patches be handled.
1320
1321Importing patches to a project
1322------------------------------
1323
1324Git also provides a tool called gitlink:git-am[1] (am stands for
1325"apply mailbox"), for importing such an emailed series of patches.
1326Just save all of the patch-containing messages, in order, into a
1327single mailbox file, say "patches.mbox", then run
1328
1329-------------------------------------------------
1330$ git am patches.mbox
1331-------------------------------------------------
1332
1333Git will apply each patch in order; if any conflicts are found, it
1334will stop, and you can fix the conflicts as described in
1335"<<resolving-a-merge,Resolving a merge>>".  Once the index is updated
1336with the results of the conflict resolution, instead of creating a
1337new commit, just run
1338
1339-------------------------------------------------
1340$ git am --resolved
1341-------------------------------------------------
1342
1343and git will create the commit for you and continue applying the
1344remaining patches from the mailbox.
1345
1346The final result will be a series of commits, one for each patch in
1347the original mailbox, with authorship and commit log message each
1348taken from the message containing each patch.
1349
1350[[setting-up-a-public-repository]]
1351Setting up a public repository
1352------------------------------
1353
1354Another way to submit changes to a project is to simply tell the
1355maintainer of that project to pull from your repository, exactly as
1356you did in the section "<<getting-updates-with-git-pull, Getting
1357updates with git pull>>".
1358
1359If you and maintainer both have accounts on the same machine, then
1360then you can just pull changes from each other's repositories
1361directly; note that all of the command (gitlink:git-clone[1],
1362git-fetch[1], git-pull[1], etc.) which accept a URL as an argument
1363will also accept a local file patch; so, for example, you can
1364use
1365
1366-------------------------------------------------
1367$ git clone /path/to/repository
1368$ git pull /path/to/other/repository
1369-------------------------------------------------
1370
1371If this sort of setup is inconvenient or impossible, another (more
1372common) option is to set up a public repository on a public server.
1373This also allows you to cleanly separate private work in progress
1374from publicly visible work.
1375
1376You will continue to do your day-to-day work in your personal
1377repository, but periodically "push" changes from your personal
1378repository into your public repository, allowing other developers to
1379pull from that repository.  So the flow of changes, in a situation
1380where there is one other developer with a public repository, looks
1381like this:
1382
1383                        you push
1384  your personal repo ------------------> your public repo
1385        ^                                     |
1386        |                                     |
1387        | you pull                            | they pull
1388        |                                     |
1389        |                                     |
1390        |               they push             V
1391  their public repo <------------------- their repo
1392
1393Now, assume your personal repository is in the directory ~/proj.  We
1394first create a new clone of the repository:
1395
1396-------------------------------------------------
1397$ git clone --bare proj-clone.git
1398-------------------------------------------------
1399
1400The resulting directory proj-clone.git will contains a "bare" git
1401repository--it is just the contents of the ".git" directory, without
1402a checked-out copy of a working directory.
1403
1404Next, copy proj-clone.git to the server where you plan to host the
1405public repository.  You can use scp, rsync, or whatever is most
1406convenient.
1407
1408If somebody else maintains the public server, they may already have
1409set up a git service for you, and you may skip to the section
1410"<<pushing-changes-to-a-public-repository,Pushing changes to a public
1411repository>>", below.
1412
1413Otherwise, the following sections explain how to export your newly
1414created public repository:
1415
1416[[exporting-via-http]]
1417Exporting a git repository via http
1418-----------------------------------
1419
1420The git protocol gives better performance and reliability, but on a
1421host with a web server set up, http exports may be simpler to set up.
1422
1423All you need to do is place the newly created bare git repository in
1424a directory that is exported by the web server, and make some
1425adjustments to give web clients some extra information they need:
1426
1427-------------------------------------------------
1428$ mv proj.git /home/you/public_html/proj.git
1429$ cd proj.git
1430$ git update-server-info
1431$ chmod a+x hooks/post-update
1432-------------------------------------------------
1433
1434(For an explanation of the last two lines, see
1435gitlink:git-update-server-info[1], and the documentation
1436link:hooks.txt[Hooks used by git].)
1437
1438Advertise the url of proj.git.  Anybody else should then be able to
1439clone or pull from that url, for example with a commandline like:
1440
1441-------------------------------------------------
1442$ git clone http://yourserver.com/~you/proj.git
1443-------------------------------------------------
1444
1445(See also
1446link:howto/setup-git-server-over-http.txt[setup-git-server-over-http]
1447for a slightly more sophisticated setup using WebDAV which also
1448allows pushing over http.)
1449
1450[[exporting-via-git]]
1451Exporting a git repository via the git protocol
1452-----------------------------------------------
1453
1454This is the preferred method.
1455
1456For now, we refer you to the gitlink:git-daemon[1] man page for
1457instructions.  (See especially the examples section.)
1458
1459[[pushing-changes-to-a-public-repository]]
1460Pushing changes to a public repository
1461--------------------------------------
1462
1463Note that the two techniques outline above (exporting via
1464<<exporting-via-http,http>> or <<exporting-via-git,git>>) allow other
1465maintainers to fetch your latest changes, but they do not allow write
1466access, which you will need to update the public repository with the
1467latest changes created in your private repository.
1468
1469The simplest way to do this is using gitlink:git-push[1] and ssh; to
1470update the remote branch named "master" with the latest state of your
1471branch named "master", run
1472
1473-------------------------------------------------
1474$ git push ssh://yourserver.com/~you/proj.git master:master
1475-------------------------------------------------
1476
1477or just
1478
1479-------------------------------------------------
1480$ git push ssh://yourserver.com/~you/proj.git master
1481-------------------------------------------------
1482
1483As with git-fetch, git-push will complain if this does not result in
1484a <<fast-forwards,fast forward>>.  Normally this is a sign of
1485something wrong.  However, if you are sure you know what you're
1486doing, you may force git-push to perform the update anyway by
1487proceeding the branch name by a plus sign:
1488
1489-------------------------------------------------
1490$ git push ssh://yourserver.com/~you/proj.git +master
1491-------------------------------------------------
1492
1493As with git-fetch, you may also set up configuration options to
1494save typing; so, for example, after
1495
1496-------------------------------------------------
1497$ cat >.git/config <<EOF
1498[remote "public-repo"]
1499        url = ssh://yourserver.com/~you/proj.git
1500EOF
1501-------------------------------------------------
1502
1503you should be able to perform the above push with just
1504
1505-------------------------------------------------
1506$ git push public-repo master
1507-------------------------------------------------
1508
1509See the explanations of the remote.<name>.url, branch.<name>.remote,
1510and remote.<name>.push options in gitlink:git-repo-config[1] for
1511details.
1512
1513Setting up a shared repository
1514------------------------------
1515
1516Another way to collaborate is by using a model similar to that
1517commonly used in CVS, where several developers with special rights
1518all push to and pull from a single shared repository.  See
1519link:cvs-migration.txt[git for CVS users] for instructions on how to
1520set this up.
1521
1522Allow web browsing of a repository
1523----------------------------------
1524
1525TODO: Brief setup-instructions for gitweb
1526
1527Examples
1528--------
1529
1530TODO: topic branches, typical roles as in everyday.txt, ?
1531
1532
1533Working with other version control systems
1534==========================================
1535
1536TODO: CVS, Subversion, series-of-release-tarballs, ?
1537
1538[[cleaning-up-history]]
1539Rewriting history and maintaining patch series
1540==============================================
1541
1542Normally commits are only added to a project, never taken away or
1543replaced.  Git is designed with this assumption, and violating it will
1544cause git's merge machinery (for example) to do the wrong thing.
1545
1546However, there is a situation in which it can be useful to violate this
1547assumption.
1548
1549Creating the perfect patch series
1550---------------------------------
1551
1552Suppose you are a contributor to a large project, and you want to add a
1553complicated feature, and to present it to the other developers in a way
1554that makes it easy for them to read your changes, verify that they are
1555correct, and understand why you made each change.
1556
1557If you present all of your changes as a single patch (or commit), they may
1558find it is too much to digest all at once.
1559
1560If you present them with the entire history of your work, complete with
1561mistakes, corrections, and dead ends, they may be overwhelmed.
1562
1563So the ideal is usually to produce a series of patches such that:
1564
1565        1. Each patch can be applied in order.
1566
1567        2. Each patch includes a single logical change, together with a
1568           message explaining the change.
1569
1570        3. No patch introduces a regression: after applying any initial
1571           part of the series, the resulting project still compiles and
1572           works, and has no bugs that it didn't have before.
1573
1574        4. The complete series produces the same end result as your own
1575           (probably much messier!) development process did.
1576
1577We will introduce some tools that can help you do this, explain how to use
1578them, and then explain some of the problems that can arise because you are
1579rewriting history.
1580
1581Keeping a patch series up to date using git-rebase
1582--------------------------------------------------
1583
1584Suppose you have a series of commits in a branch "mywork", which
1585originally branched off from "origin".
1586
1587Suppose you create a branch "mywork" on a remote-tracking branch "origin",
1588and created some commits on top of it:
1589
1590-------------------------------------------------
1591$ git checkout -b mywork origin
1592$ vi file.txt
1593$ git commit
1594$ vi otherfile.txt
1595$ git commit
1596...
1597-------------------------------------------------
1598
1599You have performed no merges into mywork, so it is just a simple linear
1600sequence of patches on top of "origin":
1601
1602
1603 o--o--o <-- origin
1604        \
1605         o--o--o <-- mywork
1606
1607Some more interesting work has been done in the upstream project, and
1608"origin" has advanced:
1609
1610 o--o--O--o--o--o <-- origin
1611        \
1612         a--b--c <-- mywork
1613
1614At this point, you could use "pull" to merge your changes back in;
1615the result would create a new merge commit, like this:
1616
1617
1618 o--o--O--o--o--o <-- origin
1619        \        \
1620         a--b--c--m <-- mywork
1621 
1622However, if you prefer to keep the history in mywork a simple series of
1623commits without any merges, you may instead choose to use
1624gitlink:git-rebase[1]:
1625
1626-------------------------------------------------
1627$ git checkout mywork
1628$ git rebase origin
1629-------------------------------------------------
1630
1631This will remove each of your commits from mywork, temporarily saving them
1632as patches (in a directory named ".dotest"), update mywork to point at the
1633latest version of origin, then apply each of the saved patches to the new
1634mywork.  The result will look like:
1635
1636
1637 o--o--O--o--o--o <-- origin
1638                 \
1639                  a'--b'--c' <-- mywork
1640
1641In the process, it may discover conflicts.  In that case it will stop and
1642allow you to fix the conflicts as described in
1643"<<resolving-a-merge,Resolving a merge>>".
1644
1645XXX: no, maybe not: git diff doesn't produce very useful results, and there's
1646no MERGE_HEAD.
1647
1648Once the index is updated with
1649the results of the conflict resolution, instead of creating a new commit,
1650just run
1651
1652-------------------------------------------------
1653$ git rebase --continue
1654-------------------------------------------------
1655
1656and git will continue applying the rest of the patches.
1657
1658At any point you may use the --abort option to abort this process and
1659return mywork to the state it had before you started the rebase:
1660
1661-------------------------------------------------
1662$ git rebase --abort
1663-------------------------------------------------
1664
1665Reordering or selecting from a patch series
1666-------------------------------------------
1667
1668Given one existing commit, the gitlink:git-cherry-pick[1] command allows
1669you to apply the change introduced by that commit and create a new commit
1670that records it.
1671
1672This can be useful for modifying a patch series.
1673
1674TODO: elaborate
1675
1676Other tools
1677-----------
1678
1679There are numerous other tools, such as stgit, which exist for the purpose
1680of maintianing a patch series.  These are out of the scope of this manual.
1681
1682Problems with rewriting history
1683-------------------------------
1684
1685The primary problem with rewriting the history of a branch has to do with
1686merging.
1687
1688TODO: elaborate
1689
1690
1691Git internals
1692=============
1693
1694Architectural overview
1695----------------------
1696
1697TODO: Sources, README, core-tutorial, tutorial-2.txt, technical/
1698
1699Glossary of git terms
1700=====================
1701
1702include::glossary.txt[]
1703
1704Notes and todo list for this manual
1705===================================
1706
1707This is a work in progress.
1708
1709The basic requirements:
1710        - It must be readable in order, from beginning to end, by someone
1711          intelligent with a basic grasp of the unix commandline, but
1712          without any special knowledge of git.  If necessary, any other
1713          prerequisites should be specifically mentioned as they arise.
1714        - Whenever possible, section headings should clearly describe the
1715          task they explain how to do, in language that requires no more
1716          knowledge than necessary: for example, "importing patches into a
1717          project" rather than "the git-am command"
1718
1719Think about how to create a clear chapter dependency graph that will
1720allow people to get to important topics without necessarily reading
1721everything in between.
1722
1723Scan Documentation/ for other stuff left out; in particular:
1724        howto's
1725        README
1726        some of technical/?
1727        hooks
1728        etc.
1729
1730Scan email archives for other stuff left out
1731
1732Scan man pages to see if any assume more background than this manual
1733provides.
1734
1735Simplify beginning by suggesting disconnected head instead of temporary
1736branch creation.
1737
1738Explain how to refer to file stages in the "how to resolve a merge"
1739section: diff -1, -2, -3, --ours, --theirs :1:/path notation.  The
1740"git ls-files --unmerged --stage" thing is sorta useful too, actually.  And
1741note gitk --merge.  Also what's easiest way to see common merge base?
1742
1743Add more good examples.  Entire sections of just cookbook examples might
1744be a good idea; maybe make an "advanced examples" section a standard
1745end-of-chapter section?
1746
1747Include cross-references to the glossary, where appropriate.
1748
1749To document:
1750        reflogs, git reflog expire
1751        shallow clones??  See draft 1.5.0 release notes for some documentation.