Documentation: multi-head fetch.

Junio C Hamano · Junio C Hamano · commit ab9b31386b49 · 2005-08-24T16:50:54.000-07:00
Add documentation related to multi-head work, including $GIT_DIR/remotes/
changes.

Signed-off-by: Junio C Hamano &lt;junkio@cox.net&gt;
diff --git a/Documentation/git-fetch-script.txt b/Documentation/git-fetch-script.txt
@@ -1,6 +1,6 @@
 git-fetch-script(1)
 ===================
-v0.99.4, Aug 2005
+v0.99.5, Aug 2005
 
 NAME
 ----
@@ -9,24 +9,17 @@ git-fetch-script - Download objects and a head from another repository.
 
 SYNOPSIS
 --------
-'git-fetch-script' <repository> [ <head> | tag <tag> ]
+'git-fetch-script' <repository> <refspec>...
 
 
 DESCRIPTION
 -----------
-Fetches a named head or a tag from another repository, along
-with the objects necessary to complete that head or tag.  The
-head to pull defaults to HEAD if unspecified.  The head or tag
-fetched from the remote repository is stored in
-$GIT_DIR/FETCH_HEAD.
-
-When a <tag> is specified, the <tag> fetched from the remote is
-also copied to the local $GIT_DIR/tags/<tag> file.  When no
-<head> nor <tag> is specified, and <repository> was specified
-with the short-hand notation (i.e. naming a file under the
-$GIT_DIR/branches directory), the head fetched from the remote
-repository is also copied to the local $GIT_DIR/heads/<repository>
-file.
+Fetches named heads or tags from another repository, along with
+the objects necessary to complete them.
+
+The ref names and their object names of fetched refs are stored
+in $GIT_DIR/FETCH_HEAD.  This information is left for a later merge
+operation done by "git resolve" or "git octopus".
 
 
 OPTIONS
diff --git a/Documentation/git-octopus-script.txt b/Documentation/git-octopus-script.txt
@@ -0,0 +1,39 @@
+git-octopus-script(1)
+=====================
+v0.99.5, Aug 2005
+
+NAME
+----
+git-octopus-script - Merge more than two commits.
+
+
+SYNOPSIS
+--------
+'git-octopus'
+
+DESCRIPTION
+-----------
+After running 'git fetch', $GIT_DIR/FETCH_HEAD contains the
+following information, one line per remote ref:
+
+------------------------------------------------
+<object name>	<ref name> from <repository>
+------------------------------------------------
+
+Using this information, create and commit an Octopus merge on
+top of the current HEAD.
+
+
+Author
+------
+Written by Junio C Hamano <junkio@cox.net>
+
+
+Documentation
+--------------
+Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the link:git.html[git] suite
+
diff --git a/Documentation/git-pull-script.txt b/Documentation/git-pull-script.txt
@@ -9,13 +9,16 @@ git-pull-script - Pull and merge from another repository.
 
 SYNOPSIS
 --------
-'git-pull-script' <repository> [ <head> | tag <tag> ]
+'git-pull-script' <repository> <refspec>...
 
 
 DESCRIPTION
 -----------
-Runs 'git-fetch-script' with the given parameters, then
-'git-resolve-script' to merge the local HEAD and FETCH_HEAD.
+Runs 'git-fetch-script' with the given parameters.
+
+When only one ref is downloaded, runs 'git resolve' to merge it
+into the local HEAD.  Otherwise uses 'git octopus' to merge them
+into the local HEAD.
 
 
 OPTIONS
diff --git a/Documentation/git-push-script.txt b/Documentation/git-push-script.txt
@@ -3,25 +3,23 @@ git-push-script(1)
 
 NAME
 ----
-git-push-script - Some git command not yet documented.
+git-push-script - Update remote refs along with associated objects.
 
 
 SYNOPSIS
 --------
-'git-push-script' [ --option ] <args>...
+'git-push-script' [--all] [--force] <repository> <refspec>...
 
 DESCRIPTION
 -----------
-Does something not yet documented.
+
+Updates remote refs using local refs, while sending objects
+necessary to complete the given refs.
 
 
 OPTIONS
 -------
---option::
-	Some option not yet documented.
-
-<args>...::
-	Some argument not yet documented.
+include::pull-fetch-param.txt[]
 
 
 Author
