Documentation: multi-head fetch.
authorJunio C Hamano <junkio@cox.net>
Wed, 24 Aug 2005 23:23:08 +0000 (16:23 -0700)
committerJunio C Hamano <junkio@cox.net>
Wed, 24 Aug 2005 23:50:54 +0000 (16:50 -0700)
Add documentation related to multi-head work, including $GIT_DIR/remotes/
changes.

Signed-off-by: Junio C Hamano <junkio@cox.net>
Documentation/git-fetch-script.txt
Documentation/git-octopus-script.txt [new file with mode: 0644]
Documentation/git-pull-script.txt
Documentation/git-push-script.txt
Documentation/git-resolve-script.txt
Documentation/git-send-pack.txt
Documentation/git.txt
Documentation/pull-fetch-param.txt
index db3086c7329bdbcad32b81e9f5c7ad23d6cca0b1..d15222b5619fbf0fae24f4aac764b6de0c29817c 100644 (file)
@@ -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
new file mode 100644 (file)
index 0000000..f7a073d
--- /dev/null
@@ -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
+
index ad9d3ab31534ab2f71bb791eb96970c7048ac843..8111813b857ff0a18bd02ab72c407c5a937dccc7 100644 (file)
@@ -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
index 3c1208d5a24a5c493ecd85382d13a8a860d70331..556682f991d612ca3a277e640c0f8d6d2e205c49 100644 (file)
@@ -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
index 99c399a073cd9cd69783312a6930f3fb2cca55f0..77076aa90dea8e7080ccdb5e0b64845018604ac7 100644 (file)
@@ -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
index 6192c5dc41e57a33afc203fab46940fa4596ba26..5ed25f54d1a68c3cf3c43d7189337106519a1131 100644 (file)
@@ -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
 ------
index d13325063520ca005765a4769c71321950b5dd8a..664b88a917c65389e3ea9702ca1398f591f29a42 100644 (file)
@@ -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.
 
index 7ae4ba0bd895dbc1adc94d893cf8b5aa8d29a108..ea0ad2c48f56211139d9b0e3100bf975f0be7e87 100644 (file)
                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.