Autogenerated HTML docs for v1.5.6.3-350-g6c11a
authorJunio C Hamano <junio@hera.kernel.org>
Tue, 15 Jul 2008 15:49:03 +0000 (15:49 +0000)
committerJunio C Hamano <junio@hera.kernel.org>
Tue, 15 Jul 2008 15:49:03 +0000 (15:49 +0000)
15 files changed:
RelNotes-1.6.0.txt
git-add.html
git-add.txt
git-am.html
git-am.txt
git-branch.html
git-branch.txt
git-merge.html
git-merge.txt
git-rebase.html
git-rebase.txt
git-submodule.html
git-submodule.txt
gittutorial.html
gittutorial.txt

index 9125ee01a6c4d4cb6d9104b2ac008b05b92e3a3a..89ea1e9385bdea0ec42891c1f5ac7763cdbf8a73 100644 (file)
@@ -110,6 +110,9 @@ Updates since v1.5.6
 * "git-add -i" has a new action 'e/dit' to allow you edit the patch hunk
   manually.
 
+* git-am records the original tip of the branch in ORIG_HEAD before it
+  starts applying patches.
+
 * git-apply can handle a patch that touches the same path more than once
   much better than before.
 
@@ -126,6 +129,14 @@ Updates since v1.5.6
   similar to the way git-checkout reports by how many commits your branch
   is ahead/behind.
 
+* git-branch's --contains option used to always require a commit parameter
+  to limit the branches with; it now defaults to list branches that
+  contains HEAD if this parameter is omitted.
+
+* git-branch's --merged and --no-merged option used to always limit the
+  branches relative to the HEAD, but they can now take an optional commit
+  argument that is used in place of HEAD.
+
 * git-bundle can read the revision arguments from the standard input.
 
 * git-cherry-pick can replay a root commit now.
@@ -144,6 +155,9 @@ Updates since v1.5.6
 * fast-export learned to export and import marks file; this can be used to
   interface with fast-import incrementally.
 
+* git-rebase records the original tip of branch in ORIG_HEAD before it is
+  rewound.
+
 * "git rerere" can be told to update the index with auto-reused resolution
   with rerere.autoupdate configuration variable.
 
@@ -152,6 +166,8 @@ Updates since v1.5.6
 
 * git-send-mail can talk not just over SSL but over TLS now.
 
+* git-shortlog honors custom output format specified with "--pretty=format:".
+
 * "git-stash save" learned --keep-index option.  This lets you stash away the
   local changes and bring the changes staged in the index to your working
   tree for examination and testing.
@@ -185,6 +201,6 @@ this release, unless otherwise noted.
 
 ---
 exec >/var/tmp/1
-O=v1.5.6.3-315-g10ce020
+O=v1.5.6.3-350-g499027b
 echo O=$(git describe refs/heads/master)
 git shortlog --no-merges $O..refs/heads/master ^refs/heads/maint
index ebfafcd8a4a278c574f3ca50c022aefd311793ff..643a85d7678225216a1c8cb7de2b2a52e8d93809 100644 (file)
@@ -565,8 +565,9 @@ update
    "Update&gt;&gt;".  When the prompt ends with double <em>&gt;&gt;</em>, you can\r
    make more than one selection, concatenated with whitespace or\r
    comma.  Also you can say ranges.  E.g. "2-5 7,9" to choose\r
-   2,3,4,5,7,9 from the list.  You can say <em>*</em> to choose\r
-   everything.\r
+   2,3,4,5,7,9 from the list.  If the second number in a range is\r
+   omitted, all remaining patches are taken.  E.g. "7-" to choose\r
+   7,8,9 from the list.  You can say <em>*</em> to choose everything.\r
 </p>\r
 <div class="para"><p>What you chose are then highlighted with <em>*</em>,\r
 like this:</p></div>\r
@@ -672,7 +673,7 @@ double-quote and control characters will still have problems.</p></div>
 </div>\r
 <div id="footer">\r
 <div id="footer-text">\r
-Last updated 2008-07-14 03:12:28 UTC\r
+Last updated 2008-07-15 15:48:33 UTC\r
 </div>\r
 </div>\r
 </body>\r
index 46dd56c12a8167c3861a304e820c664e3c92ca4f..3558905a92a20f1f615a48821638ce239ecb6232 100644 (file)
@@ -187,8 +187,9 @@ update::
    "Update>>".  When the prompt ends with double '>>', you can
    make more than one selection, concatenated with whitespace or
    comma.  Also you can say ranges.  E.g. "2-5 7,9" to choose
