From ab9b31386b494b6c16d651d1560f3ba11c3a1964 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Wed, 24 Aug 2005 16:23:08 -0700 Subject: Documentation: multi-head fetch. Add documentation related to multi-head work, including $GIT_DIR/remotes/ changes. Signed-off-by: Junio C Hamano --- Documentation/git-fetch-script.txt | 23 ++++------- Documentation/git-octopus-script.txt | 39 ++++++++++++++++++ Documentation/git-pull-script.txt | 9 ++-- Documentation/git-push-script.txt | 14 +++---- Documentation/git-resolve-script.txt | 14 +++++-- Documentation/git-send-pack.txt | 37 +++++++++++++---- Documentation/git.txt | 17 ++++---- Documentation/pull-fetch-param.txt | 80 ++++++++++++++++++++++++++++-------- 8 files changed, 170 insertions(+), 63 deletions(-) create mode 100644 Documentation/git-octopus-script.txt 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' [ | tag ] +'git-fetch-script' ... 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 is specified, the fetched from the remote is -also copied to the local $GIT_DIR/tags/ file. When no - nor is specified, and 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/ -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: + +------------------------------------------------ + from +------------------------------------------------ + +Using this information, create and commit an Octopus merge on +top of the current HEAD. + + +Author +------ +Written by Junio C Hamano + + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list . + +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' [ | tag ] +'git-pull-script' ... 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 ] ... +'git-push-script' [--all] [--force] ... 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. - -...:: - 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' DESCRIPTION ----------- -This script is used by Linus to merge two trees. +Given two commits and a merge message, merge the commit +into commit, with the commit log message . + +When is a descendant of , or is an +ancestor of , no new commit is created and the +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-send-pack' [--all] [--force] [--exec=] [:] [...] 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. + :: A remote host to house the repository. When this part is specified, 'git-receive-pack' is invoked via @@ -37,7 +44,7 @@ OPTIONS :: The repository to update. -...: +...: 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 '' if you use +the remote side. You cannot specify any '' if you use this flag. -Without '--all' and without any '', the refs that exist +Without '--all' and without any '', the refs that exist both on the local side and on the remote side are updated. -When ''s are specified explicitly, it can be either a +When ''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 '' is just a shorthand for ':'. + 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 does not match exactly one of local - refs. + - It is an error if does not match exactly one of the + local refs. - It is an error if matches more than one remote refs. @@ -78,6 +86,17 @@ destination side. exist in the set of remote refs; the ref matched locally is used as the name of the destination. +Without '--force', the ref is stored at the remote only if + does not exist, or is a proper subset (i.e. an +ancestor) of . 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 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. - -:: - The remote head name to fetch from. That is, make the - objects reachable from the commit recorded in - $GIT_DIR/refs/heads/ in the remote repository - available locally. - -tag :: - The remote head tag to fetch from. That is, make the - objects reachable from the commit recorded in - $GIT_DIR/refs/tags/ 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: ... + Pull: ... + + When such a short-hand is specified in place of + without parameters on the command + line, ... 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/ file that stores a + without the fragment is equivalent to have this in the + corresponding file in the $GIT_DIR/remotes/ directory + + URL: + Pull: refs/heads/master: + + while having # is equivalent to + + URL: + Pull: refs/heads/: + +:: + The canonical format of a parameter is + +?:; 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 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 is used + to fast forward the remote ref that matches . 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 + is fetched, and if is not empty string, the local + ref that matches it is fast forwarded using . + 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 to mean a + refspec "refs/tags/:refs/tags/". + + * A parameter without a colon is equivalent to + : when pulling/fetching, and : when + pushing. That is, do not store it locally if + fetching, and update the same name if pushing. -- cgit v1.2.3