Files
git/Documentation/config/fetch.txt
Ævar Arnfjörð Bjarmason 4a169da280 fetch doc: note "pushurl" caveat about "credentialsInUrl", elaborate
Amend the documentation and release notes entry for the
"fetch.credentialsInUrl" feature added in 6dcbdc0d66 (remote: create
fetch.credentialsInUrl config, 2022-06-06), it currently doesn't
detect passwords in `remote.<name>.pushurl` configuration. We
shouldn't lull users into a false sense of security, so we need to
mention that prominently.

This also elaborates and clarifies the "exposes the password in
multiple ways" part of the documentation. As noted in [1] a user
unfamiliar with git's implementation won't know what to make of that
scary claim, e.g. git hypothetically have novel git-specific ways of
exposing configured credentials.

The reality is that this configuration is intended as an aid for users
who can't fully trust their OS's or system's security model, so lets
say that's what this is intended for, and mention the most common ways
passwords stored in configuration might inadvertently get exposed.

1. https://lore.kernel.org/git/220524.86ilpuvcqh.gmgdl@evledraar.gmail.com/

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Acked-by: Derrick Stolee <derrickstolee@github.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-06-15 11:39:02 -07:00

135 lines
6.0 KiB
Plaintext

fetch.recurseSubmodules::
This option controls whether `git fetch` (and the underlying fetch
in `git pull`) will recursively fetch into populated submodules.
This option can be set either to a boolean value or to 'on-demand'.
Setting it to a boolean changes the behavior of fetch and pull to
recurse unconditionally into submodules when set to true or to not
recurse at all when set to false. When set to 'on-demand', fetch and
pull will only recurse into a populated submodule when its
superproject retrieves a commit that updates the submodule's
reference.
Defaults to 'on-demand', or to the value of 'submodule.recurse' if set.
fetch.fsckObjects::
If it is set to true, git-fetch-pack will check all fetched
objects. See `transfer.fsckObjects` for what's
checked. Defaults to false. If not set, the value of
`transfer.fsckObjects` is used instead.
fetch.fsck.<msg-id>::
Acts like `fsck.<msg-id>`, but is used by
linkgit:git-fetch-pack[1] instead of linkgit:git-fsck[1]. See
the `fsck.<msg-id>` documentation for details.
fetch.fsck.skipList::
Acts like `fsck.skipList`, but is used by
linkgit:git-fetch-pack[1] instead of linkgit:git-fsck[1]. See
the `fsck.skipList` documentation for details.
fetch.unpackLimit::
If the number of objects fetched over the Git native
transfer is below this
limit, then the objects will be unpacked into loose object
files. However if the number of received objects equals or
exceeds this limit then the received pack will be stored as
a pack, after adding any missing delta bases. Storing the
pack from a push can make the push operation complete faster,
especially on slow filesystems. If not set, the value of
`transfer.unpackLimit` is used instead.
fetch.prune::
If true, fetch will automatically behave as if the `--prune`
option was given on the command line. See also `remote.<name>.prune`
and the PRUNING section of linkgit:git-fetch[1].
fetch.pruneTags::
If true, fetch will automatically behave as if the
`refs/tags/*:refs/tags/*` refspec was provided when pruning,
if not set already. This allows for setting both this option
and `fetch.prune` to maintain a 1=1 mapping to upstream
refs. See also `remote.<name>.pruneTags` and the PRUNING
section of linkgit:git-fetch[1].
fetch.output::
Control how ref update status is printed. Valid values are
`full` and `compact`. Default value is `full`. See section
OUTPUT in linkgit:git-fetch[1] for detail.
fetch.negotiationAlgorithm::
Control how information about the commits in the local repository
is sent when negotiating the contents of the packfile to be sent by
the server. Set to "consecutive" to use an algorithm that walks
over consecutive commits checking each one. Set to "skipping" to
use an algorithm that skips commits in an effort to converge
faster, but may result in a larger-than-necessary packfile; or set
to "noop" to not send any information at all, which will almost
certainly result in a larger-than-necessary packfile, but will skip
the negotiation step. Set to "default" to override settings made
previously and use the default behaviour. The default is normally
"consecutive", but if `feature.experimental` is true, then the
default is "skipping". Unknown values will cause 'git fetch' to
error out.
+
See also the `--negotiate-only` and `--negotiation-tip` options to
linkgit:git-fetch[1].
fetch.showForcedUpdates::
Set to false to enable `--no-show-forced-updates` in
linkgit:git-fetch[1] and linkgit:git-pull[1] commands.
Defaults to true.
fetch.parallel::
Specifies the maximal number of fetch operations to be run in parallel
at a time (submodules, or remotes when the `--multiple` option of
linkgit:git-fetch[1] is in effect).
+
A value of 0 will give some reasonable default. If unset, it defaults to 1.
+
For submodules, this setting can be overridden using the `submodule.fetchJobs`
config setting.
fetch.writeCommitGraph::
Set to true to write a commit-graph after every `git fetch` command
that downloads a pack-file from a remote. Using the `--split` option,
most executions will create a very small commit-graph file on top of
the existing commit-graph file(s). Occasionally, these files will
merge and the write may take longer. Having an updated commit-graph
file helps performance of many Git commands, including `git merge-base`,
`git push -f`, and `git log --graph`. Defaults to false.
fetch.credentialsInUrl::
A configured URL can contain plaintext credentials in the form
`<protocol>://<user>:<password>@<domain>/<path>`. You may want
to warn or forbid the use of such configuration (in favor of
using linkgit:git-credential[1]).
+
Note that this is currently limited to detecting credentials in
`remote.<name>.url` configuration, it won't detect credentials in
`remote.<name>.pushurl` configuration.
+
You might want to enable this to prevent inadvertent credentials
exposure, e.g. because:
+
* The OS or system where you're running git may not provide way way or
otherwise allow you to configure the permissions of the
configuration file where the username and/or password are stored.
* Even if it does, having such data stored "at rest" might expose you
in other ways, e.g. a backup process might copy the data to another
system.
* The git programs will pass the full URL to one another as arguments
on the command-line, meaning the credentials will be exposed to oher
users on OS's or systems that allow other users to see the full
process list of other users. On linux the "hidepid" setting
documented in procfs(5) allows for configuring this behavior.
+
If such concerns don't apply to you then you probably don't need to be
concerned about credentials exposure due to storing that sensitive
data in git's configuration files. If you do want to use this, set
`fetch.credentialsInUrl` to one of these values:
+
* `allow` (default): Git will proceed with its activity without warning.
* `warn`: Git will write a warning message to `stderr` when parsing a URL
with a plaintext credential.
* `die`: Git will write a failure message to `stderr` when parsing a URL
with a plaintext credential.