diff options
| author |  Junio C Hamano <junkio@cox.net> | 2005-08-24 16:23:08 -0700 |
|---|---|---|
| committer | Junio C Hamano <junkio@cox.net> | 2005-08-24 16:50:54 -0700 |
| commit | ab9b31386b494b6c16d651d1560f3ba11c3a1964 (patch) | |
| tree | b236326ca11e2180a58dd15cbde457871bb56244 | |
| parent | Support +<src>:<dst> format in push as well. (diff) | |
| download | tgif-ab9b31386b494b6c16d651d1560f3ba11c3a1964.tar.xz | |
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>
| -rw-r--r-- | Documentation/git-fetch-script.txt | 23 | ||||
| -rw-r--r-- | Documentation/git-octopus-script.txt | 39 | ||||
| -rw-r--r-- | Documentation/git-pull-script.txt | 9 | ||||
| -rw-r--r-- | Documentation/git-push-script.txt | 14 | ||||
| -rw-r--r-- | Documentation/git-resolve-script.txt | 14 | ||||
| -rw-r--r-- | Documentation/git-send-pack.txt | 37 | ||||
| -rw-r--r-- | Documentation/git.txt | 17 | ||||
| -rw-r--r-- | Documentation/pull-fetch-param.txt | 80 |
8 files changed, 170 insertions, 63 deletions
diff --git a/Documentation/git-fetch-script.txt b/Documentation/git-fetch-script.txt index db3086c732..d15222b561 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 @@ 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 index 0000000000..f7a073d4f9 --- /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 ad9d3ab315..8111813b85 100644 --- 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 index 3c1208d5a2..556682f991 100644 --- 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 index 99c399a073..77076aa90d 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 6192c5dc41..5ed25f54d1 100644 --- 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 index d133250635..664b88a917 100644 --- 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 index 7ae4ba0bd8..ea0ad2c48f 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. - -<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. |