The top piece of feedback users always give about man pages is always
that they want better examples that are relevant to them.

The EXAMPLES section's structure has remained mostly unchanged since
2007, which was before we knew how people were going to use `git diff`.
Update it with ways of using `git diff` that are popular with Git
users, gathered by asking Mastodon users for their most commonly used
incantations. Keep the example that was added since 2007
(`git diff AUTO_MERGE`), rewording it to use the more familiar term
"merge conflict" instead of "textual conflict".

Add a note about the EXAMPLES section in the DESCRIPTION since otherwise
readers are unlikely to know it's there. `git diff` is a command where
it's more important than usual to have examples because the command has
so many different forms.

Some design choices:

- Mention both `git diff --staged` and `git diff --cached`, because
  "staged" is the term the Git user interface uses and several users
  said they find it easier to understand. Add an entry for --staged
  saying that it's a synonym. Like with `git switch`, and `git checkout`
  it's useful to leave the older version for folks who are used to using
  `git diff --cached` since we've seen that many people who are used to
  using a command don't see any value in changing how they use it.
- Use a definition list for the examples instead of the footnote style,
  so that the description and the example are right next to each other
  and it's easier to read.
- Use `--merge-base` instead of `...` since several users said they
  find .. vs ... confusing. It's much more obvious what --merge-base
  does.
- Link the options in the examples to make them faster to look up
- Use sub-subsection headings for the different parts to make
  them more visually distinct and easy to scan.

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>

AsciiDoc needs these anchors spelled this way

it is likely that the annotation was meant to go with --dashed-option

The description of the detached HEAD state in 'git help checkout'  has
been updated and moved to a standalone guide to make it easier  for
users to understand and reference.

* je/doc-detached-head:
  SQUASH???
  doc: checkout: rewrite detached HEAD state explanation

The default and skipping fetch negotiators have been updated to parse
parent commits before adding them to the priority queue.  This ensures
they are sorted by actual commit date rather than being delayed as old
commits, and leaves unparsable commits out of the priority queue
without incorrectly marking them as seen.

* tb/negotiator-skipping-parse-parents:
  negotiator/skipping.c: parse parents before queueing
  negotiator/default.c: mark commits seen only after parsing

The verbose "Checking connectivity" message in 'git fsck' has been
updated to report the actual number of objects instead of the size
of the object hash bucket array.

* ag/fsck-connectivity-count:
  fsck: report the real object count in the connectivity message

Basic tests for the batch mode of 'git mktree' have been added.

* rk/mktree-batch-tests:
  t1010: add basic tests for mktree --batch

The server-side computation of shallow boundaries for a protocol v2
fetch from a shallow repository has been optimized by directly
sending all known shallow roots, avoiding expensive commit history
walks and matching protocol v0 behavior.  Additionally, local commit
history traversal for 'git fetch --unshallow' has been corrected to
visit each commit exactly once, preventing hangs on repositories
with long histories.

* hn/fetch-shallow-v2-fix:
  upload-pack: fix slow fetches from a shallow repository

A test script has been modernized to use 'test_path_is_file'
instead of 'test -e' to verify the existence of a file.

* jg/t3429-test-path-is-file:
  t3429: use test_path_is_file helper

The default behavior of 'git status' has been updated to compare
the current branch against both its upstream and push tracking
counterparts.  This makes it easier for users with triangular
workflows to see all relevant comparisons without needing to
configure 'status.compareBranches'.

* hn/status-compare-branches-default:
  status: compare against both upstream and push branch by default

The third part of the SHA-1/SHA-256 interoperability work has been
added, implementing support for reading and writing pack index v3.
This allows packed objects to be mapped between hash algorithms by
storing object IDs in both the main and compatibility hash
algorithms.

* cc/pack-index-v3:
  doc: move pack index v3 documentation
  packfile: allow looking up compat object IDs in packs
  loose: map object IDs using pack index v3
  packfile: validate pack index v3 tables
  packfile: add support for reading pack index v3
  object-file: handle compatibility algorithm
  builtin: populate pack index v3 fields when indexing
  pack-write: add support for pack index v3
  object-file-convert: implement mapping in terms of object DB
  odb: implement interoperability functions
  loose: add a flag to control whether we write mapped OIDs
  loose: rename repo_add_loose_object_map
  loose: allow looking up in object map with source