diff --git a/Documentation/git-resolve-script.txt b/Documentation/git-resolve-script.txt
@@ -1,19 +1,25 @@
 git-resolve-script(1)
 =====================
-v0.99.4, Aug 2005
+v0.99.5, Aug 2005
 
 NAME
 ----
-git-resolve-script - Script used to merge two trees
+git-resolve-script - Merge two commits
 
 
 SYNOPSIS
 --------
-'git-resolve-script'
+'git resolve' <current> <merged> <message>
 
 DESCRIPTION
 -----------
-This script is used by Linus to merge two trees.
+Given two commits and a merge message, merge the <merged> commit
+into <current> commit, with the commit log message <message>.
+
+When <current> is a descendant of <merged>, or <current> is an
+ancestor of <merged>, no new commit is created and the <message>
+is ignored.  The former is informally called "already up to
+date", and the latter is often called "fast forward".
 
 
 Author
diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt
@@ -9,12 +9,12 @@ git-send-pack - Push missing objects packed.
 
 SYNOPSIS
 --------
-'git-send-pack' [--all] [--exec=<git-receive-pack>] [<host>:]<directory> [<head>...]
+'git-send-pack' [--all] [--force] [--exec=<git-receive-pack>] [<host>:]<directory> [<ref>...]
 
 DESCRIPTION
 -----------
 Invokes 'git-receive-pack' on a possibly remote repository, and
-updates it from the current repository, sending named heads.
+updates it from the current repository, sending named refs.
 
 
 OPTIONS
@@ -29,6 +29,13 @@ OPTIONS
 	Instead of explicitly specifying which refs to update,
 	update all refs that locally exist.
 
+--force::
+	Usually, the command refuses to update a remote ref that
+	is not an ancestor of the local ref used to overwrite it.
+	This flag disables the check.  What this means is that
+	the remote repository can lose commits; use it with
+	care.
+
 <host>::
 	A remote host to house the repository.  When this
 	part is specified, 'git-receive-pack' is invoked via
@@ -37,7 +44,7 @@ OPTIONS
 <directory>::
 	The repository to update.
 
-<head>...:
+<ref>...:
 	The remote refs to update.
 
 
@@ -48,24 +55,25 @@ There are three ways to specify which refs to update on the
 remote end.
 
 With '--all' flag, all refs that exist locally are transfered to
-the remote side.  You cannot specify any '<head>' if you use
+the remote side.  You cannot specify any '<ref>' if you use
 this flag.
 
-Without '--all' and without any '<head>', the refs that exist
+Without '--all' and without any '<ref>', the refs that exist
 both on the local side and on the remote side are updated.
 
-When '<head>'s are specified explicitly, it can be either a
+When '<ref>'s are specified explicitly, it can be either a
 single pattern, or a pair of such pattern separated by a colon
 ':' (this means that a ref name cannot have a colon in it).  A
 single pattern '<name>' is just a shorthand for '<name>:<name>'.
+
 Each pattern pair consists of the source side (before the colon)
-and the destination side (after the colon).  The ref that is
+and the destination side (after the colon).  The ref to be
 pushed is determined by finding a match that matches the source
 side, and where it is pushed is determined by using the
 destination side.
 
- - It is an error if <src> does not match exactly one of local
-   refs.
+ - It is an error if <src> does not match exactly one of the
+   local refs.
 
  - It is an error if <dst> matches more than one remote refs.
 
@@ -78,6 +86,17 @@ destination side.
      exist in the set of remote refs; the ref matched <src>
      locally is used as the name of the destination.
 
+Without '--force', the <src> ref is stored at the remote only if
+<dst> does not exist, or <dst> is a proper subset (i.e. an
+ancestor) of <src>.  This check, known as "fast forward check",
+is performed in order to avoid accidentally overwriting the
+remote ref and lose other peoples' commits from there.
+
+With '--force', the fast forward check is disabled for all refs.
+
+Optionally, a <ref> parameter can be prefixed with a plus '+' sign
+to disable the fast-forward check only on that ref.
+
 
 Author
 ------
diff --git a/Documentation/git.txt b/Documentation/git.txt
@@ -208,7 +208,16 @@ link:git-fetch-script.html[git-fetch-script]::
 link:git-pull-script.html[git-pull-script]::
 	Fetch from and merge with a remote repository.
 
