docs: clarify remote restrictions for git-upload-archive

diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt
index b295bf83302de3fdac2833df756799a7aad6b404..808426faac5b9b607810777a718113e77b836715 100644 (file)
--- a/Documentation/git-merge-base.txt
+++ b/Documentation/git-merge-base.txt
@@ -11,7 +11,9 @@ SYNOPSIS
 [verse]
 'git merge-base' [-a|--all] <commit> <commit>...
 'git merge-base' [-a|--all] --octopus <commit>...
+'git merge-base' --is-ancestor <commit> <commit>
 'git merge-base' --independent <commit>...
+'git merge-base' --fork-point <ref> [<commit>]
 
 DESCRIPTION
 -----------
@@ -23,8 +25,8 @@ that does not have any better common ancestor is a 'best common
 ancestor', i.e. a 'merge base'.  Note that there can be more than one
 merge base for a pair of commits.
 
-OPERATION MODE
---------------
+OPERATION MODES
+---------------
 
 As the most common special case, specifying only two commits on the
 command line means computing the merge base between the given two commits.
@@ -50,6 +52,20 @@ from linkgit:git-show-branch[1] when used with the `--merge-base` option.
        from any other.  This mimics the behavior of 'git show-branch
        --independent'.
 
+--is-ancestor::
+       Check if the first <commit> is an ancestor of the second <commit>,
+       and exit with status 0 if true, or with status 1 if not.
+       Errors are signaled by a non-zero status that is not 1.
+
+--fork-point::
+       Find the point at which a branch (or any history that leads
+       to <commit>) forked from another branch (or any reference)
+       <ref>. This does not just look for the common ancestor of
+       the two commits, but also takes into account the reflog of
+       <ref> to see if the history leading to <commit> forked from
+       an earlier incarnation of the branch <ref> (see discussion
+       on this mode below).
+
 OPTIONS
 -------
 -a::
@@ -110,6 +126,52 @@ both '1' and '2' are merge-bases of A and B.  Neither one is better than
 the other (both are 'best' merge bases).  When the `--all` option is not given,
 it is unspecified which best one is output.
 
+A common idiom to check "fast-forward-ness" between two commits A
+and B is (or at least used to be) to compute the merge base between
+A and B, and check if it is the same as A, in which case, A is an
+ancestor of B.  You will see this idiom used often in older scripts.
+
+       A=$(git rev-parse --verify A)
+       if test "$A" = "$(git merge-base A B)"
+       then
+               ... A is an ancestor of B ...
+       fi
+
+In modern git, you can say this in a more direct way:
+
+       if git merge-base --is-ancestor A B
+       then
+               ... A is an ancestor of B ...
+       fi
+
+instead.
+
+Discussion on fork-point mode
+-----------------------------
+
+After working on the `topic` branch created with `git checkout -b
+topic origin/master`, the history of remote-tracking branch
+`origin/master` may have been rewound and rebuilt, leading to a
+history of this shape:
+
+                        o---B1
+                       /
+       ---o---o---B2--o---o---o---B (origin/master)
+               \
+                B3
+                 \
+                  Derived (topic)
+
+where `origin/master` used to point at commits B3, B2, B1 and now it
+points at B, and your `topic` branch was started on top of it back
+when `origin/master` was at B3. This mode uses the reflog of
+`origin/master` to find B3 as the fork point, so that the `topic`
+can be rebased on top of the updated `origin/master` by:
+
+    $ fork_point=$(git merge-base --fork-point origin/master topic)
+    $ git rebase --onto origin/master $fork_point topic
+
+
 See also
 --------
 linkgit:git-rev-list[1],