The 'git imap-send' command has been updated to accept message
headers in any order and to match header names case-insensitively,
allowing it to properly process messages saved by 'git send-email'.
A memory leak in the IMAP tunnel initialization has also been
plugged.

* hn/imap-send-header-fix:
  imap-send: match header names case insensitively
  imap-send: check git send-email copies like other messages
  imap-send: accept messages with Subject before Date
  imap-send: wait for the tunnel command to finish

The message given by 'git status' and 'git checkout' when the
upstream branch does not exist has been reworded to explicitly say
so, and to suggest running 'git push' if pushing would create it,
instead of claiming that the upstream is gone.

* ep/status-missing-upstream:
  status: reword message for a missing upstream branch

A new '--delete-integrated' option has been added to 'git branch' to
find and remove branches whose work has been squash-merged or
rebase-merged into the upstream, by comparing the blobs of changed
files.

* hn/branch-delete-merged-squash:
  branch: let --delete-integrated find branches merged onto changed files
  branch: add --delete-integrated to delete rebase and squash merged branches
  branch: let delete_branches() name where a branch landed
  branch: move the deleteMerged opt-out check into a helper

The signal handler chaining mechanism has been updated to recover
from concurrent deliveries of the same signal to multiple threads,
which previously could corrupt the handler stack and cause the
process to enter an infinite loop.

* iy/sigchain-recover-concurrent-pops:
  sigchain: recover from concurrent double-pops of the same signal

The 'git reflog' and 'git log -g' commands have learned the '%gb'
format placeholder, which decorates each reflog entry with the name of
the branch HEAD was on when the entry was recorded, parsing the
historical branch name even during a rebase.

* hn/reflog-operations:
  pretty: add %gb to name the branch of each reflog entry
  reflog: name the strings that mark switches, renames and rebase steps

The allocation size validation and memory allocation functions in the
reftable backend have been updated to use 'uintmax_t' for their size
and element count arguments. This prevents wide values from being
truncated to 'size_t' on 32-bit platforms before the allocation size
overflow check is performed.

* ms/reftable-alloc-size-truncation:
  reftable/basics: widen allocation size arguments to uintmax_t
  Makefile: build the reftable record unit tests

The terminology in the documentation and tests has been updated to
consistently distinguish between root refs (like 'HEAD' and
'ORIG_HEAD' that are stored in the ref backends) and pseudorefs
(like 'FETCH_HEAD' and 'MERGE_HEAD' that are not).

* ak/root-refs-vs-pseudorefs:
  t: stop calling root refs pseudorefs
  refs: stop calling root refs pseudorefs
  doc: stop calling root refs pseudorefs
  doc: glossary: update per-worktree refs
  doc: glossary: add root ref and clarify pseudorefs

The unique_tracking_name() function in checkout.c was the only
function that still assumed it works on 'the_repository'; the function
and its dependencies have been updated to take an instance of 'struct
repository' to work on an arbitrary repository.

* oa/checkout-wo-the-repository:
  checkout: pass the repository to unique_tracking_name()
  remote: add repo_for_each_remote()

The integer arithmetic used to compute the memory allocation size for
the delta index has been updated to use safe helpers. While current
limits prevent wrap-around on 32-bit platforms, this provides
defensive hardening.

* sp/diff-delta-safe-arithmetic:
  diff-delta: use safe integer arithmetic

The error message given when a reflog entry is requested that is out
of bounds has been updated to use the pluralized translation function,
Q_().

* ag/reflog-count-plural:
  object-name: use Q_() for the reflog entry count

The configuration validation for 'remote.<name>.followRemoteHEAD' has
been deferred from parse time to execution time, preventing commands
that do not use the setting (like 'git push' or 'git remote -v') from
emitting spurious warnings about unrecognized values.

