A new document, gitsecurityboundary(7), has been added to clarify
the security boundaries Git guarantees and the responsibilities of
the user, aiming to provide a clear reference for what constitutes a
security vulnerability in Git.
* tc/security-boundary-doc:
Documentation: clarify Git's security boundary
The obsolete 'gittutorial-2' documentation and all references to it
have been removed from the documentation tree and 'command-list.txt'.
* je/doc-remove-gittutorial-2:
doc: remove references to gittutorial-2
doc: remove gittutorial-2
The coding guidelines have been updated to officially allow the use
of C99 compound literals, as the test balloon has been flying
without issues since late 2024.
* pw/allow-compound-literals:
CodingGuidelines: allow compound literals
A new user manual page on how to resolve merge conflicts has been
introduced, and other commands that could encounter conflicts have
been updated to link to it.
* je/doc-merge-conflicts:
doc: git-pull: link to new merge conflicts guide
doc: git-cherry-pick: link to new merge conflicts guide
doc: git-revert: link to new merge conflicts guide
doc: git-rebase: link to new merge conflicts guide
doc: git-merge: link to new merge conflicts guide
doc: add new gitmergeconflicts man page
The command-line completion for 'git stash' has been updated to
dynamically discover subcommands and to correct a Zsh-specific
formatting issue where stash references were improperly unquoted.
Additionally, the deprecated 'save' subcommand has been removed from
completions and synopsis documentation.
* dk/stash-completion-updates:
completion: drop "stash save" completion altogether
doc: drop usage mentions of "git stash save"
completion: fix Zsh handling of stash names
Completion: extract common stash listing code
completion: simplify stash subcommand completion
The beginner's tutorial in 'gittutorial.adoc' has been rewritten to
focus on a minimal set of commands needed to create a repository,
make commits, and push to a remote host, optimizing for a quick
one-hour learning experience.
* je/doc-new-git-tutorial:
doc: add new Git tutorial for beginners
doc: remove gittutorial
The documentation on contributing has been updated to emphasize the
importance of discussing review feedback before sending the next
iteration, and the section on sending an updated version has been
moved to appear after the discussion of the review process.
* jc/myfirstcontribution-discuss-then-reroll:
MyFirstContribution: clarify that "reviewing" is a discussion
MyFirstContribution: move "how to send v2" after discussing reviews
Like so many other open source projects, the Git project has seen an
ever-increasing flood of security reports. Many of those reports
describe valid bugs yet are redirected from the git-security mailing
list because they are deemed "not vulnerabilities". While some Git
contributors seem to have a very concrete idea how to discern between
bugs that constitute vulnerabilities (and hence must be fixed in secret,
to keep Git users safe) from bugs that can be fixed in the open, most
reporters must be quite puzzled because the Git project provides no
clear document to help define the security boundaries Git tries to
guarantee.
Of course, there _are_ hints and bits and pieces of documentation: Git's
security guidance has accumulated across individual fixes. Some might be
tempted to describe the boundary as "before clone" versus "after clone",
but history establishes a more precise distinction. e69ac42fcc (docs:
document security issues around untrusted .git dirs, 2024-04-16)
explains why cloned content can generally be inspected with `git log`:
repository-local hooks and configuration are not copied, whereas an
untrusted `.git` directory remains unsafe. 779ea9303a (Documentation:
define protected configuration, 2022-07-14) likewise ties trust to
configuration scope rather than timing alone.
State the governing principle in one place: Git's security boundary
concerns unexpected or implicit execution of attacker-controlled code. A
theoretical opportunity to inspect repository contents is not consent to
execute them. Conversely, explicitly choosing an execution-capable
mechanism is materially different. Execution after clone is therefore
not inherently a vulnerability.
This distinction underlies 4cd1cf31ef (Git 2.20.2, 2019-12-04), which
describes CVE-2019-19604 as code running during recursive clone plus a
submodule update "without the user explicitly having asked for that".
a1d4f67c12 (transport: make protocol.file.allow be user by default,
2022-07-29) likewise contrasts direct user action with recursion lacking
user input. e4930e86c0 (t5510: verify that D/F confusion cannot lead to
an RCE, 2024-03-24) similarly frames remote code execution as code run
by an operation not expected to run it.
Timing remains relevant when it removes any meaningful choice.
873a466ea3 (clone: drop the protections where hooks aren't run,
2024-05-20) notes that clone-time hook execution leaves no chance to
inspect first. Conversely, 8d1a744820 (setup.c: create
safe.bareRepository, 2022-07-14) addresses post-clone use of embedded
bare repositories. Together these cases show why timing alone cannot
define the boundary.
Assisted-by: GPT-5.6 Sol
Helped-by: Patrick Steinhardt <ps@pks.im>
Helped-by: Junio C Hamano <gitster@pobox.com>
Co-authored-by: Johannes Schindelin <johannes.schindelin@gmx.de>
Signed-off-by: Toon Claes <toon@iotcl.com>
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The documentation for SSH signature verification has been updated to
clarify that key lifetime checks depend on spoofable dates.
* cr/doc-gpg-ssh-key-lifetime:
doc: gpg: say which date SSH key lifetimes are checked against
The object storage format has been made configurable via the
'extensions.objectStorage' configuration variable, allowing users
to specify the storage backend and an optional payload, mirroring
the design of 'extensions.refStorage'.
* ps/odb-object-storage-extension:
builtin/submodule: propagate "--object-storage-format="
builtin/clone: introduce "--object-storage-format="
builtin/init: introduce handling of object storage format
builtin: expose the object storage format
setup: allow overriding object storage format via environment
setup: introduce object storage extension
loose: drop unused `repo_write_loose_object_map()`
The post-fetch connectivity check in 'git fetch' has been corrected
to avoid passing alternate refs as positive revisions during a
deepening fetch, plugging a severe performance bug.
* iw/connected-deepen-fetch-no-alternate-refs:
odb: ignore refs of shallow and grafted alternates
connected: negate alternate refs in deepening fetches too
The output of 'git repo info' has been updated to use
'references.storageFormat' instead of 'references.format' for
consistency with recent ref-storage-format terminology updates.
* ps/repo-ref-storage-format-fix:
builtin/repo: rename "references.format" to "references.storageFormat"
The hook.<event>.enabled configuration variable has been extended to
also disable traditional hookdir hooks in addition to configured
hooks. In addition, the hook configuration parser has been updated
to treat missing values for boolean variables like enabled and
parallel as true.
* tb/hook-enabled-covers-traditional-hooks:
hook: accept .enabled and .parallel given without a value
hook: make hook.<event>.enabled cover the hookdir hook
The connectivity check in 'git fetch' and 'git receive-pack' has
been optimized with an alternative incremental mode, available via
'transfer.connectivityCheck=incremental'. Instead of walking the
full object closure of the boundary commits, it compares the trees
of incoming commits against their trusted parent trees, skipping
unchanged subtrees.
* kk/connectivity-check-incremental:
connected: add "auto" connectivity check mode
connected: add incremental connectivity check via rev-list
connected: add transfer.connectivityCheck config
connected: drop dependency on `the_repository`
p5413: add perf tests for connectivity check
Documentation: describe connectivity checking
Introduce Git in two parts:
Steps 1-7: Create an empty repo & make 2 commits (`git init`,
`git add`, `git commit`, `git status`, `git diff`)
Steps 8-12: Push the repo to a remote host like GitHub or GitLab
(`git remote add`, `git push`)
Some design choices:
- Only use commands present in 2.23.0 (when `git switch` as introduced),
to support older versions of Git.
- Introduce a much smaller set of commands than the old tutorial, to
keep the tutorial quick (doable in an hour). Some users found it to be
very fast and some wanted to stop early (after step 7) so this seems
to be a good balance.
- Have users start with an empty repository instead of an existing
project, because many of the testers did not have an existing project
to test, or were scared of using an existing project.
- Add a troubleshooting section, since in the testing some users got
extremely stuck (for 4+ hours) on minor issues like needing to say
"yes" when SSHing to a new host.
- Don't explain branches, because explaining branches and collaboration
is complicated and deserves its own tutorial. Instead just tell users
we're not going to explain them in this document.
- Tell users to set their default branch to `main`, because many Git
hosts use it as their default branch and it really simplifies things.
- Keep it as vendor neutral as possible, while acknowledging the reality
that Git hosting services like GitHub, GitLab, etc are extremely
popular. Do this by creating the repo locally and then optionally
pushing it later.
- Use SSH for authentication, explaining how to set up SSH in the
easiest way possible (with disclaimers to check your security team's
policy if applicable since the "easiest way" may not be the best), and
giving some instructions for how to translate an HTTPS URL to an SSH
URL.
- Use Git Credential Manager for authentication on Windows, since it's
simpler, SSH auth is a very "unixy" thing to do, and GCM comes with
Git for Windows
- Warn people about how `vi` is the default text editor and give some
instructions for how to escape
At least 20 people have successfully completed it, and feedback was
incorporated from problems the testers ran into.
Helped-by: D. Ben Knoble <ben.knoble@gmail.com>
Co-authored-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>
Signed-off-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>
Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The next commit replaces it with a new tutorial.
Do this as a remove/add instead of just replacing the file in a single
commit to make the patches easier to read on the mailing list, since the
existing content isn't being reused.
Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The description of gpg.ssh.allowedSignersFile says that Git marks a
signature as valid if the signing key was valid at the time of the
signature's creation. An SSH signature does not record when it was
made, though. When verifying a commit or a tag, Git passes the
committer or tagger date to ssh-keygen with -Overify-time, and the
valid-after and valid-before options of a key are checked against
that date.
Say which date is used, and that the signer chooses it. While at it,
fix the spelling of "OpenSSH" in the same paragraph.
Helped-by: Phillip Wood <phillip.wood@dunelm.org.uk>
Helped-by: Junio C Hamano <gitster@pobox.com>
Helped-by: Patrick Steinhardt <ps@pks.im>
Signed-off-by: Christian Noé Ramos López <chris@nortesoftware.dev>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Fix an obvious spelling error in `Documentation/config/log.adoc`
"overriden" -> "overridden"
Signed-off-by: Hardik Kumar <hardikxk@gmail.com>
Acked-by: Patrick Steinhardt <ps@pks.im>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The ref storage format passed to git-clone(1) propagates to recursively
cloned submodules, and git-submodule(1)'s "add" and "update" subcommands
accept `--ref-storage-format=` so that newly cloned submodules can be
set up with a specific format.
Teach git-submodule(1) to also propagate the object storage format.
Signed-off-by: Patrick Steinhardt <ps@pks.im>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Wire up the new object storage format in git-clone(1) via a new
`--object-storage-format=` option, same as we have introduced in the
preceding commit for git-init(1).
Note that "--local" clones will not work if either of the object
databases is not using the "files" format. This is because we hardlink
loose objects and packfiles into the new repository, and that is
something that simply won't work with alternative backends.
Consequently, we either downgrade to a non-local clone with a warning,
or we die in case the user has explicitly asked for a local clone.
We _could_ in theory handle the case where the "files" backend has been
configured with an alternative object directory path (that is, with
"files:///path/to/dir"). But that's left for a future patch series to
implement for the sake of simplicity.
Signed-off-by: Patrick Steinhardt <ps@pks.im>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
While the object storage format extension can already be configured
manually via git-config(1), this isn't exactly an ergonomic way of doing
so. For the reference storage format extension, users have a host of
options available to them.
Introduce the equivalent options for the object storage format.
Signed-off-by: Patrick Steinhardt <ps@pks.im>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The ref storage format of a repository can be inspected via both
git-rev-parse(1)'s "--show-ref-storage-format" and git-repo(1)'s
"references.storageFormat" field. Introduce the equivalent options for
the object storage format, as well.
Signed-off-by: Patrick Steinhardt <ps@pks.im>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The ref storage format configured via "extensions.refStorage" can be
overridden with the GIT_REF_STORAGE_FORMAT environment variable.
Introduce the GIT_OBJECT_STORAGE_FORMAT environment variable that
overrides "extensions.objectStorage" in the same way.
Signed-off-by: Patrick Steinhardt <ps@pks.im>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Introduce a new "extensions.objectStorage" extension that allows the
user to configure the primary object database source of a repository.
The value is a URI in the format "<schema>[://<payload>]", mirroring
the format used by "extensions.refStorage":
- The schema identifies the backend that shall be used. For now the
only supported schema is "files", which is the existing object
database backed by loose objects and packfiles.
- The payload can be passed to configure the backend, and its
interpretation is backend-specific. For the "files" backend, it
allows you to configure a different location for the ".git/objects"
directory.
Making the location of the "files" backend configurable is not the most
thrilling feature of this new extension. But it gives us a couple of
advantages:
- It allows us to start exercising the payload logic in our tests so
that we know it's working properly for backends that will need it.
- It allows us to easily detect tests that are broken with the new
extension because they for example assume that an object is a file
in ".git/objects/". Testing is not part of this series yet, but will
be done in subsequent patch series.
- It aligns with how we handle the ref storage extension, where we can
also change its location to an arbitrary path.
- It allows for some very esoteric and edge-case-y gimmicks. For
example, you can initialize a single repository "skeleton" and then
multiplex therein by setting both GIT_REF_STORAGE_FORMAT and
GIT_OBJECT_STORAGE_FORMAT to point to different databases. These
edge cases won't matter to many people out there, but we will use
this for example as a building block for migrations.
Eventually, this mechanism will be used to support alternative backends.
Signed-off-by: Patrick Steinhardt <ps@pks.im>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The obsolete 'gittutorial-2' documentation and all references to it
have been removed from the documentation tree and 'command-list.txt'.
* je/doc-remove-gittutorial-2:
doc: remove references to gittutorial-2
doc: remove gittutorial-2
The coding guidelines have been updated to officially allow the use
of C99 compound literals, as the test balloon has been flying
without issues since late 2024.
* pw/allow-compound-literals:
CodingGuidelines: allow compound literals
A new user manual page on how to resolve merge conflicts has been
introduced, and other commands that could encounter conflicts have
been updated to link to it.
* je/doc-merge-conflicts:
doc: git-pull: link to new merge conflicts guide
doc: git-cherry-pick: link to new merge conflicts guide
doc: git-revert: link to new merge conflicts guide
doc: git-rebase: link to new merge conflicts guide
doc: git-merge: link to new merge conflicts guide
doc: add new gitmergeconflicts man page
The command-line completion for 'git stash' has been updated to
dynamically discover subcommands and to correct a Zsh-specific
formatting issue where stash references were improperly unquoted.
Additionally, the deprecated 'save' subcommand has been removed from
completions and synopsis documentation.
* dk/stash-completion-updates:
completion: drop "stash save" completion altogether
doc: drop usage mentions of "git stash save"
completion: fix Zsh handling of stash names
Completion: extract common stash listing code
completion: simplify stash subcommand completion
The documentation on contributing has been updated to emphasize the
importance of discussing review feedback before sending the next
iteration, and the section on sending an updated version has been
moved to appear after the discussion of the review process.
* jc/myfirstcontribution-discuss-then-reroll:
MyFirstContribution: clarify that "reviewing" is a discussion
MyFirstContribution: move "how to send v2" after discussing reviews
Instead of failing to record conflicts to be resolved immediately,
wait while "rerere gc" is ongoing.
* tb/rerere-wait-for-merge-rr-lock:
rerere: add "gc --skip-locked" for auto maintenance
rerere: wait for MERGE_RR.lock before giving up
Redirect folks to `gitdatamodel` instead, since every time it's
referenced the intent is to explain objects, references, blobs, etc.
The update to `gittutorial` isn't very carefully thought through since
we're planning to delete that entire document anyway. It's just there to
maintain some internal consistency.
Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
It hasn't been substantially updated for 20 years
(see `git diff e31952da5c52a4c1:Documentation/tutorial-2.txt
0f8e75abebff0877:Documentation/gittutorial-2.adoc`)
and it's becoming out of date, for example:
- refs do not necessarily live in `.git/refs`
- we don't really call it "the index file" anymore, and we don't
encourage users to think about the individual files in `.git` as much
as we did 20 years ago
More importantly, this approach of introducing Git by learning about the
contents of `.git` does not work for most people learning Git for the
first time. It's interesting information for some people (maybe more
advanced users or folks with a strong computer science background, for
not appropriate for a general tutorial).
Right now `gittutorial-2` is meant to be a logical sequel to
`gittutorial` ("read gittutorial, then gittutorial-2").
Deleting `gittutorial-2` means that we can more easily rewrite the main
`gittutorial` (which is also not effective) in any way we want, without
having to make sure that `gittutorial-2` is the logical next step.
We have other documentation which can serve a similar purpose to
tutorial-2 and isn't framed as a general tutorial appropriate for
everyone.
Keep building the man page for now and leave behind a stub to
redirect folks to those other documents.
Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Our coding guidelines say that we'll allow compound literals from
mid 2026 if no problems are reported in relation to the test balloon
added in 01e49941d6 (reftable/system: provide thin wrapper for tempfile
subsystem, 2024-11-18). As no such reports have been received, update
the guidelines to allow this construct.
Signed-off-by: Phillip Wood <phillip.wood@dunelm.org.uk>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Remove some of the detail about how to handle a merge conflict, since
it's explained in detail in the new guide, and there probably isn't
enough detail anyway.
Leave the steps since rebase is special and has a `--skip` option which
the other commands which cause merge conflicts don't have.
Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Junio C Hamano