-ulink:git-commit-script.html[git-commit-script]::
+link:git-resolve-script.html[git-resolve-script]::
+	Merge two commits.
+
+link:git-octopus-script.html[git-octopus-script]::
+	Merge more than two commits.
+
+link:git-push-script.html[git-push-script]::
+	Update remote refs along with associated objects.
+
+link:git-commit-script.html[git-commit-script]::
 	Record changes to the repository.
 
 link:git-show-branch.html[git-show-branch]::
@@ -240,9 +249,6 @@ link:git-merge-one-file-script.html[git-merge-one-file-script]::
 link:git-prune-script.html[git-prune-script]::
 	Prunes all unreachable objects from the object database
 
-link:git-resolve-script.html[git-resolve-script]::
-	Script used to merge two trees
-
 link:git-tag-script.html[git-tag-script]::
 	An example script to create a tag object signed with GPG
 
@@ -316,9 +322,6 @@ link:git-get-tar-commit-id.html[git-get-tar-commit-id]::
 link:git-patch-id.html[git-patch-id]::
 	git-patch-id.
 
-link:git-push-script.html[git-push-script]::
-	git-push-script.
-
 link:git-rebase-script.html[git-rebase-script]::
 	git-rebase-script.
 
diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt
@@ -16,21 +16,67 @@
 		Local directory
 			/path/to/repo.git/
 
-	In addition to that, as a short-hand, the name of a file
-	in $GIT_DIR/branches directory can be specified; the
-	named file should contain a single line, a URL in one of
-	the above formats, optionally followed by a hash '#' and
-	the name of remote head.
-
-<head>::
-	The remote head name to fetch from.  That is, make the
-	objects reachable from the commit recorded in
-	$GIT_DIR/refs/heads/<head> in the remote repository
-	available locally.
-
-tag <tag>::
-	The remote head tag to fetch from.  That is, make the
-	objects reachable from the commit recorded in
-	$GIT_DIR/refs/tags/<tag> in the remote repository
-	available locally.
+	In addition to the above, as a short-hand, the name of a
+	file in $GIT_DIR/remotes directory can be given; the
+	named file should be in the following format:
 
+		URL: one of the above URL format
+		Push: <refspec>...
+		Pull: <refspec>...
+
+	When such a short-hand is specified in place of
+	<repository> without <refspec> parameters on the command
+	line, <refspec>... specified on Push lines or Pull lines
+	are used for "git push" and "git fetch/pull",
+	respectively.
+
+	The name of a file in $GIT_DIR/branches directory can be
+	specified as an older notation short-hand; the named
+	file should contain a single line, a URL in one of the
+	above formats, optionally followed by a hash '#' and the
+	name of remote head (URL fragment notation).
+	$GIT_DIR/branches/<remote> file that stores a <url>
+	without the fragment is equivalent to have this in the
+	corresponding file in the $GIT_DIR/remotes/ directory
+
+		URL: <url>
+		Pull: refs/heads/master:<remote>
+
+	while having <url>#<head> is equivalent to
+
+		URL: <url>
+		Pull: refs/heads/<head>:<remote>
+
+<refspec>::
+	The canonical format of a <refspec> parameter is
+	+?<src>:<dst>; that is, an optional plus '+', followed
+	by the source ref, followed by a colon ':', followed by
+	the destination ref.
+
+	When used in "git push", the <src> side can be an
+	arbitrary "SHA1 expression" that can be used as an
+	argument to "git-cat-file -t".  E.g. "master~4" (push
+	four parents before the current master head).
+
+        For "git push", the local ref that matches <src> is used
+        to fast forward the remote ref that matches <dst>.  If
+        the optional plus '+' is used, the remote ref is updated
+        even if it does not result in a fast forward update.
+
+	For "git fetch/pull", the remote ref that matches <src>
+	is fetched, and if <dst> is not empty string, the local
+	ref that matches it is fast forwarded using <src>.
+	Again, if the optional plus '+' is used, the local ref
+	is updated even if it does not result in a fast forward
+	update.
+
+	Some short-cut notations are also supported.
+
+	* For backward compatibility, "tag" is almost ignored;
+          it just makes the following parameter <tag> to mean a
+          refspec "refs/tags/<tag>:refs/tags/<tag>".
+
+        * A parameter <ref> without a colon is equivalent to
+          <ref>: when pulling/fetching, and <ref>:<ref> when
+          pushing.  That is, do not store it locally if
+          fetching, and update the same name if pushing.
