Documentation/fetch-options.txt

   1 --all::
   2         Fetch all remotes.
   3
   4 -a::
   5 --append::
   6         Append ref names and object names of fetched refs to the
   7         existing contents of `.git/FETCH_HEAD`.  Without this
   8         option old data in `.git/FETCH_HEAD` will be overwritten.
   9
  10 --atomic::
  11         Use an atomic transaction to update local refs. Either all refs are
  12         updated, or on error, no refs are updated.
  13
  14 --depth=<depth>::
  15         Limit fetching to the specified number of commits from the tip of
  16         each remote branch history. If fetching to a 'shallow' repository
  17         created by `git clone` with `--depth=<depth>` option (see
  18         linkgit:git-clone[1]), deepen or shorten the history to the specified
  19         number of commits. Tags for the deepened commits are not fetched.
  20
  21 --deepen=<depth>::
  22         Similar to --depth, except it specifies the number of commits
  23         from the current shallow boundary instead of from the tip of
  24         each remote branch history.
  25
  26 --shallow-since=<date>::
  27         Deepen or shorten the history of a shallow repository to
  28         include all reachable commits after <date>.
  29
  30 --shallow-exclude=<revision>::
  31         Deepen or shorten the history of a shallow repository to
  32         exclude commits reachable from a specified remote branch or tag.
  33         This option can be specified multiple times.
  34
  35 --unshallow::
  36         If the source repository is complete, convert a shallow
  37         repository to a complete one, removing all the limitations
  38         imposed by shallow repositories.
  39 +
  40 If the source repository is shallow, fetch as much as possible so that
  41 the current repository has the same history as the source repository.
  42
  43 --update-shallow::
  44         By default when fetching from a shallow repository,
  45         `git fetch` refuses refs that require updating
  46         .git/shallow. This option updates .git/shallow and accepts such
  47         refs.
  48
  49 --negotiation-tip=<commit|glob>::
  50         By default, Git will report, to the server, commits reachable
  51         from all local refs to find common commits in an attempt to
  52         reduce the size of the to-be-received packfile. If specified,
  53         Git will only report commits reachable from the given tips.
  54         This is useful to speed up fetches when the user knows which
  55         local ref is likely to have commits in common with the
  56         upstream ref being fetched.
  57 +
  58 This option may be specified more than once; if so, Git will report
  59 commits reachable from any of the given commits.
  60 +
  61 The argument to this option may be a glob on ref names, a ref, or the (possibly
  62 abbreviated) SHA-1 of a commit. Specifying a glob is equivalent to specifying
  63 this option multiple times, one for each matching ref name.
  64 +
  65 See also the `fetch.negotiationAlgorithm` and `push.negotiate`
  66 configuration variables documented in linkgit:git-config[1], and the
  67 `--negotiate-only` option below.
  68
  69 --negotiate-only::
  70         Do not fetch anything from the server, and instead print the
  71         ancestors of the provided `--negotiation-tip=*` arguments,
  72         which we have in common with the server.
  73 +
  74 This is incompatible with `--recurse-submodules=[yes|on-demand]`.
  75 Internally this is used to implement the `push.negotiate` option, see
  76 linkgit:git-config[1].
  77
  78 --dry-run::
  79         Show what would be done, without making any changes.
  80
  81 --porcelain::
  82         Print the output to standard output in an easy-to-parse format for
  83         scripts. See section OUTPUT in linkgit:git-fetch[1] for details.
  84 +
  85 This is incompatible with `--recurse-submodules=[yes|on-demand]` and takes
  86 precedence over the `fetch.output` config option.
  87
  88 ifndef::git-pull[]
  89 --[no-]write-fetch-head::
  90         Write the list of remote refs fetched in the `FETCH_HEAD`
  91         file directly under `$GIT_DIR`.  This is the default.
  92         Passing `--no-write-fetch-head` from the command line tells
  93         Git not to write the file.  Under `--dry-run` option, the
  94         file is never written.
  95 endif::git-pull[]
  96
  97 -f::
  98 --force::
  99         When 'git fetch' is used with `<src>:<dst>` refspec, it may
 100         refuse to update the local branch as discussed
 101 ifdef::git-pull[]
 102         in the `<refspec>` part of the linkgit:git-fetch[1]
 103         documentation.
 104 endif::git-pull[]
 105 ifndef::git-pull[]
 106         in the `<refspec>` part below.
 107 endif::git-pull[]
 108         This option overrides that check.
 109
 110 -k::
 111 --keep::
 112         Keep downloaded pack.
 113
 114 ifndef::git-pull[]
 115 --multiple::
 116         Allow several <repository> and <group> arguments to be
 117         specified. No <refspec>s may be specified.
 118
 119 --[no-]auto-maintenance::
 120 --[no-]auto-gc::
 121         Run `git maintenance run --auto` at the end to perform automatic
 122         repository maintenance if needed. (`--[no-]auto-gc` is a synonym.)
 123         This is enabled by default.
 124
 125 --[no-]write-commit-graph::
 126         Write a commit-graph after fetching. This overrides the config
 127         setting `fetch.writeCommitGraph`.
 128 endif::git-pull[]
 129
 130 --prefetch::
 131         Modify the configured refspec to place all refs into the
 132         `refs/prefetch/` namespace. See the `prefetch` task in
 133         linkgit:git-maintenance[1].
 134
 135 -p::
 136 --prune::
 137         Before fetching, remove any remote-tracking references that no
 138         longer exist on the remote.  Tags are not subject to pruning
 139         if they are fetched only because of the default tag
 140         auto-following or due to a --tags option.  However, if tags
 141         are fetched due to an explicit refspec (either on the command
 142         line or in the remote configuration, for example if the remote
 143         was cloned with the --mirror option), then they are also
 144         subject to pruning. Supplying `--prune-tags` is a shorthand for
 145         providing the tag refspec.
 146 ifndef::git-pull[]
 147 +
 148 See the PRUNING section below for more details.
 149
 150 -P::
 151 --prune-tags::
 152         Before fetching, remove any local tags that no longer exist on
 153         the remote if `--prune` is enabled. This option should be used
 154         more carefully, unlike `--prune` it will remove any local
 155         references (local tags) that have been created. This option is
 156         a shorthand for providing the explicit tag refspec along with
 157         `--prune`, see the discussion about that in its documentation.
 158 +
 159 See the PRUNING section below for more details.
 160
 161 endif::git-pull[]
 162
 163 ifndef::git-pull[]
 164 -n::
 165 endif::git-pull[]
 166 --no-tags::
 167         By default, tags that point at objects that are downloaded
 168         from the remote repository are fetched and stored locally.
 169         This option disables this automatic tag following. The default
 170         behavior for a remote may be specified with the remote.<name>.tagOpt
 171         setting. See linkgit:git-config[1].
 172
 173 ifndef::git-pull[]
 174 --refetch::
 175         Instead of negotiating with the server to avoid transferring commits and
 176         associated objects that are already present locally, this option fetches
 177         all objects as a fresh clone would. Use this to reapply a partial clone
 178         filter from configuration or using `--filter=` when the filter
 179         definition has changed. Automatic post-fetch maintenance will perform
 180         object database pack consolidation to remove any duplicate objects.
 181 endif::git-pull[]
 182
 183 --refmap=<refspec>::
 184         When fetching refs listed on the command line, use the
 185         specified refspec (can be given more than once) to map the
 186         refs to remote-tracking branches, instead of the values of
 187         `remote.*.fetch` configuration variables for the remote
 188         repository.  Providing an empty `<refspec>` to the
 189         `--refmap` option causes Git to ignore the configured
 190         refspecs and rely entirely on the refspecs supplied as
 191         command-line arguments. See section on "Configured Remote-tracking
 192         Branches" for details.
 193
 194 -t::
 195 --tags::
 196         Fetch all tags from the remote (i.e., fetch remote tags
 197         `refs/tags/*` into local tags with the same name), in addition
 198         to whatever else would otherwise be fetched.  Using this
 199         option alone does not subject tags to pruning, even if --prune
 200         is used (though tags may be pruned anyway if they are also the
 201         destination of an explicit refspec; see `--prune`).
 202
 203 ifndef::git-pull[]
 204 --recurse-submodules[=yes|on-demand|no]::
 205         This option controls if and under what conditions new commits of
 206         submodules should be fetched too. When recursing through submodules,
 207         `git fetch` always attempts to fetch "changed" submodules, that is, a
 208         submodule that has commits that are referenced by a newly fetched
 209         superproject commit but are missing in the local submodule clone. A
 210         changed submodule can be fetched as long as it is present locally e.g.
 211         in `$GIT_DIR/modules/` (see linkgit:gitsubmodules[7]); if the upstream
 212         adds a new submodule, that submodule cannot be fetched until it is
 213         cloned e.g. by `git submodule update`.
 214 +
 215 When set to 'on-demand', only changed submodules are fetched. When set
 216 to 'yes', all populated submodules are fetched and submodules that are
 217 both unpopulated and changed are fetched. When set to 'no', submodules
 218 are never fetched.
 219 +
 220 When unspecified, this uses the value of `fetch.recurseSubmodules` if it
 221 is set (see linkgit:git-config[1]), defaulting to 'on-demand' if unset.
 222 When this option is used without any value, it defaults to 'yes'.
 223 endif::git-pull[]
 224
 225 -j::
 226 --jobs=<n>::
 227         Number of parallel children to be used for all forms of fetching.
 228 +
 229 If the `--multiple` option was specified, the different remotes will be fetched
 230 in parallel. If multiple submodules are fetched, they will be fetched in
 231 parallel. To control them independently, use the config settings
 232 `fetch.parallel` and `submodule.fetchJobs` (see linkgit:git-config[1]).
 233 +
 234 Typically, parallel recursive and multi-remote fetches will be faster. By
 235 default fetches are performed sequentially, not in parallel.
 236
 237 ifndef::git-pull[]
 238 --no-recurse-submodules::
 239         Disable recursive fetching of submodules (this has the same effect as
 240         using the `--recurse-submodules=no` option).
 241 endif::git-pull[]
 242
 243 --set-upstream::
 244         If the remote is fetched successfully, add upstream
 245         (tracking) reference, used by argument-less
 246         linkgit:git-pull[1] and other commands. For more information,
 247         see `branch.<name>.merge` and `branch.<name>.remote` in
 248         linkgit:git-config[1].
 249
 250 ifndef::git-pull[]
 251 --submodule-prefix=<path>::
 252         Prepend <path> to paths printed in informative messages
 253         such as "Fetching submodule foo".  This option is used
 254         internally when recursing over submodules.
 255
 256 --recurse-submodules-default=[yes|on-demand]::
 257         This option is used internally to temporarily provide a
 258         non-negative default value for the --recurse-submodules
 259         option.  All other methods of configuring fetch's submodule
 260         recursion (such as settings in linkgit:gitmodules[5] and
 261         linkgit:git-config[1]) override this option, as does
 262         specifying --[no-]recurse-submodules directly.
 263
 264 -u::
 265 --update-head-ok::
 266         By default 'git fetch' refuses to update the head which
 267         corresponds to the current branch.  This flag disables the
 268         check.  This is purely for the internal use for 'git pull'
 269         to communicate with 'git fetch', and unless you are
 270         implementing your own Porcelain you are not supposed to
 271         use it.
 272 endif::git-pull[]
 273
 274 --upload-pack <upload-pack>::
 275         When given, and the repository to fetch from is handled
 276         by 'git fetch-pack', `--exec=<upload-pack>` is passed to
 277         the command to specify non-default path for the command
 278         run on the other end.
 279
 280 ifndef::git-pull[]
 281 -q::
 282 --quiet::
 283         Pass --quiet to git-fetch-pack and silence any other internally
 284         used git commands. Progress is not reported to the standard error
 285         stream.
 286
 287 -v::
 288 --verbose::
 289         Be verbose.
 290 endif::git-pull[]
 291
 292 --progress::
 293         Progress status is reported on the standard error stream
 294         by default when it is attached to a terminal, unless -q
 295         is specified. This flag forces progress status even if the
 296         standard error stream is not directed to a terminal.
 297
 298 -o <option>::
 299 --server-option=<option>::
 300         Transmit the given string to the server when communicating using
 301         protocol version 2.  The given string must not contain a NUL or LF
 302         character.  The server's handling of server options, including
 303         unknown ones, is server-specific.
 304         When multiple `--server-option=<option>` are given, they are all
 305         sent to the other side in the order listed on the command line.
 306
 307 --show-forced-updates::
 308         By default, git checks if a branch is force-updated during
 309         fetch. This can be disabled through fetch.showForcedUpdates, but
 310         the --show-forced-updates option guarantees this check occurs.
 311         See linkgit:git-config[1].
 312
 313 --no-show-forced-updates::
 314         By default, git checks if a branch is force-updated during
 315         fetch. Pass --no-show-forced-updates or set fetch.showForcedUpdates
 316         to false to skip this check for performance reasons. If used during
 317         'git-pull' the --ff-only option will still check for forced updates
 318         before attempting a fast-forward update. See linkgit:git-config[1].
 319
 320 -4::
 321 --ipv4::
 322         Use IPv4 addresses only, ignoring IPv6 addresses.
 323
 324 -6::
 325 --ipv6::
 326         Use IPv6 addresses only, ignoring IPv4 addresses.