-   2,3,4,5,7,9 from the list.  You can say '*' to choose
-   everything.
+   2,3,4,5,7,9 from the list.  If the second number in a range is
+   omitted, all remaining patches are taken.  E.g. "7-" to choose
+   7,8,9 from the list.  You can say '*' to choose everything.
 +
 What you chose are then highlighted with '*',
 like this:
index b913f1ad2c0ebb2b800608a175d9f07bdb2950ca..4c7a7b7eef2ffe193414bd718d565d827972656d 100644 (file)
@@ -553,6 +553,11 @@ hand resolve the conflict in the working directory, and update
 directory exists, so if you decide to start over from scratch,\r
 run <tt>rm -f -r .dotest</tt> before running the command with mailbox\r
 names.</p></div>\r
+<div class="para"><p>Before any patches are applied, ORIG_HEAD is set to the tip of the\r
+current branch.  This is useful if you have problems with multiple\r
+commits, like running <em>git am</em> on the wrong branch or an error in the\r
+commits that is more easily fixed by changing the mailbox (e.g.\r
+errors in the "From:" lines).</p></div>\r
 </div>\r
 <h2 id="_see_also">SEE ALSO</h2>\r
 <div class="sectionbody">\r
@@ -572,7 +577,7 @@ names.</p></div>
 </div>\r
 <div id="footer">\r
 <div id="footer-text">\r
-Last updated 2008-07-14 03:12:28 UTC\r
+Last updated 2008-07-15 15:48:33 UTC\r
 </div>\r
 </div>\r
 </body>\r
index eeb23b25b0d70c4ccc3eb9d091971b1f20ad4b4b..1395c7d986c82eb1e7e91140c8f97b80e7a8a41d 100644 (file)
@@ -145,6 +145,12 @@ directory exists, so if you decide to start over from scratch,
 run `rm -f -r .dotest` before running the command with mailbox
 names.
 
+Before any patches are applied, ORIG_HEAD is set to the tip of the
+current branch.  This is useful if you have problems with multiple
+commits, like running 'git am' on the wrong branch or an error in the
+commits that is more easily fixed by changing the mailbox (e.g.
+errors in the "From:" lines).
+
 
 SEE ALSO
 --------
index 6365ba299530ce8f952f7767dd067dd4718e3ed9..d0c3c5e56436e74b72324e6d578c027bc2333485 100644 (file)
@@ -321,24 +321,25 @@ git-branch(1) Manual Page
 <h2>SYNOPSIS</h2>\r
 <div class="sectionbody">\r
 <div class="verseblock">\r
-<div class="content"><em>git branch</em> [--color | --no-color] [-r | -a] [--merged | --no-merged]\r
-           [-v [--abbrev=&lt;length&gt; | --no-abbrev]]\r
-           [--contains &lt;commit&gt;]\r
+<div class="content"><em>git branch</em> [--color | --no-color] [-r | -a]\r
+        [-v [--abbrev=&lt;length&gt; | --no-abbrev]]\r
+        [(--merged | --no-merged | --contains) [&lt;commit&gt;]]\r
 <em>git branch</em> [--track | --no-track] [-l] [-f] &lt;branchname&gt; [&lt;start-point&gt;]\r
 <em>git branch</em> (-m | -M) [&lt;oldbranch&gt;] &lt;newbranch&gt;\r
 <em>git branch</em> (-d | -D) [-r] &lt;branchname&gt;&#8230;</div></div>\r
 </div>\r
 <h2 id="_description">DESCRIPTION</h2>\r
 <div class="sectionbody">\r
