Documentation: multi-head fetch.
Add documentation related to multi-head work, including $GIT_DIR/remotes/
changes.
Signed-off-by: Junio C Hamano <junkio@cox.net>
diff --git a/Documentation/git-fetch-script.txt b/Documentation/git-fetch-script.txt
index db3086c..d15222b 100644
--- 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 @@
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.
+Fetches named heads or tags from another repository, along with
+the objects necessary to complete them.
-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.
+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
new file mode 100644
index 0000000..f7a073d
--- /dev/null
+++ 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
index ad9d3ab..8111813 100644
--- a/Documentation/git-pull-script.txt
+++ b/Documentation/git-pull-script.txt
@@ -9,13 +9,16 @@
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
index 3c1208d..556682f 100644
--- a/Documentation/git-push-script.txt
+++ b/Documentation/git-push-script.txt
@@ -3,25 +3,23 @@
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
index 99c399a..77076aa 100644
--- 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
index 6192c5d..5ed25f5 100644
--- a/Documentation/git-send-pack.txt
+++ b/Documentation/git-send-pack.txt
@@ -9,12 +9,12 @@
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 @@
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 @@
<directory>::
The repository to update.
-<head>...:
+<ref>...:
The remote refs to update.
@@ -48,24 +55,25 @@
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 @@
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
index d133250..664b88a 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -208,7 +208,16 @@
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-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-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
index 7ae4ba0..ea0ad2c 100644
--- 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.
+ 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:
-<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.
+ URL: one of the above URL format
+ Push: <refspec>...
+ Pull: <refspec>...
-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.
+ 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.