* ch/remote-defer-follow-remote-head-validation:
  SQUASH??? factor out parsing of follow-remote-head-raw into a helper
  remote.c: defer remote.<name>.followRemoteHEAD validation

The 'test-lint' target in the test suite has been optimized. The
parsing effort of test scripts is now amortized by having the
'chainlint' script perform 'greplint' checks during its tokenization
phase, significantly speeding up the linting process.

* tc/test-greplint-in-chainlint:
  t/chainlint: add --greplint to run greplint
  t/greplint: move parsing and token check to library
  t/greplint: skip test bodies without the word grep
  t/interop: replace bare grep with test_grep

A new ^/ URL syntax has been introduced for submodules to specify
paths relative to the superproject's remote's server root, allowing
submodules to remain reachable when the superproject is forked into
a subgroup or different hierarchy depth.

* sa/submodule-root-relative-url:
  SQUASH??? test number conflict resolution
  submodule: make '^/' work like '../' but with an absolute path

The subcommand parsing of 'git rerere' has been converted to use
the standard 'OPT_SUBCOMMAND()' API, removing custom ad-hoc parsing
logic and bringing it in line with other Git commands.

* ps/rerere-subcommands:
  builtin/rerere: introduce proper usage strings for subcommands
  builtin/rerere: use `OPT_SUBCOMMAND()`
  builtin/rerere: turn "gc" into a proper subcommand
  builtin/rerere: turn "diff" into a proper subcommand
  builtin/rerere: turn "remaining" into a proper subcommand
  builtin/rerere: turn "status" into a proper subcommand
  builtin/rerere: turn "clear" into a proper subcommand
  builtin/rerere: turn "forget" into a proper subcommand
  builtin/rerere: stop passing flags to subcommands that ignore them
  builtin/rerere: drop `the_repository`
  rerere: convert flags into an enum
  rerere: rename `repo_rerere()`

The 'test-chmtime' test helper has been updated to use the standard
'parse_options()' API for command-line argument parsing,
simplifying the code and standardizing option handling.

* sm/test-chmtime-parse-options:
  test-chmtime: use parse_options() to parse command-line flags

The unit-test execution has been refactored to run inside a regular
'test-lib.sh' shell script, which allows unit tests to benefit from
standard test setup like sanitizer options and logging.  The test
suite's interaction with external TAP generators and JUnit XML
reporting has also been cleaned up and simplified.

* jk/unit-tests-via-test-lib:
  test-lib: drop the shell JUnit XML reporting code
  test-tool: drop the run-command testsuite mode
  t: drop redundant unit-test invocations
  t: run clar unit tests through test-lib.sh
  test-lib: allow an external program to supply TAP output
  test-lib: stop inventing a JUnit testcase for empty suites
  test-lib: drop unused test_external_has_tap variable
  unit-tests: report the correct unexpected argument

The documentation for '.gitignore' has been updated to clarify how
wildcard characters like the asterisk and question mark behave,
without relying on external references to the fnmatch(3) or glob(7)
manuals.

* jc/doc-gitignore-wildcard:
  gitignore: rewrite wildcard description

'git describe' has been taught to use commit generation numbers when
available to accurately calculate commit distance even when commit
dates are skewed.

* lt/describe-commit-date-skew:
  describe: count the distance correctly when commit dates are skewed

The 'git repo info' command has been taught more keys to output
paths of various repository components (such as the working tree
root, superproject working tree, object database, etc.), supporting
both absolute and relative path formats.

* kj/repo-info-more-path-keys:
  repo: add path.cdup
  repo: add path.git-prefix
  repo: add path.index with absolute and relative suffixes
  repo: add path.hooks with absolute and relative suffixes
  repo: add path.superproject-root with absolute and relative suffixes
  submodule: use repository to find superproject
  repo: add path.toplevel with absolute and relative suffix formatting

The parser for hex object names has been updated to reject uppercase
hexadecimal characters when running in the breaking changes mode, in
preparation for Git 3.0.

