diff options
Diffstat (limited to 'Documentation/pull-fetch-param.adoc')
| -rw-r--r-- | Documentation/pull-fetch-param.adoc | 51 |
1 files changed, 26 insertions, 25 deletions
diff --git a/Documentation/pull-fetch-param.adoc b/Documentation/pull-fetch-param.adoc index d79d2f6065..d903dc8900 100644 --- a/Documentation/pull-fetch-param.adoc +++ b/Documentation/pull-fetch-param.adoc @@ -1,19 +1,20 @@ -<repository>:: +_<repository>_:: The "remote" repository that is the source of a fetch or pull operation. This parameter can be either a URL (see the section <<URLS,GIT URLS>> below) or the name of a remote (see the section <<REMOTES,REMOTES>> below). ifndef::git-pull[] -<group>:: +_<group>_:: A name referring to a list of repositories as the value - of remotes.<group> in the configuration file. + of `remotes.<group>` in the configuration file. (See linkgit:git-config[1]). endif::git-pull[] -<refspec>:: +[[fetch-refspec]] +_<refspec>_:: Specifies which refs to fetch and which local refs to update. - When no <refspec>s appear on the command line, the refs to fetch + When no __<refspec>__s appear on the command line, the refs to fetch are read from `remote.<repository>.fetch` variables instead ifndef::git-pull[] (see <<CRTB,CONFIGURED REMOTE-TRACKING BRANCHES>> below). @@ -23,18 +24,18 @@ ifdef::git-pull[] in linkgit:git-fetch[1]). endif::git-pull[] + -The format of a <refspec> parameter is an optional plus -`+`, followed by the source <src>, followed -by a colon `:`, followed by the destination <dst>. -The colon can be omitted when <dst> is empty. <src> is +The format of a _<refspec>_ parameter is an optional plus +`+`, followed by the source _<src>_, followed +by a colon `:`, followed by the destination _<dst>_. +The colon can be omitted when _<dst>_ is empty. _<src>_ is typically a ref, or a glob pattern with a single `*` that is used to match a set of refs, but it can also be a fully spelled hex object name. + -A <refspec> may contain a `*` in its <src> to indicate a simple pattern +A _<refspec>_ may contain a `*` in its _<src>_ to indicate a simple pattern match. Such a refspec functions like a glob that matches any ref with the -pattern. A pattern <refspec> must have one and only one `*` in both the <src> and -<dst>. It will map refs to the destination by replacing the `*` with the +pattern. A pattern _<refspec>_ must have one and only one `*` in both the _<src>_ and +_<dst>_. It will map refs to the destination by replacing the `*` with the contents matched from the source. + If a refspec is prefixed by `^`, it will be interpreted as a negative @@ -44,14 +45,14 @@ considered to match if it matches at least one positive refspec, and does not match any negative refspec. Negative refspecs can be useful to restrict the scope of a pattern refspec so that it will not include specific refs. Negative refspecs can themselves be pattern refspecs. However, they may only -contain a <src> and do not specify a <dst>. Fully spelled out hex object +contain a _<src>_ and do not specify a _<dst>_. Fully spelled out hex object names are also not supported. + `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`; it requests fetching everything up to the given tag. + -The remote ref that matches <src> -is fetched, and if <dst> is not an empty string, an attempt +The remote ref that matches _<src>_ +is fetched, and if _<dst>_ is not an empty string, an attempt is made to update the local ref that matches it. + Whether that update is allowed without `--force` depends on the ref @@ -59,7 +60,7 @@ namespace it's being fetched to, the type of object being fetched, and whether the update is considered to be a fast-forward. Generally, the same rules apply for fetching as when pushing, see the `<refspec>...` section of linkgit:git-push[1] for what those are. Exceptions to those -rules particular to 'git fetch' are noted below. +rules particular to `git fetch` are noted below. + Until Git version 2.20, and unlike when pushing with linkgit:git-push[1], any updates to `refs/tags/*` would be accepted @@ -100,19 +101,19 @@ must know this is the expected usage pattern for a branch. ifdef::git-pull[] + [NOTE] -There is a difference between listing multiple <refspec> -directly on 'git pull' command line and having multiple +There is a difference between listing multiple _<refspec>_ +directly on `git pull` command line and having multiple `remote.<repository>.fetch` entries in your configuration -for a <repository> and running a -'git pull' command without any explicit <refspec> parameters. -<refspec>s listed explicitly on the command line are always +for a _<repository>_ and running a +`git pull` command without any explicit _<refspec>_ parameters. +__<refspec>__s listed explicitly on the command line are always merged into the current branch after fetching. In other words, -if you list more than one remote ref, 'git pull' will create +if you list more than one remote ref, `git pull` will create an Octopus merge. On the other hand, if you do not list any -explicit <refspec> parameter on the command line, 'git pull' -will fetch all the <refspec>s it finds in the +explicit _<refspec>_ parameter on the command line, `git pull` +will fetch all the __<refspec>__s it finds in the `remote.<repository>.fetch` configuration and merge -only the first <refspec> found into the current branch. +only the first _<refspec>_ found into the current branch. This is because making an Octopus from remote refs is rarely done, while keeping track of multiple remote heads in one-go by fetching more than one |