-<div class="para"><p>With no arguments given a list of existing branches\r
-will be shown, the current branch will be highlighted with an asterisk.\r
-Option <tt>-r</tt> causes the remote-tracking branches to be listed,\r
-and option <tt>-a</tt> shows both.\r
-With <tt>--contains &lt;commit&gt;</tt>, shows only the branches that\r
-contains the named commit (in other words, the branches whose\r
-tip commits are descendant of the named commit).\r
-With <tt>--merged</tt>, only branches merged into HEAD will be listed, and\r
-with <tt>--no-merged</tt> only branches not merged into HEAD will be listed.</p></div>\r
+<div class="para"><p>With no arguments, existing branches are listed, the current branch will\r
+be highlighted with an asterisk.  Option <tt>-r</tt> causes the remote-tracking\r
+branches to be listed, and option <tt>-a</tt> shows both.</p></div>\r
+<div class="para"><p>With <tt>--contains</tt>, shows only the branches that contains the named commit\r
+(in other words, the branches whose tip commits are descendant of the\r
+named commit).  With <tt>--merged</tt>, only branches merged into the named\r
+commit (i.e. the branches whose tip commits are reachable from the named\r
+commit) will be listed.  With <tt>--no-merged</tt> only branches not merged into\r
+the named commit will be listed.  Missing &lt;commit&gt; argument defaults to\r
+<em>HEAD</em> (i.e. the tip of the current branch).</p></div>\r
 <div class="para"><p>In its second form, a new branch named &lt;branchname&gt; will be created.\r
 It will start out with a head equal to the one given as &lt;start-point&gt;.\r
 If no &lt;start-point&gt; is given, the branch will be created with a head\r
@@ -664,7 +665,7 @@ but different purposes:</p></div>
 </div>\r
 <div id="footer">\r
 <div id="footer-text">\r
-Last updated 2008-07-06 05:16:36 UTC\r
+Last updated 2008-07-15 15:48:34 UTC\r
 </div>\r
 </div>\r
 </body>\r
index b3e62ed011f0a99ce3f173a3f22758edc457f72b..fc5a4a602fb7cbc5e73f7029a0b82bba05d0b913 100644 (file)
@@ -8,24 +8,27 @@ git-branch - List, create, or delete branches
 SYNOPSIS
 --------
 [verse]
-'git branch' [--color | --no-color] [-r | -a] [--merged | --no-merged]
-          [-v [--abbrev=<length> | --no-abbrev]]
-          [--contains <commit>]
+'git branch' [--color | --no-color] [-r | -a]
+       [-v [--abbrev=<length> | --no-abbrev]]
+       [(--merged | --no-merged | --contains) [<commit>]]
 'git branch' [--track | --no-track] [-l] [-f] <branchname> [<start-point>]
 'git branch' (-m | -M) [<oldbranch>] <newbranch>
 'git branch' (-d | -D) [-r] <branchname>...
 
 DESCRIPTION
 -----------
-With no arguments given a list of existing branches
-will be shown, the current branch will be highlighted with an asterisk.
-Option `-r` causes the remote-tracking branches to be listed,
-and option `-a` shows both.
-With `--contains <commit>`, shows only the branches that
-contains the named commit (in other words, the branches whose
-tip commits are descendant of the named commit).
-With `--merged`, only branches merged into HEAD will be listed, and
-with `--no-merged` only branches not merged into HEAD will be listed.
+
+With no arguments, existing branches are listed, the current branch will
+be highlighted with an asterisk.  Option `-r` causes the remote-tracking
+branches to be listed, and option `-a` shows both.
+
+With `--contains`, shows only the branches that contains the named commit
+(in other words, the branches whose tip commits are descendant of the
+named commit).  With `--merged`, only branches merged into the named
+commit (i.e. the branches whose tip commits are reachable from the named
+commit) will be listed.  With `--no-merged` only branches not merged into
+the named commit will be listed.  Missing <commit> argument defaults to
+'HEAD' (i.e. the tip of the current branch).
 
 In its second form, a new branch named <branchname> will be created.
 It will start out with a head equal to the one given as <start-point>.
index 90992fcf11a41a8144c9fd63cfd37192f41e9fda..46166165c5e6c3a0986c2b03769f914af516ceff 100644 (file)
@@ -685,7 +685,9 @@ fail.</td>
 (that is, it may fetch the objects from remote, and it may even\r
 update the local branch used to keep track of the remote branch\r
 with <tt>git pull remote rbranch:lbranch</tt>, but your working tree,\r
-<tt>.git/HEAD</tt> pointer and index file are left intact).</p></div>\r
+<tt>.git/HEAD</tt> pointer and index file are left intact).  In addition,\r
+merge always sets <tt>.git/ORIG_HEAD</tt> to the original state of HEAD so\r
+a problematic merge can be removed by using <tt>git reset ORIG_HEAD</tt>.</p></div>\r
 <div class="para"><p>You may have local modifications in the working tree files.  In\r
 other words, <em>git-diff</em> is allowed to report changes.\r
 However, the merge uses your working tree as the working area,\r
@@ -809,7 +811,7 @@ Resolve the conflicts.  <tt>git diff</tt> would report only the
 </div>\r
 <div id="footer">\r
 <div id="footer-text">\r
