Replace a link to a site that disappeared with a link to web archive
of the last known good copy.
* dk/fix-shattered-io-link:
doc: fix shattered.io link
The requirement for a 'SYNOPSIS' section in section 7 manual pages
has been relaxed by updating the linter script, and dummy
'SYNOPSIS' sections from existing section 7 documentation have been
removed to improve the rendered output
* je/doc-section-7-synopsis:
doc: don't require a SYNOPSIS in section 7
The documentation for core.pager has been updated to provide
examples of overriding the LESS environment variable for custom
pagers by prefixing the pager command in the configuration.
* tz/doc-override-less-env:
doc: add more examples of overriding LESS in core.pager
The 'format-patch' command has been updated with options to
configure notes specifically for range-diff output, allowing them to
differ from the notes displayed on the patches themselves.
* kh/format-patch-range-diff-notes:
format-patch: learn --[no-]range-diff-notes
format-patch: simplify get_notes_arg parameters
The documentation for 'git interpret-trailers' has been updated to
fix the grammatical errors in the descriptions of command examples.
* kh/doc-trailers-cmd-examples:
doc: interpret-trailers: fix cmd examples
The documentation for 'git remote set-head' has been updated to
clarify that it only modifies the local repository's remote-tracking
symbolic reference, and does not alter the target remote
repository's own 'HEAD'.
* mg/doc-remote-set-head:
doc: remote: say that it only affects the local repository
The parse-options API has been updated to support grouping
subcommands, and the 'git refs' command has been updated to use this
new feature to categorize its subcommands in its help output.
* ps/parse-options-subcommand-groups:
builtin/refs: introduce subcommand groups
parse-options: allow grouping subcommands
parse-options: extract functions to print single option
parse-options: fix completion format when first option is skipped
The @{upstream} notation had short-hand @{u} from the beginning,
and @{push} learned corresponding @{p} to match.
* hn/object-name-push-short:
object-name: accept @{p} as short for @{push}
The 'git var' command has been updated to output individual components
of the author and committer identities, take multiple keys on the
command-line, and support NUL-delimited output with the '-z' option.
* ap/var-broken-down-idents:
var: add broken-out identity variables
var: accept more than one variable
var: add "-z" output mode
var: represent multi-valued variables with a string_list
The internal diff and merge machinery has been updated to use
standard size_t types rather than signed longs for buffer
allocations and offsets, preventing subtle overflow issues on LLP64
architectures, and plugging uninitialized memory leaks along error
paths.
* jk/xdiff-size_t:
merge-ll: report an error when reading external merge results fails
merge-ll: handle external driver status before reading result
merge-ll: use read_mmfile() to read external merge results
xdiff: NUL-terminate buffers read by read_mmfile()
xdiff: use size_t for buffer sizes
xdiff: replace mmbuffer_t with mmfile_t
xdiff: clean up read_mmfile() allocations on error
Since we published this document the domain has been taken over and no
longer reflects the original content. Link to the last good Web Archive
snapshot so folks can still retrieve the SHAttered information.
Suggested-by: Mae Eckert <mae.eckert@albellus.de>
Signed-off-by: D. Ben Knoble <ben.knoble@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Remove the SYNOPSIS section from the section 7 man pages where
appropriate, to avoid having a section that contains no information.
It's not the norm in section 7 to always require a SYNOPSIS.
Update the perl script with a special case for section 7.
Tested by running `make lint-docs`, and looked at the renaming synopses
with this fish script snippet:
for i in *.7
echo $i; grep SYNOPSIS -A 5 (string replace .7 .adoc $i)
end
Co-authored-by: Tuomas Ahola <taahol@utu.fi>
Signed-off-by: Tuomas Ahola <taahol@utu.fi>
Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The documentation for 'git-name-rev' has been updated to refer to
object IDs instead of SHA-1, to more accurately reflect that the
active hash algorithm is used.
* jk/name-rev-update-hash-descriptions:
name-rev: update hash descriptions
Various documentation files have been updated to use explicit
'<<TARGET,TARGET>>' AsciiDoc cross-references instead of plain text
references. This improves rendering on the web and avoids broken
links when manual pages are included into other pages.
* je/doc-asciidoc-xrefs:
doc: add more AsciiDoc cross-references
git-format-patch(1) passes on the notes behavior that it is using for
the patches to git-range-diff(1). In turn you get the same Git notes
displayed in the range diff as the ones you used to generate the
patches. And that makes sense in most cases.
However, I often make notes between series versions that mostly prepend
to the original. They end up looking like this:
v3:
[desc.]
v2:
[descr.]
v1:
[descr.]
These notes are meant for the git-format-patch(1) output since they
document the iterations. But including them also includes them in the
range diff. And they have nothing useful to say there.
Let’s teach git-format-patch(1) `--[no-]range-diff-notes` so that we
can pass in different notes refs to the range diff, or just turn them
off entirely.
In addition to storing the list of notes, we also need a boolean
`override` to distinguish these two cases:
1. No such options were given and empty list (use `--notes`)
2. Options were given and empty list (`--no-...` given; don’t use notes)
Unlike `--creation-factor`, `--[no-]range-diff-notes` does not error out
when used without `--range-diff`. This flexibility accommodates
workflows where users might configure default options in aliases or
wrapper scripts, allowing `--range-diff` to be toggled independently.
Add two tests here for the single-patch case, i.e. the case where the
range diff is on the patch and not in the cover letter. These are meant
as regression tests based on my encounter with single-patch range diff
notes handling bug.[1]
† 1: 155986b4 (format-patch: handle range-diff on notes correctly for
single patches, 2025-09-25)
Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Fix `trailer.<key-alias>.cmd` examples which have remained unchanged
since they were written in c364b7ef (trailer: add new .cmd config
option, 2021-05-03). (Modulo formatting changes.)
Steal how the `see` example is phrased and use that as a template:
Configure a `see` trailer with a command to show the subject of a
commit that is related, and show how it works:
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
We set the LESS environment variable unconditionally which can surprise
users of pagers which respect it but presume we'd only set LESS when
`core.pager` calls less.
Provide examples of setting LESS in `core.pager` as an additional way to
override the options we set in LESS.
Reported-by: Francisco Boni <boboniboni@gmail.com>
Signed-off-by: Todd Zullinger <tmz@pobox.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The sentence following the git tag command continues the
preceding sentence, so "You" should be lowercase.
Signed-off-by: Khan Zimov <kaliugov@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The git-refs(1) command nowadays has a bunch of different subcommands,
which makes it hard to figure out what's what at a glance. Now that the
parse-options subsystem supports grouping subcommands though we can do
better. The commands roughly fall into the following categories:
- Operations that span across the whole reference database.
- Operations that read references.
- Operations that write references.
Introduce these groups accordingly, which results in the following help
output:
Reference database
migrate migrate the reference database to a different format
verify verify the consistency of the reference database
optimize optimize the reference database
Reading references
list list references
exists check whether a reference exists
Writing references
create create a new reference
delete delete a reference
update update an existing reference
rename rename a reference
Reorder the usage strings to match the new grouping.
Signed-off-by: Patrick Steinhardt <ps@pks.im>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The `OPT_GROUP()` macro can be used to create a new group. These groups
can only be used to group options though, they do not have any effect
when used in combination with subcommands. As our use of subcommands
grows though it can be quite useful to group these, as well.
Extend `OPT_SUBCOMMAND_F()` to take an optional help string. If given,
such subcommands will be considered as part of `OPT_GROUP()` and printed
with that help string.
Signed-off-by: Patrick Steinhardt <ps@pks.im>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
"git log @{p}" fails with "unknown revision", even though "@{u}"
works for "@{upstream}".
The "@{upstream}" notation came with its "@{u}" short form from the
very beginning in 28fb84382b (Introduce <branch>@{upstream} notation,
2009-09-10). When "@{push}" was added in adfe5d0434 (sha1_name:
implement @{push} shorthand, 2015-05-21), "@{p}" was held back to
avoid confusion with a proposed "@{publish}" and talk of an "@{pull}".
Neither of those was ever added.
Add the missing "@{p}" for symmetry with "@{u}".
Signed-off-by: Harald Nordgren <haraldnordgren@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The build-time knob 'USE_NSEC' for nanosecond stat precision has been
converted to a runtime configuration 'core.useNanosec', allowing
distributions to bundle one binary that adapts to filesystem
capabilities dynamically.
* dk/use-nsec-runtime:
core: convert build-time USE_NSEC into runtime core.useNanosec
environment: align repo_config_values_init with struct declaration
meson: expose knob for xmlto relative links in manuals
The terminology regarding reference storage formats has been unified
across command-line options, environment variables, configuration
variables, and source code, standardizing on the phrase "ref storage
format" (e.g., `--ref-storage-format`, `'GIT_REF_STORAGE_FORMAT'`).
Additionally, the `--ref-storage-format` option has been updated to
accept payloads in the form `<format>://<payload>`.
* ps/ref-storage-format:
setup: allow "--ref-storage-format=" to specify a payload
setup: rename "init.defaultRefFormat" to "init.defaultRefStorageFormat"
t: rename GIT_TEST_DEFAULT_REF_FORMAT
setup: rename ref storage format environment variables
setup: refactor how we configure the ref storage format
refs: expose function to parse reference URIs
help: rename "default-ref-format" to "default-ref-storage-format"
builtin/rev-parse: rename "--show-ref-format" to "--show-ref-storage-format"
builtin/submodule: rename "--ref-format=" to "--ref-storage-format="
builtin/refs: rename "--ref-format=" to "--ref-storage-format="
builtin/clone: rename "--ref-format=" to "--ref-storage-format="
builtin/init: rename "--ref-format=" to "--ref-storage-format="
parse-options: allow for hidden aliases
A new hook 'report' is added to 'git receive-pack', which runs after
reference updates and allows the server to filter or modify the
packet-line status report sent back to the client.
* kn/receive-report-hook:
receive-pack: coccinelle fix
hook: introduce the receive-report hook
receive-pack: move message generation to separate function
receive-pack: drop static variables to track report status version
doc: add proc-receive hook info in 'git-receive-pack.adoc'
The experimental 'git history' command has been taught a new 'squash'
subcommand to fold a range of commits into a single commit, with any
descendants replayed on top.
* hn/history-squash:
history: support editing squashed commit messages
history: create squashed commits without editing
history: protect branches when squashing a range
history: validate squash revision ranges
history: add skeleton for squash subcommand
sequencer: share the squash message marker helpers and flags
history: give commit_tree_ext a message template
history: extract helper for a commit's parent tree
Our import of xdiff has two identical buffer structures: mmfile_t and
mmbuffer_t. In upstream xdiff these were actually different, but the
import in 3443546f6e (Use a *real* built-in diff generator, 2006-03-24)
simplified mmfile_t to a simple buffer.
In xdiff we usually use mmfile_t for input and mmbuffer_t for output,
but they are really both just a ptr/len pair. I don't think that having
different types is buying us anything in terms of type safety or
semantics, and having two makes it awkward to use the same helpers for
both. In particular, an external merge driver's output is read from a
file, but we can't easily use read_mmfile(), since we want the result in
an mmbuffer_t.
Let's use mmfile_t for both cases and drop mmbuffer_t. The latter is
probably a more descriptive name, but we have many more uses of
mmfile_t (and helpers like read_mmfile). So let's consolidate using that
name; we can always change it to something more sensible later.
There should be no behavior change here; this is just consolidating the
types.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Nothing that "git remote" does changes a remote repository. "set-head"
updates the local refs/remotes/<name>/HEAD, not the remote's own HEAD;
"prune" deletes stale remote-tracking branches, not branches on the
remote; and so on. The manual page never says so, and wording such as
"Set or delete the default branch ... for the named remote" can be read
as acting on the remote itself. It was recently misread that way in a
discussion on another project's mailing list.
Say it once, near the top of the DESCRIPTION, rather than in the
description of each subcommand.
Signed-off-by: Matthias Goergens <matthias.goergens@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The documentation for --annotate-stdin and --name-only refers to
SHA-1, although name-rev handles object IDs according to the active
hash algorithm.
Update the descriptions to refer to object IDs instead.
Signed-off-by: jyotish kumar <jyotishkumar725015@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
A script that wants only the author's name has to ask for
GIT_AUTHOR_IDENT and take the result apart itself, which means
reimplementing the rules split_ident_line() already knows, and getting
them subtly wrong for names that contain an e-mail address or other
awkward characters.
Add GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL and GIT_AUTHOR_DATE, together
with their GIT_COMMITTER_* counterparts, which give the individual
pieces of the corresponding *_IDENT variable. They are derived from
the same ident string, so they are strict in the same way: asking for
one of them fails if the identity cannot be determined.
Signed-off-by: Andrew Pleeter <andrewpleeter@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
"git var" takes exactly one variable and shows its value, so a script
that needs several of them has to run the command once per variable,
paying process startup and configuration parsing each time.
Teach "git var" to take any number of variables and show them the way
"git var -l" does, i.e. as "VARIABLE=value" (or "VARIABLE\nvalue\0"
under "-z"), but limited to the variables the user asked for. A single
variable still shows its bare value, and still exits with status 1 when
it has no value, so existing users are unaffected.
When more than one variable is asked for, a variable that has no value
is simply left out of the output and the rest are still shown. That a
variable is unset is not an error in itself: a caller asking for both
GIT_CONFIG_SYSTEM and GIT_CONFIG_GLOBAL should not be told that
something went wrong merely because the user set GIT_CONFIG_NOSYSTEM.
Keeping a non-zero status for genuine errors, such as naming a variable
that does not exist, also lets callers detect those by looking at the
exit code alone.
Signed-off-by: Andrew Pleeter <andrewpleeter@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Scripts that read from "git var" have no unambiguous way to parse its
output. A value that itself contains a newline, and a variable that
has more than one value, both run together with the newline that
terminates each entry.
Teach "git var" a "-z" option that terminates each entry with a NUL
byte instead. With "-l", the variable name and its value are separated
by a newline and each entry is terminated by NUL, which is the same
convention "git config list -z" already uses. When a single variable
is asked for, its bare value is terminated by NUL.
Parsing of the command line is switched over to parse_options() in
order to accept the new option; as a side effect, options now have to
come before the variable name.
Signed-off-by: Andrew Pleeter <andrewpleeter@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
A variable whose value is a list, of which GIT_CONFIG_GLOBAL is
currently the only one, is read into a single string whose elements are
joined with newlines, and "git var -l" splits that string apart again
before showing each element. Round-tripping through a delimiter that
can legitimately appear in a value is fragile, and it forces every
future caller to know which variables need splitting.
Give "struct git_var" a separate "multiread" function that appends the
elements to a string_list, and let the single "read" function stay for
the variables that have exactly one value. A variable uses one or the
other, never both, so which one is set also says whether the variable
is multi-valued.
The output is unchanged. While at it, say in the documentation that
GIT_CONFIG_GLOBAL can have multiple values, so that callers know when
to expect a list.
Signed-off-by: Andrew Pleeter <andrewpleeter@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Instead of saying "see EXAMPLES below", say "see <<EXAMPLES,EXAMPLES>>
below" to make the man pages easier to navigate on the web.
The reason for using the more verbose <<EXAMPLES,EXAMPLES>>
(instead of <<EXAMPLES>>) is that in some cases, <<EXAMPLES>> is
rendered as `the section called "EXAMPLES"` or `[EXAMPLES]`.
<<EXAMPLES,EXAMPLES>> is rendered as `EXAMPLES`, which gives us more
control over the output.
This also changes some of the HTML IDs of the headings from `_examples`
to `EXAMPLES`, which has the potential to break some links.
Signed-off-by: Julia Evans <julia@jvns.ca>
Acked-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Doc updates.
* tz/doc-pack-refs-and-refs-fixes:
doc/refs: backtick-quote commands and options consistently
doc/pack-refs: convert synopsis and options to new style
The git-refs doc was converted to the synopsis style in 89be7d2774
(builtin/refs: add '--no-reflog' flag to drop reflogs, 2025-02-21). The
commands and options were not backtick-quoted at that time. 84f3d6e11e
(doc lint: check that synopsis manpages have synopsis inlines,
2025-08-11) applied backtick-quotes to the existing commands and
options.
Subsequently, a number of commands and options were added without such
quoting, leaving the documentation rendered inconsistently. Apply
backtick-quotes to all entries.
Signed-off-by: Todd Zullinger <tmz@pobox.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Replace [verse] with [synopsis] in the SYNOPSIS block and remove
single-quote formatting from the command name.
Backtick-quote all option terms in the OPTIONS section via the included
pack-refs-options.adoc and convert the standalone placeholder _<branch>_
in prose.
Signed-off-by: Todd Zullinger <tmz@pobox.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The git rev-list command has been augmented with a '--missing-only'
option that filters the output to only show missing objects,
stripping the leading '?' character and suppressing present objects,
which is useful when used in combination with '--missing=print' or
'--missing=print-info'.
* sa/rev-list-missing-only:
rev-list: add --missing-only option to filter output
Junio C Hamano