* bc/restrict-hex-to-lowercase:
  hex: allow only lowercase object IDs in breaking changes mode
  t5324: adjust tests for corrupt commit-graph
  object-name: use hexval
  hex: label usages of hex parsing for object IDs
  hex: make hex_to_bytes accept kind of hex to use
  hex: allow specifying hex type with hex2chr
  hex: add functionality for lowercase-only hex

The default fetch negotiator has been updated to stop relying on the
global 'the_repository' variable and instead use the repository
context passed during its initialization.

* oa/negotiator-default-no-the-repository:
  negotiator/default: stop using the_repository

The forwarding of the '--force-with-lease' option when pushing to a
remote group has been fixed to ensure that both bare
'--force-with-lease' and '--force-with-lease=<ref>:' forms are
correctly passed to the underlying push commands.

* tc/push-multiple-force-with-lease:
  push: fix --force-with-lease forwarding in push_multiple()

The manual page linter has been extended to ensure that concept
guides and interface manuals listed in the documentation makefile
are also properly featured in the command list.

* ta/command-list-guides-sync-lint:
  lint-docs: check the guide list in command-list.txt
  command-list.txt: add gitformat-loose(5) and gitpacking(7)

The GitLab CI and testing frameworks have been optimized to reduce
execution time, bypassing some intermediate artifact extraction and
redundant processes, and utilizing reftables to speed up tests
dealing with large number of references.

* ps/ci-speedups:
  t5551: use reftables for repositories with many refs
  t1092: set up repositories from templates
  t0027: cache expected output files
  t0027: optimize how we reset repository state
  ci: build optimized binaries with Meson
  gitlab-ci: exclude intermediate outputs from Windows artifacts
  gitlab-ci: speed up installation of Git for Windows SDK

The object format initialization in 'git init' has been updated to
use the default hash algorithm compiled into the binary, ensuring
new repositories use 'sha256' when breaking changes are enabled.

* bc/setup-default-hash-algo:
  setup: default hash algo to GIT_HASH_DEFAULT

The EXAMPLES section of the 'git diff' manual page has been  rewritten
to use a more readable cheat-sheet format, incorporating  commonly
used examples while preserving historical examples.

* je/doc-git-diff-examples:
  SQUASH???
  SQUASH???
  SQUASH???
  doc: git-diff: rewrite EXAMPLES section

Various commands have been updated to check for missing configuration
values (where a config key is provided without an '=' sign) to prevent
NULL pointer dereferences in config callbacks.

* tb/config-null-values:
  config: handle NULL values when listing colors and expiry dates
  bundle-uri: handle NULL values in bundle lists
  config: handle NULL value for remote URLs in hasconfig includes
  scalar: handle NULL value for scalar.repo
  pseudo-merge: handle NULL value for bitmapPseudoMerge.<name>.pattern
  setup: handle NULL value for safe.bareRepository
  remote: handle NULL value for remotes.<group>
  merge: handle NULL value for branch.<name>.mergeOptions
  blame: handle NULL values for color.blame.* config
  remote: handle NULL value for remote.<name>.tagOpt
  grep: handle NULL value for grep.patternType
  bundle-uri: handle NULL value for fetch.bundleCreationToken
  add-patch: handle NULL value for color slots
  odb: handle NULL values for core.alternateRefs* config
  rebase -i: handle NULL value for rebase.missingCommitsCheck

'git checkout' to switch back from a detached HEAD state can spend a
lot of time computing what commits are left behind.  A configuration
variable is introduced to skip computing the list of orphaned commits.

* wh/checkout-orphaned-commit-warning:
  SQUASH???
  scalar: disable orphaned commit checks by default
  checkout: advise when orphaned commit checks are slow
  checkout: make orphaned commit checks configurable

The test for 'git worktree prune' in 't2401' has been updated to
avoid using 'sed' string substitution to mutate worktree paths,
fixing a failure when the trash directory path itself contains the
substring 'w2'.

* ak/t2401-w2-path-fix:
  t2401: fix misfiring substitution when path contains w2

Remove unnecessary blank line in Coverity workflow.