-Last updated 2008-07-06 05:16:54 UTC\r
+Last updated 2008-07-15 15:48:34 UTC\r
 </div>\r
 </div>\r
 </body>\r
index 62f99b5f3b8991c93d0f2e06cd382312069bccaf..019e4ca8f503e146814bf7b9f6e2ef2920d940e2 100644 (file)
@@ -81,7 +81,9 @@ Otherwise, merge will refuse to do any harm to your repository
 (that is, it may fetch the objects from remote, and it may even
 update the local branch used to keep track of the remote branch
 with `git pull remote rbranch:lbranch`, but your working tree,
-`.git/HEAD` pointer and index file are left intact).
+`.git/HEAD` pointer and index file are left intact).  In addition,
+merge always sets `.git/ORIG_HEAD` to the original state of HEAD so
+a problematic merge can be removed by using `git reset ORIG_HEAD`.
 
 You may have local modifications in the working tree files.  In
 other words, 'git-diff' is allowed to report changes.
index a2905d5021bf272b5a949a690034997aa32fb071..04fd39f3b0cf5b33c8a2464109134f968e715d92 100644 (file)
@@ -337,7 +337,8 @@ in &lt;upstream&gt; are saved to a temporary area.  This is the same set
 of commits that would be shown by <tt>git log &lt;upstream&gt;..HEAD</tt>.</p></div>\r
 <div class="para"><p>The current branch is reset to &lt;upstream&gt;, or &lt;newbase&gt; if the\r
 --onto option was supplied.  This has the exact same effect as\r
-<tt>git reset --hard &lt;upstream&gt;</tt> (or &lt;newbase&gt;).</p></div>\r
+<tt>git reset --hard &lt;upstream&gt;</tt> (or &lt;newbase&gt;).  ORIG_HEAD is set\r
+to point at the tip of the branch before the reset.</p></div>\r
 <div class="para"><p>The commits that were previously saved into the temporary area are\r
 then reapplied to the current branch, one by one, in order. Note that\r
 any commits in HEAD which introduce the same textual changes as a commit\r
@@ -906,7 +907,7 @@ Johannes E. Schindelin &lt;johannes.schindelin@gmx.de&gt;</p></div>
 </div>\r
 <div id="footer">\r
 <div id="footer-text">\r
-Last updated 2008-07-06 05:16:57 UTC\r
+Last updated 2008-07-15 15:48:34 UTC\r
 </div>\r
 </div>\r
 </body>\r
index f3459c7de7c9629f2abfdb684a359bb264ea82ed..e30f6a6982a8d9ee48c6a7d46fa435c7aee773af 100644 (file)
@@ -26,7 +26,8 @@ of commits that would be shown by `git log <upstream>..HEAD`.
 
 The current branch is reset to <upstream>, or <newbase> if the
 --onto option was supplied.  This has the exact same effect as
-`git reset --hard <upstream>` (or <newbase>).
+`git reset --hard <upstream>` (or <newbase>).  ORIG_HEAD is set
+to point at the tip of the branch before the reset.
 
 The commits that were previously saved into the temporary area are
 then reapplied to the current branch, one by one, in order. Note that
index a222a7e4f4bedac03eeff48492c5fa9181a4f41e..721a90b09bc161cd328b22252c39e2f5947a485b 100644 (file)
@@ -321,7 +321,7 @@ git-submodule(1) Manual Page
 <h2>SYNOPSIS</h2>\r
 <div class="sectionbody">\r
 <div class="verseblock">\r
