git/Documentation/git.txt, branch v2.48.2

Merge branch 'mh/doc-windows-home-env'

2025-01-06T16:23:29Z

Docfix. * mh/doc-windows-home-env: git.txt: fix heading line of tildes

git.txt: fix heading line of tildes

2025-01-03T16:23:10Z

The two-line heading added in 8525e92886 (Document HOME environment variable, 2024-12-09) uses too many tilde characters, so the heading isn't detected as such. Both AsciiDoc and Asciidoctor end up misrendering this in different ways. Use the correct number of tilde characters to fix this. Signed-off-by: Martin Ågren Signed-off-by: Junio C Hamano

Merge branch 'mh/doc-windows-home-env'

2024-12-19T18:58:32Z

Doc update. * mh/doc-windows-home-env: Document HOME environment variable

Document HOME environment variable

2024-12-09T23:47:55Z

Git documentation refers to $HOME and $XDG_CONFIG_HOME often, but does not specify how or where these values come from on Windows where neither is set by default. The new documentation reflects the behavior of setup_windows_environment() in compat/mingw.c. Signed-off-by: Alejandro Barreto Signed-off-by: M Hickford Signed-off-by: Junio C Hamano

Documentation: allow sourcing generated includes from separate dir

2024-12-06T22:52:12Z

Our documentation uses "include::" directives to include parts that are either reused across multiple documents or parts that we generate at build time. Unfortunately, top-level includes are only ever resolved relative to the base directory, which is typically the directory of the including document. Most importantly, it is not possible to have either asciidoc or asciidoctor search multiple directories. It follows that both kinds of includes must live in the same directory. This is of course a bummer for out-of-tree builds, because here the dynamically-built includes live in the build directory whereas the static includes live in the source directory. Introduce a `build_dir` attribute and prepend it to all of our includes for dynamically-built files. This attribute gets set to the build directory and thus converts the include path to an absolute path, which asciidoc and asciidoctor know how to resolve. Note that this change also requires us to update "build-docdep.perl", which tries to figure out included files such our Makefile can set up proper build-time dependencies. This script simply scans through the source files for any lines that match "^include::" and treats the remainder of the line as included file path. But given that those may now contain the "{build_dir}" variable we have to teach the script to replace that attribute with the actual build directory. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano

advice: recommend GIT_ADVICE=0 for tools

2024-09-06T21:15:16Z

The GIT_ADVICE environment variable was added implicitly in b79deeb5544 (advice: add --no-advice global option, 2024-05-03) but was not documented. Add documentation to show that it is an option for tools that want to disable these messages. Make note that while the --no-advice option exists, older Git versions will fail to parse that option. The environment variable presents a way to change the behavior of Git versions that understand it without disrupting older versions. Co-authored-by: Junio C Hamano Signed-off-by: Derrick Stolee Signed-off-by: Junio C Hamano

diff: let external diffs report that changes are uninteresting

2024-06-10T16:20:46Z

The options --exit-code and --quiet instruct git diff to indicate whether it found any significant changes by exiting with code 1 if it did and 0 if there were none. Currently this doesn't work if external diff programs are involved, as we have no way to learn what they found. Add that ability in the form of the new configuration options diff.trustExitCode and diff..trustExitCode and the environment variable GIT_EXTERNAL_DIFF_TRUST_EXIT_CODE. They pair with the config options diff.external and diff..command and the environment variable GIT_EXTERNAL_DIFF, respectively. The new options are off by default, keeping the old behavior. Enabling them indicates that the external diff returns exit code 1 if it finds significant changes and 0 if it doesn't, like diff(1). The name of the new options is taken from the git difftool and mergetool options of similar purpose. (There they enable passing on the exit code of a diff tool and to infer whether a merge done by a merge tool is successful.) The new feature sets the diff flag diff_from_contents in diff_setup_done() if we need the exit code and are allowed to call external diffs. This disables the optimization that avoids calling the program with --quiet. Add it back by skipping the call if the external diff is not able to report empty diffs. We can only do that check after evaluating the file-specific attributes in run_external_diff(). If we do run the external diff with --quiet, send its output to /dev/null. I considered checking the output of the external diff to check whether its empty. It was added as 11be65cfa4 (diff: fix --exit-code with external diff, 2024-05-05) and quickly reverted, as it does not work with external diffs that do not write to stdout. There's no reason why a graphical diff tool would even need to write anything there at all. I also considered using a non-zero exit code for empty diffs, which could be done without adding new configuration options. We'd need to disable the optimization that allows git diff --quiet to skip calling external diffs, though -- that might be quite surprising if graphical diff programs are involved. And assigning the opposite meaning of the exit codes compared to diff(1) and git diff --exit-code to the external diff can cause unnecessary confusion. Suggested-by: Phillip Wood Signed-off-by: René Scharfe Signed-off-by: Junio C Hamano

Merge branch 'jl/git-no-advice'

2024-05-16T17:10:13Z

A new global "--no-advice" option can be used to disable all advice messages, which is meant to be used only in scripts. * jl/git-no-advice: t0018: two small fixes advice: add --no-advice global option doc: add spacing around paginate options doc: clean up usage documentation for --no-* opts

advice: add --no-advice global option

2024-05-03T17:36:59Z

Advice hints must be disabled individually by setting the relevant advice.* variables to false in the Git configuration. For server-side and scripted usages of Git where hints can be a hindrance, it can be cumbersome to maintain configuration to ensure all advice hints are disabled in perpetuity. This is a particular concern in tests, where new or changed hints can result in failed assertions. Add a --no-advice global option to disable all advice hints from being displayed. This is independent of the toggles for individual advice hints. Use an internal environment variable (GIT_ADVICE) to ensure this configuration is propagated to the usage site, even if it executes in a subprocess. Signed-off-by: James Liu Signed-off-by: Junio C Hamano

doc: add spacing around paginate options

2024-05-03T17:33:12Z

Make the documentation page consistent with the usage string printed by "git help git" and consistent with the description of "[-v | --version]" option. Signed-off-by: James Liu Signed-off-by: Junio C Hamano