-<div class="content"><em>git submodule</em> [--quiet] add [-b branch] [--] &lt;repository&gt; [&lt;path&gt;]\r
+<div class="content"><em>git submodule</em> [--quiet] add [-b branch] [--] &lt;repository&gt; &lt;path&gt;\r
 <em>git submodule</em> [--quiet] status [--cached] [--] [&lt;path&gt;&#8230;]\r
 <em>git submodule</em> [--quiet] init [--] [&lt;path&gt;&#8230;]\r
 <em>git submodule</em> [--quiet] update [--init] [--] [&lt;path&gt;&#8230;]\r
@@ -336,15 +336,28 @@ add
 <dd>\r
 <p>\r
         Add the given repository as a submodule at the given path\r
-        to the changeset to be committed next.  If path is a valid\r
-        repository within the project, it is added as is. Otherwise,\r
-        repository is cloned at the specified path. path is added to the\r
-        changeset and registered in .gitmodules.   If no path is\r
-        specified, the path is deduced from the repository specification.\r
-        If the repository url begins with ./ or ../, it is stored as\r
-        given but resolved as a relative path from the main project's\r
-        url when cloning.\r
+        to the changeset to be committed next to the current\r
+        project: the current project is termed termed the "superproject".\r
 </p>\r
+<div class="para"><p>This requires two arguments: &lt;repository&gt; and &lt;path&gt;.</p></div>\r
+<div class="para"><p>&lt;repository&gt; is the URL of the new submodule's origin repository.\r
+This may be either an absolute URL, or (if it begins with ./\r
+or ../), the location relative to the superproject's origin\r
+repository.</p></div>\r
+<div class="para"><p>&lt;path&gt; is the relative location for the cloned submodule to\r
+exist in the superproject. If &lt;path&gt; does not exist, then the\r
+submodule is created by cloning from the named URL. If &lt;path&gt; does\r
+exist and is already a valid git repository, then this is added\r
+to the changeset without cloning. This second form is provided\r
+to ease creating a new submodule from scratch, and presumes\r
+the user will later push the submodule to the given URL.</p></div>\r
+<div class="para"><p>In either case, the given URL is recorded into .gitmodules for\r
+use by subsequent users cloning the superproject. If the URL is\r
+given relative to the superproject's repository, the presumption\r
+is the superproject and submodule repositories will be kept\r
+together in the same relative location, and only the\r
+superproject's URL need be provided: git-submodule will correctly\r
+locate the submodule using the relative URL in .gitmodules.</p></div>\r
 </dd>\r
 <dt>\r
 status\r
@@ -454,6 +467,7 @@ summary
 <p>\r
         Path to submodule(s). When specified this will restrict the command\r
         to only operate on the submodules found at the specified paths.\r
+        (This argument is required with add).\r
 </p>\r
 </dd>\r
 </dl></div>\r
@@ -476,7 +490,7 @@ for details.</p></div>
 </div>\r
 <div id="footer">\r
 <div id="footer-text">\r
-Last updated 2008-07-06 05:17:04 UTC\r
+Last updated 2008-07-15 15:48:35 UTC\r
 </div>\r
 </div>\r
 </body>\r
index 105fc2dcdceb454a7a45e7d4c92f2fd43f44c6c7..76702a0a5aa2b8825096ebf37f76d090a1c2627b 100644 (file)
@@ -9,7 +9,7 @@ git-submodule - Initialize, update or inspect submodules
 SYNOPSIS
 --------
 [verse]
-'git submodule' [--quiet] add [-b branch] [--] <repository> [<path>]
+'git submodule' [--quiet] add [-b branch] [--] <repository> <path>
 'git submodule' [--quiet] status [--cached] [--] [<path>...]
 'git submodule' [--quiet] init [--] [<path>...]
 'git submodule' [--quiet] update [--init] [--] [<path>...]
@@ -20,14 +20,31 @@ COMMANDS
 --------
 add::
        Add the given repository as a submodule at the given path
-       to the changeset to be committed next.  If path is a valid
-       repository within the project, it is added as is. Otherwise,
-       repository is cloned at the specified path. path is added to the
-       changeset and registered in .gitmodules.   If no path is
-       specified, the path is deduced from the repository specification.
-       If the repository url begins with ./ or ../, it is stored as
-       given but resolved as a relative path from the main project's
-       url when cloning.
+       to the changeset to be committed next to the current
+       project: the current project is termed termed the "superproject".
++
+This requires two arguments: <repository> and <path>.
++
+<repository> is the URL of the new submodule's origin repository.
+This may be either an absolute URL, or (if it begins with ./
+or ../), the location relative to the superproject's origin
+repository.
++
+<path> is the relative location for the cloned submodule to
+exist in the superproject. If <path> does not exist, then the
+submodule is created by cloning from the named URL. If <path> does
+exist and is already a valid git repository, then this is added
+to the changeset without cloning. This second form is provided
+to ease creating a new submodule from scratch, and presumes
+the user will later push the submodule to the given URL.
++
+In either case, the given URL is recorded into .gitmodules for
+use by subsequent users cloning the superproject. If the URL is
+given relative to the superproject's repository, the presumption
+is the superproject and submodule repositories will be kept
+together in the same relative location, and only the
+superproject's URL need be provided: git-submodule will correctly
+locate the submodule using the relative URL in .gitmodules.
 
 status::
        Show the status of the submodules. This will print the SHA-1 of the
@@ -85,6 +102,7 @@ OPTIONS
 <path>::
        Path to submodule(s). When specified this will restrict the command
        to only operate on the submodules found at the specified paths.
+       (This argument is required with add).
 
 FILES
 -----
index b77223e5f36edd7ad6ab755e4e4fc51e162d556c..8651c5bc68301914425424cb3a53d2eb6034de5d 100644 (file)
@@ -546,7 +546,7 @@ same machine, wants to contribute.</p></div>
 <div class="para"><p>Bob begins with:</p></div>\r
 <div class="listingblock">\r
 <div class="content">\r
-<pre><tt>$ git clone /home/alice/project myrepo</tt></pre>\r
+<pre><tt>bob$ git clone /home/alice/project myrepo</tt></pre>\r
 </div></div>\r
 <div class="para"><p>This creates a new directory "myrepo" containing a clone of Alice's\r
 repository.  The clone is on an equal footing with the original\r
@@ -555,15 +555,15 @@ project, possessing its own copy of the original project's history.</p></div>
 <div class="listingblock">\r
 <div class="content">\r
 <pre><tt>(edit files)\r
-$ git commit -a\r
+bob$ git commit -a\r
 (repeat as necessary)</tt></pre>\r
 </div></div>\r
 <div class="para"><p>When he's ready, he tells Alice to pull changes from the repository\r
 at /home/bob/myrepo.  She does this with:</p></div>\r
 <div class="listingblock">\r
 <div class="content">\r
-<pre><tt>$ cd /home/alice/project\r
-$ git pull /home/bob/myrepo master</tt></pre>\r
+<pre><tt>alice$ cd /home/alice/project\r
+alice$ git pull /home/bob/myrepo master</tt></pre>\r
 </div></div>\r
 <div class="para"><p>This merges the changes from Bob's "master" branch into Alice's\r
 current branch.  If Alice has made her own changes in the meantime,\r
@@ -572,20 +572,42 @@ then she may need to manually fix any conflicts.  (Note that the
 is the default.)</p></div>\r
 <div class="para"><p>The "pull" command thus performs two operations: it fetches changes\r
 from a remote branch, then merges them into the current branch.</p></div>\r
+<div class="para"><p>Note that in general, Alice would want her local changes committed before\r
+initiating this "pull".  If Bob's work conflicts with what Alice did since\r
+their histories forked, Alice will use her working tree and the index to\r
+resolve conflicts, and existing local changes will interfere with the\r
+conflict resolution process (git will still perform the fetch but will\r
+refuse to merge --- Alice will have to get rid of her local changes in\r
+some way and pull again when this happens).</p></div>\r
+<div class="para"><p>Alice can peek at what Bob did without merging first, using the "fetch"\r
+command; this allows Alice to inspect what Bob did, using a special\r
+symbol "FETCH_HEAD", in order to determine if he has anything worth\r
+pulling, like this:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>alice$ git fetch /home/bob/myrepo master\r
+alice$ git log -p ..FETCH_HEAD</tt></pre>\r
+</div></div>\r
+<div class="para"><p>This operation is safe even if Alice has uncommitted local changes.</p></div>\r
+<div class="para"><p>After inspecting what Bob did, if there is nothing urgent, Alice may\r
+decide to continue working without pulling from Bob.  If Bob's history\r
+does have something Alice would immediately need, Alice may choose to\r
+stash her work-in-progress first, do a "pull", and then finally unstash\r
+her work-in-progress on top of the resulting history.</p></div>\r
 <div class="para"><p>When you are working in a small closely knit group, it is not\r
 unusual to interact with the same repository over and over\r
 again.  By defining <em>remote</em> repository shorthand, you can make\r
 it easier:</p></div>\r
 <div class="listingblock">\r
 <div class="content">\r
-<pre><tt>$ git remote add bob /home/bob/myrepo</tt></pre>\r
+<pre><tt>alice$ git remote add bob /home/bob/myrepo</tt></pre>\r
 </div></div>\r
-<div class="para"><p>With this, Alice can perform the first operation alone using the\r
+<div class="para"><p>With this, Alice can perform the first part of the "pull" operation alone using the\r
 <em>git-fetch</em> command without merging them with her own branch,\r
 using:</p></div>\r
 <div class="listingblock">\r
 <div class="content">\r
-<pre><tt>$ git fetch bob</tt></pre>\r
+<pre><tt>alice$ git fetch bob</tt></pre>\r
 </div></div>\r
 <div class="para"><p>Unlike the longhand form, when Alice fetches from Bob using a\r
 remote repository shorthand set up with <em>git-remote</em>, what was\r
@@ -593,7 +615,7 @@ fetched is stored in a remote tracking branch, in this case
 <tt>bob/master</tt>.  So after this:</p></div>\r
 <div class="listingblock">\r
 <div class="content">\r
-<pre><tt>$ git log -p master..bob/master</tt></pre>\r
+<pre><tt>alice$ git log -p master..bob/master</tt></pre>\r
 </div></div>\r
 <div class="para"><p>shows a list of all the changes that Bob made since he branched from\r
 Alice's master branch.</p></div>\r
@@ -601,20 +623,20 @@ Alice's master branch.</p></div>
 could merge the changes into her master branch:</p></div>\r
 <div class="listingblock">\r
 <div class="content">\r
-<pre><tt>$ git merge bob/master</tt></pre>\r
+<pre><tt>alice$ git merge bob/master</tt></pre>\r
 </div></div>\r
 <div class="para"><p>This <tt>merge</tt> can also be done by <em>pulling from her own remote\r
 tracking branch</em>, like this:</p></div>\r
 <div class="listingblock">\r
 <div class="content">\r
-<pre><tt>$ git pull . remotes/bob/master</tt></pre>\r
+<pre><tt>alice$ git pull . remotes/bob/master</tt></pre>\r
 </div></div>\r
 <div class="para"><p>Note that git pull always merges into the current branch,\r
 regardless of what else is given on the command line.</p></div>\r
 <div class="para"><p>Later, Bob can update his repo with Alice's latest changes using</p></div>\r
 <div class="listingblock">\r
 <div class="content">\r
-<pre><tt>$ git pull</tt></pre>\r
+<pre><tt>bob$ git pull</tt></pre>\r
 </div></div>\r
 <div class="para"><p>Note that he doesn't need to give the path to Alice's repository;\r
 when Bob cloned Alice's repository, git stored the location of her\r
@@ -622,7 +644,7 @@ repository in the repository configuration, and that location is
 used for pulls:</p></div>\r
 <div class="listingblock">\r
 <div class="content">\r
-<pre><tt>$ git config --get remote.origin.url\r
+<pre><tt>bob$ git config --get remote.origin.url\r
 /home/alice/project</tt></pre>\r
 </div></div>\r
 <div class="para"><p>(The complete configuration created by <em>git-clone</em> is visible using\r
@@ -632,14 +654,14 @@ explains the meaning of each option.)</p></div>
 name "origin/master":</p></div>\r
 <div class="listingblock">\r
 <div class="content">\r
-<pre><tt>$ git branch -r\r
+<pre><tt>bob$ git branch -r\r
   origin/master</tt></pre>\r
 </div></div>\r
 <div class="para"><p>If Bob later decides to work from a different host, he can still\r
 perform clones and pulls using the ssh protocol:</p></div>\r
 <div class="listingblock">\r
 <div class="content">\r
-<pre><tt>$ git clone alice.org:/home/alice/project myrepo</tt></pre>\r
+<pre><tt>bob$ git clone alice.org:/home/alice/project myrepo</tt></pre>\r
 </div></div>\r
 <div class="para"><p>Alternatively, git has a native protocol, or can use rsync or http;\r
 see <a href="git-pull.html">git-pull(1)</a> for details.</p></div>\r
@@ -859,7 +881,7 @@ digressions that may be interesting at this point are:</p></div>
 </div>\r
 <div id="footer">\r
 <div id="footer-text">\r
-Last updated 2008-07-06 05:17:11 UTC\r
+Last updated 2008-07-15 15:48:35 UTC\r
 </div>\r
 </div>\r
 </body>\r
index e71b561172030bbd4c524891f6525fadd160b54b..48d1454a90cf9453e5e3c9fa01b3dbc369a58f1f 100644 (file)
@@ -274,7 +274,7 @@ same machine, wants to contribute.
 Bob begins with:
 
 ------------------------------------------------
-$ git clone /home/alice/project myrepo
+bob$ git clone /home/alice/project myrepo
 ------------------------------------------------
 
 This creates a new directory "myrepo" containing a clone of Alice's
@@ -285,7 +285,7 @@ Bob then makes some changes and commits them:
 
 ------------------------------------------------
 (edit files)
-$ git commit -a
+bob$ git commit -a
 (repeat as necessary)
 ------------------------------------------------
 
@@ -293,8 +293,8 @@ When he's ready, he tells Alice to pull changes from the repository
 at /home/bob/myrepo.  She does this with:
 
 ------------------------------------------------
-$ cd /home/alice/project
-$ git pull /home/bob/myrepo master
+alice$ cd /home/alice/project
+alice$ git pull /home/bob/myrepo master
 ------------------------------------------------
 
 This merges the changes from Bob's "master" branch into Alice's
@@ -306,21 +306,47 @@ is the default.)
 The "pull" command thus performs two operations: it fetches changes
 from a remote branch, then merges them into the current branch.
 
+Note that in general, Alice would want her local changes committed before
+initiating this "pull".  If Bob's work conflicts with what Alice did since
+their histories forked, Alice will use her working tree and the index to
+resolve conflicts, and existing local changes will interfere with the
+conflict resolution process (git will still perform the fetch but will
+refuse to merge --- Alice will have to get rid of her local changes in
+some way and pull again when this happens).
+
+Alice can peek at what Bob did without merging first, using the "fetch"
+command; this allows Alice to inspect what Bob did, using a special
+symbol "FETCH_HEAD", in order to determine if he has anything worth
+pulling, like this:
+
+------------------------------------------------
+alice$ git fetch /home/bob/myrepo master
+alice$ git log -p ..FETCH_HEAD
+------------------------------------------------
+
+This operation is safe even if Alice has uncommitted local changes.
+
+After inspecting what Bob did, if there is nothing urgent, Alice may
+decide to continue working without pulling from Bob.  If Bob's history
+does have something Alice would immediately need, Alice may choose to
+stash her work-in-progress first, do a "pull", and then finally unstash
+her work-in-progress on top of the resulting history.
+
 When you are working in a small closely knit group, it is not
 unusual to interact with the same repository over and over
 again.  By defining 'remote' repository shorthand, you can make
 it easier:
 
 ------------------------------------------------
-$ git remote add bob /home/bob/myrepo
+alice$ git remote add bob /home/bob/myrepo
 ------------------------------------------------
 
-With this, Alice can perform the first operation alone using the
+With this, Alice can perform the first part of the "pull" operation alone using the
 'git-fetch' command without merging them with her own branch,
 using:
 
 -------------------------------------
-$ git fetch bob
+alice$ git fetch bob
 -------------------------------------
 
 Unlike the longhand form, when Alice fetches from Bob using a
@@ -329,7 +355,7 @@ fetched is stored in a remote tracking branch, in this case
 `bob/master`.  So after this:
 
 -------------------------------------
-$ git log -p master..bob/master
+alice$ git log -p master..bob/master
 -------------------------------------
 
 shows a list of all the changes that Bob made since he branched from
@@ -339,14 +365,14 @@ After examining those changes, Alice
 could merge the changes into her master branch:
 
 -------------------------------------
-$ git merge bob/master
+alice$ git merge bob/master
 -------------------------------------
 
 This `merge` can also be done by 'pulling from her own remote
 tracking branch', like this:
 
 -------------------------------------
-$ git pull . remotes/bob/master
+alice$ git pull . remotes/bob/master
 -------------------------------------
 
 Note that git pull always merges into the current branch,
@@ -355,7 +381,7 @@ regardless of what else is given on the command line.
 Later, Bob can update his repo with Alice's latest changes using
 
 -------------------------------------
-$ git pull
+bob$ git pull
 -------------------------------------
 
 Note that he doesn't need to give the path to Alice's repository;
@@ -364,7 +390,7 @@ repository in the repository configuration, and that location is
 used for pulls:
 
 -------------------------------------
-$ git config --get remote.origin.url
+bob$ git config --get remote.origin.url
 /home/alice/project
 -------------------------------------
 
@@ -376,7 +402,7 @@ Git also keeps a pristine copy of Alice's master branch under the
 name "origin/master":
 
 -------------------------------------
-$ git branch -r
+bob$ git branch -r
   origin/master
 -------------------------------------
 
@@ -384,7 +410,7 @@ If Bob later decides to work from a different host, he can still
 perform clones and pulls using the ssh protocol:
 
 -------------------------------------
-$ git clone alice.org:/home/alice/project myrepo
+bob$ git clone alice.org:/home/alice/project myrepo
 -------------------------------------
 
 Alternatively, git has a native protocol, or can use rsync or http;