Merge branch 'tb/precompose-getcwd' into maint-2.45
We forgot to normalize the result of getcwd() to NFC on macOS where
all other paths are normalized, which has been corrected. This still
does not address the case where core.precomposeUnicode configuration
is not defined globally.
* tb/precompose-getcwd:
macOS: ls-files path fails if path of workdir is NFD
diff --git a/.cirrus.yml b/.cirrus.yml
index 4860beb..77346a4 100644
--- a/.cirrus.yml
+++ b/.cirrus.yml
@@ -1,7 +1,7 @@
env:
CIRRUS_CLONE_DEPTH: 1
-freebsd_12_task:
+freebsd_task:
env:
GIT_PROVE_OPTS: "--timer --jobs 10"
GIT_TEST_OPTS: "--no-chain-lint --no-bin-wrappers"
@@ -9,7 +9,7 @@
DEFAULT_TEST_TARGET: prove
DEVELOPER: 1
freebsd_instance:
- image_family: freebsd-12-3
+ image_family: freebsd-13-2
memory: 2G
install_script:
pkg install -y gettext gmake perl5
@@ -19,4 +19,4 @@
build_script:
- su git -c gmake
test_script:
- - su git -c 'gmake test'
+ - su git -c 'gmake DEFAULT_UNIT_TEST_TARGET=unit-tests-prove test unit-tests'
diff --git a/.clang-format b/.clang-format
index c592dda..3ed4fac 100644
--- a/.clang-format
+++ b/.clang-format
@@ -83,9 +83,9 @@
BreakBeforeBraces: Linux
# Break after operators
-# int valuve = aaaaaaaaaaaaa +
-# bbbbbb -
-# ccccccccccc;
+# int value = aaaaaaaaaaaaa +
+# bbbbbb -
+# ccccccccccc;
BreakBeforeBinaryOperators: None
BreakBeforeTernaryOperators: false
diff --git a/.editorconfig b/.editorconfig
index f9d8196..15d6cbe 100644
--- a/.editorconfig
+++ b/.editorconfig
@@ -4,7 +4,7 @@
# The settings for C (*.c and *.h) files are mirrored in .clang-format. Keep
# them in sync.
-[*.{c,h,sh,perl,pl,pm,txt}]
+[{*.{c,h,sh,perl,pl,pm,txt},config.mak.*,Makefile}]
indent_style = tab
tab_width = 8
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 952c7c3..37654cd 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -4,4 +4,7 @@
bug reports. Nevertheless, you can use GitGitGadget (https://gitgitgadget.github.io/)
to conveniently send your Pull Requests commits to our mailing list.
+For a single-commit pull request, please *leave the pull request description
+empty*: your commit message itself should describe your changes.
+
Please read the "guidelines for contributing" linked above!
diff --git a/.github/workflows/check-whitespace.yml b/.github/workflows/check-whitespace.yml
index a58e2dc..a241a63 100644
--- a/.github/workflows/check-whitespace.yml
+++ b/.github/workflows/check-whitespace.yml
@@ -19,7 +19,7 @@
check-whitespace:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v4
with:
fetch-depth: 0
diff --git a/.github/workflows/coverity.yml b/.github/workflows/coverity.yml
index e5532d3..53cf12f 100644
--- a/.github/workflows/coverity.yml
+++ b/.github/workflows/coverity.yml
@@ -38,7 +38,7 @@
COVERITY_LANGUAGE: cxx
COVERITY_PLATFORM: overridden-below
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v4
- name: install minimal Git for Windows SDK
if: contains(matrix.os, 'windows')
uses: git-for-windows/setup-git-for-windows-sdk@v1
@@ -98,7 +98,7 @@
# A cache miss will add ~30s to create, but a cache hit will save minutes.
- name: restore the Coverity Build Tool
id: cache
- uses: actions/cache/restore@v3
+ uses: actions/cache/restore@v4
with:
path: ${{ runner.temp }}/cov-analysis
key: cov-build-${{ env.COVERITY_LANGUAGE }}-${{ env.COVERITY_PLATFORM }}-${{ steps.lookup.outputs.hash }}
@@ -141,7 +141,7 @@
esac
- name: cache the Coverity Build Tool
if: steps.cache.outputs.cache-hit != 'true'
- uses: actions/cache/save@v3
+ uses: actions/cache/save@v4
with:
path: ${{ runner.temp }}/cov-analysis
key: cov-build-${{ env.COVERITY_LANGUAGE }}-${{ env.COVERITY_PLATFORM }}-${{ steps.lookup.outputs.hash }}
diff --git a/.github/workflows/l10n.yml b/.github/workflows/l10n.yml
index 6c38496..e2c3dbd 100644
--- a/.github/workflows/l10n.yml
+++ b/.github/workflows/l10n.yml
@@ -63,9 +63,10 @@
origin \
${{ github.ref }} \
$args
- - uses: actions/setup-go@v2
+ - uses: actions/setup-go@v5
with:
go-version: '>=1.16'
+ cache: false
- name: Install git-po-helper
run: go install github.com/git-l10n/git-po-helper@main
- name: Install other dependencies
@@ -91,14 +92,13 @@
cat git-po-helper.out
exit $exit_code
- name: Create comment in pull request for report
- uses: mshick/add-pr-comment@v1
+ uses: mshick/add-pr-comment@v2
if: >-
always() &&
github.event_name == 'pull_request_target' &&
env.COMMENT_BODY != ''
with:
repo-token: ${{ secrets.GITHUB_TOKEN }}
- repo-token-user-login: 'github-actions[bot]'
message: >
${{ steps.check-commits.outcome == 'failure' && 'Errors and warnings' || 'Warnings' }}
found by [git-po-helper](https://github.com/git-l10n/git-po-helper#readme) in workflow
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index dcf7d78..8922bd7 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -63,7 +63,7 @@
echo "skip_concurrent=$skip_concurrent" >>$GITHUB_OUTPUT
- name: skip if the commit or tree was already tested
id: skip-if-redundant
- uses: actions/github-script@v6
+ uses: actions/github-script@v7
if: steps.check-ref.outputs.enabled == 'yes'
with:
github-token: ${{secrets.GITHUB_TOKEN}}
@@ -112,7 +112,7 @@
group: windows-build-${{ github.ref }}
cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }}
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v4
- uses: git-for-windows/setup-git-for-windows-sdk@v1
- name: build
shell: bash
@@ -123,7 +123,7 @@
- name: zip up tracked files
run: git archive -o artifacts/tracked.tar.gz HEAD
- name: upload tracked files and build artifacts
- uses: actions/upload-artifact@v3
+ uses: actions/upload-artifact@v4
with:
name: windows-artifacts
path: artifacts
@@ -140,7 +140,7 @@
cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }}
steps:
- name: download tracked files and build artifacts
- uses: actions/download-artifact@v3
+ uses: actions/download-artifact@v4
with:
name: windows-artifacts
path: ${{github.workspace}}
@@ -157,9 +157,9 @@
run: ci/print-test-failures.sh
- name: Upload failed tests' directories
if: failure() && env.FAILED_TEST_ARTIFACTS != ''
- uses: actions/upload-artifact@v3
+ uses: actions/upload-artifact@v4
with:
- name: failed-tests-windows
+ name: failed-tests-windows-${{ matrix.nr }}
path: ${{env.FAILED_TEST_ARTIFACTS}}
vs-build:
name: win+VS build
@@ -173,10 +173,10 @@
group: vs-build-${{ github.ref }}
cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }}
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v4
- uses: git-for-windows/setup-git-for-windows-sdk@v1
- name: initialize vcpkg
- uses: actions/checkout@v3
+ uses: actions/checkout@v4
with:
repository: 'microsoft/vcpkg'
path: 'compat/vcbuild/vcpkg'
@@ -212,7 +212,7 @@
- name: zip up tracked files
run: git archive -o artifacts/tracked.tar.gz HEAD
- name: upload tracked files and build artifacts
- uses: actions/upload-artifact@v3
+ uses: actions/upload-artifact@v4
with:
name: vs-artifacts
path: artifacts
@@ -230,7 +230,7 @@
steps:
- uses: git-for-windows/setup-git-for-windows-sdk@v1
- name: download tracked files and build artifacts
- uses: actions/download-artifact@v3
+ uses: actions/download-artifact@v4
with:
name: vs-artifacts
path: ${{github.workspace}}
@@ -248,9 +248,9 @@
run: ci/print-test-failures.sh
- name: Upload failed tests' directories
if: failure() && env.FAILED_TEST_ARTIFACTS != ''
- uses: actions/upload-artifact@v3
+ uses: actions/upload-artifact@v4
with:
- name: failed-tests-windows
+ name: failed-tests-windows-vs-${{ matrix.nr }}
path: ${{env.FAILED_TEST_ARTIFACTS}}
regular:
name: ${{matrix.vector.jobname}} (${{matrix.vector.pool}})
@@ -266,6 +266,9 @@
- jobname: linux-sha256
cc: clang
pool: ubuntu-latest
+ - jobname: linux-reftable
+ cc: clang
+ pool: ubuntu-latest
- jobname: linux-gcc
cc: gcc
cc_package: gcc-8
@@ -276,17 +279,22 @@
pool: ubuntu-20.04
- jobname: osx-clang
cc: clang
- pool: macos-12
+ pool: macos-13
+ - jobname: osx-reftable
+ cc: clang
+ pool: macos-13
- jobname: osx-gcc
- cc: gcc
- cc_package: gcc-9
- pool: macos-12
+ cc: gcc-13
+ pool: macos-13
- jobname: linux-gcc-default
cc: gcc
pool: ubuntu-latest
- jobname: linux-leaks
cc: gcc
pool: ubuntu-latest
+ - jobname: linux-reftable-leaks
+ cc: gcc
+ pool: ubuntu-latest
- jobname: linux-asan-ubsan
cc: clang
pool: ubuntu-latest
@@ -297,7 +305,7 @@
runs_on_pool: ${{matrix.vector.pool}}
runs-on: ${{matrix.vector.pool}}
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v4
- run: ci/install-dependencies.sh
- run: ci/run-build-and-tests.sh
- name: print test failures
@@ -305,10 +313,21 @@
run: ci/print-test-failures.sh
- name: Upload failed tests' directories
if: failure() && env.FAILED_TEST_ARTIFACTS != ''
- uses: actions/upload-artifact@v3
+ uses: actions/upload-artifact@v4
with:
name: failed-tests-${{matrix.vector.jobname}}
path: ${{env.FAILED_TEST_ARTIFACTS}}
+ fuzz-smoke-test:
+ name: fuzz smoke test
+ needs: ci-config
+ if: needs.ci-config.outputs.enabled == 'yes'
+ env:
+ CC: clang
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - run: ci/install-dependencies.sh
+ - run: ci/run-build-and-minimal-fuzzers.sh
dockerized:
name: ${{matrix.vector.jobname}} (${{matrix.vector.image}})
needs: ci-config
@@ -331,9 +350,9 @@
runs-on: ubuntu-latest
container: ${{matrix.vector.image}}
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v4
if: matrix.vector.jobname != 'linux32'
- - uses: actions/checkout@v1
+ - uses: actions/checkout@v1 # cannot be upgraded because Node.js Actions aren't supported in this container
if: matrix.vector.jobname == 'linux32'
- run: ci/install-docker-dependencies.sh
- run: ci/run-build-and-tests.sh
@@ -342,13 +361,13 @@
run: ci/print-test-failures.sh
- name: Upload failed tests' directories
if: failure() && env.FAILED_TEST_ARTIFACTS != '' && matrix.vector.jobname != 'linux32'
- uses: actions/upload-artifact@v3
+ uses: actions/upload-artifact@v4
with:
name: failed-tests-${{matrix.vector.jobname}}
path: ${{env.FAILED_TEST_ARTIFACTS}}
- name: Upload failed tests' directories
if: failure() && env.FAILED_TEST_ARTIFACTS != '' && matrix.vector.jobname == 'linux32'
- uses: actions/upload-artifact@v1
+ uses: actions/upload-artifact@v1 # cannot be upgraded because Node.js Actions aren't supported in this container
with:
name: failed-tests-${{matrix.vector.jobname}}
path: ${{env.FAILED_TEST_ARTIFACTS}}
@@ -362,7 +381,7 @@
group: static-analysis-${{ github.ref }}
cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }}
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v4
- run: ci/install-dependencies.sh
- run: ci/run-static-analysis.sh
- run: ci/check-directional-formatting.bash
@@ -385,7 +404,7 @@
artifact: sparse-20.04
- name: Install the current `sparse` package
run: sudo dpkg -i sparse-20.04/sparse_*.deb
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v4
- name: Install other dependencies
run: ci/install-dependencies.sh
- run: make sparse
@@ -400,6 +419,6 @@
jobname: Documentation
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v4
- run: ci/install-dependencies.sh
- run: ci/test-documentation.sh
diff --git a/.gitignore b/.gitignore
index 5e56e47..612c0f6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -135,6 +135,7 @@
/git-remote-ext
/git-repack
/git-replace
+/git-replay
/git-request-pull
/git-rerere
/git-reset
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
new file mode 100644
index 0000000..c0fa2fe
--- /dev/null
+++ b/.gitlab-ci.yml
@@ -0,0 +1,104 @@
+default:
+ timeout: 2h
+
+workflow:
+ rules:
+ - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+ - if: $CI_COMMIT_TAG
+ - if: $CI_COMMIT_REF_PROTECTED == "true"
+
+test:linux:
+ image: $image
+ before_script:
+ - ./ci/install-docker-dependencies.sh
+ script:
+ - useradd builder --create-home
+ - chown -R builder "${CI_PROJECT_DIR}"
+ - sudo --preserve-env --set-home --user=builder ./ci/run-build-and-tests.sh
+ after_script:
+ - |
+ if test "$CI_JOB_STATUS" != 'success'
+ then
+ sudo --preserve-env --set-home --user=builder ./ci/print-test-failures.sh
+ fi
+ parallel:
+ matrix:
+ - jobname: linux-sha256
+ image: ubuntu:latest
+ CC: clang
+ - jobname: linux-reftable
+ image: ubuntu:latest
+ CC: clang
+ - jobname: linux-gcc
+ image: ubuntu:20.04
+ CC: gcc
+ CC_PACKAGE: gcc-8
+ - jobname: linux-TEST-vars
+ image: ubuntu:20.04
+ CC: gcc
+ CC_PACKAGE: gcc-8
+ - jobname: linux-gcc-default
+ image: ubuntu:latest
+ CC: gcc
+ - jobname: linux-leaks
+ image: ubuntu:latest
+ CC: gcc
+ - jobname: linux-reftable-leaks
+ image: ubuntu:latest
+ CC: gcc
+ - jobname: linux-asan-ubsan
+ image: ubuntu:latest
+ CC: clang
+ - jobname: pedantic
+ image: fedora:latest
+ - jobname: linux-musl
+ image: alpine:latest
+ artifacts:
+ paths:
+ - t/failed-test-artifacts
+ when: on_failure
+
+test:osx:
+ image: $image
+ tags:
+ - saas-macos-medium-m1
+ variables:
+ TEST_OUTPUT_DIRECTORY: "/Volumes/RAMDisk"
+ before_script:
+ # Create a 4GB RAM disk that we use to store test output on. This small hack
+ # significantly speeds up tests by more than a factor of 2 because the
+ # macOS runners use network-attached storage as disks, which is _really_
+ # slow with the many small writes that our tests do.
+ - sudo diskutil apfs create $(hdiutil attach -nomount ram://8192000) RAMDisk
+ - ./ci/install-dependencies.sh
+ script:
+ - ./ci/run-build-and-tests.sh
+ after_script:
+ - |
+ if test "$CI_JOB_STATUS" != 'success'
+ then
+ ./ci/print-test-failures.sh
+ mv "$TEST_OUTPUT_DIRECTORY"/failed-test-artifacts t/
+ fi
+ parallel:
+ matrix:
+ - jobname: osx-clang
+ image: macos-13-xcode-14
+ CC: clang
+ - jobname: osx-reftable
+ image: macos-13-xcode-14
+ CC: clang
+ artifacts:
+ paths:
+ - t/failed-test-artifacts
+ when: on_failure
+
+static-analysis:
+ image: ubuntu:22.04
+ variables:
+ jobname: StaticAnalysis
+ before_script:
+ - ./ci/install-docker-dependencies.sh
+ script:
+ - ./ci/run-static-analysis.sh
+ - ./ci/check-directional-formatting.bash
diff --git a/.mailmap b/.mailmap
index dc31d70..18128a1 100644
--- a/.mailmap
+++ b/.mailmap
@@ -59,9 +59,9 @@
David S. Miller <davem@davemloft.net>
David Turner <novalis@novalis.org> <dturner@twopensource.com>
David Turner <novalis@novalis.org> <dturner@twosigma.com>
-Derrick Stolee <derrickstolee@github.com> <stolee@gmail.com>
-Derrick Stolee <derrickstolee@github.com> Derrick Stolee via GitGitGadget <gitgitgadget@gmail.com>
-Derrick Stolee <derrickstolee@github.com> <dstolee@microsoft.com>
+Derrick Stolee <stolee@gmail.com> <derrickstolee@github.com>
+Derrick Stolee <stolee@gmail.com> Derrick Stolee via GitGitGadget <gitgitgadget@gmail.com>
+Derrick Stolee <stolee@gmail.com> <dstolee@microsoft.com>
Deskin Miller <deskinm@umich.edu>
Đoàn Trần Công Danh <congdanhqx@gmail.com> Doan Tran Cong Danh
Dirk Süsserott <newsletter@dirk.my1.cc>
@@ -152,6 +152,7 @@
Lars Doelle <lars.doelle@on-line.de>
Lars Noschinski <lars@public.noschinski.de> <lars.noschinski@rwth-aachen.de>
Li Hong <leehong@pku.edu.cn>
+Linus Arver <linus@ucla.edu> <linusa@google.com>
Linus Torvalds <torvalds@linux-foundation.org> <torvalds@evo.osdl.org>
Linus Torvalds <torvalds@linux-foundation.org> <torvalds@g5.osdl.org>
Linus Torvalds <torvalds@linux-foundation.org> <torvalds@osdl.org>
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
index 0215b1f..e58917c 100644
--- a/CODE_OF_CONDUCT.md
+++ b/CODE_OF_CONDUCT.md
@@ -130,11 +130,11 @@
version 2.0, available at
[https://www.contributor-covenant.org/version/2/0/code_of_conduct.html][v2.0].
-Community Impact Guidelines were inspired by
+Community Impact Guidelines were inspired by
[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
For answers to common questions about this code of conduct, see the FAQ at
-[https://www.contributor-covenant.org/faq][FAQ]. Translations are available
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available
at [https://www.contributor-covenant.org/translations][translations].
[homepage]: https://www.contributor-covenant.org
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 9495df8..1d92b2d 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -1,5 +1,5 @@
-Like other projects, we also have some guidelines to keep to the
-code. For Git in general, a few rough rules are:
+Like other projects, we also have some guidelines for our code. For
+Git in general, a few rough rules are:
- Most importantly, we never say "It's in POSIX; we'll happily
ignore your needs should your system not conform to it."
@@ -40,7 +40,7 @@
contributing to). It is always preferable to match the _local_
convention. New code added to Git suite is expected to match
the overall style of existing code. Modifications to existing
-code is expected to match the style the surrounding code already
+code are expected to match the style the surrounding code already
uses (even if it doesn't match the overall style of existing code).
But if you must have a list of rules, here are some language
@@ -188,6 +188,22 @@
hopefully nobody starts using "local" before they are reimplemented
in C ;-)
+ - Some versions of shell do not understand "export variable=value",
+ so we write "variable=value" and then "export variable" on two
+ separate lines.
+
+ - Some versions of dash have broken variable assignment when prefixed
+ with "local", "export", and "readonly", in that the value to be
+ assigned goes through field splitting at $IFS unless quoted.
+
+ (incorrect)
+ local variable=$value
+ local variable=$(command args)
+
+ (correct)
+ local variable="$value"
+ local variable="$(command args)"
+
- Use octal escape sequences (e.g. "\302\242"), not hexadecimal (e.g.
"\xc2\xa2") in printf format strings, since hexadecimal escape
sequences are not portable.
@@ -446,12 +462,41 @@
detail.
- The first #include in C files, except in platform specific compat/
- implementations and sha1dc/, must be either "git-compat-util.h" or
- one of the approved headers that includes it first for you. (The
- approved headers currently include "builtin.h",
- "t/helper/test-tool.h", "xdiff/xinclude.h", or
- "reftable/system.h"). You do not have to include more than one of
- these.
+ implementations and sha1dc/, must be <git-compat-util.h>. This
+ header file insulates other header files and source files from
+ platform differences, like which system header files must be
+ included in what order, and what C preprocessor feature macros must
+ be defined to trigger certain features we expect out of the system.
+ A collorary to this is that C files should not directly include
+ system header files themselves.
+
+ There are some exceptions, because certain group of files that
+ implement an API all have to include the same header file that
+ defines the API and it is convenient to include <git-compat-util.h>
+ there. Namely:
+
+ - the implementation of the built-in commands in the "builtin/"
+ directory that include "builtin.h" for the cmd_foo() prototype
+ definition,
+
+ - the test helper programs in the "t/helper/" directory that include
+ "t/helper/test-tool.h" for the cmd__foo() prototype definition,
+
+ - the xdiff implementation in the "xdiff/" directory that includes
+ "xdiff/xinclude.h" for the xdiff machinery internals,
+
+ - the unit test programs in "t/unit-tests/" directory that include
+ "t/unit-tests/test-lib.h" that gives them the unit-tests
+ framework, and
+
+ - the source files that implement reftable in the "reftable/"
+ directory that include "reftable/system.h" for the reftable
+ internals,
+
+ are allowed to assume that they do not have to include
+ <git-compat-util.h> themselves, as it is included as the first
+ '#include' in these header files. These headers must be the first
+ header file to be "#include"d in them, though.
- A C file must directly include the header files that declare the
functions and the types it uses, except for the functions and types
@@ -490,7 +535,7 @@
- Most of the C guidelines above apply.
- - We try to support Perl 5.8 and later ("use Perl 5.008").
+ - We try to support Perl 5.8.1 and later ("use Perl 5.008001").
- use strict and use warnings are strongly preferred.
@@ -518,7 +563,7 @@
For Python scripts:
- - We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/).
+ - We follow PEP-8 (https://peps.python.org/pep-0008/).
- As a minimum, we aim to be compatible with Python 2.7.
@@ -578,7 +623,7 @@
. The variable name describes the effect of tweaking this knob.
The section and variable names that consist of multiple words are
- formed by concatenating the words without punctuations (e.g. `-`),
+ formed by concatenating the words without punctuation marks (e.g. `-`),
and are broken using bumpyCaps in documentation as a hint to the
reader.
@@ -612,15 +657,15 @@
- Prefer succinctness and matter-of-factly describing functionality
in the abstract. E.g.
- --short:: Emit output in the short-format.
+ `--short`:: Emit output in the short-format.
and avoid something like these overly verbose alternatives:
- --short:: Use this to emit output in the short-format.
- --short:: You can use this to get output in the short-format.
- --short:: A user who prefers shorter output could....
- --short:: Should a person and/or program want shorter output, he
- she/they/it can...
+ `--short`:: Use this to emit output in the short-format.
+ `--short`:: You can use this to get output in the short-format.
+ `--short`:: A user who prefers shorter output could....
+ `--short`:: Should a person and/or program want shorter output, he
+ she/they/it can...
This practice often eliminates the need to involve human actors in
your description, but it is a good practice regardless of the
@@ -630,12 +675,12 @@
addressing the hypothetical user, and possibly "we" when
discussing how the program might react to the user. E.g.
- You can use this option instead of --xyz, but we might remove
+ You can use this option instead of `--xyz`, but we might remove
support for it in future versions.
while keeping in mind that you can probably be less verbose, e.g.
- Use this instead of --xyz. This option might be removed in future
+ Use this instead of `--xyz`. This option might be removed in future
versions.
- If you still need to refer to an example person that is
@@ -653,80 +698,12 @@
The same general rule as for code applies -- imitate the existing
conventions.
- A few commented examples follow to provide reference when writing or
- modifying command usage strings and synopsis sections in the manual
- pages:
- Placeholders are spelled in lowercase and enclosed in angle brackets:
- <file>
- --sort=<key>
- --abbrev[=<n>]
+Markup:
- If a placeholder has multiple words, they are separated by dashes:
- <new-branch-name>
- --template=<template-directory>
-
- Possibility of multiple occurrences is indicated by three dots:
- <file>...
- (One or more of <file>.)
-
- Optional parts are enclosed in square brackets:
- [<file>...]
- (Zero or more of <file>.)
-
- --exec-path[=<path>]
- (Option with an optional argument. Note that the "=" is inside the
- brackets.)
-
- [<patch>...]
- (Zero or more of <patch>. Note that the dots are inside, not
- outside the brackets.)
-
- Multiple alternatives are indicated with vertical bars:
- [-q | --quiet]
- [--utf8 | --no-utf8]
-
- Use spacing around "|" token(s), but not immediately after opening or
- before closing a [] or () pair:
- Do: [-q | --quiet]
- Don't: [-q|--quiet]
-
- Don't use spacing around "|" tokens when they're used to separate the
- alternate arguments of an option:
- Do: --track[=(direct|inherit)]
- Don't: --track[=(direct | inherit)]
-
- Parentheses are used for grouping:
- [(<rev> | <range>)...]
- (Any number of either <rev> or <range>. Parens are needed to make
- it clear that "..." pertains to both <rev> and <range>.)
-
- [(-p <parent>)...]
- (Any number of option -p, each with one <parent> argument.)
-
- git remote set-head <name> (-a | -d | <branch>)
- (One and only one of "-a", "-d" or "<branch>" _must_ (no square
- brackets) be provided.)
-
- And a somewhat more contrived example:
- --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]
- Here "=" is outside the brackets, because "--diff-filter=" is a
- valid usage. "*" has its own pair of brackets, because it can
- (optionally) be specified only when one or more of the letters is
- also provided.
-
- A note on notation:
- Use 'git' (all lowercase) when talking about commands i.e. something
- the user would type into a shell and use 'Git' (uppercase first letter)
- when talking about the version control system and its properties.
-
- A few commented examples follow to provide reference when writing or
- modifying paragraphs or option/command explanations that contain options
- or commands:
-
- Literal examples (e.g. use of command-line options, command names,
+ Literal parts (e.g. use of command-line options, command names,
branch names, URLs, pathnames (files and directories), configuration and
- environment variables) must be typeset in monospace (i.e. wrapped with
+ environment variables) must be typeset as verbatim (i.e. wrapped with
backticks):
`--pretty=oneline`
`git rev-list`
@@ -735,6 +712,7 @@
`.git/config`
`GIT_DIR`
`HEAD`
+ `umask`(2)
An environment variable must be prefixed with "$" only when referring to its
value and not when referring to the variable itself, in this case there is
@@ -751,6 +729,97 @@
Incorrect:
`\--pretty=oneline`
+ Placeholders are spelled in lowercase and enclosed in
+ angle brackets surrounded by underscores:
+ _<file>_
+ _<commit>_
+
+ If a placeholder has multiple words, they are separated by dashes:
+ _<new-branch-name>_
+ _<template-directory>_
+
+ A placeholder is not enclosed in backticks, as it is not a literal.
+
+ When needed, use a distinctive identifier for placeholders, usually
+ made of a qualification and a type:
+ _<git-dir>_
+ _<key-id>_
+
+ When literal and placeholders are mixed, each markup is applied for
+ each sub-entity. If they are stuck, a special markup, called
+ unconstrained formatting is required.
+ Unconstrained formating for placeholders is __<like-this>__
+ Unconstrained formatting for literal formatting is ++like this++
+ `--jobs` _<n>_
+ ++--sort=++__<key>__
+ __<directory>__++/.git++
+ ++remote.++__<name>__++.mirror++
+
+ caveat: ++ unconstrained format is not verbatim and may expand
+ content. Use Asciidoc escapes inside them.
+
+Synopsis Syntax
+
+ Syntax grammar is formatted neither as literal nor as placeholder.
+
+ A few commented examples follow to provide reference when writing or
+ modifying command usage strings and synopsis sections in the manual
+ pages:
+
+ Possibility of multiple occurrences is indicated by three dots:
+ _<file>_...
+ (One or more of <file>.)
+
+ Optional parts are enclosed in square brackets:
+ [_<file>_...]
+ (Zero or more of <file>.)
+
+ ++--exec-path++[++=++__<path>__]
+ (Option with an optional argument. Note that the "=" is inside the
+ brackets.)
+
+ [_<patch>_...]
+ (Zero or more of <patch>. Note that the dots are inside, not
+ outside the brackets.)
+
+ Multiple alternatives are indicated with vertical bars:
+ [`-q` | `--quiet`]
+ [`--utf8` | `--no-utf8`]
+
+ Use spacing around "|" token(s), but not immediately after opening or
+ before closing a [] or () pair:
+ Do: [`-q` | `--quiet`]
+ Don't: [`-q`|`--quiet`]
+
+ Don't use spacing around "|" tokens when they're used to separate the
+ alternate arguments of an option:
+ Do: ++--track++[++=++(`direct`|`inherit`)]`
+ Don't: ++--track++[++=++(`direct` | `inherit`)]
+
+ Parentheses are used for grouping:
+ [(_<rev>_ | _<range>_)...]
+ (Any number of either <rev> or <range>. Parens are needed to make
+ it clear that "..." pertains to both <rev> and <range>.)
+
+ [(`-p` _<parent>_)...]
+ (Any number of option -p, each with one <parent> argument.)
+
+ `git remote set-head` _<name>_ (`-a` | `-d` | _<branch>_)
+ (One and only one of "-a", "-d" or "<branch>" _must_ (no square
+ brackets) be provided.)
+
+ And a somewhat more contrived example:
+ `--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]`
+ Here "=" is outside the brackets, because "--diff-filter=" is a
+ valid usage. "*" has its own pair of brackets, because it can
+ (optionally) be specified only when one or more of the letters is
+ also provided.
+
+ A note on notation:
+ Use 'git' (all lowercase) when talking about commands i.e. something
+ the user would type into a shell and use 'Git' (uppercase first letter)
+ when talking about the version control system and its properties.
+
If some place in the documentation needs to typeset a command usage
example with inline substitutions, it is fine to use +monospaced and
inline substituted text+ instead of `monospaced literal text`, and with
diff --git a/Documentation/Makefile b/Documentation/Makefile
index b629176..3f2383a 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -122,6 +122,7 @@
TECH_DOCS += technical/send-pack-pipeline
TECH_DOCS += technical/shallow
TECH_DOCS += technical/trivial-merge
+TECH_DOCS += technical/unit-tests
SP_ARTICLES += $(TECH_DOCS)
SP_ARTICLES += technical/api-index
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 62d11a5..f06563e 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -35,8 +35,9 @@
contributing are welcome to post questions here. The Git list requires
plain-text-only emails and prefers inline and bottom-posting when replying to
mail; you will be CC'd in all replies to you. Optionally, you can subscribe to
-the list by sending an email to majordomo@vger.kernel.org with "subscribe git"
-in the body. The https://lore.kernel.org/git[archive] of this mailing list is
+the list by sending an email to <git+subscribe@vger.kernel.org>
+(see https://subspace.kernel.org/subscribing.html for details).
+The https://lore.kernel.org/git[archive] of this mailing list is
available to view in a browser.
==== https://groups.google.com/forum/#!forum/git-mentoring[git-mentoring@googlegroups.com]
@@ -160,10 +161,11 @@
int cmd_psuh(int argc, const char **argv, const char *prefix);
----
-Be sure to `#include "builtin.h"` in your `psuh.c`.
+Be sure to `#include "builtin.h"` in your `psuh.c`. You'll also need to
+`#include "gettext.h"` to use functions related to printing output text.
-Go ahead and add some throwaway printf to that function. This is a decent
-starting point as we can now add build rules and register the command.
+Go ahead and add some throwaway printf to the `cmd_psuh` function. This is a
+decent starting point as we can now add build rules and register the command.
NOTE: Your throwaway text, as well as much of the text you will be adding over
the course of this tutorial, is user-facing. That means it needs to be
@@ -832,7 +834,7 @@
the GitHub PR workflow. It allows contributors to open pull requests against its
mirror of the Git project, and does some magic to turn the PR into a set of
emails and send them out for you. It also runs the Git continuous integration
-suite for you. It's documented at http://gitgitgadget.github.io.
+suite for you. It's documented at https://gitgitgadget.github.io/.
[[create-fork]]
=== Forking `git/git` on GitHub
diff --git a/Documentation/MyFirstObjectWalk.txt b/Documentation/MyFirstObjectWalk.txt
index c68cdb1..dec8afe 100644
--- a/Documentation/MyFirstObjectWalk.txt
+++ b/Documentation/MyFirstObjectWalk.txt
@@ -210,13 +210,14 @@
...
-static int git_walken_config(const char *var, const char *value, void *cb)
+static int git_walken_config(const char *var, const char *value,
+ const struct config_context *ctx, void *cb)
{
/*
* For now, we don't have any custom configuration, so fall back to
* the default config.
*/
- return git_default_config(var, value, cb);
+ return git_default_config(var, value, ctx, cb);
}
----
@@ -389,10 +390,11 @@
First some setup. Add `grep_config()` to `git_walken_config()`:
----
-static int git_walken_config(const char *var, const char *value, void *cb)
+static int git_walken_config(const char *var, const char *value,
+ const struct config_context *ctx, void *cb)
{
- grep_config(var, value, cb);
- return git_default_config(var, value, cb);
+ grep_config(var, value, ctx, cb);
+ return git_default_config(var, value, ctx, cb);
}
----
@@ -523,7 +525,7 @@
We can base our work on an example. `git pack-objects` prepares all kinds of
objects for packing into a bitmap or packfile. The work we are interested in
-resides in `builtins/pack-objects.c:get_object_list()`; examination of that
+resides in `builtin/pack-objects.c:get_object_list()`; examination of that
function shows that the all-object walk is being performed by
`traverse_commit_list()` or `traverse_commit_list_filtered()`. Those two
functions reside in `list-objects.c`; examining the source shows that, despite
@@ -732,8 +734,8 @@
} else {
trace_printf(
_("Filtered object walk with filterspec 'tree:1'.\n"));
- CALLOC_ARRAY(rev->filter, 1);
- parse_list_objects_filter(rev->filter, "tree:1");
+
+ parse_list_objects_filter(&rev->filter, "tree:1");
}
traverse_commit_list(rev, walken_show_commit,
walken_show_object, NULL);
@@ -752,10 +754,12 @@
=== Counting Omitted Objects
We also have the capability to enumerate all objects which were omitted by a
-filter, like with `git log --filter=<spec> --filter-print-omitted`. Asking
-`traverse_commit_list_filtered()` to populate the `omitted` list means that our
-object walk does not perform any better than an unfiltered object walk; all
-reachable objects are walked in order to populate the list.
+filter, like with `git log --filter=<spec> --filter-print-omitted`. To do this,
+change `traverse_commit_list()` to `traverse_commit_list_filtered()`, which is
+able to populate an `omitted` list. Asking for this list of filtered objects
+may cause performance degradations, however, because in this case, despite
+filtering objects, the possibly much larger set of all reachable objects must
+be processed in order to populate that list.
First, add the `struct oidset` and related items we will use to iterate it:
@@ -776,8 +780,9 @@
...
----
-Modify the call to `traverse_commit_list_filtered()` to include your `omitted`
-object:
+Replace the call to `traverse_commit_list()` with
+`traverse_commit_list_filtered()` and pass a pointer to the `omitted` oidset
+defined and initialized above:
----
...
@@ -843,7 +848,7 @@
With only that change, run again (but save yourself some scrollback):
----
-$ GIT_TRACE=1 ./bin-wrappers/git walken | head -n 10
+$ GIT_TRACE=1 ./bin-wrappers/git walken 2>&1 | head -n 10
----
Take a look at the top commit with `git show` and the object ID you printed; it
@@ -871,7 +876,7 @@
----
$ make
-$ GIT_TRACE=1 ./bin-wrappers git walken | tail -n 10
+$ GIT_TRACE=1 ./bin-wrappers/git walken 2>&1 | tail -n 10
----
The last commit object given should have the same OID as the one we saw at the
diff --git a/Documentation/RelNotes/1.6.2.txt b/Documentation/RelNotes/1.6.2.txt
index 980adfb..166d73c 100644
--- a/Documentation/RelNotes/1.6.2.txt
+++ b/Documentation/RelNotes/1.6.2.txt
@@ -10,7 +10,7 @@
push running this release will issue a big warning when the
configuration variable is missing. Please refer to:
- http://git.or.cz/gitwiki/GitFaq#non-bare
+ https://archive.kernel.org/oldwiki/git.wiki.kernel.org/index.php/GitFaq.html#non-bare
https://lore.kernel.org/git/7vbptlsuyv.fsf@gitster.siamese.dyndns.org/
for more details on the reason why this change is needed and the
diff --git a/Documentation/RelNotes/1.6.3.txt b/Documentation/RelNotes/1.6.3.txt
index 4bcff94..bbf177f 100644
--- a/Documentation/RelNotes/1.6.3.txt
+++ b/Documentation/RelNotes/1.6.3.txt
@@ -10,7 +10,7 @@
push running this release will issue a big warning when the
configuration variable is missing. Please refer to:
- http://git.or.cz/gitwiki/GitFaq#non-bare
+ https://archive.kernel.org/oldwiki/git.wiki.kernel.org/index.php/GitFaq.html#non-bare
https://lore.kernel.org/git/7vbptlsuyv.fsf@gitster.siamese.dyndns.org/
for more details on the reason why this change is needed and the
diff --git a/Documentation/RelNotes/1.6.4.txt b/Documentation/RelNotes/1.6.4.txt
index a2a34b4..0fccfb0 100644
--- a/Documentation/RelNotes/1.6.4.txt
+++ b/Documentation/RelNotes/1.6.4.txt
@@ -10,7 +10,7 @@
push running this release will issue a big warning when the
configuration variable is missing. Please refer to:
- http://git.or.cz/gitwiki/GitFaq#non-bare
+ https://archive.kernel.org/oldwiki/git.wiki.kernel.org/index.php/GitFaq.html#non-bare
https://lore.kernel.org/git/7vbptlsuyv.fsf@gitster.siamese.dyndns.org/
for more details on the reason why this change is needed and the
diff --git a/Documentation/RelNotes/1.6.5.txt b/Documentation/RelNotes/1.6.5.txt
index 6c7f7da..79cb1b2 100644
--- a/Documentation/RelNotes/1.6.5.txt
+++ b/Documentation/RelNotes/1.6.5.txt
@@ -21,7 +21,7 @@
push running this release will issue a big warning when the
configuration variable is missing. Please refer to:
- http://git.or.cz/gitwiki/GitFaq#non-bare
+ https://archive.kernel.org/oldwiki/git.wiki.kernel.org/index.php/GitFaq.html#non-bare
https://lore.kernel.org/git/7vbptlsuyv.fsf@gitster.siamese.dyndns.org/
for more details on the reason why this change is needed and the
diff --git a/Documentation/RelNotes/1.6.6.txt b/Documentation/RelNotes/1.6.6.txt
index 3ed1e01..88b86a8 100644
--- a/Documentation/RelNotes/1.6.6.txt
+++ b/Documentation/RelNotes/1.6.6.txt
@@ -63,7 +63,7 @@
Please refer to:
- http://git.or.cz/gitwiki/GitFaq#non-bare
+ https://archive.kernel.org/oldwiki/git.wiki.kernel.org/index.php/GitFaq.html#non-bare
https://lore.kernel.org/git/7vbptlsuyv.fsf@gitster.siamese.dyndns.org/
for more details on the reason why this change is needed and the
diff --git a/Documentation/RelNotes/2.39.4.txt b/Documentation/RelNotes/2.39.4.txt
new file mode 100644
index 0000000..7f54521
--- /dev/null
+++ b/Documentation/RelNotes/2.39.4.txt
@@ -0,0 +1,79 @@
+Git v2.39.4 Release Notes
+=========================
+
+This addresses the security issues CVE-2024-32002, CVE-2024-32004,
+CVE-2024-32020 and CVE-2024-32021.
+
+This release also backports fixes necessary to let the CI builds pass
+successfully.
+
+Fixes since v2.39.3
+-------------------
+
+ * CVE-2024-32002:
+
+ Recursive clones on case-insensitive filesystems that support symbolic
+ links are susceptible to case confusion that can be exploited to
+ execute just-cloned code during the clone operation.
+
+ * CVE-2024-32004:
+
+ Repositories can be configured to execute arbitrary code during local
+ clones. To address this, the ownership checks introduced in v2.30.3
+ are now extended to cover cloning local repositories.
+
+ * CVE-2024-32020:
+
+ Local clones may end up hardlinking files into the target repository's
+ object database when source and target repository reside on the same
+ disk. If the source repository is owned by a different user, then
+ those hardlinked files may be rewritten at any point in time by the
+ untrusted user.
+
+ * CVE-2024-32021:
+
+ When cloning a local source repository that contains symlinks via the
+ filesystem, Git may create hardlinks to arbitrary user-readable files
+ on the same filesystem as the target repository in the objects/
+ directory.
+
+ * CVE-2024-32465:
+
+ It is supposed to be safe to clone untrusted repositories, even those
+ unpacked from zip archives or tarballs originating from untrusted
+ sources, but Git can be tricked to run arbitrary code as part of the
+ clone.
+
+ * Defense-in-depth: submodule: require the submodule path to contain
+ directories only.
+
+ * Defense-in-depth: clone: when symbolic links collide with directories, keep
+ the latter.
+
+ * Defense-in-depth: clone: prevent hooks from running during a clone.
+
+ * Defense-in-depth: core.hooksPath: add some protection while cloning.
+
+ * Defense-in-depth: fsck: warn about symlink pointing inside a gitdir.
+
+ * Various fix-ups on HTTP tests.
+
+ * Test update.
+
+ * HTTP Header redaction code has been adjusted for a newer version of
+ cURL library that shows its traces differently from earlier
+ versions.
+
+ * Fix was added to work around a regression in libcURL 8.7.0 (which has
+ already been fixed in their tip of the tree).
+
+ * Replace macos-12 used at GitHub CI with macos-13.
+
+ * ci(linux-asan/linux-ubsan): let's save some time
+
+ * Tests with LSan from time to time seem to emit harmless message that makes
+ our tests unnecessarily flakey; we work it around by filtering the
+ uninteresting output.
+
+ * Update GitHub Actions jobs to avoid warnings against using deprecated
+ version of Node.js.
diff --git a/Documentation/RelNotes/2.39.5.txt b/Documentation/RelNotes/2.39.5.txt
new file mode 100644
index 0000000..97c0185
--- /dev/null
+++ b/Documentation/RelNotes/2.39.5.txt
@@ -0,0 +1,26 @@
+Git v2.39.5 Release Notes
+=========================
+
+In preparing security fixes for four CVEs, we made overly aggressive
+"defense in depth" changes that broke legitimate use cases like 'git
+lfs' and 'git annex.' This release is to revert these misguided, if
+well-intentioned, changes that were shipped in 2.39.4 and were not
+direct security fixes.
+
+Jeff King (5):
+ send-email: drop FakeTerm hack
+ send-email: avoid creating more than one Term::ReadLine object
+ ci: drop mention of BREW_INSTALL_PACKAGES variable
+ ci: avoid bare "gcc" for osx-gcc job
+ ci: stop installing "gcc-13" for osx-gcc
+
+Johannes Schindelin (6):
+ hook: plug a new memory leak
+ init: use the correct path of the templates directory again
+ Revert "core.hooksPath: add some protection while cloning"
+ tests: verify that `clone -c core.hooksPath=/dev/null` works again
+ clone: drop the protections where hooks aren't run
+ Revert "Add a helper function to compare file contents"
+
+Junio C Hamano (1):
+ Revert "fsck: warn about symlink pointing inside a gitdir"
diff --git a/Documentation/RelNotes/2.40.2.txt b/Documentation/RelNotes/2.40.2.txt
new file mode 100644
index 0000000..646a2cc
--- /dev/null
+++ b/Documentation/RelNotes/2.40.2.txt
@@ -0,0 +1,7 @@
+Git v2.40.2 Release Notes
+=========================
+
+This release merges up the fix that appears in v2.39.4 to address
+the security issues CVE-2024-32002, CVE-2024-32004, CVE-2024-32020,
+CVE-2024-32021 and CVE-2024-32465; see the release notes for that
+version for details.
diff --git a/Documentation/RelNotes/2.40.3.txt b/Documentation/RelNotes/2.40.3.txt
new file mode 100644
index 0000000..6ca088e
--- /dev/null
+++ b/Documentation/RelNotes/2.40.3.txt
@@ -0,0 +1,26 @@
+Git v2.40.3 Release Notes
+=========================
+
+In preparing security fixes for four CVEs, we made overly aggressive
+"defense in depth" changes that broke legitimate use cases like 'git
+lfs' and 'git annex.' This release is to revert these misguided, if
+well-intentioned, changes that were shipped in 2.40.2 and were not
+direct security fixes.
+
+Jeff King (5):
+ send-email: drop FakeTerm hack
+ send-email: avoid creating more than one Term::ReadLine object
+ ci: drop mention of BREW_INSTALL_PACKAGES variable
+ ci: avoid bare "gcc" for osx-gcc job
+ ci: stop installing "gcc-13" for osx-gcc
+
+Johannes Schindelin (6):
+ hook: plug a new memory leak
+ init: use the correct path of the templates directory again
+ Revert "core.hooksPath: add some protection while cloning"
+ tests: verify that `clone -c core.hooksPath=/dev/null` works again
+ clone: drop the protections where hooks aren't run
+ Revert "Add a helper function to compare file contents"
+
+Junio C Hamano (1):
+ Revert "fsck: warn about symlink pointing inside a gitdir"
diff --git a/Documentation/RelNotes/2.41.1.txt b/Documentation/RelNotes/2.41.1.txt
new file mode 100644
index 0000000..9fb4c21
--- /dev/null
+++ b/Documentation/RelNotes/2.41.1.txt
@@ -0,0 +1,7 @@
+Git v2.41.1 Release Notes
+=========================
+
+This release merges up the fix that appears in v2.39.4 and v2.40.2
+to address the security issues CVE-2024-32002, CVE-2024-32004,
+CVE-2024-32020, CVE-2024-32021 and CVE-2024-32465; see the release
+notes for these versions for details.
diff --git a/Documentation/RelNotes/2.41.2.txt b/Documentation/RelNotes/2.41.2.txt
new file mode 100644
index 0000000..f94afde
--- /dev/null
+++ b/Documentation/RelNotes/2.41.2.txt
@@ -0,0 +1,26 @@
+Git v2.41.2 Release Notes
+=========================
+
+In preparing security fixes for four CVEs, we made overly aggressive
+"defense in depth" changes that broke legitimate use cases like 'git
+lfs' and 'git annex.' This release is to revert these misguided, if
+well-intentioned, changes that were shipped in 2.41.1 and were not
+direct security fixes.
+
+Jeff King (5):
+ send-email: drop FakeTerm hack
+ send-email: avoid creating more than one Term::ReadLine object
+ ci: drop mention of BREW_INSTALL_PACKAGES variable
+ ci: avoid bare "gcc" for osx-gcc job
+ ci: stop installing "gcc-13" for osx-gcc
+
+Johannes Schindelin (6):
+ hook: plug a new memory leak
+ init: use the correct path of the templates directory again
+ Revert "core.hooksPath: add some protection while cloning"
+ tests: verify that `clone -c core.hooksPath=/dev/null` works again
+ clone: drop the protections where hooks aren't run
+ Revert "Add a helper function to compare file contents"
+
+Junio C Hamano (1):
+ Revert "fsck: warn about symlink pointing inside a gitdir"
diff --git a/Documentation/RelNotes/2.42.2.txt b/Documentation/RelNotes/2.42.2.txt
new file mode 100644
index 0000000..dbf761a
--- /dev/null
+++ b/Documentation/RelNotes/2.42.2.txt
@@ -0,0 +1,7 @@
+Git v2.42.2 Release Notes
+=========================
+
+This release merges up the fix that appears in v2.39.4, v2.40.2
+and v2.41.1 to address the security issues CVE-2024-32002,
+CVE-2024-32004, CVE-2024-32020, CVE-2024-32021 and CVE-2024-32465;
+see the release notes for these versions for details.
diff --git a/Documentation/RelNotes/2.42.3.txt b/Documentation/RelNotes/2.42.3.txt
new file mode 100644
index 0000000..bfe3ba5
--- /dev/null
+++ b/Documentation/RelNotes/2.42.3.txt
@@ -0,0 +1,26 @@
+Git v2.42.3 Release Notes
+=========================
+
+In preparing security fixes for four CVEs, we made overly aggressive
+"defense in depth" changes that broke legitimate use cases like 'git
+lfs' and 'git annex.' This release is to revert these misguided, if
+well-intentioned, changes that were shipped in 2.42.2 and were not
+direct security fixes.
+
+Jeff King (5):
+ send-email: drop FakeTerm hack
+ send-email: avoid creating more than one Term::ReadLine object
+ ci: drop mention of BREW_INSTALL_PACKAGES variable
+ ci: avoid bare "gcc" for osx-gcc job
+ ci: stop installing "gcc-13" for osx-gcc
+
+Johannes Schindelin (6):
+ hook: plug a new memory leak
+ init: use the correct path of the templates directory again
+ Revert "core.hooksPath: add some protection while cloning"
+ tests: verify that `clone -c core.hooksPath=/dev/null` works again
+ clone: drop the protections where hooks aren't run
+ Revert "Add a helper function to compare file contents"
+
+Junio C Hamano (1):
+ Revert "fsck: warn about symlink pointing inside a gitdir"
diff --git a/Documentation/RelNotes/2.43.0.txt b/Documentation/RelNotes/2.43.0.txt
new file mode 100644
index 0000000..e0e5b53
--- /dev/null
+++ b/Documentation/RelNotes/2.43.0.txt
@@ -0,0 +1,323 @@
+Git v2.43 Release Notes
+=======================
+
+Backward Compatibility Notes
+
+ * The "--rfc" option of "git format-patch" used to be a valid way to
+ override an earlier "--subject-prefix=<something>" on the command
+ line and replace it with "[RFC PATCH]", but from this release, it
+ merely prefixes the string "RFC " in front of the given subject
+ prefix. If you are negatively affected by this change, please use
+ "--subject-prefix=PATCH --rfc" as a replacement.
+
+ * In Git 2.42, "git rev-list --stdin" learned to take non-revisions
+ (like "--not") from the standard input, but the way such a "--not" was
+ handled was quite confusing, which has been rethought. The updated
+ rule is that "--not" given from the command line only affects revs
+ given from the command line that comes but not revs read from the
+ standard input, and "--not" read from the standard input affects
+ revs given from the standard input and not revs given from the
+ command line.
+
+UI, Workflows & Features
+
+ * A message written in olden time prevented a branch from getting
+ checked out, saying it is already checked out elsewhere. But these
+ days, we treat a branch that is being bisected or rebased just like
+ a branch that is checked out and protect it from getting modified
+ with the same codepath. The message has been rephrased to say that
+ the branch is "in use" to avoid confusion.
+
+ * Hourly and other schedules of "git maintenance" jobs are randomly
+ distributed now.
+
+ * "git cmd -h" learned to signal which options can be negated by
+ listing such options like "--[no-]opt".
+
+ * The way authentication related data other than passwords (e.g.,
+ oauth token and password expiration data) are stored in libsecret
+ keyrings has been rethought.
+
+ * Update the libsecret and wincred credential helpers to correctly
+ match which credential to erase; they erased the wrong entry in
+ some cases.
+
+ * Git GUI updates.
+
+ * "git format-patch" learned a new "--description-file" option that
+ lets cover letter description to be fed; this can be used on
+ detached HEAD where there is no branch description available, and
+ also can override the branch description if there is one.
+
+ * Use of the "--max-pack-size" option to allow multiple packfiles to
+ be created is now supported even when we are sending unreachable
+ objects to cruft packs.
+
+ * "git format-patch --rfc --subject-prefix=<foo>" used to ignore the
+ "--subject-prefix" option and used "[RFC PATCH]"; now we will add
+ "RFC" prefix to whatever subject prefix is specified.
+
+ * "git log --format" has been taught the %(decorate) placeholder for
+ further customization over what the "--decorate" option offers.
+
+ * The default log message created by "git revert", when reverting a
+ commit that records a revert, has been tweaked, to encourage people
+ to describe complex "revert of revert of revert" situations better in
+ their own words.
+
+ * The command-line completion support (in contrib/) learned to
+ complete "git commit --trailer=" for possible trailer keys.
+
+ * "git update-index" learned the "--show-index-version" option to
+ inspect the index format version used by the on-disk index file.
+
+ * "git diff" learned the "diff.statNameWidth" configuration variable,
+ to give the default width for the name part in the "--stat" output.
+
+ * "git range-diff --notes=foo" compared "log --notes=foo --notes" of
+ the two ranges, instead of using just the specified notes tree,
+ which has been corrected to use only the specified notes tree.
+
+ * The command line completion script (in contrib/) can be told to
+ complete aliases by including ": git <cmd> ;" in the alias to tell
+ it that the alias should be completed in a similar way to how "git
+ <cmd>" is completed. The parsing code for the alias has been
+ loosened to allow ';' without an extra space before it.
+
+ * "git for-each-ref" and friends learned to apply mailmap to
+ authorname and other fields in a more flexible way than using
+ separate placeholder letters like %a[eElL] every time we want to
+ come up with small variants.
+
+ * "git repack" machinery learned to pay attention to the "--filter="
+ option.
+
+ * "git repack" learned the "--max-cruft-size" option to prevent cruft
+ packs from growing without bounds.
+
+ * "git merge-tree" learned to take strategy backend specific options
+ via the "-X" option, like "git merge" does.
+
+ * "git log" and friends learned the "--dd" option that is a
+ short-hand for "--diff-merges=first-parent -p".
+
+ * The attribute subsystem learned to honor the "attr.tree"
+ configuration variable that specifies which tree to read the
+ .gitattributes files from.
+
+ * "git merge-file" learns a mode to read three variants of the
+ contents to be merged from blob objects.
+
+
+Performance, Internal Implementation, Development Support etc.
+
+ * "git check-attr" has been taught to work better with sparse-index.
+
+ * It may be tempting to leave the help text NULL for a command line
+ option that is either hidden or too obvious, but "git subcmd -h"
+ and "git subcmd --help-all" would have segfaulted if done so. Now
+ the help text is truly optional.
+
+ * Tests that are known to pass with LSan are now marked as such.
+
+ * Flaky "git p4" tests, as well as "git svn" tests, are now skipped
+ in the (rather expensive) sanitizer CI job.
+
+ * Tests with LSan from time to time seem to emit harmless messages
+ that make our tests unnecessarily flaky; we work around it by
+ filtering the uninteresting output.
+
+ * Unused parameters to functions are marked as such, and/or removed,
+ in order to bring us closer to "-Wunused-parameter" clean.
+
+ * The code to keep track of existing packs in the repository while
+ repacking has been refactored.
+
+ * The "streaming" interface used for bulk-checkin codepath has been
+ narrowed to take only blob objects for now, with no real loss of
+ functionality.
+
+ * GitHub CI workflow has learned to trigger Coverity check.
+
+ * Test coverage for trailers has been improved.
+
+ * The code to iterate over loose references has been optimized to
+ reduce the number of lstat() system calls.
+
+ * The codepaths that read "chunk" formatted files have been corrected
+ to pay attention to the chunk size and notice broken files.
+
+ * Replace macos-12 used at GitHub CI with macos-13.
+ (merge 682a868f67 js/ci-use-macos-13 later to maint).
+
+
+Fixes since v2.42
+-----------------
+
+ * Overly long label names used in the sequencer machinery are now
+ chopped to fit under filesystem limitation.
+
+ * Scalar updates.
+
+ * Tweak GitHub Actions CI so that pushing the same commit to multiple
+ branch tips at the same time will not waste building and testing
+ the same thing twice.
+
+ * The commit-graph verification code that detects a mixture of zero and
+ non-zero generation numbers has been updated.
+
+ * "git diff -w --exit-code" with various options did not work
+ correctly, which has been corrected.
+
+ * The "transfer.unpackLimit" configuration variable ought to be used
+ as a fallback, but overrode the more specific "fetch.unpackLimit"
+ and "receive.unpackLimit" configuration variables by mistake, which
+ has been corrected.
+
+ * The use of API between two calls to require_clean_work_tree() from
+ the sequencer code has been cleaned up for consistency.
+
+ * "git diff --no-such-option" and other corner cases around the exit
+ status of the "diff" command have been corrected.
+
+ * "git for-each-ref --sort='contents:size'" sorted the refs according
+ to size numerically, giving a ref that points at a blob twelve-byte
+ (12) long before showing a blob hundred-byte (100) long, which has
+ been corrected.
+
+ * We now limit the depth of the tree objects and maximum length of
+ pathnames recorded in tree objects.
+ (merge 4d5693ba05 jk/tree-name-and-depth-limit later to maint).
+
+ * Various fixes to the behavior of "rebase -i", when the command got
+ interrupted by conflicting changes, have been made.
+
+ * References from a description of the `--patch` option in various
+ manual pages have been simplified and improved.
+
+ * "git grep -e A --no-or -e B" is accepted, even though the negation
+ of the "--or" option did not mean anything, which has been tightened.
+
+ * The completion script (in contrib/) has been taught to treat the
+ "-t" option to "git checkout" and "git switch" just like the
+ "--track" option, to complete remote-tracking branches.
+
+ * "git diff --no-index -R <(one) <(two)" did not work correctly,
+ which has been corrected.
+
+ * "git maintenance" timers' implementation has been updated, based on
+ systemd timers, to work with WSL.
+
+ * "git diff --cached" codepath did not fill the necessary stat
+ information for a file when fsmonitor knows it is clean and ended
+ up behaving as if it were not clean, which has been corrected.
+
+ * How "alias.foo = : git cmd ; aliased-command-string" should be
+ spelled with necessary whitespace around punctuation marks to work
+ has been more clearly documented (but this will be moot with newer
+ versions of Git where the parsing rules have been improved).
+
+ * HTTP Header redaction code has been adjusted for a newer version of
+ cURL library that shows its traces differently from earlier
+ versions.
+
+ * An error message given by "git send-email", when given a malformed
+ address, did not show the offending address, which has been corrected.
+
+ * UBSan options were not propagated through the test framework to git
+ run via the httpd, unlike ASan options, which has been corrected.
+
+ * "checkout --merge -- path" and "update-index --unresolve path" did
+ not resurrect conflicted state that was resolved to remove path,
+ but now they do.
+ (merge 5bdedac3c7 jc/unresolve-removal later to maint).
+
+ * The display width table for unicode characters has been updated for
+ Unicode 15.1
+ (merge 872976c37e bb/unicode-width-table-15 later to maint).
+
+ * Update mailmap entry for Derrick.
+ (merge 6e5457d8c7 ds/mailmap-entry-update later to maint).
+
+ * In the ".gitmodules" files, submodules are keyed by their names,
+ and the path to the submodule whose name is $name is specified by
+ the submodule.$name.path variable. There were a few codepaths that
+ mixed the name and path up when consulting the submodule database,
+ which have been corrected. It took long for these bugs to be found
+ as the name of a submodule initially is the same as its path, and
+ the problem does not surface until it is moved to a different path,
+ which apparently happens very rarely.
+
+ * "git diff --merge-base X other args..." insisted that X must be a
+ commit and errored out when given an annotated tag that peels to a
+ commit, but we only need it to be a committish. This has been
+ corrected.
+ (merge 4adceb5a29 ar/diff-index-merge-base-fix later to maint).
+
+ * "git merge-tree" used to segfault when the "--attr-source"
+ option is used, which has been corrected.
+ (merge e95bafc52f jc/merge-ort-attr-index-fix later to maint).
+
+ * Unlike "git log --pretty=%D", "git log --pretty="%(decorate)" did
+ not auto-initialize the decoration subsystem, which has been
+ corrected.
+
+ * Feeding "git stash store" with a random commit that was not created
+ by "git stash create" now errors out.
+ (merge d9b6634589 jc/fail-stash-to-store-non-stash later to maint).
+
+ * The index file has room only for the lower 32-bit of the file size in
+ the cached stat information, which means cached stat information
+ will have 0 in its sd_size member for a file whose size is a multiple
+ of 4GiB. This is mistaken for a racily clean path. Avoid it by
+ storing a bogus sd_size value instead for such files.
+ (merge 5143ac07b1 bc/racy-4gb-files later to maint).
+
+ * "git p4" tried to store symlinks to LFS when told, but has been
+ fixed not to do so, because it does not make sense.
+ (merge 10c89a02b0 mm/p4-symlink-with-lfs later to maint).
+
+ * The codepath to handle recipient addresses `git send-email
+ --compose` learns from the user was completely broken, which has
+ been corrected.
+ (merge 3ec6167567 jk/send-email-fix-addresses-from-composed-messages later to maint).
+
+ * "cd sub && git grep -f patterns" tried to read "patterns" file at
+ the top level of the working tree; it has been corrected to read
+ "sub/patterns" instead.
+
+ * "git reflog expire --single-worktree" has been broken for the past
+ 20 months or so, which has been corrected.
+
+ * "git send-email" did not have certain pieces of data computed yet
+ when it tried to validate the outgoing messages and its recipient
+ addresses, which has been sorted out.
+
+ * "git bugreport" learned to complain when it received a command line
+ argument that it will not use.
+
+ * The codepath to traverse the commit-graph learned to notice that a
+ commit is missing (e.g., corrupt repository lost an object), even
+ though it knows something about the commit (like its parents) from
+ what is in commit-graph.
+ (merge 7a5d604443 ps/do-not-trust-commit-graph-blindly-for-existence later to maint).
+
+ * "git rev-list --missing" did not work for missing commit objects,
+ which has been corrected.
+
+ * "git rev-list --unpacked --objects" failed to exclude packed
+ non-commit objects, which has been corrected.
+ (merge 7b3c8e9f38 tb/rev-list-unpacked-fix later to maint).
+
+ * "To dereference" and "to peel" were sometimes used in in-code
+ comments and documentation but without description in the glossary.
+ (merge 893dce2ffb vd/glossary-dereference-peel later to maint).
+
+ * Other code cleanup, docfix, build fix, etc.
+ (merge c2c349a15c xz/commit-title-soft-limit-doc later to maint).
+ (merge 1bd809938a tb/format-pack-doc-update later to maint).
+ (merge 8f81532599 an/clang-format-typofix later to maint).
+ (merge 3ca86adc2d la/strvec-header-fix later to maint).
+ (merge 6789275d37 jc/test-i18ngrep later to maint).
+ (merge 9972cd6004 ps/leakfixes later to maint).
+ (merge 46edab516b tz/send-email-helpfix later to maint).
diff --git a/Documentation/RelNotes/2.43.1.txt b/Documentation/RelNotes/2.43.1.txt
new file mode 100644
index 0000000..20e96f2
--- /dev/null
+++ b/Documentation/RelNotes/2.43.1.txt
@@ -0,0 +1,82 @@
+Git 2.43.1 Release Notes
+========================
+
+There is nothing exciting to see here. Relative to Git 2.43, this
+release contains the fixes that have already been merged to the
+'master' branch of the development towards the next major release.
+
+Fixes since Git 2.43.0
+----------------------
+
+ * The way CI testing used "prove" could lead to running the test
+ suite twice needlessly, which has been corrected.
+
+ * Newer versions of Getopt::Long started giving warnings against our
+ (ab)use of it in "git send-email". Bump the minimum version
+ requirement for Perl to 5.8.1 (from September 2002) to allow
+ simplifying our implementation.
+
+ * Earlier we stopped relying on commit-graph that (still) records
+ information about commits that are lost from the object store,
+ which has negative performance implications. The default has been
+ flipped to disable this pessimization.
+
+ * Stale URLs have been updated to their current counterparts (or
+ archive.org) and HTTP links are replaced with working HTTPS links.
+
+ * trace2 streams used to record the URLs that potentially embed
+ authentication material, which has been corrected.
+
+ * The sample pre-commit hook that tries to catch introduction of new
+ paths that use potentially non-portable characters did not notice
+ an existing path getting renamed to such a problematic path, when
+ rename detection was enabled.
+
+ * The command line parser for the "log" family of commands was too
+ loose when parsing certain numbers, e.g., silently ignoring the
+ extra 'q' in "git log -n 1q" without complaining, which has been
+ tightened up.
+
+ * "git $cmd --end-of-options --rev -- --path" for some $cmd failed
+ to interpret "--rev" as a rev, and "--path" as a path. This was
+ fixed for many programs like "reset" and "checkout".
+
+ * "git bisect reset" has been taught to clean up state files and refs
+ even when BISECT_START file is gone.
+
+ * Some codepaths did not correctly parse configuration variables
+ specified with valueless "true", which has been corrected.
+
+ * Code clean-up for sanity checking of command line options for "git
+ show-ref".
+
+ * The code to parse the From e-mail header has been updated to avoid
+ recursion.
+
+ * "git fetch --atomic" issued an unnecessary empty error message,
+ which has been corrected.
+
+ * Command line completion script (in contrib/) learned to work better
+ with the reftable backend.
+
+ * "git status" is taught to show both the branch being bisected and
+ being rebased when both are in effect at the same time.
+ cf. <xmqqil76kyov.fsf@gitster.g>
+
+ * "git archive --list extra garbage" silently ignored excess command
+ line parameters, which has been corrected.
+
+ * "git sparse-checkout set" added default patterns even when the
+ patterns are being fed from the standard input, which has been
+ corrected.
+
+ * Unlike other environment variables that took the usual
+ true/false/yes/no as well as 0/1, GIT_FLUSH only understood 0/1,
+ which has been corrected.
+
+ * Clearing in-core repository (happens during e.g., "git fetch
+ --recurse-submodules" with commit graph enabled) made in-core
+ commit object in an inconsistent state by discarding the necessary
+ data from commit-graph too early, which has been corrected.
+
+Also contains various documentation updates, code clean-ups and minor fixups.
diff --git a/Documentation/RelNotes/2.43.2.txt b/Documentation/RelNotes/2.43.2.txt
new file mode 100644
index 0000000..5895e23
--- /dev/null
+++ b/Documentation/RelNotes/2.43.2.txt
@@ -0,0 +1,37 @@
+Git 2.43.2 Release Notes
+========================
+
+Relative to Git 2.43.1, this release has two important fixes to allow
+"git imap-send" to be built with NO_CURL defined, and to restore the
+forced flushing behaviour when GIT_FLUSH=1 is set. It also contains
+other, unexciting, fixes that have already been merged to the 'master'
+branch of the development towards the next major release.
+
+Fixes since Git 2.43.1
+----------------------
+
+ * Update to a new feature recently added, "git show-ref --exists".
+
+ * Rename detection logic ignored the final line of a file if it is an
+ incomplete line.
+
+ * "git diff --no-rename A B" did not disable rename detection but did
+ not trigger an error from the command line parser.
+
+ * "git diff --no-index file1 file2" segfaulted while invoking the
+ external diff driver, which has been corrected.
+
+ * Rewrite //-comments to /* comments */ in files whose comments
+ prevalently use the latter.
+
+ * A failed "git tag -s" did not necessarily result in an error
+ depending on the crypto backend, which has been corrected.
+
+ * "git stash" sometimes was silent even when it failed due to
+ unwritable index file, which has been corrected.
+
+ * Recent conversion to allow more than 0/1 in GIT_FLUSH broke the
+ mechanism by flipping what yes/no means by mistake, which has been
+ corrected.
+
+Also contains documentation updates, code clean-ups and minor fixups.
diff --git a/Documentation/RelNotes/2.43.3.txt b/Documentation/RelNotes/2.43.3.txt
new file mode 100644
index 0000000..924f205
--- /dev/null
+++ b/Documentation/RelNotes/2.43.3.txt
@@ -0,0 +1,12 @@
+Git 2.43.3 Release Notes
+========================
+
+Relative to Git 2.43.2, this release fixes one regression that
+manifests while running "git commit -v --trailer".
+
+Fixes since Git 2.43.2
+----------------------
+
+ * "git commit -v --trailer=..." was broken with recent update and
+ placed the trailer _after_ the divider line, which has been
+ corrected.
diff --git a/Documentation/RelNotes/2.43.4.txt b/Documentation/RelNotes/2.43.4.txt
new file mode 100644
index 0000000..0a84251
--- /dev/null
+++ b/Documentation/RelNotes/2.43.4.txt
@@ -0,0 +1,7 @@
+Git v2.43.4 Release Notes
+=========================
+
+This release merges up the fix that appears in v2.39.4, v2.40.2,
+v2.41.1 and v2.42.2 to address the security issues CVE-2024-32002,
+CVE-2024-32004, CVE-2024-32020, CVE-2024-32021 and CVE-2024-32465;
+see the release notes for these versions for details.
diff --git a/Documentation/RelNotes/2.43.5.txt b/Documentation/RelNotes/2.43.5.txt
new file mode 100644
index 0000000..236b234
--- /dev/null
+++ b/Documentation/RelNotes/2.43.5.txt
@@ -0,0 +1,26 @@
+Git v2.43.5 Release Notes
+=========================
+
+In preparing security fixes for four CVEs, we made overly aggressive
+"defense in depth" changes that broke legitimate use cases like 'git
+lfs' and 'git annex.' This release is to revert these misguided, if
+well-intentioned, changes that were shipped in 2.43.4 and were not
+direct security fixes.
+
+Jeff King (5):
+ send-email: drop FakeTerm hack
+ send-email: avoid creating more than one Term::ReadLine object
+ ci: drop mention of BREW_INSTALL_PACKAGES variable
+ ci: avoid bare "gcc" for osx-gcc job
+ ci: stop installing "gcc-13" for osx-gcc
+
+Johannes Schindelin (6):
+ hook: plug a new memory leak
+ init: use the correct path of the templates directory again
+ Revert "core.hooksPath: add some protection while cloning"
+ tests: verify that `clone -c core.hooksPath=/dev/null` works again
+ clone: drop the protections where hooks aren't run
+ Revert "Add a helper function to compare file contents"
+
+Junio C Hamano (1):
+ Revert "fsck: warn about symlink pointing inside a gitdir"
diff --git a/Documentation/RelNotes/2.44.0.txt b/Documentation/RelNotes/2.44.0.txt
new file mode 100644
index 0000000..14f9ce8
--- /dev/null
+++ b/Documentation/RelNotes/2.44.0.txt
@@ -0,0 +1,334 @@
+Git v2.44 Release Notes
+=======================
+
+Backward Compatibility Notes
+
+ * "git checkout -B <branch>" used to allow switching to a branch that
+ is in use on another worktree, but this was by mistake. The users
+ need to use "--ignore-other-worktrees" option.
+
+
+UI, Workflows & Features
+
+ * "git add" and "git stash" learned to support the ":(attr:...)"
+ magic pathspec.
+
+ * "git rebase --autosquash" is now enabled for non-interactive rebase,
+ but it is still incompatible with the apply backend.
+
+ * Introduce "git replay", a tool meant on the server side without
+ working tree to recreate a history.
+
+ * "git merge-file" learned to take the "--diff-algorithm" option to
+ use algorithm different from the default "myers" diff.
+
+ * Command line completion (in contrib/) learned to complete path
+ arguments to the "add/set" subcommands of "git sparse-checkout"
+ better.
+
+ * "git checkout -B <branch> [<start-point>]" allowed a branch that is
+ in use in another worktree to be updated and checked out, which
+ might be a bit unexpected. The rule has been tightened, which is a
+ breaking change. "--ignore-other-worktrees" option is required to
+ unbreak you, if you are used to the current behaviour that "-B"
+ overrides the safety.
+
+ * The builtin_objectmode attribute is populated for each path
+ without adding anything in .gitattributes files, which would be
+ useful in magic pathspec, e.g., ":(attr:builtin_objectmode=100755)"
+ to limit to executables.
+
+ * "git fetch" learned to pay attention to "fetch.all" configuration
+ variable, which pretends as if "--all" was passed from the command
+ line when no remote parameter was given.
+
+ * In addition to (rather cryptic) Security Identifiers, show username
+ and domain in the error message when we barf on mismatch between
+ the Git directory and the current user on Windows.
+
+ * The error message given when "git branch -d branch" fails due to
+ commits unique to the branch has been split into an error and a new
+ conditional advice message.
+
+ * When given an existing but unreadable file as a configuration file,
+ gitweb behaved as if the file did not exist at all, but now it
+ errors out. This is a change that may break backward compatibility.
+
+ * When $HOME/.gitconfig is missing but XDG config file is available, we
+ should write into the latter, not former. "git gc" and "git
+ maintenance" wrote into a wrong "global config" file, which have
+ been corrected.
+
+ * Define "special ref" as a very narrow set that consists of
+ FETCH_HEAD and MERGE_HEAD, and clarify everything else that used to
+ be classified as such are actually just pseudorefs.
+
+ * All conditional "advice" messages show how to turn them off, which
+ becomes repetitive. Setting advice.* configuration explicitly on
+ now omits the instruction part.
+
+ * The "disable repository discovery of a bare repository" check,
+ triggered by setting safe.bareRepository configuration variable to
+ 'explicit', has been loosened to exclude the ".git/" directory inside
+ a non-bare repository from the check. So you can do "cd .git &&
+ git cmd" to run a Git command that works on a bare repository without
+ explicitly specifying $GIT_DIR now.
+
+ * The completion script (in contrib/) learned more options that can
+ be used with "git log".
+
+ * The labels on conflict markers for the common ancestor, our version,
+ and the other version are available to custom 3-way merge driver
+ via %S, %X, and %Y placeholders.
+
+ * The write codepath for the reftable data learned to honor
+ core.fsync configuration.
+
+ * The "--fsck-objects" option of "git index-pack" now can take the
+ optional parameter to tweak severity of different fsck errors.
+
+ * The wincred credential backend has been taught to support oauth
+ refresh token the same way as credential-cache and
+ credential-libsecret backends.
+
+ * Command line completion support (in contrib/) has been
+ updated for "git bisect".
+
+ * "git branch" and friends learned to use the formatted text as
+ sorting key, not the underlying timestamp value, when the --sort
+ option is used with author or committer timestamp with a format
+ specifier (e.g., "--sort=creatordate:format:%H:%M:%S").
+
+ * The command line completion script (in contrib/) learned to
+ complete configuration variable names better.
+
+
+Performance, Internal Implementation, Development Support etc.
+
+ * Process to add some form of low-level unit tests has started.
+
+ * Add support for GitLab CI.
+
+ * "git for-each-ref --no-sort" still sorted the refs alphabetically
+ which paid non-trivial cost. It has been redefined to show output
+ in an unspecified order, to allow certain optimizations to take
+ advantage of.
+
+ * Simplify API implementation to delete references by eliminating
+ duplication.
+
+ * Subject approxidate() and show_date() machinery to OSS-Fuzz.
+
+ * A new helper to let us pretend that we called lstat() when we know
+ our cache_entry is up-to-date via fsmonitor.
+
+ * The optimization based on fsmonitor in the "diff --cached"
+ codepath is resurrected with the "fake-lstat" introduced earlier.
+
+ * Test balloon to use C99 "bool" type from <stdbool.h> has been
+ added.
+
+ * "git clone" has been prepared to allow cloning a repository with
+ non-default hash function into a repository that uses the reftable
+ backend.
+
+ * Streaming spans of packfile data used to be done only from a
+ single, primary, pack in a repository with multiple packfiles. It
+ has been extended to allow reuse from other packfiles, too.
+
+ * Comment updates to help developers not to attempt to modify
+ messages from plumbing commands that must stay constant.
+
+ It might make sense to reassess the plumbing needs every few years,
+ but that should be done as a separate effort.
+
+ * Move test-ctype helper to the unit-test framework.
+
+ * Instead of manually creating refs/ hierarchy on disk upon a
+ creation of a secondary worktree, which is only usable via the
+ files backend, use the refs API to populate it.
+
+ * CI for GitLab learned to drive macOS jobs.
+
+ * A few tests to "git commit -o <pathspec>" and "git commit -i
+ <pathspec>" has been added.
+
+ * Tests on ref API are moved around to prepare for reftable.
+
+ * The Makefile often had to say "-L$(path) -R$(path)" that repeats
+ the path to the same library directory for link time and runtime.
+ A Makefile template is used to reduce such repetition.
+
+ * The priority queue test has been migrated to the unit testing
+ framework.
+
+ * Setting `feature.experimental` opts the user into multi-pack reuse
+ experiment
+
+ * Squelch node.js 16 deprecation warnings from GitHub Actions CI
+ by updating actions/github-script and actions/checkout that use
+ node.js 20.
+
+ * The mechanism to report the filename in the source code, used by
+ the unit-test machinery, assumed that the compiler expanded __FILE__
+ to the path to the source given to the $(CC), but some compilers
+ give full path, breaking the output. This has been corrected.
+
+
+Fixes since v2.43
+-----------------
+
+ * The way CI testing used "prove" could lead to running the test
+ suite twice needlessly, which has been corrected.
+
+ * Update ref-related tests.
+
+ * "git format-patch --encode-email-headers" ignored the option when
+ preparing the cover letter, which has been corrected.
+
+ * Newer versions of Getopt::Long started giving warnings against our
+ (ab)use of it in "git send-email". Bump the minimum version
+ requirement for Perl to 5.8.1 (from September 2002) to allow
+ simplifying our implementation.
+
+ * Earlier we stopped relying on commit-graph that (still) records
+ information about commits that are lost from the object store,
+ which has negative performance implications. The default has been
+ flipped to disable this pessimization.
+
+ * Stale URLs have been updated to their current counterparts (or
+ archive.org) and HTTP links are replaced with working HTTPS links.
+
+ * trace2 streams used to record the URLs that potentially embed
+ authentication material, which has been corrected.
+
+ * The sample pre-commit hook that tries to catch introduction of new
+ paths that use potentially non-portable characters did not notice
+ an existing path getting renamed to such a problematic path, when
+ rename detection was enabled.
+
+ * The command line parser for the "log" family of commands was too
+ loose when parsing certain numbers, e.g., silently ignoring the
+ extra 'q' in "git log -n 1q" without complaining, which has been
+ tightened up.
+
+ * "git $cmd --end-of-options --rev -- --path" for some $cmd failed
+ to interpret "--rev" as a rev, and "--path" as a path. This was
+ fixed for many programs like "reset" and "checkout".
+
+ * "git bisect reset" has been taught to clean up state files and refs
+ even when BISECT_START file is gone.
+
+ * Some codepaths did not correctly parse configuration variables
+ specified with valueless "true", which has been corrected.
+
+ * Code clean-up for sanity checking of command line options for "git
+ show-ref".
+
+ * The code to parse the From e-mail header has been updated to avoid
+ recursion.
+
+ * "git fetch --atomic" issued an unnecessary empty error message,
+ which has been corrected.
+
+ * Command line completion script (in contrib/) learned to work better
+ with the reftable backend.
+
+ * "git status" is taught to show both the branch being bisected and
+ being rebased when both are in effect at the same time.
+
+ * "git archive --list extra garbage" silently ignored excess command
+ line parameters, which has been corrected.
+
+ * "git sparse-checkout set" added default patterns even when the
+ patterns are being fed from the standard input, which has been
+ corrected.
+
+ * "git sparse-checkout (add|set) --[no-]cone --end-of-options" did
+ not handle "--end-of-options" correctly after a recent update.
+
+ * Unlike other environment variables that took the usual
+ true/false/yes/no as well as 0/1, GIT_FLUSH only understood 0/1,
+ which has been corrected.
+
+ * Clearing in-core repository (happens during e.g., "git fetch
+ --recurse-submodules" with commit graph enabled) made in-core
+ commit object in an inconsistent state by discarding the necessary
+ data from commit-graph too early, which has been corrected.
+
+ * Update to a new feature recently added, "git show-ref --exists".
+
+ * oss-fuzz tests are built and run in CI.
+ (merge c4a9cf1df3 js/oss-fuzz-build-in-ci later to maint).
+
+ * Rename detection logic ignored the final line of a file if it is an
+ incomplete line.
+
+ * GitHub CI update.
+ (merge 0188b2c8e0 pb/ci-github-skip-logs-for-broken-tests later to maint).
+
+ * "git diff --no-rename A B" did not disable rename detection but did
+ not trigger an error from the command line parser.
+
+ * "git archive --remote=<remote>" learned to talk over the smart
+ http (aka stateless) transport.
+ (merge 176cd68634 jx/remote-archive-over-smart-http later to maint).
+
+ * Fetching via protocol v0 over Smart HTTP transport sometimes failed
+ to correctly auto-follow tags.
+ (merge fba732c462 jk/fetch-auto-tag-following-fix later to maint).
+
+ * The documentation for the --exclude-per-directory option marked it
+ as deprecated, which confused readers into thinking there may be a
+ plan to remove it in the future, which was not our intention.
+ (merge 0009542cab jc/ls-files-doc-update later to maint).
+
+ * "git diff --no-index file1 file2" segfaulted while invoking the
+ external diff driver, which has been corrected.
+
+ * Rewrite //-comments to /* comments */ in files whose comments
+ prevalently use the latter.
+
+ * Cirrus CI jobs started breaking because we specified version of
+ FreeBSD that is no longer available, which has been corrected.
+ (merge 81fffb66d3 cb/use-freebsd-13-2-at-cirrus-ci later to maint).
+
+ * A caller called index_file_exists() that takes a string expressed
+ as <ptr, length> with a wrong length, which has been corrected.
+ (merge 156e28b36d jh/sparse-index-expand-to-path-fix later to maint).
+
+ * A failed "git tag -s" did not necessarily result in an error
+ depending on the crypto backend, which has been corrected.
+
+ * "git stash" sometimes was silent even when it failed due to
+ unwritable index file, which has been corrected.
+
+ * "git show-ref --verify" did not show things like "CHERRY_PICK_HEAD",
+ which has been corrected.
+
+ * Recent conversion to allow more than 0/1 in GIT_FLUSH broke the
+ mechanism by flipping what yes/no means by mistake, which has been
+ corrected.
+
+ * The sequencer machinery does not use the ref API and instead
+ records names of certain objects it needs for its correct operation
+ in temporary files, which makes these objects susceptible to loss
+ by garbage collection. These temporary files have been added as
+ starting points for reachability analysis to fix this.
+ (merge bc7f5db896 pw/gc-during-rebase later to maint).
+
+ * "git cherry-pick" invoked during "git rebase -i" session lost
+ the authorship information, which has been corrected.
+ (merge e4301f73ff vn/rebase-with-cherry-pick-authorship later to maint).
+
+ * The code paths that call repo_read_object_file() have been
+ tightened to react to errors.
+ (merge 568459bf5e js/check-null-from-read-object-file later to maint).
+
+ * Other code cleanup, docfix, build fix, etc.
+ (merge 5aea3955bc rj/clarify-branch-doc-m later to maint).
+ (merge 9cce3be2df bk/bisect-doc-fix later to maint).
+ (merge 8430b438f6 vd/fsck-submodule-url-test later to maint).
+ (merge 3cb4384683 jc/t0091-with-unknown-git later to maint).
+ (merge 020456cb74 rs/receive-pack-remove-find-header later to maint).
+ (merge bc47139f4f la/trailer-cleanups later to maint).
diff --git a/Documentation/RelNotes/2.44.1.txt b/Documentation/RelNotes/2.44.1.txt
new file mode 100644
index 0000000..b5135c3
--- /dev/null
+++ b/Documentation/RelNotes/2.44.1.txt
@@ -0,0 +1,8 @@
+Git v2.44.1 Release Notes
+=========================
+
+This release merges up the fix that appears in v2.39.4, v2.40.2,
+v2.41.1, v2.42.2 and v2.43.4 to address the security issues
+CVE-2024-32002, CVE-2024-32004, CVE-2024-32020, CVE-2024-32021
+and CVE-2024-32465; see the release notes for these versions
+for details.
diff --git a/Documentation/RelNotes/2.44.2.txt b/Documentation/RelNotes/2.44.2.txt
new file mode 100644
index 0000000..76700f0
--- /dev/null
+++ b/Documentation/RelNotes/2.44.2.txt
@@ -0,0 +1,26 @@
+Git v2.44.2 Release Notes
+=========================
+
+In preparing security fixes for four CVEs, we made overly aggressive
+"defense in depth" changes that broke legitimate use cases like 'git
+lfs' and 'git annex.' This release is to revert these misguided, if
+well-intentioned, changes that were shipped in 2.44.1 and were not
+direct security fixes.
+
+Jeff King (5):
+ send-email: drop FakeTerm hack
+ send-email: avoid creating more than one Term::ReadLine object
+ ci: drop mention of BREW_INSTALL_PACKAGES variable
+ ci: avoid bare "gcc" for osx-gcc job
+ ci: stop installing "gcc-13" for osx-gcc
+
+Johannes Schindelin (6):
+ hook: plug a new memory leak
+ init: use the correct path of the templates directory again
+ Revert "core.hooksPath: add some protection while cloning"
+ tests: verify that `clone -c core.hooksPath=/dev/null` works again
+ clone: drop the protections where hooks aren't run
+ Revert "Add a helper function to compare file contents"
+
+Junio C Hamano (1):
+ Revert "fsck: warn about symlink pointing inside a gitdir"
diff --git a/Documentation/RelNotes/2.45.0.txt b/Documentation/RelNotes/2.45.0.txt
new file mode 100644
index 0000000..fec1936
--- /dev/null
+++ b/Documentation/RelNotes/2.45.0.txt
@@ -0,0 +1,476 @@
+Git v2.45 Release Notes
+=======================
+
+Backward Compatibility Notes
+
+UI, Workflows & Features
+
+ * Integrate the reftable code into the refs framework as a backend.
+ With "git init --ref-format=reftable", hopefully it would be a lot
+ more efficient to manage a repository with many references.
+
+ * "git checkout -p" and friends learned that that "@" is a synonym
+ for "HEAD".
+
+ * Variants of vimdiff learned to honor mergetool.<variant>.layout
+ settings.
+
+ * "git reflog" learned a "list" subcommand that enumerates known reflogs.
+
+ * When a merge conflicted at a submodule, merge-ort backend used to
+ unconditionally give a lengthy message to suggest how to resolve
+ it. Now the message can be squelched as an advice message.
+
+ * "git for-each-ref" learned "--include-root-refs" option to show
+ even the stuff outside the 'refs/' hierarchy.
+
+ * "git rev-list --missing=print" has learned to optionally take
+ "--allow-missing-tips", which allows the objects at the starting
+ points to be missing.
+
+ * "git merge-tree" has learned that the three trees involved in the
+ 3-way merge only need to be trees, not necessarily commits.
+
+ * "git log --merge" learned to pay attention to CHERRY_PICK_HEAD and
+ other kinds of *_HEAD pseudorefs.
+
+ * Platform specific tweaks for OS/390 has been added to
+ config.mak.uname.
+
+ * Users with safe.bareRepository=explicit can still work from within
+ $GIT_DIR of a seconary worktree (which resides at .git/worktrees/$name/)
+ of the primary worktree without explicitly specifying the $GIT_DIR
+ environment variable or the --git-dir=<path> option.
+
+ * The output format for dates "iso-strict" has been tweaked to show
+ a time in the Zulu timezone with "Z" suffix, instead of "+00:00".
+
+ * "git diff" and friends learned two extra configuration variables,
+ diff.srcPrefix and diff.dstPrefix.
+
+ * The status.showUntrackedFiles configuration variable had a name
+ that tempts users to set a Boolean value expressed in our usual
+ "false", "off", and "0", but it only took "no". This has been
+ corrected so "true" and its synonyms are taken as "normal", while
+ "false" and its synonyms are taken as "no".
+
+ * Remove an ancient and not well maintained Hg-to-git migration
+ script from contrib/.
+
+ * Hints that suggest what to do after resolving conflicts can now be
+ squelched by disabling advice.mergeConflict.
+
+ * Allow git-cherry-pick(1) to automatically drop redundant commits via
+ a new `--empty` option, similar to the `--empty` options for
+ git-rebase(1) and git-am(1). Includes a soft deprecation of
+ `--keep-redundant-commits` as well as some related docs changes and
+ sequencer code cleanup.
+
+ * "git config" learned "--comment=<message>" option to leave a
+ comment immediately after the "variable = value" on the same line
+ in the configuration file.
+
+ * core.commentChar used to be limited to a single byte, but has been
+ updated to allow an arbitrary multi-byte sequence.
+
+ * "git add -p" and other "interactive hunk selection" UI has learned to
+ skip showing the hunk immediately after it has already been shown, and
+ an additional action to explicitly ask to reshow the current hunk.
+
+ * "git pack-refs" learned the "--auto" option, which defers the decision of
+ whether and how to pack to the ref backend. This is used by the reftable
+ backend to avoid repacking of an already-optimal ref database. The new mode
+ is triggered from "git gc --auto".
+
+ * "git add -u <pathspec>" and "git commit [-i] <pathspec>" did not
+ diagnose a pathspec element that did not match any files in certain
+ situations, unlike "git add <pathspec>" did.
+
+ * The userdiff patterns for C# has been updated.
+
+ * Git writes a "waiting for your editor" message on an incomplete
+ line after launching an editor, and then append another error
+ message on the same line if the editor errors out. It now clears
+ the "waiting for..." line before giving the error message.
+
+ * The filename used for rejected hunks "git apply --reject" creates
+ was limited to PATH_MAX, which has been lifted.
+
+ * When "git bisect" reports the commit it determined to be the
+ culprit, we used to show it in a format that does not honor common
+ UI tweaks, like log.date and log.decorate. The code has been
+ taught to use "git show" to follow more customizations.
+
+
+Performance, Internal Implementation, Development Support etc.
+
+ * The code to iterate over refs with the reftable backend has seen
+ some optimization.
+
+ * More tests that are marked as "ref-files only" have been updated to
+ improve test coverage of reftable backend.
+
+ * Some parts of command line completion script (in contrib/) have
+ been micro-optimized.
+
+ * The way placeholders are to be marked-up in documentation have been
+ specified; use "_<placeholder>_" to typeset the word inside a pair
+ of <angle-brackets> emphasized.
+
+ * "git --no-lazy-fetch cmd" allows to run "cmd" while disabling lazy
+ fetching of objects from the promisor remote, which may be handy
+ for debugging.
+
+ * The implementation in "git clean" that makes "-n" and "-i" ignore
+ clean.requireForce has been simplified, together with the
+ documentation.
+
+ * Uses of xwrite() helper have been audited and updated for better
+ error checking and simpler code.
+
+ * Some trace2 events that lacked def_param have learned to show it,
+ enriching the output.
+
+ * The parse-options code that deals with abbreviated long option
+ names have been cleaned up.
+
+ * The code in reftable backend that creates new table files works
+ better with the tempfile framework to avoid leaving cruft after a
+ failure.
+
+ * The reftable code has its own custom binary search function whose
+ comparison callback has an unusual interface, which caused the
+ binary search to degenerate into a linear search, which has been
+ corrected.
+
+ * The code to iterate over reflogs in the reftable has been optimized
+ to reduce memory allocation and deallocation.
+
+ * Work to support a repository that work with both SHA-1 and SHA-256
+ hash algorithms has started.
+
+ * A new fuzz target that exercises config parsing code has been
+ added.
+
+ * Fix the way recently added tests interpolate variables defined
+ outside them, and document the best practice to help future
+ developers.
+
+ * Introduce an experimental protocol for contributors to propose the
+ topic description to be used in the "What's cooking" report, the
+ merge commit message for the topic, and in the release notes and
+ document it in the SubmittingPatches document.
+
+ * The t/README file now gives a hint on running individual tests in
+ the "t/" directory with "make t<num>-*.sh t<num>-*.sh".
+ (merge 8d383806fc pb/test-scripts-are-build-targets later to maint).
+
+ * The "hint:" messages given by the advice mechanism, when given a
+ message with a blank line, left a line with trailing whitespace,
+ which has been cleansed.
+
+ * Documentation rules has been explicitly described how to mark-up
+ literal parts and a few manual pages have been updated as examples.
+
+ * The .editorconfig file has been taught that a Makefile uses HT
+ indentation.
+
+ * t-prio-queue test has been cleaned up by using C99 compound
+ literals; this is meant to also serve as a weather-balloon to smoke
+ out folks with compilers who have trouble compiling code that uses
+ the feature.
+
+ * Windows binary used to decide the use of unix-domain socket at
+ build time, but it learned to make the decision at runtime instead.
+
+ * The "shared repository" test in the t0610 reftable test failed
+ under restrictive umask setting (e.g. 007), which has been
+ corrected.
+
+ * Document and apply workaround for a buggy version of dash that
+ mishandles "local var=val" construct.
+
+ * The codepaths that reach date_mode_from_type() have been updated to
+ pass "struct date_mode" by value to make them thread safe.
+
+ * The strategy to compact multiple tables of reftables after many
+ operations accumulate many entries has been improved to avoid
+ accumulating too many tables uncollected.
+
+ * The code to iterate over reftable blocks has seen some optimization
+ to reduce memory allocation and deallocation.
+
+ * The way "git fast-import" handles paths described in its input has
+ been tightened up and more clearly documented.
+
+ * The cvsimport tests required that the platform understands
+ traditional timezone notations like CST6CDT, which has been
+ updated to work on those systems as long as they understand
+ POSIX notation with explicit tz transition dates.
+
+ * The code to format trailers have been cleaned up.
+
+
+Fixes since v2.44
+-----------------
+
+ * "git apply" on a filesystem without filemode support have learned
+ to take a hint from what is in the index for the path, even when
+ not working with the "--index" or "--cached" option, when checking
+ the executable bit match what is required by the preimage in the
+ patch.
+ (merge 45b625142d cp/apply-core-filemode later to maint).
+
+ * "git column" has been taught to reject negative padding value, as
+ it would lead to nonsense behaviour including division by zero.
+ (merge 76fb807faa kh/column-reject-negative-padding later to maint).
+
+ * "git am --help" now tells readers what actions are available in
+ "git am --whitespace=<action>", in addition to saying that the
+ option is passed through to the underlying "git apply".
+ (merge a171dac734 jc/am-whitespace-doc later to maint).
+
+ * "git tag --column" failed to check the exit status of its "git
+ column" invocation, which has been corrected.
+ (merge 92e66478fc rj/tag-column-fix later to maint).
+
+ * Credential helper based on libsecret (in contrib/) has been updated
+ to handle an empty password correctly.
+ (merge 8f1f2023b7 mh/libsecret-empty-password-fix later to maint).
+
+ * "git difftool --dir-diff" learned to honor the "--trust-exit-code"
+ option; it used to always exit with 0 and signalled success.
+ (merge eb84c8b6ce ps/difftool-dir-diff-exit-code later to maint).
+
+ * The code incorrectly attempted to use textconv cache when asked,
+ even when we are not running in a repository, which has been
+ corrected.
+ (merge affe355fe7 jk/textconv-cache-outside-repo-fix later to maint).
+
+ * Remove an empty file that shouldn't have been added in the first
+ place.
+ (merge 4f66942215 js/remove-cruft-files later to maint).
+
+ * The logic to access reflog entries by date and number had ugly
+ corner cases at the boundaries, which have been cleaned up.
+ (merge 5edd126720 jk/reflog-special-cases-fix later to maint).
+
+ * An error message from "git upload-pack", which responds to "git
+ fetch" requests, had a trailing NUL in it, which has been
+ corrected.
+ (merge 3f4c7a0805 sg/upload-pack-error-message-fix later to maint).
+
+ * Clarify wording in the CodingGuidelines that requires <git-compat-util.h>
+ to be the first header file.
+ (merge 4e89f0e07c jc/doc-compat-util later to maint).
+
+ * "git commit -v --cleanup=scissors" used to add the scissors line
+ twice in the log message buffer, which has been corrected.
+ (merge e90cc075cc jt/commit-redundant-scissors-fix later to maint).
+
+ * A custom remote helper no longer cannot access the newly created
+ repository during "git clone", which is a regression in Git 2.44.
+ This has been corrected.
+ (merge 199f44cb2e ps/remote-helper-repo-initialization-fix later to maint).
+
+ * Various parts of upload-pack have been updated to bound the resource
+ consumption relative to the size of the repository to protect from
+ abusive clients.
+ (merge 6cd05e768b jk/upload-pack-bounded-resources later to maint).
+
+ * The upload-pack program, when talking over v2, accepted the
+ packfile-uris protocol extension from the client, even if it did
+ not advertise the capability, which has been corrected.
+ (merge a922bfa3b5 jk/upload-pack-v2-capability-cleanup later to maint).
+
+ * Make sure failure return from merge_bases_many() is properly caught.
+ (merge 25fd20eb44 js/merge-base-with-missing-commit later to maint).
+
+ * FSMonitor client code was confused when FSEvents were given in a
+ different case on a case-insensitive filesystem, which has been
+ corrected.
+ (merge 29c139ce78 jh/fsmonitor-icase-corner-case-fix later to maint).
+
+ * The "core.commentChar" configuration variable only allows an ASCII
+ character, which was not clearly documented, which has been
+ corrected.
+ (merge fb7c556f58 kh/doc-commentchar-is-a-byte later to maint).
+
+ * With release 2.44 we got rid of all uses of test_i18ngrep and there
+ is no in-flight topic that adds a new use of it. Make a call to
+ test_i18ngrep a hard failure, so that we can remove it at the end
+ of this release cycle.
+ (merge 381a83dfa3 jc/test-i18ngrep later to maint).
+
+ * The command line completion script (in contrib/) learned to
+ complete "git reflog" better.
+ (merge 1284f9cc11 rj/complete-reflog later to maint).
+
+ * The logic to complete the command line arguments to "git worktree"
+ subcommand (in contrib/) has been updated to correctly honor things
+ like "git -C dir" etc.
+ (merge 3574816d98 rj/complete-worktree-paths-fix later to maint).
+
+ * When git refuses to create a branch because the proposed branch
+ name is not a valid refname, an advice message is given to refer
+ the user to exact naming rules.
+ (merge 8fbd903e58 kh/branch-ref-syntax-advice later to maint).
+
+ * Code simplification by getting rid of code that sets an environment
+ variable that is no longer used.
+ (merge 72a8d3f027 pw/rebase-i-ignore-cherry-pick-help-environment later to maint).
+
+ * The code to find the effective end of log messages can fall into an
+ endless loop, which has been corrected.
+ (merge 2541cba2d6 fs/find-end-of-log-message-fix later to maint).
+
+ * Mark-up used in the documentation has been improved for
+ consistency.
+ (merge 45d5ed3e50 ja/doc-markup-fixes later to maint).
+
+ * The status.showUntrackedFiles configuration variable was
+ incorrectly documented to accept "false", which has been corrected.
+
+ * Leaks from "git restore" have been plugged.
+ (merge 2f64da0790 rj/restore-plug-leaks later to maint).
+
+ * "git bugreport --no-suffix" was not supported and instead
+ segfaulted, which has been corrected.
+ (merge b3b57c69da js/bugreport-no-suffix-fix later to maint).
+
+ * The documentation for "%(trailers[:options])" placeholder in the
+ "--pretty" option of commands in the "git log" family has been
+ updated.
+ (merge bff85a338c bl/doc-key-val-sep-fix later to maint).
+
+ * "git checkout --conflict=bad" reported a bad conflictStyle as if it
+ were given to a configuration variable; it has been corrected to
+ report that the command line option is bad.
+ (merge 5a99c1ac1a pw/checkout-conflict-errorfix later to maint).
+
+ * Code clean-up in the "git log" machinery that implements custom log
+ message formatting.
+ (merge 1c10b8e5b0 jk/pretty-subject-cleanup later to maint).
+
+ * "git config" corrupted literal HT characters written in the
+ configuration file as part of a value, which has been corrected.
+ (merge e6895c3f97 ds/config-internal-whitespace-fix later to maint).
+
+ * A unit test for reftable code tried to enumerate all files in a
+ directory after reftable operations and expected to see nothing but
+ the files it wanted to leave there, but was fooled by .nfs* cruft
+ files left, which has been corrected.
+ (merge 0068aa7946 ps/reftable-unit-test-nfs-workaround later to maint).
+
+ * The implementation and documentation of "object-format" option
+ exchange between the Git itself and its remote helpers did not
+ quite match, which has been corrected.
+
+ * The "--pretty=<shortHand>" option of the commands in the "git log"
+ family, defined as "[pretty] shortHand = <expansion>" should have
+ been looked up case insensitively, but was not, which has been
+ corrected.
+ (merge f999d5188b bl/pretty-shorthand-config-fix later to maint).
+
+ * "git apply" failed to extract the filename the patch applied to,
+ when the change was about an empty file created in or deleted from
+ a directory whose name ends with a SP, which has been corrected.
+ (merge 776ffd1a30 jc/apply-parse-diff-git-header-names-fix later to maint).
+
+ * Update a more recent tutorial doc.
+ (merge 95ab557b4b dg/myfirstobjectwalk-updates later to maint).
+
+ * The test script had an incomplete and ineffective attempt to avoid
+ clobbering the testing user's real crontab (and its equivalents),
+ which has been completed.
+ (merge 73cb87773b es/test-cron-safety later to maint).
+
+ * Use advice_if_enabled() API to rewrite a simple pattern to
+ call advise() after checking advice_enabled().
+ (merge 6412d01527 rj/use-adv-if-enabled later to maint).
+
+ * Another "set -u" fix for the bash prompt (in contrib/) script.
+ (merge d7805bc743 vs/complete-with-set-u-fix later to maint).
+
+ * "git checkout/switch --detach foo", after switching to the detached
+ HEAD state, gave the tracking information for the 'foo' branch,
+ which was pointless.
+
+ * "git apply" has been updated to lift the hardcoded pathname length
+ limit, which in turn allowed a mksnpath() function that is no
+ longer used.
+ (merge 708f7e0590 rs/apply-lift-path-length-limit later to maint).
+
+ * A file descriptor leak in an error codepath, used when "git apply
+ --reject" fails to create the *.rej file, has been corrected.
+ (merge 2b1f456adf rs/apply-reject-fd-leakfix later to maint).
+
+ * A config parser callback function fell through instead of returning
+ after recognising and processing a variable, wasting cycles, which
+ has been corrected.
+ (merge a816ccd642 ds/fetch-config-parse-microfix later to maint).
+
+ * Fix was added to work around a regression in libcURL 8.7.0 (which has
+ already been fixed in their tip of the tree).
+ (merge 92a209bf24 jk/libcurl-8.7-regression-workaround later to maint).
+
+ * The variable that holds the value read from the core.excludefile
+ configuration variable used to leak, which has been corrected.
+ (merge 0e0fefb29f jc/unleak-core-excludesfile later to maint).
+
+ * vreportf(), which is used by error() and friends, has been taught
+ to give the error message printf-format string when its vsnprintf()
+ call fails, instead of showing nothing useful to identify the
+ nature of the error.
+ (merge c63adab961 rs/usage-fallback-to-show-message-format later to maint).
+
+ * Adjust to an upcoming changes to GNU make that breaks our Makefiles.
+ (merge 227b8fd902 tb/make-indent-conditional-with-non-spaces later to maint).
+
+ * Git 2.44 introduced a regression that makes the updated code to
+ barf in repositories with multi-pack index written by older
+ versions of Git, which has been corrected.
+
+ * When .git/rr-cache/ rerere database gets corrupted or rerere is fed to
+ work on a file with conflicted hunks resolved incompletely, the rerere
+ machinery got confused and segfaulted, which has been corrected.
+ (merge 167395bb47 mr/rerere-crash-fix later to maint).
+
+ * The "receive-pack" program (which responds to "git push") was not
+ converted to run "git maintenance --auto" when other codepaths that
+ used to run "git gc --auto" were updated, which has been corrected.
+ (merge 7bf3057d9c ps/run-auto-maintenance-in-receive-pack later to maint).
+
+ * Other code cleanup, docfix, build fix, etc.
+ (merge f0e578c69c rs/use-xstrncmpz later to maint).
+ (merge 83e6eb7d7a ba/credential-test-clean-fix later to maint).
+ (merge 64562d784d jb/doc-interactive-singlekey-do-not-need-perl later to maint).
+ (merge c431a235e2 cp/t9146-use-test-path-helpers later to maint).
+ (merge 82d75402d5 ds/doc-send-email-capitalization later to maint).
+ (merge 41bff66e35 jc/doc-add-placeholder-fix later to maint).
+ (merge 6835f0efe9 jw/remote-doc-typofix later to maint).
+ (merge 244001aa20 hs/rebase-not-in-progress later to maint).
+ (merge 2ca6c07db2 jc/no-include-of-compat-util-from-headers later to maint).
+ (merge 87bd7fbb9c rs/fetch-simplify-with-starts-with later to maint).
+ (merge f39addd0d9 rs/name-rev-with-mempool later to maint).
+ (merge 9a97b43e03 rs/submodule-prefix-simplify later to maint).
+ (merge 40b8076462 ak/rebase-autosquash later to maint).
+ (merge 3223204456 eg/add-uflags later to maint).
+ (merge 5f78d52dce es/config-doc-sort-sections later to maint).
+ (merge 781fb7b4c2 as/option-names-in-messages later to maint).
+ (merge 51d41dc243 jk/doc-remote-helpers-markup-fix later to maint).
+ (merge e1aaf309db pb/ci-win-artifact-names-fix later to maint).
+ (merge ad538c61da jc/index-pack-fsck-levels later to maint).
+ (merge 67471bc704 ja/doc-formatting-fix later to maint).
+ (merge 86f9ce7dd6 bl/doc-config-fixes later to maint).
+ (merge 0d527842b7 az/grep-group-error-message-update later to maint).
+ (merge 7c43bdf07b rs/strbuf-expand-bad-format later to maint).
+ (merge 8b68b48d5c ds/typofix-core-config-doc later to maint).
+ (merge 39bb692152 rs/imap-send-use-xsnprintf later to maint).
+ (merge 8d320cec60 jc/t2104-style-fixes later to maint).
+ (merge b4454d5a7b pw/t3428-cleanup later to maint).
+ (merge 84a7c33a4b pf/commitish-committish later to maint).
+ (merge 8882ee9d68 la/mailmap-entry later to maint).
+ (merge 44bdba2fa6 rs/no-openssl-compilation-fix-on-macos later to maint).
+ (merge f412d72c19 yb/replay-doc-linkfix later to maint).
+ (merge 5da40be8d7 xx/rfc2822-date-format-in-doc later to maint).
diff --git a/Documentation/RelNotes/2.45.1.txt b/Documentation/RelNotes/2.45.1.txt
new file mode 100644
index 0000000..3b0d60c
--- /dev/null
+++ b/Documentation/RelNotes/2.45.1.txt
@@ -0,0 +1,8 @@
+Git v2.45.1 Release Notes
+=========================
+
+This release merges up the fix that appears in v2.39.4,
+v2.40.2, v2.41.1, v2.42.2, v2.43.4 and v2.44.1 to address the
+security issues CVE-2024-32002, CVE-2024-32004, CVE-2024-32020,
+CVE-2024-32021 and CVE-2024-32465; see the release notes for
+these versions for details.
diff --git a/Documentation/RelNotes/2.45.2.txt b/Documentation/RelNotes/2.45.2.txt
new file mode 100644
index 0000000..13429e6
--- /dev/null
+++ b/Documentation/RelNotes/2.45.2.txt
@@ -0,0 +1,26 @@
+Git v2.45.2 Release Notes
+=========================
+
+In preparing security fixes for four CVEs, we made overly aggressive
+"defense in depth" changes that broke legitimate use cases like 'git
+lfs' and 'git annex.' This release is to revert these misguided, if
+well-intentioned, changes that were shipped in 2.45.1 and were not
+direct security fixes.
+
+Jeff King (5):
+ send-email: drop FakeTerm hack
+ send-email: avoid creating more than one Term::ReadLine object
+ ci: drop mention of BREW_INSTALL_PACKAGES variable
+ ci: avoid bare "gcc" for osx-gcc job
+ ci: stop installing "gcc-13" for osx-gcc
+
+Johannes Schindelin (6):
+ hook: plug a new memory leak
+ init: use the correct path of the templates directory again
+ Revert "core.hooksPath: add some protection while cloning"
+ tests: verify that `clone -c core.hooksPath=/dev/null` works again
+ clone: drop the protections where hooks aren't run
+ Revert "Add a helper function to compare file contents"
+
+Junio C Hamano (1):
+ Revert "fsck: warn about symlink pointing inside a gitdir"
diff --git a/Documentation/RelNotes/2.45.3.txt b/Documentation/RelNotes/2.45.3.txt
new file mode 100644
index 0000000..90098d2
--- /dev/null
+++ b/Documentation/RelNotes/2.45.3.txt
@@ -0,0 +1,80 @@
+Git v2.45.3 Release Notes
+=========================
+
+This primarily is to backport various small fixes accumulated on the
+'master' front during the development towards Git 2.46, the next
+feature release.
+
+
+Fixes since v2.45.2
+-------------------
+
+ * Git-GUI has a new maintainer, Johannes Sixt.
+
+ * Tests that try to corrupt in-repository files in chunked format did
+ not work well on macOS due to its broken "mv", which has been
+ worked around.
+
+ * The maximum size of attribute files is enforced more consistently.
+
+ * Unbreak CI jobs so that we do not attempt to use Python 2 that has
+ been removed from the platform.
+
+ * Git 2.43 started using the tree of HEAD as the source of attributes
+ in a bare repository, which has severe performance implications.
+ For now, revert the change, without ripping out a more explicit
+ support for the attr.tree configuration variable.
+
+ * Windows CI running in GitHub Actions started complaining about the
+ order of arguments given to calloc(); the imported regex code uses
+ the wrong order almost consistently, which has been corrected.
+
+ * The SubmittingPatches document now refers folks to manpages
+ translation project.
+
+ * "git rebase --signoff" used to forget that it needs to add a
+ sign-off to the resulting commit when told to continue after a
+ conflict stops its operation.
+
+ * The procedure to build multi-pack-index got confused by the
+ replace-refs mechanism, which has been corrected by disabling the
+ latter.
+
+ * "git stash -S" did not handle binary files correctly, which has
+ been corrected.
+
+ * A scheduled "git maintenance" job is expected to work on all
+ repositories it knows about, but it stopped at the first one that
+ errored out. Now it keeps going.
+
+ * zsh can pretend to be a normal shell pretty well except for some
+ glitches that we tickle in some of our scripts. Work them around
+ so that "vimdiff" and our test suite works well enough with it.
+
+ * Command line completion support for zsh (in contrib/) has been
+ updated to stop exposing internal state to end-user shell
+ interaction.
+
+ * The documentation for "git diff --name-only" has been clarified
+ that it is about showing the names in the post-image tree.
+
+ * The chainlint script (invoked during "make test") did nothing when
+ it failed to detect the number of available CPUs. It now falls
+ back to 1 CPU to avoid the problem.
+
+ * "git init" in an already created directory, when the user
+ configuration has includeif.onbranch, started to fail recently,
+ which has been corrected.
+
+ * The safe.directory configuration knob has been updated to
+ optionally allow leading path matches.
+
+ * An overly large ".gitignore" files are now rejected silently.
+
+ * Fix for an embarrassing typo that prevented Python2 tests from running
+ anywhere.
+
+ * Varargs functions that are unannotated as printf-like or execl-like
+ have been annotated as such.
+
+Also contains various documentation updates and code clean-ups.
diff --git a/Documentation/ReviewingGuidelines.txt b/Documentation/ReviewingGuidelines.txt
index 0e323d5..515d470 100644
--- a/Documentation/ReviewingGuidelines.txt
+++ b/Documentation/ReviewingGuidelines.txt
@@ -19,7 +19,7 @@
Selecting patch(es) to review
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you are looking for a patch series in need of review, start by checking
-latest "What's cooking in git.git" email
+the latest "What's cooking in git.git" email
(https://lore.kernel.org/git/xmqqilm1yp3m.fsf@gitster.g/[example]). The "What's
cooking" emails & replies can be found using the query `s:"What's cooking"` on
the https://lore.kernel.org/git/[`lore.kernel.org` mailing list archive];
@@ -126,7 +126,7 @@
-----------
nit: ::
Denotes a small issue that should be fixed, such as a typographical error
- or mis-alignment of conditions in an `if()` statement.
+ or misalignment of conditions in an `if()` statement.
aside: ::
optional: ::
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 973d7a8..625bdd0 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -87,7 +87,7 @@
Under truly exceptional circumstances where you absolutely must depend
on a select few topic branches that are already in `next` but not in
`master`, you may want to create your own custom base-branch by forking
-`master` and merging the required topic branches to it. You could then
+`master` and merging the required topic branches into it. You could then
work on top of this base-branch. But keep in mind that this base-branch
would only be known privately to you. So when you are ready to send
your patches to the list, be sure to communicate how you created it in
@@ -266,7 +266,7 @@
noticed that ...
....
-The "Copy commit summary" command of gitk can be used to obtain this
+The "Copy commit reference" command of gitk can be used to obtain this
format (with the subject enclosed in a pair of double-quotes), or this
invocation of `git show`:
@@ -355,9 +355,21 @@
patch after a detailed analysis.
. `Tested-by:` is used to indicate that the person applied the patch
and found it to have the desired effect.
+. `Co-authored-by:` is used to indicate that people exchanged drafts
+ of a patch before submitting it.
+. `Helped-by:` is used to credit someone who suggested ideas for
+ changes without providing the precise changes in patch form.
+. `Mentored-by:` is used to credit someone with helping develop a
+ patch as part of a mentorship program (e.g., GSoC or Outreachy).
+. `Suggested-by:` is used to credit someone with suggesting the idea
+ for a patch.
-You can also create your own tag or use one that's in common usage
-such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:".
+While you can also create your own trailer if the situation warrants it, we
+encourage you to instead use one of the common trailers in this project
+highlighted above.
+
+Only capitalize the very first letter of tags, i.e. favor
+"Signed-off-by" over "Signed-Off-By" and "Acked-by:" over "Acked-By".
[[git-tools]]
=== Generate your patch using Git tools out of your commits.
@@ -393,8 +405,8 @@
Learn to use format-patch and send-email if possible. These commands
are optimized for the workflow of sending patches, avoiding many ways
-your existing e-mail client that is optimized for "multipart/*" mime
-type e-mails to corrupt and render your patches unusable.
+your existing e-mail client (often optimized for "multipart/*" MIME
+type e-mails) might render your patches unusable.
People on the Git mailing list need to be able to read and
comment on the changes you are submitting. It is important for
@@ -403,10 +415,12 @@
your code. For this reason, each patch should be submitted
"inline" in a separate message.
-Multiple related patches should be grouped into their own e-mail
-thread to help readers find all parts of the series. To that end,
-send them as replies to either an additional "cover letter" message
-(see below), the first patch, or the respective preceding patch.
+All subsequent versions of a patch series and other related patches should be
+grouped into their own e-mail thread to help readers find all parts of the
+series. To that end, send them as replies to either an additional "cover
+letter" message (see below), the first patch, or the respective preceding patch.
+Here is a link:MyFirstContribution.html#v2-git-send-email[step-by-step guide] on
+how to submit updated versions of a patch series.
If your log message (including your name on the
`Signed-off-by` trailer) is not writable in ASCII, make sure that
@@ -447,6 +461,18 @@
Git-notes and inserted automatically following the three-dash
line via `git format-patch --notes`.
+[[the-topic-summary]]
+*This is EXPERIMENTAL*.
+
+When sending a topic, you can propose a one-paragraph summary that
+should appear in the "What's cooking" report when it is picked up to
+explain the topic. If you choose to do so, please write a 2-5 line
+paragraph that will fit well in our release notes (see many bulleted
+entries in the Documentation/RelNotes/* files for examples), and make
+it the first paragraph of the cover letter. For a single-patch
+series, use the space between the three-dash line and the diffstat, as
+described earlier.
+
[[attachment]]
Do not attach the patch as a MIME attachment, compressed or not.
Do not let your e-mail client send quoted-printable. Do not let
@@ -507,16 +533,16 @@
Some parts of the system have dedicated maintainers with their own
repositories.
-- `git-gui/` comes from git-gui project, maintained by Pratyush Yadav:
+- `git-gui/` comes from git-gui project, maintained by Johannes Sixt:
- https://github.com/prati0100/git-gui.git
+ https://github.com/j6t/git-gui
- `gitk-git/` comes from Paul Mackerras's gitk project:
git://git.ozlabs.org/~paulus/gitk
- Those who are interested in improve gitk can volunteer to help Paul
- in maintaining it cf. <YntxL/fTplFm8lr6@cleo>.
+ Those who are interested in improving gitk can volunteer to help Paul
+ maintain it, cf. <YntxL/fTplFm8lr6@cleo>.
- `po/` comes from the localization coordinator, Jiang Xin:
@@ -524,6 +550,13 @@
Patches to these parts should be based on their trees.
+- The "Git documentation translations" project, led by Jean-Noël
+ Avila, translates our documentation pages. Their work products are
+ maintained separately from this project, not as part of our tree:
+
+ https://github.com/jnavila/git-manpages-l10n/
+
+
[[patch-flow]]
== An ideal patch flow
@@ -556,7 +589,7 @@
In any time between the (2)-(3) cycle, the maintainer may pick it up
from the list and queue it to `seen`, in order to make it easier for
-people play with it without having to pick up and apply the patch to
+people to play with it without having to pick up and apply the patch to
their trees themselves.
[[patch-status]]
@@ -570,7 +603,7 @@
master).
* Read the Git mailing list, the maintainer regularly posts messages
- entitled "What's cooking in git.git" and "What's in git.git" giving
+ entitled "What's cooking in git.git" giving
the status of various proposed changes.
== GitHub CI[[GHCI]]
@@ -590,11 +623,12 @@
to your fork of Git on GitHub. You can monitor the test state of all your
branches here: `https://github.com/<Your GitHub handle>/git/actions/workflows/main.yml`
-If a branch did not pass all test cases then it is marked with a red
-cross. In that case you can click on the failing job and navigate to
-"ci/run-build-and-tests.sh" and/or "ci/print-test-failures.sh". You
-can also download "Artifacts" which are tarred (or zipped) archives
-with test data relevant for debugging.
+If a branch does not pass all test cases then it will be marked with a
+red +x+, instead of a green check. In that case, you can click on the
+failing job and navigate to "ci/run-build-and-tests.sh" and/or
+"ci/print-test-failures.sh". You can also download "Artifacts" which
+are zip archives containing tarred (or zipped) archives with test data
+relevant for debugging.
Then fix the problem and push your fix to your GitHub fork. This will
trigger a new CI build to ensure all tests pass.
@@ -686,7 +720,7 @@
`git am`. However, if the message is MIME encoded, what is
piped into the program is the representation you see in your
`*Article*` buffer after unwrapping MIME. This is often not what
-you would want for two reasons. It tends to screw up non ASCII
+you would want for two reasons. It tends to screw up non-ASCII
characters (most notably in people's names), and also
whitespaces (fatal in patches). Running "C-u g" to display the
message in raw form before using "|" to run the pipe can work
diff --git a/Documentation/ToolsForGit.txt b/Documentation/ToolsForGit.txt
index 5060d0d..ae7690b 100644
--- a/Documentation/ToolsForGit.txt
+++ b/Documentation/ToolsForGit.txt
@@ -5,7 +5,7 @@
[[summary]]
== Summary
-This document gathers tips, scripts and configuration file to help people
+This document gathers tips, scripts, and configuration files to help people
working on Git's codebase use their favorite tools while following Git's
coding style.
@@ -32,7 +32,7 @@
This is adapted from Linux's suggestion in its CodingStyle document:
-- To follow rules of the CodingGuideline, it's useful to put the following in
+- To follow the rules in CodingGuidelines, it's useful to put the following in
GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode:
----
;; note the first part is useful for C editing, too
diff --git a/Documentation/config.txt b/Documentation/config.txt
index 229b63a..70b448b 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -11,7 +11,7 @@
default configuration.
The configuration variables are used by both the Git plumbing
-and the porcelains. The variables are divided into sections, wherein
+and the porcelain commands. The variables are divided into sections, wherein
the fully qualified variable name of the variable itself is the last
dot-separated segment and the section name is everything before the last
dot. The variable names are case-insensitive, allow only alphanumeric
@@ -22,9 +22,10 @@
Syntax
~~~~~~
-The syntax is fairly flexible and permissive; whitespaces are mostly
-ignored. The '#' and ';' characters begin comments to the end of line,
-blank lines are ignored.
+The syntax is fairly flexible and permissive. Whitespace characters,
+which in this context are the space character (SP) and the horizontal
+tabulation (HT), are mostly ignored. The '#' and ';' characters begin
+comments to the end of line. Blank lines are ignored.
The file consists of sections and variables. A section begins with
the name of the section in square brackets and continues until the next
@@ -63,16 +64,17 @@
The variable names are case-insensitive, allow only alphanumeric characters
and `-`, and must start with an alphabetic character.
-A line that defines a value can be continued to the next line by
-ending it with a `\`; the backslash and the end-of-line are
-stripped. Leading whitespaces after 'name =', the remainder of the
-line after the first comment character '#' or ';', and trailing
-whitespaces of the line are discarded unless they are enclosed in
-double quotes. Internal whitespaces within the value are retained
-verbatim.
+Whitespace characters surrounding `name`, `=` and `value` are discarded.
+Internal whitespace characters within 'value' are retained verbatim.
+Comments starting with either `#` or `;` and extending to the end of line
+are discarded. A line that defines a value can be continued to the next
+line by ending it with a backslash (`\`); the backslash and the end-of-line
+characters are discarded.
-Inside double quotes, double quote `"` and backslash `\` characters
-must be escaped: use `\"` for `"` and `\\` for `\`.
+If `value` needs to contain leading or trailing whitespace characters,
+it must be enclosed in double quotation marks (`"`). Inside double quotation
+marks, double quote (`"`) and backslash (`\`) characters must be escaped:
+use `\"` for `"` and `\\` for `\`.
The following escape sequences (beside `\"` and `\\`) are recognized:
`\n` for newline character (NL), `\t` for horizontal tabulation (HT, TAB)
@@ -103,7 +105,7 @@
Conditional includes
~~~~~~~~~~~~~~~~~~~~
-You can include a config file from another conditionally by setting a
+You can conditionally include a config file from another by setting an
`includeIf.<condition>.path` variable to the name of the file to be
included.
@@ -118,7 +120,7 @@
pattern, the include condition is met.
+
The .git location may be auto-discovered, or come from `$GIT_DIR`
-environment variable. If the repository is auto discovered via a .git
+environment variable. If the repository is auto-discovered via a .git
file (e.g. from submodules, or a linked worktree), the .git location
would be the final location where the .git directory is, not where the
.git file is.
@@ -369,18 +371,18 @@
names do not conflict with those that are used by Git itself and
other popular tools, and describe them in your documentation.
-include::config/advice.txt[]
-
-include::config/core.txt[]
-
include::config/add.txt[]
+include::config/advice.txt[]
+
include::config/alias.txt[]
include::config/am.txt[]
include::config/apply.txt[]
+include::config/attr.txt[]
+
include::config/blame.txt[]
include::config/branch.txt[]
@@ -403,10 +405,12 @@
include::config/commitgraph.txt[]
-include::config/credential.txt[]
-
include::config/completion.txt[]
+include::config/core.txt[]
+
+include::config/credential.txt[]
+
include::config/diff.txt[]
include::config/difftool.txt[]
@@ -419,10 +423,10 @@
include::config/fetch.txt[]
-include::config/format.txt[]
-
include::config/filter.txt[]
+include::config/format.txt[]
+
include::config/fsck.txt[]
include::config/fsmonitor--daemon.txt[]
@@ -433,10 +437,10 @@
include::config/gitweb.txt[]
-include::config/grep.txt[]
-
include::config/gpg.txt[]
+include::config/grep.txt[]
+
include::config/gui.txt[]
include::config/guitool.txt[]
@@ -517,10 +521,10 @@
include::config/ssh.txt[]
-include::config/status.txt[]
-
include::config/stash.txt[]
+include::config/status.txt[]
+
include::config/submodule.txt[]
include::config/tag.txt[]
diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt
index c548a91..fa61241 100644
--- a/Documentation/config/advice.txt
+++ b/Documentation/config/advice.txt
@@ -1,30 +1,65 @@
advice.*::
These variables control various optional help messages designed to
- aid new users. All 'advice.*' variables default to 'true', and you
- can tell Git that you do not need help by setting these to 'false':
+ aid new users. When left unconfigured, Git will give the message
+ alongside instructions on how to squelch it. You can tell Git
+ that you do not need the help message by setting these to `false`:
+
--
+ addEmbeddedRepo::
+ Shown when the user accidentally adds one
+ git repo inside of another.
+ addEmptyPathspec::
+ Shown when the user runs `git add` without providing
+ the pathspec parameter.
+ addIgnoredFile::
+ Shown when the user attempts to add an ignored file to
+ the index.
+ amWorkDir::
+ Shown when linkgit:git-am[1] fails to apply a patch
+ file, to tell the user the location of the file.
ambiguousFetchRefspec::
- Advice shown when fetch refspec for multiple remotes map to
+ Shown when a fetch refspec for multiple remotes maps to
the same remote-tracking branch namespace and causes branch
tracking set-up to fail.
+ checkoutAmbiguousRemoteBranchName::
+ Shown when the argument to
+ linkgit:git-checkout[1] and linkgit:git-switch[1]
+ ambiguously resolves to a
+ remote tracking branch on more than one remote in
+ situations where an unambiguous argument would have
+ otherwise caused a remote-tracking branch to be
+ checked out. See the `checkout.defaultRemote`
+ configuration variable for how to set a given remote
+ to be used by default in some situations where this
+ advice would be printed.
+ commitBeforeMerge::
+ Shown when linkgit:git-merge[1] refuses to
+ merge to avoid overwriting local changes.
+ detachedHead::
+ Shown when the user uses
+ linkgit:git-switch[1] or linkgit:git-checkout[1]
+ to move to the detached HEAD state, to tell the user how
+ to create a local branch after the fact.
+ diverging::
+ Shown when a fast-forward is not possible.
fetchShowForcedUpdates::
- Advice shown when linkgit:git-fetch[1] takes a long time
+ Shown when linkgit:git-fetch[1] takes a long time
to calculate forced updates after ref updates, or to warn
that the check is disabled.
- pushUpdateRejected::
- Set this variable to 'false' if you want to disable
- 'pushNonFFCurrent', 'pushNonFFMatching', 'pushAlreadyExists',
- 'pushFetchFirst', 'pushNeedsForce', and 'pushRefNeedsUpdate'
- simultaneously.
- pushNonFFCurrent::
- Advice shown when linkgit:git-push[1] fails due to a
- non-fast-forward update to the current branch.
- pushNonFFMatching::
- Advice shown when you ran linkgit:git-push[1] and pushed
- 'matching refs' explicitly (i.e. you used ':', or
- specified a refspec that isn't your current branch) and
- it resulted in a non-fast-forward error.
+ forceDeleteBranch::
+ Shown when the user tries to delete a not fully merged
+ branch without the force option set.
+ ignoredHook::
+ Shown when a hook is ignored because the hook is not
+ set as executable.
+ implicitIdentity::
+ Shown when the user's information is guessed from the
+ system username and domain name, to tell the user how to
+ set their identity configuration.
+ mergeConflict::
+ Shown when various commands stop because of conflicts.
+ nestedTag::
+ Shown when a user attempts to recursively tag a tag object.
pushAlreadyExists::
Shown when linkgit:git-push[1] rejects an update that
does not qualify for fast-forwarding (e.g., a tag.)
@@ -37,17 +72,47 @@
tries to overwrite a remote ref that points at an
object that is not a commit-ish, or make the remote
ref point at an object that is not a commit-ish.
+ pushNonFFCurrent::
+ Shown when linkgit:git-push[1] fails due to a
+ non-fast-forward update to the current branch.
+ pushNonFFMatching::
+ Shown when the user ran linkgit:git-push[1] and pushed
+ "matching refs" explicitly (i.e. used `:`, or
+ specified a refspec that isn't the current branch) and
+ it resulted in a non-fast-forward error.
+ pushRefNeedsUpdate::
+ Shown when linkgit:git-push[1] rejects a forced update of
+ a branch when its remote-tracking ref has updates that we
+ do not have locally.
pushUnqualifiedRefname::
Shown when linkgit:git-push[1] gives up trying to
guess based on the source and destination refs what
remote ref namespace the source belongs in, but where
we can still suggest that the user push to either
- refs/heads/* or refs/tags/* based on the type of the
+ `refs/heads/*` or `refs/tags/*` based on the type of the
source object.
- pushRefNeedsUpdate::
- Shown when linkgit:git-push[1] rejects a forced update of
- a branch when its remote-tracking ref has updates that we
- do not have locally.
+ pushUpdateRejected::
+ Set this variable to `false` if you want to disable
+ `pushNonFFCurrent`, `pushNonFFMatching`, `pushAlreadyExists`,
+ `pushFetchFirst`, `pushNeedsForce`, and `pushRefNeedsUpdate`
+ simultaneously.
+ rebaseTodoError::
+ Shown when there is an error after editing the rebase todo list.
+ refSyntax::
+ Shown when the user provides an illegal ref name, to
+ tell the user about the ref syntax documentation.
+ resetNoRefresh::
+ Shown when linkgit:git-reset[1] takes more than 2
+ seconds to refresh the index after reset, to tell the user
+ that they can use the `--no-refresh` option.
+ resolveConflict::
+ Shown by various commands when conflicts
+ prevent the operation from being performed.
+ rmHints::
+ Shown on failure in the output of linkgit:git-rm[1], to
+ give directions on how to proceed from the current state.
+ sequencerInUse::
+ Shown when a sequencer command is already in progress.
skippedCherryPicks::
Shown when linkgit:git-rebase[1] skips a commit that has already
been cherry-picked onto the upstream branch.
@@ -63,83 +128,32 @@
the template shown when writing commit messages in
linkgit:git-commit[1], and in the help message shown
by linkgit:git-switch[1] or
- linkgit:git-checkout[1] when switching branch.
+ linkgit:git-checkout[1] when switching branches.
statusUoption::
- Advise to consider using the `-u` option to linkgit:git-status[1]
- when the command takes more than 2 seconds to enumerate untracked
- files.
- commitBeforeMerge::
- Advice shown when linkgit:git-merge[1] refuses to
- merge to avoid overwriting local changes.
- resetNoRefresh::
- Advice to consider using the `--no-refresh` option to
- linkgit:git-reset[1] when the command takes more than 2 seconds
- to refresh the index after reset.
- resolveConflict::
- Advice shown by various commands when conflicts
- prevent the operation from being performed.
- sequencerInUse::
- Advice shown when a sequencer command is already in progress.
- implicitIdentity::
- Advice on how to set your identity configuration when
- your information is guessed from the system username and
- domain name.
- detachedHead::
- Advice shown when you used
- linkgit:git-switch[1] or linkgit:git-checkout[1]
- to move to the detach HEAD state, to instruct how to
- create a local branch after the fact.
- suggestDetachingHead::
- Advice shown when linkgit:git-switch[1] refuses to detach HEAD
- without the explicit `--detach` option.
- checkoutAmbiguousRemoteBranchName::
- Advice shown when the argument to
- linkgit:git-checkout[1] and linkgit:git-switch[1]
- ambiguously resolves to a
- remote tracking branch on more than one remote in
- situations where an unambiguous argument would have
- otherwise caused a remote-tracking branch to be
- checked out. See the `checkout.defaultRemote`
- configuration variable for how to set a given remote
- to used by default in some situations where this
- advice would be printed.
- amWorkDir::
- Advice that shows the location of the patch file when
- linkgit:git-am[1] fails to apply it.
- rmHints::
- In case of failure in the output of linkgit:git-rm[1],
- show directions on how to proceed from the current state.
- addEmbeddedRepo::
- Advice on what to do when you've accidentally added one
- git repo inside of another.
- ignoredHook::
- Advice shown if a hook is ignored because the hook is not
- set as executable.
- waitingForEditor::
- Print a message to the terminal whenever Git is waiting for
- editor input from the user.
- nestedTag::
- Advice shown if a user attempts to recursively tag a tag object.
+ Shown when linkgit:git-status[1] takes more than 2
+ seconds to enumerate untracked files, to tell the user that
+ they can use the `-u` option.
submoduleAlternateErrorStrategyDie::
- Advice shown when a submodule.alternateErrorStrategy option
+ Shown when a submodule.alternateErrorStrategy option
configured to "die" causes a fatal error.
+ submoduleMergeConflict::
+ Advice shown when a non-trivial submodule merge conflict is
+ encountered.
submodulesNotUpdated::
- Advice shown when a user runs a submodule command that fails
+ Shown when a user runs a submodule command that fails
because `git submodule update --init` was not run.
- addIgnoredFile::
- Advice shown if a user attempts to add an ignored file to
- the index.
- addEmptyPathspec::
- Advice shown if a user runs the add command without providing
- the pathspec parameter.
+ suggestDetachingHead::
+ Shown when linkgit:git-switch[1] refuses to detach HEAD
+ without the explicit `--detach` option.
updateSparsePath::
- Advice shown when either linkgit:git-add[1] or linkgit:git-rm[1]
+ Shown when either linkgit:git-add[1] or linkgit:git-rm[1]
is asked to update index entries outside the current sparse
checkout.
- diverging::
- Advice shown when a fast-forward is not possible.
+ waitingForEditor::
+ Shown when Git is waiting for editor input. Relevant
+ when e.g. the editor is not launched inside the terminal.
worktreeAddOrphan::
- Advice shown when a user tries to create a worktree from an
- invalid reference, to instruct how to create a new orphan
+ Shown when the user tries to create a worktree from an
+ invalid reference, to tell the user how to create a new unborn
branch instead.
--
diff --git a/Documentation/config/alias.txt b/Documentation/config/alias.txt
index f1ca739..01df96f 100644
--- a/Documentation/config/alias.txt
+++ b/Documentation/config/alias.txt
@@ -4,7 +4,7 @@
`git last` is equivalent to `git cat-file commit HEAD`. To avoid
confusion and troubles with script usage, aliases that
hide existing Git commands are ignored. Arguments are split by
- spaces, the usual shell quoting and escaping is supported.
+ spaces, the usual shell quoting and escaping are supported.
A quote pair or a backslash can be used to quote them.
+
Note that the first word of an alias does not necessarily have to be a
diff --git a/Documentation/config/apply.txt b/Documentation/config/apply.txt
index 8fb8ef7..f9908e2 100644
--- a/Documentation/config/apply.txt
+++ b/Documentation/config/apply.txt
@@ -2,10 +2,10 @@
When set to 'change', tells 'git apply' to ignore changes in
whitespace, in the same way as the `--ignore-space-change`
option.
- When set to one of: no, none, never, false tells 'git apply' to
+ When set to one of: no, none, never, false, it tells 'git apply' to
respect all whitespace differences.
See linkgit:git-apply[1].
apply.whitespace::
- Tells 'git apply' how to handle whitespaces, in the same way
+ Tells 'git apply' how to handle whitespace, in the same way
as the `--whitespace` option. See linkgit:git-apply[1].
diff --git a/Documentation/config/attr.txt b/Documentation/config/attr.txt
new file mode 100644
index 0000000..1a482d6
--- /dev/null
+++ b/Documentation/config/attr.txt
@@ -0,0 +1,7 @@
+attr.tree::
+ A reference to a tree in the repository from which to read attributes,
+ instead of the `.gitattributes` file in the working tree. In a bare
+ repository, this defaults to `HEAD:.gitattributes`. If the value does
+ not resolve to a valid tree object, an empty tree is used instead.
+ When the `GIT_ATTR_SOURCE` environment variable or `--attr-source`
+ command line option are used, this configuration variable has no effect.
diff --git a/Documentation/config/branch.txt b/Documentation/config/branch.txt
index 445341a..432b9cd 100644
--- a/Documentation/config/branch.txt
+++ b/Documentation/config/branch.txt
@@ -36,7 +36,7 @@
branch.<name>.remote::
When on branch <name>, it tells 'git fetch' and 'git push'
- which remote to fetch from/push to. The remote to push to
+ which remote to fetch from or push to. The remote to push to
may be overridden with `remote.pushDefault` (for all branches).
The remote to push to, for the current branch, may be further
overridden by `branch.<name>.pushRemote`. If no remote is
@@ -64,7 +64,7 @@
handled like the remote part of a refspec, and must match a
ref which is fetched from the remote given by
"branch.<name>.remote".
- The merge information is used by 'git pull' (which at first calls
+ The merge information is used by 'git pull' (which first calls
'git fetch') to lookup the default branch for merging. Without
this option, 'git pull' defaults to merge the first refspec fetched.
Specify multiple values to get an octopus merge.
@@ -99,5 +99,5 @@
branch.<name>.description::
Branch description, can be edited with
`git branch --edit-description`. Branch description is
- automatically added in the format-patch cover letter or
+ automatically added to the format-patch cover letter or
request-pull summary.
diff --git a/Documentation/config/checkout.txt b/Documentation/config/checkout.txt
index bfbca90..a323022 100644
--- a/Documentation/config/checkout.txt
+++ b/Documentation/config/checkout.txt
@@ -30,7 +30,7 @@
all commands that perform checkout. E.g. checkout, clone, reset,
sparse-checkout, etc.
+
-Note: parallel checkout usually delivers better performance for repositories
+Note: Parallel checkout usually delivers better performance for repositories
located on SSDs or over NFS. For repositories on spinning disks and/or machines
with a small number of cores, the default sequential checkout often performs
better. The size and compression level of a repository might also influence how
@@ -39,6 +39,6 @@
checkout.thresholdForParallelism::
When running parallel checkout with a small number of files, the cost
of subprocess spawning and inter-process communication might outweigh
- the parallelization gains. This setting allows to define the minimum
+ the parallelization gains. This setting allows you to define the minimum
number of files for which parallel checkout should be attempted. The
default is 100.
diff --git a/Documentation/config/clean.txt b/Documentation/config/clean.txt
index a807c92..c0188ea 100644
--- a/Documentation/config/clean.txt
+++ b/Documentation/config/clean.txt
@@ -1,3 +1,3 @@
clean.requireForce::
- A boolean to make git-clean do nothing unless given -f,
- -i or -n. Defaults to true.
+ A boolean to make git-clean refuse to delete files unless -f
+ is given. Defaults to true.
diff --git a/Documentation/config/clone.txt b/Documentation/config/clone.txt
index 26f4fb1..0a10efd 100644
--- a/Documentation/config/clone.txt
+++ b/Documentation/config/clone.txt
@@ -1,13 +1,23 @@
-clone.defaultRemoteName::
+`clone.defaultRemoteName`::
The name of the remote to create when cloning a repository. Defaults to
- `origin`, and can be overridden by passing the `--origin` command-line
+ `origin`.
+ifdef::git-clone[]
+ It can be overridden by passing the `--origin` command-line
+ option.
+endif::[]
+ifndef::git-clone[]
+ It can be overridden by passing the `--origin` command-line
option to linkgit:git-clone[1].
+endif::[]
-clone.rejectShallow::
- Reject to clone a repository if it is a shallow one, can be overridden by
- passing option `--reject-shallow` in command line. See linkgit:git-clone[1]
+`clone.rejectShallow`::
+ Reject cloning a repository if it is a shallow one; this can be overridden by
+ passing the `--reject-shallow` option on the command line.
+ifndef::git-clone[]
+ See linkgit:git-clone[1].
+endif::[]
-clone.filterSubmodules::
+`clone.filterSubmodules`::
If a partial clone filter is provided (see `--filter` in
linkgit:git-rev-list[1]) and `--recurse-submodules` is used, also apply
the filter to submodules.
diff --git a/Documentation/config/color.txt b/Documentation/config/color.txt
index 1795b2d..2f2275a 100644
--- a/Documentation/config/color.txt
+++ b/Documentation/config/color.txt
@@ -106,7 +106,7 @@
matching text in context lines
`matchSelected`;;
matching text in selected lines. Also, used to customize the following
- linkgit:git-log[1] subcommands: `--grep`, `--author` and `--committer`.
+ linkgit:git-log[1] subcommands: `--grep`, `--author`, and `--committer`.
`selected`;;
non-matching text in selected lines. Also, used to customize the
following linkgit:git-log[1] subcommands: `--grep`, `--author` and
diff --git a/Documentation/config/column.txt b/Documentation/config/column.txt
index 76aa2f2..01e4198 100644
--- a/Documentation/config/column.txt
+++ b/Documentation/config/column.txt
@@ -43,7 +43,7 @@
See `column.ui` for details.
column.clean::
- Specify the layout when list items in `git clean -i`, which always
+ Specify the layout when listing items in `git clean -i`, which always
shows files and directories in columns. See `column.ui` for details.
column.status::
@@ -51,5 +51,5 @@
See `column.ui` for details.
column.tag::
- Specify whether to output tag listing in `git tag` in columns.
+ Specify whether to output tag listings in `git tag` in columns.
See `column.ui` for details.
diff --git a/Documentation/config/commit.txt b/Documentation/config/commit.txt
index 2c95573..62f0d92 100644
--- a/Documentation/config/commit.txt
+++ b/Documentation/config/commit.txt
@@ -2,7 +2,7 @@
This setting overrides the default of the `--cleanup` option in
`git commit`. See linkgit:git-commit[1] for details. Changing the
default can be useful when you always want to keep lines that begin
- with comment character `#` in your log message, in which case you
+ with the comment character `#` in your log message, in which case you
would do `git config commit.cleanup whitespace` (note that you will
have to remove the help lines that begin with `#` in the commit log
template yourself, if you do this).
@@ -25,5 +25,5 @@
new commit messages.
commit.verbose::
- A boolean or int to specify the level of verbose with `git commit`.
+ A boolean or int to specify the level of verbosity with `git commit`.
See linkgit:git-commit[1].
diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt
index dfbdaf0..93d65e1 100644
--- a/Documentation/config/core.txt
+++ b/Documentation/config/core.txt
@@ -520,6 +520,7 @@
`GIT_EDITOR` is not set. See linkgit:git-var[1].
core.commentChar::
+core.commentString::
Commands such as `commit` and `tag` that let you edit
messages consider a line that begins with this character
commented, and removes them after the editor returns
@@ -527,6 +528,20 @@
+
If set to "auto", `git-commit` would select a character that is not
the beginning character of any line in existing commit messages.
++
+Note that these two variables are aliases of each other, and in modern
+versions of Git you are free to use a string (e.g., `//` or `⁑⁕⁑`) with
+`commentChar`. Versions of Git prior to v2.45.0 will ignore
+`commentString` but will reject a value of `commentChar` that consists
+of more than a single ASCII byte. If you plan to use your config with
+older and newer versions of Git, you may want to specify both:
++
+ [core]
+ # single character for older versions
+ commentChar = "#"
+ # string for newer versions (which will override commentChar
+ # because it comes later in the file)
+ commentString = "//"
core.filesRefLockTimeout::
The length of time, in milliseconds, to retry when trying to
@@ -688,7 +703,7 @@
will not overwrite existing objects.
+
On some file system/operating system combinations, this is unreliable.
-Set this config setting to 'rename' there; However, This will remove the
+Set this config setting to 'rename' there; however, this will remove the
check that makes sure that existing object files will not get overwritten.
core.notesRef::
@@ -736,3 +751,9 @@
If set to "no", no abbreviation is made and the object names
are shown in their full length.
The minimum length is 4.
+
+core.maxTreeDepth::
+ The maximum depth Git is willing to recurse while traversing a
+ tree (e.g., "a/b/cde/f" has a depth of 4). This is a fail-safe
+ to allow Git to abort cleanly, and should not generally need to
+ be adjusted. The default is 4096.
diff --git a/Documentation/config/credential.txt b/Documentation/config/credential.txt
index 512f318..0221c3e 100644
--- a/Documentation/config/credential.txt
+++ b/Documentation/config/credential.txt
@@ -21,7 +21,7 @@
credential.<url>.*::
Any of the credential.* options above can be applied selectively to
- some credentials. For example "credential.https://example.com.username"
+ some credentials. For example, "credential.https://example.com.username"
would set the default username only for https connections to
example.com. See linkgit:gitcredentials[7] for details on how URLs are
matched.
@@ -31,6 +31,6 @@
credentialStore.lockTimeoutMS::
The length of time, in milliseconds, for git-credential-store to retry
- when trying to lock the credentials file. Value 0 means not to retry at
+ when trying to lock the credentials file. A value of 0 means not to retry at
all; -1 means to try indefinitely. Default is 1000 (i.e., retry for
1s).
diff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt
index 35a7bf8..5ce7b91 100644
--- a/Documentation/config/diff.txt
+++ b/Documentation/config/diff.txt
@@ -1,6 +1,6 @@
diff.autoRefreshIndex::
When using 'git diff' to compare with work tree
- files, do not consider stat-only change as changed.
+ files, do not consider stat-only changes as changed.
Instead, silently run `git update-index --refresh` to
update the cached stat information for paths whose
contents in the work tree match the contents in the
@@ -52,6 +52,10 @@
and accumulating child directory counts in the parent directories:
`files,10,cumulative`.
+diff.statNameWidth::
+ Limit the width of the filename part in --stat output. If set, applies
+ to all commands generating --stat output except format-patch.
+
diff.statGraphWidth::
Limit the width of the graph part in --stat output. If set, applies
to all commands generating --stat output except format-patch.
@@ -104,9 +108,15 @@
`git diff --no-index a b`;;
compares two non-git things (1) and (2).
-diff.noprefix::
+diff.noPrefix::
If set, 'git diff' does not show any source or destination prefix.
+diff.srcPrefix::
+ If set, 'git diff' uses this source prefix. Defaults to "a/".
+
+diff.dstPrefix::
+ If set, 'git diff' uses this destination prefix. Defaults to "b/".
+
diff.relative::
If set to 'true', 'git diff' does not show changes outside of the directory
and show pathnames relative to the current directory.
@@ -219,5 +229,5 @@
diff.colorMovedWS::
When moved lines are colored using e.g. the `diff.colorMoved` setting,
- this option controls the `<mode>` how spaces are treated
- for details of valid modes see '--color-moved-ws' in linkgit:git-diff[1].
+ this option controls the `<mode>` how spaces are treated.
+ For details of valid modes see '--color-moved-ws' in linkgit:git-diff[1].
diff --git a/Documentation/config/extensions.txt b/Documentation/config/extensions.txt
index bccaec7..38dce3d 100644
--- a/Documentation/config/extensions.txt
+++ b/Documentation/config/extensions.txt
@@ -7,6 +7,29 @@
linkgit:git-clone[1]. Trying to change it after initialization will not
work and will produce hard-to-diagnose issues.
+extensions.compatObjectFormat::
+
+ Specify a compatitbility hash algorithm to use. The acceptable values
+ are `sha1` and `sha256`. The value specified must be different from the
+ value of extensions.objectFormat. This allows client level
+ interoperability between git repositories whose objectFormat matches
+ this compatObjectFormat. In particular when fully implemented the
+ pushes and pulls from a repository in whose objectFormat matches
+ compatObjectFormat. As well as being able to use oids encoded in
+ compatObjectFormat in addition to oids encoded with objectFormat to
+ locally specify objects.
+
+extensions.refStorage::
+ Specify the ref storage format to use. The acceptable values are:
++
+include::../ref-storage-format.txt[]
++
+It is an error to specify this key unless `core.repositoryFormatVersion` is 1.
++
+Note that this setting should only be set by linkgit:git-init[1] or
+linkgit:git-clone[1]. Trying to change it after initialization will not
+work and will produce hard-to-diagnose issues.
+
extensions.worktreeConfig::
If enabled, then worktrees will load config settings from the
`$GIT_DIR/config.worktree` file in addition to the
diff --git a/Documentation/config/fastimport.txt b/Documentation/config/fastimport.txt
index c1166e3..903677d 100644
--- a/Documentation/config/fastimport.txt
+++ b/Documentation/config/fastimport.txt
@@ -1,8 +1,8 @@
fastimport.unpackLimit::
If the number of objects imported by linkgit:git-fast-import[1]
is below this limit, then the objects will be unpacked into
- loose object files. However if the number of imported objects
- equals or exceeds this limit then the pack will be stored as a
+ loose object files. However, if the number of imported objects
+ equals or exceeds this limit, then the pack will be stored as a
pack. Storing the pack from a fast-import can make the import
operation complete faster, especially on slow filesystems. If
not set, the value of `transfer.unpackLimit` is used instead.
diff --git a/Documentation/config/feature.txt b/Documentation/config/feature.txt
index bf9546f..f061b64 100644
--- a/Documentation/config/feature.txt
+++ b/Documentation/config/feature.txt
@@ -17,6 +17,9 @@
+
* `pack.useBitmapBoundaryTraversal=true` may improve bitmap traversal times by
walking fewer objects.
++
+* `pack.allowPackReuse=multi` may improve the time it takes to create a pack by
+reusing objects from multiple packs instead of just one.
feature.manyFiles::
Enable config options that optimize for repos with many files in the
diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt
index 568f0f7..d7dc461 100644
--- a/Documentation/config/fetch.txt
+++ b/Documentation/config/fetch.txt
@@ -50,10 +50,16 @@
refs. See also `remote.<name>.pruneTags` and the PRUNING
section of linkgit:git-fetch[1].
+fetch.all::
+ If true, fetch will attempt to update all available remotes.
+ This behavior can be overridden by passing `--no-all` or by
+ explicitly specifying one or more remote(s) to fetch from.
+ Defaults to false.
+
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.
+ `full` and `compact`. Default value is `full`. See the
+ OUTPUT section in linkgit:git-fetch[1] for details.
fetch.negotiationAlgorithm::
Control how information about the commits in the local repository
diff --git a/Documentation/config/format.txt b/Documentation/config/format.txt
index 8cf6f00..7410e93 100644
--- a/Documentation/config/format.txt
+++ b/Documentation/config/format.txt
@@ -68,7 +68,7 @@
Defaults to true.
format.pretty::
- The default pretty format for log/show/whatchanged command,
+ The default pretty format for log/show/whatchanged command.
See linkgit:git-log[1], linkgit:git-show[1],
linkgit:git-whatchanged[1].
@@ -119,7 +119,7 @@
`--notes=<ref>`, where `ref` is the non-boolean value. Defaults
to false.
+
-If one wishes to use the ref `ref/notes/true`, please use that literal
+If one wishes to use the ref `refs/notes/true`, please use that literal
instead.
+
This configuration can be specified multiple times in order to allow
diff --git a/Documentation/config/fsck.txt b/Documentation/config/fsck.txt
index a3c865d..8e9e508 100644
--- a/Documentation/config/fsck.txt
+++ b/Documentation/config/fsck.txt
@@ -11,13 +11,13 @@
+
The rest of the documentation discusses `fsck.*` for brevity, but the
same applies for the corresponding `receive.fsck.*` and
-`fetch.<msg-id>.*`. variables.
+`fetch.fsck.*`. variables.
+
-Unlike variables like `color.ui` and `core.editor` the
+Unlike variables like `color.ui` and `core.editor`, the
`receive.fsck.<msg-id>` and `fetch.fsck.<msg-id>` variables will not
fall back on the `fsck.<msg-id>` configuration if they aren't set. To
-uniformly configure the same fsck settings in different circumstances
-all three of them they must all set to the same values.
+uniformly configure the same fsck settings in different circumstances,
+all three of them must be set to the same values.
+
When `fsck.<msg-id>` is set, errors can be switched to warnings and
vice versa by configuring the `fsck.<msg-id>` setting where the
@@ -36,19 +36,19 @@
doing the same for `receive.fsck.<msg-id>` and `fetch.fsck.<msg-id>`
will only cause git to warn.
+
-See `Fsck Messages` section of linkgit:git-fsck[1] for supported
+See the `Fsck Messages` section of linkgit:git-fsck[1] for supported
values of `<msg-id>`.
fsck.skipList::
The path to a list of object names (i.e. one unabbreviated SHA-1 per
line) that are known to be broken in a non-fatal way and should
- be ignored. On versions of Git 2.20 and later comments ('#'), empty
- lines, and any leading and trailing whitespace is ignored. Everything
+ be ignored. On versions of Git 2.20 and later, comments ('#'), empty
+ lines, and any leading and trailing whitespace are ignored. Everything
but a SHA-1 per line will error out on older versions.
+
This feature is useful when an established project should be accepted
-despite early commits containing errors that can be safely ignored
+despite early commits containing errors that can be safely ignored,
such as invalid committer email addresses. Note: corrupt objects
cannot be skipped with this setting.
+
@@ -58,11 +58,11 @@
Unlike variables like `color.ui` and `core.editor` the
`receive.fsck.skipList` and `fetch.fsck.skipList` variables will not
fall back on the `fsck.skipList` configuration if they aren't set. To
-uniformly configure the same fsck settings in different circumstances
-all three of them they must all set to the same values.
+uniformly configure the same fsck settings in different circumstances,
+all three of them must be set to the same values.
+
Older versions of Git (before 2.20) documented that the object names
-list should be sorted. This was never a requirement, the object names
+list should be sorted. This was never a requirement; the object names
could appear in any order, but when reading the list we tracked whether
the list was sorted for the purposes of an internal binary search
implementation, which could save itself some work with an already sorted
diff --git a/Documentation/config/fsmonitor--daemon.txt b/Documentation/config/fsmonitor--daemon.txt
index c225c6c..671f9b9 100644
--- a/Documentation/config/fsmonitor--daemon.txt
+++ b/Documentation/config/fsmonitor--daemon.txt
@@ -1,5 +1,5 @@
fsmonitor.allowRemote::
- By default, the fsmonitor daemon refuses to work against network-mounted
+ By default, the fsmonitor daemon refuses to work with network-mounted
repositories. Setting `fsmonitor.allowRemote` to `true` overrides this
behavior. Only respected when `core.fsmonitor` is set to `true`.
diff --git a/Documentation/config/gc.txt b/Documentation/config/gc.txt
index ca47eb2..664a3c2 100644
--- a/Documentation/config/gc.txt
+++ b/Documentation/config/gc.txt
@@ -24,7 +24,7 @@
default value is 6700.
+
Setting this to 0 disables not only automatic packing based on the
-number of loose objects, but any other heuristic `git gc --auto` will
+number of loose objects, but also any other heuristic `git gc --auto` will
otherwise use to determine if there's work to do, such as
`gc.autoPackLimit`.
@@ -39,7 +39,7 @@
use, it'll affect how the auto pack limit works.
gc.autoDetach::
- Make `git gc --auto` return immediately and run in background
+ Make `git gc --auto` return immediately and run in the background
if the system supports it. Default is true.
gc.bigPackThreshold::
@@ -86,6 +86,12 @@
linkgit:git-repack[1]) instead of as loose objects. The default
is `true`.
+gc.maxCruftSize::
+ Limit the size of new cruft packs when repacking. When
+ specified in addition to `--max-cruft-size`, the command line
+ option takes priority. See the `--max-cruft-size` option of
+ linkgit:git-repack[1].
+
gc.pruneExpire::
When 'git gc' is run, it will call 'prune --expire 2.weeks.ago'
(and 'repack --cruft --cruft-expiration 2.weeks.ago' if using
@@ -145,6 +151,22 @@
operation (either generating a cruft pack or unpacking unreachable
objects) will be halted.
+gc.repackFilter::
+ When repacking, use the specified filter to move certain
+ objects into a separate packfile. See the
+ `--filter=<filter-spec>` option of linkgit:git-repack[1].
+
+gc.repackFilterTo::
+ When repacking and using a filter, see `gc.repackFilter`, the
+ specified location will be used to create the packfile
+ containing the filtered out objects. **WARNING:** The
+ specified location should be accessible, using for example the
+ Git alternates mechanism, otherwise the repo could be
+ considered corrupt by Git as it migh not be able to access the
+ objects in that packfile. See the `--filter-to=<dir>` option
+ of linkgit:git-repack[1] and the `objects/info/alternates`
+ section of linkgit:gitrepository-layout[5].
+
gc.rerereResolved::
Records of conflicted merge you resolved earlier are
kept for this many days when 'git rerere gc' is run.
diff --git a/Documentation/config/gpg.txt b/Documentation/config/gpg.txt
index 37e2831..5cf32b1 100644
--- a/Documentation/config/gpg.txt
+++ b/Documentation/config/gpg.txt
@@ -4,7 +4,7 @@
same command-line interface as GPG, namely, to verify a detached
signature, "`gpg --verify $signature - <$file`" is run, and the
program is expected to signal a good signature by exiting with
- code 0, and to generate an ASCII-armored detached signature, the
+ code 0. To generate an ASCII-armored detached signature, the
standard input of "`gpg -bsau $key`" is fed with the contents to be
signed, and the program is expected to send the result to its
standard output.
@@ -25,7 +25,7 @@
gpg.minTrustLevel::
Specifies a minimum trust level for signature verification. If
this option is unset, then signature verification for merge
- operations require a key with at least `marginal` trust. Other
+ operations requires a key with at least `marginal` trust. Other
operations that perform signature verification require a key
with at least `undefined` trust. Setting this option overrides
the required trust-level for all operations. Supported values,
@@ -38,7 +38,7 @@
* `ultimate`
gpg.ssh.defaultKeyCommand::
- This command that will be run when user.signingkey is not set and a ssh
+ This command will be run when user.signingkey is not set and a ssh
signature is requested. On successful exit a valid ssh public key
prefixed with `key::` is expected in the first line of its output.
This allows for a script doing a dynamic lookup of the correct public
diff --git a/Documentation/config/grep.txt b/Documentation/config/grep.txt
index e521f20..10041f2 100644
--- a/Documentation/config/grep.txt
+++ b/Documentation/config/grep.txt
@@ -24,5 +24,5 @@
If set to true, enable `--full-name` option by default.
grep.fallbackToNoIndex::
- If set to true, fall back to git grep --no-index if git grep
+ If set to true, fall back to `git grep --no-index` if `git grep`
is executed outside of a git repository. Defaults to false.
diff --git a/Documentation/config/gui.txt b/Documentation/config/gui.txt
index 0c087fd..171be77 100644
--- a/Documentation/config/gui.txt
+++ b/Documentation/config/gui.txt
@@ -24,7 +24,7 @@
not. Default: "false".
gui.newBranchTemplate::
- Is used as suggested name when creating new branches using the
+ Is used as a suggested name when creating new branches using the
linkgit:git-gui[1].
gui.pruneDuringFetch::
diff --git a/Documentation/config/http.txt b/Documentation/config/http.txt
index 51a7078..2d4e0c9 100644
--- a/Documentation/config/http.txt
+++ b/Documentation/config/http.txt
@@ -254,13 +254,13 @@
http.noEPSV::
A boolean which disables using of EPSV ftp command by curl.
- This can helpful with some "poor" ftp servers which don't
+ This can be helpful with some "poor" ftp servers which don't
support EPSV mode. Can be overridden by the `GIT_CURL_FTP_NO_EPSV`
environment variable. Default is false (curl will use EPSV).
http.userAgent::
The HTTP USER_AGENT string presented to an HTTP server. The default
- value represents the version of the client Git such as git/1.7.1.
+ value represents the version of the Git client such as git/1.7.1.
This option allows you to override this value to a more common value
such as Mozilla/4.0. This may be necessary, for instance, if
connecting through a firewall that restricts HTTP connections to a set
diff --git a/Documentation/config/i18n.txt b/Documentation/config/i18n.txt
index cc25621..6e72fdb 100644
--- a/Documentation/config/i18n.txt
+++ b/Documentation/config/i18n.txt
@@ -2,7 +2,7 @@
Character encoding the commit messages are stored in; Git itself
does not care per se, but this information is necessary e.g. when
importing commits from emails or in the gitk graphical history
- browser (and possibly at other places in the future or in other
+ browser (and possibly in other places in the future or in other
porcelains). See e.g. linkgit:git-mailinfo[1]. Defaults to 'utf-8'.
i18n.logOutputEncoding::
diff --git a/Documentation/config/imap.txt b/Documentation/config/imap.txt
index 06166fb..3d28f72 100644
--- a/Documentation/config/imap.txt
+++ b/Documentation/config/imap.txt
@@ -4,7 +4,7 @@
"[Gmail]/Drafts". Required.
imap.tunnel::
- Command used to setup a tunnel to the IMAP server through which
+ Command used to set up a tunnel to the IMAP server through which
commands will be piped instead of using a direct network connection
to the server. Required when imap.host is not set.
@@ -37,7 +37,7 @@
format=fixed email. Default is `false`.
imap.authMethod::
- Specify authenticate method for authentication with IMAP server.
+ Specify the authentication method for authenticating with the IMAP server.
If Git was built with the NO_CURL option, or if your curl version is older
than 7.34.0, or if you're running git-imap-send with the `--no-curl`
option, the only supported method is 'CRAM-MD5'. If this is not set
diff --git a/Documentation/config/index.txt b/Documentation/config/index.txt
index 23c7985..3eff420 100644
--- a/Documentation/config/index.txt
+++ b/Documentation/config/index.txt
@@ -23,7 +23,7 @@
Specifies the number of threads to spawn when loading the index.
This is meant to reduce index load time on multiprocessor machines.
Specifying 0 or 'true' will cause Git to auto-detect the number of
- CPU's and set the number of threads accordingly. Specifying 1 or
+ CPUs and set the number of threads accordingly. Specifying 1 or
'false' will disable multithreading. Defaults to 'true'.
index.version::
diff --git a/Documentation/config/init.txt b/Documentation/config/init.txt
index 79c79d6..af03acd 100644
--- a/Documentation/config/init.txt
+++ b/Documentation/config/init.txt
@@ -1,7 +1,10 @@
-init.templateDir::
- Specify the directory from which templates will be copied.
- (See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].)
+:see-git-init:
+ifndef::git-init[]
+:see-git-init: (See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].)
+endif::[]
-init.defaultBranch::
+`init.templateDir`::
+ Specify the directory from which templates will be copied. {see-git-init}
+`init.defaultBranch`::
Allows overriding the default branch name e.g. when initializing
a new repository.
diff --git a/Documentation/config/interactive.txt b/Documentation/config/interactive.txt
index a2d3c7e..8b876cb 100644
--- a/Documentation/config/interactive.txt
+++ b/Documentation/config/interactive.txt
@@ -1,12 +1,10 @@
interactive.singleKey::
- In interactive commands, allow the user to provide one-letter
- input with a single key (i.e., without hitting enter).
- Currently this is used by the `--patch` mode of
- linkgit:git-add[1], linkgit:git-checkout[1],
+ When set to true, allow the user to provide one-letter input
+ with a single key (i.e., without hitting the Enter key) in
+ interactive commands. This is currently used by the `--patch`
+ mode of linkgit:git-add[1], linkgit:git-checkout[1],
linkgit:git-restore[1], linkgit:git-commit[1],
- linkgit:git-reset[1], and linkgit:git-stash[1]. Note that this
- setting is silently ignored if portable keystroke input
- is not available; requires the Perl module Term::ReadKey.
+ linkgit:git-reset[1], and linkgit:git-stash[1].
interactive.diffFilter::
When an interactive command (such as `git add --patch`) shows
diff --git a/Documentation/config/log.txt b/Documentation/config/log.txt
index 5f96cf8..9003a82 100644
--- a/Documentation/config/log.txt
+++ b/Documentation/config/log.txt
@@ -9,7 +9,7 @@
`--date` option. See linkgit:git-log[1] for details.
+
If the format is set to "auto:foo" and the pager is in use, format
-"foo" will be the used for the date format. Otherwise "default" will
+"foo" will be used for the date format. Otherwise, "default" will
be used.
log.decorate::
diff --git a/Documentation/config/mailinfo.txt b/Documentation/config/mailinfo.txt
index 3854d4a..ec3a5d8 100644
--- a/Documentation/config/mailinfo.txt
+++ b/Documentation/config/mailinfo.txt
@@ -1,6 +1,6 @@
mailinfo.scissors::
If true, makes linkgit:git-mailinfo[1] (and therefore
linkgit:git-am[1]) act by default as if the --scissors option
- was provided on the command-line. When active, this features
+ was provided on the command-line. When active, this feature
removes everything from the message body before a scissors
line (i.e. consisting mainly of ">8", "8<" and "-").
diff --git a/Documentation/config/maintenance.txt b/Documentation/config/maintenance.txt
index 18f0562..69a4f05 100644
--- a/Documentation/config/maintenance.txt
+++ b/Documentation/config/maintenance.txt
@@ -12,7 +12,7 @@
then that value is used instead of the one provided by
`maintenance.strategy`. The possible strategy strings are:
+
-* `none`: This default setting implies no task are run at any schedule.
+* `none`: This default setting implies no tasks are run at any schedule.
* `incremental`: This setting optimizes for performing small maintenance
activities that do not delete any data. This does not schedule the `gc`
task, but runs the `prefetch` and `commit-graph` tasks hourly, the
diff --git a/Documentation/config/man.txt b/Documentation/config/man.txt
index a727d98..5a0f82c 100644
--- a/Documentation/config/man.txt
+++ b/Documentation/config/man.txt
@@ -5,7 +5,7 @@
man.<tool>.cmd::
Specify the command to invoke the specified man viewer. The
specified command is evaluated in shell with the man page
- passed as argument. (See linkgit:git-help[1].)
+ passed as an argument. (See linkgit:git-help[1].)
man.<tool>.path::
Override the path for the given tool that may be used to
diff --git a/Documentation/config/merge.txt b/Documentation/config/merge.txt
index 99e83dd..8851b6c 100644
--- a/Documentation/config/merge.txt
+++ b/Documentation/config/merge.txt
@@ -7,7 +7,7 @@
marker and the original text before the `=======` marker. The
"merge" style tends to produce smaller conflict regions than diff3,
both because of the exclusion of the original text, and because
- when a subset of lines match on the two sides they are just pulled
+ when a subset of lines match on the two sides, they are just pulled
out of the conflict region. Another alternate style, "zdiff3", is
similar to diff3 but removes matching lines on the two sides from
the conflict region when those matching lines appear near either
diff --git a/Documentation/config/mergetool.txt b/Documentation/config/mergetool.txt
index 56a7eee..00bf665 100644
--- a/Documentation/config/mergetool.txt
+++ b/Documentation/config/mergetool.txt
@@ -22,8 +22,8 @@
For a custom merge command, specify whether the exit code of
the merge command can be used to determine whether the merge was
successful. If this is not set to true then the merge target file
- timestamp is checked and the merge assumed to have been successful
- if the file has been updated, otherwise the user is prompted to
+ timestamp is checked, and the merge is assumed to have been successful
+ if the file has been updated; otherwise, the user is prompted to
indicate the success of the merge.
mergetool.meld.hasOutput::
@@ -37,7 +37,7 @@
mergetool.meld.useAutoMerge::
When the `--auto-merge` is given, meld will merge all non-conflicting
- parts automatically, highlight the conflicting parts and wait for
+ parts automatically, highlight the conflicting parts, and wait for
user decision. Setting `mergetool.meld.useAutoMerge` to `true` tells
Git to unconditionally use the `--auto-merge` option with `meld`.
Setting this value to `auto` makes git detect whether `--auto-merge`
@@ -45,17 +45,24 @@
value of `false` avoids using `--auto-merge` altogether, and is the
default value.
-mergetool.vimdiff.layout::
- The vimdiff backend uses this variable to control how its split
- windows look like. Applies even if you are using Neovim (`nvim`) or
- gVim (`gvim`) as the merge tool. See BACKEND SPECIFIC HINTS section
-ifndef::git-mergetool[]
- in linkgit:git-mergetool[1].
+mergetool.<vimdiff variant>.layout::
+ Configure the split window layout for vimdiff's `<variant>`, which is any of `vimdiff`,
+ `nvimdiff`, `gvimdiff`.
+ Upon launching `git mergetool` with `--tool=<variant>` (or without `--tool`
+ if `merge.tool` is configured as `<variant>`), Git will consult
+ `mergetool.<variant>.layout` to determine the tool's layout. If the
+ variant-specific configuration is not available, `vimdiff`'s is used as
+ fallback. If that too is not available, a default layout with 4 windows
+ will be used. To configure the layout, see the `BACKEND SPECIFIC HINTS`
+ifdef::git-mergetool[]
+ section.
endif::[]
- for details.
+ifndef::git-mergetool[]
+ section in linkgit:git-mergetool[1].
+endif::[]
mergetool.hideResolved::
- During a merge Git will automatically resolve as many conflicts as
+ During a merge, Git will automatically resolve as many conflicts as
possible and write the 'MERGED' file containing conflict markers around
any conflicts that it cannot resolve; 'LOCAL' and 'REMOTE' normally
represent the versions of the file from before Git's conflict
@@ -74,7 +81,7 @@
When invoking a custom merge tool, Git uses a set of temporary
files to pass to the tool. If the tool returns an error and this
variable is set to `true`, then these temporary files will be
- preserved, otherwise they will be removed after the tool has
+ preserved; otherwise, they will be removed after the tool has
exited. Defaults to `false`.
mergetool.writeToTemp::
diff --git a/Documentation/config/notes.txt b/Documentation/config/notes.txt
index c7c4811..43db8e8 100644
--- a/Documentation/config/notes.txt
+++ b/Documentation/config/notes.txt
@@ -1,7 +1,7 @@
notes.mergeStrategy::
Which merge strategy to choose by default when resolving notes
conflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or
- `cat_sort_uniq`. Defaults to `manual`. See "NOTES MERGE STRATEGIES"
+ `cat_sort_uniq`. Defaults to `manual`. See the "NOTES MERGE STRATEGIES"
section of linkgit:git-notes[1] for more information on each strategy.
+
This setting can be overridden by passing the `--strategy` option to
diff --git a/Documentation/config/pack.txt b/Documentation/config/pack.txt
index 3748136..da52737 100644
--- a/Documentation/config/pack.txt
+++ b/Documentation/config/pack.txt
@@ -28,11 +28,16 @@
to linkgit:git-repack[1].
pack.allowPackReuse::
- When true, and when reachability bitmaps are enabled,
- pack-objects will try to send parts of the bitmapped packfile
- verbatim. This can reduce memory and CPU usage to serve fetches,
- but might result in sending a slightly larger pack. Defaults to
- true.
+ When true or "single", and when reachability bitmaps are
+ enabled, pack-objects will try to send parts of the bitmapped
+ packfile verbatim. When "multi", and when a multi-pack
+ reachability bitmap is available, pack-objects will try to send
+ parts of all packs in the MIDX.
++
+If only a single pack bitmap is available, and `pack.allowPackReuse`
+is set to "multi", reuse parts of just the bitmapped packfile. This
+can reduce memory and CPU usage to serve fetches, but might result in
+sending a slightly larger pack. Defaults to true.
pack.island::
An extended regular expression configuring a set of delta
@@ -74,7 +79,7 @@
warning. This is meant to reduce packing time on multiprocessor
machines. The required amount of memory for the delta search window
is however multiplied by the number of threads.
- Specifying 0 will cause Git to auto-detect the number of CPU's
+ Specifying 0 will cause Git to auto-detect the number of CPUs
and set the number of threads accordingly.
pack.indexVersion::
@@ -83,11 +88,11 @@
the new pack index with capabilities for packs larger than 4 GB
as well as proper protection against the repacking of corrupted
packs. Version 2 is the default. Note that version 2 is enforced
- and this config option ignored whenever the corresponding pack is
+ and this config option is ignored whenever the corresponding pack is
larger than 2 GB.
+
If you have an old Git that does not understand the version 2 `*.idx` file,
-cloning or fetching over a non native protocol (e.g. "http")
+cloning or fetching over a non-native protocol (e.g. "http")
that will copy both `*.pack` file and corresponding `*.idx` file from the
other side may give you a repository that cannot be accessed with your
older version of Git. If the `*.pack` file is smaller than 2 GB, however,
@@ -102,8 +107,8 @@
in the creation of multiple packfiles.
+
Note that this option is rarely useful, and may result in a larger total
-on-disk size (because Git will not store deltas between packs), as well
-as worse runtime performance (object lookup within multiple packs is
+on-disk size (because Git will not store deltas between packs) and
+worse runtime performance (object lookup within multiple packs is
slower than a single pack, and optimizations like reachability bitmaps
cannot cope with multiple packs).
+
diff --git a/Documentation/config/push.txt b/Documentation/config/push.txt
index 43338b6..0acbbea 100644
--- a/Documentation/config/push.txt
+++ b/Documentation/config/push.txt
@@ -35,7 +35,7 @@
* `tracking` - This is a deprecated synonym for `upstream`.
-* `simple` - pushes the current branch with the same name on the remote.
+* `simple` - push the current branch with the same name on the remote.
+
If you are working on a centralized workflow (pushing to the same repository you
pull from, which is typically `origin`), then you need to configure an upstream
@@ -67,7 +67,7 @@
--
push.followTags::
- If set to true enable `--follow-tags` option by default. You
+ If set to true, enable `--follow-tags` option by default. You
may override this configuration at time of push by specifying
`--no-follow-tags`.
diff --git a/Documentation/config/rebase.txt b/Documentation/config/rebase.txt
index 9c248ac..c6187ab 100644
--- a/Documentation/config/rebase.txt
+++ b/Documentation/config/rebase.txt
@@ -9,7 +9,9 @@
rebase. False by default.
rebase.autoSquash::
- If set to true enable `--autosquash` option by default.
+ If set to true, enable the `--autosquash` option of
+ linkgit:git-rebase[1] by default for interactive mode.
+ This can be overridden with the `--no-autosquash` option.
rebase.autoStash::
When set to true, automatically create a temporary stash entry
@@ -38,7 +40,7 @@
rebase.instructionFormat::
A format string, as specified in linkgit:git-log[1], to be used for the
todo list during an interactive rebase. The format will
- automatically have the long commit hash prepended to the format.
+ automatically have the commit hash prepended to the format.
rebase.abbreviateCommands::
If set to true, `git rebase` will use abbreviated command names in the
diff --git a/Documentation/config/receive.txt b/Documentation/config/receive.txt
index 85d5b5a..36a1e6f 100644
--- a/Documentation/config/receive.txt
+++ b/Documentation/config/receive.txt
@@ -8,18 +8,18 @@
capability to its clients. False by default.
receive.autogc::
- By default, git-receive-pack will run "git-gc --auto" after
+ By default, git-receive-pack will run "git maintenance run --auto" after
receiving data from git-push and updating refs. You can stop
it by setting this variable to false.
receive.certNonceSeed::
By setting this variable to a string, `git receive-pack`
- will accept a `git push --signed` and verifies it by using
+ will accept a `git push --signed` and verify it by using
a "nonce" protected by HMAC using this string as a secret
key.
receive.certNonceSlop::
- When a `git push --signed` sent a push certificate with a
+ When a `git push --signed` sends a push certificate with a
"nonce" that was issued by a receive-pack serving the same
repository within this many seconds, export the "nonce"
found in the certificate to `GIT_PUSH_CERT_NONCE` to the
diff --git a/Documentation/config/rerere.txt b/Documentation/config/rerere.txt
index 40abdf6..3a78b5e 100644
--- a/Documentation/config/rerere.txt
+++ b/Documentation/config/rerere.txt
@@ -1,7 +1,7 @@
rerere.autoUpdate::
When set to true, `git-rerere` updates the index with the
resulting contents after it cleanly resolves conflicts using
- previously recorded resolution. Defaults to false.
+ previously recorded resolutions. Defaults to false.
rerere.enabled::
Activate recording of resolved conflicts, so that identical
diff --git a/Documentation/config/safe.txt b/Documentation/config/safe.txt
index bde7f31..2d45c98 100644
--- a/Documentation/config/safe.txt
+++ b/Documentation/config/safe.txt
@@ -14,7 +14,7 @@
within that directory.
+
This config setting is only respected in protected configuration (see
-<<SCOPES>>). This prevents the untrusted repository from tampering with
+<<SCOPES>>). This prevents untrusted repositories from tampering with
this value.
safe.directory::
@@ -32,7 +32,7 @@
`safe.directory` entry with an empty value.
+
This config setting is only respected in protected configuration (see
-<<SCOPES>>). This prevents the untrusted repository from tampering with this
+<<SCOPES>>). This prevents untrusted repositories from tampering with this
value.
+
The value of this setting is interpolated, i.e. `~/<path>` expands to a
@@ -44,7 +44,8 @@
directory was listed in the `safe.directory` list. If `safe.directory=*`
is set in system config and you want to re-enable this protection, then
initialize your list with an empty value before listing the repositories
-that you deem safe.
+that you deem safe. Giving a directory with `/*` appended to it will
+allow access to all repositories under the named directory.
+
As explained, Git only allows you to access repositories owned by
yourself, i.e. the user who is running Git, by default. When Git
diff --git a/Documentation/config/sendemail.txt b/Documentation/config/sendemail.txt
index 92a9ebe..6a869d6 100644
--- a/Documentation/config/sendemail.txt
+++ b/Documentation/config/sendemail.txt
@@ -8,7 +8,7 @@
See linkgit:git-send-email[1] for description. Note that this
setting is not subject to the 'identity' mechanism.
-sendemail.smtpsslcertpath::
+sendemail.smtpSSLCertPath::
Path to ca-certificates (either a directory or a single file).
Set it to an empty string to disable certificate verification.
@@ -36,7 +36,7 @@
sendemail.aliasFileType::
Format of the file(s) specified in sendemail.aliasesFile. Must be
- one of 'mutt', 'mailrc', 'pine', 'elm', or 'gnus', or 'sendmail'.
+ one of 'mutt', 'mailrc', 'pine', 'elm', 'gnus', or 'sendmail'.
+
What an alias file in each format looks like can be found in
the documentation of the email program of the same name. The
@@ -62,12 +62,12 @@
sendemail.envelopeSender::
sendemail.from::
sendemail.headerCmd::
-sendemail.signedoffbycc::
+sendemail.signedOffByCc::
sendemail.smtpPass::
-sendemail.suppresscc::
+sendemail.suppressCc::
sendemail.suppressFrom::
sendemail.to::
-sendemail.tocmd::
+sendemail.toCmd::
sendemail.smtpDomain::
sendemail.smtpServer::
sendemail.smtpServerPort::
@@ -81,8 +81,8 @@
linkgit:git-send-email[1] command-line options. See its
documentation for details.
-sendemail.signedoffcc (deprecated)::
- Deprecated alias for `sendemail.signedoffbycc`.
+sendemail.signedOffCc (deprecated)::
+ Deprecated alias for `sendemail.signedOffByCc`.
sendemail.smtpBatchSize::
Number of messages to be sent per connection, after that a relogin
@@ -91,7 +91,7 @@
See also the `--batch-size` option of linkgit:git-send-email[1].
sendemail.smtpReloginDelay::
- Seconds wait before reconnecting to smtp server.
+ Seconds to wait before reconnecting to the smtp server.
See also the `--relogin-delay` option of linkgit:git-send-email[1].
sendemail.forbidSendmailVariables::
diff --git a/Documentation/config/sequencer.txt b/Documentation/config/sequencer.txt
index b48d532..e664eef 100644
--- a/Documentation/config/sequencer.txt
+++ b/Documentation/config/sequencer.txt
@@ -2,4 +2,4 @@
Text editor used by `git rebase -i` for editing the rebase instruction file.
The value is meant to be interpreted by the shell when it is used.
It can be overridden by the `GIT_SEQUENCE_EDITOR` environment variable.
- When not configured the default commit message editor is used instead.
+ When not configured, the default commit message editor is used instead.
diff --git a/Documentation/config/splitindex.txt b/Documentation/config/splitindex.txt
index afdb186..cfaa296 100644
--- a/Documentation/config/splitindex.txt
+++ b/Documentation/config/splitindex.txt
@@ -3,10 +3,10 @@
percent of entries the split index can contain compared to the
total number of entries in both the split index and the shared
index before a new shared index is written.
- The value should be between 0 and 100. If the value is 0 then
- a new shared index is always written, if it is 100 a new
+ The value should be between 0 and 100. If the value is 0, then
+ a new shared index is always written; if it is 100, a new
shared index is never written.
- By default the value is 20, so a new shared index is written
+ By default, the value is 20, so a new shared index is written
if the number of entries in the split index would be greater
than 20 percent of the total number of entries.
See linkgit:git-update-index[1].
diff --git a/Documentation/config/stash.txt b/Documentation/config/stash.txt
index b9f609e..ec1edae 100644
--- a/Documentation/config/stash.txt
+++ b/Documentation/config/stash.txt
@@ -1,14 +1,14 @@
stash.showIncludeUntracked::
If this is set to true, the `git stash show` command will show
the untracked files of a stash entry. Defaults to false. See
- description of 'show' command in linkgit:git-stash[1].
+ the description of the 'show' command in linkgit:git-stash[1].
stash.showPatch::
If this is set to true, the `git stash show` command without an
option will show the stash entry in patch form. Defaults to false.
- See description of 'show' command in linkgit:git-stash[1].
+ See the description of the 'show' command in linkgit:git-stash[1].
stash.showStat::
If this is set to true, the `git stash show` command without an
- option will show diffstat of the stash entry. Defaults to true.
- See description of 'show' command in linkgit:git-stash[1].
+ option will show a diffstat of the stash entry. Defaults to true.
+ See the description of the 'show' command in linkgit:git-stash[1].
diff --git a/Documentation/config/status.txt b/Documentation/config/status.txt
index 0fc704a..8caf90f 100644
--- a/Documentation/config/status.txt
+++ b/Documentation/config/status.txt
@@ -47,7 +47,7 @@
contain only untracked files, are shown with the directory name
only. Showing untracked files means that Git needs to lstat() all
the files in the whole repository, which might be slow on some
- systems. So, this variable controls how the commands displays
+ systems. So, this variable controls how the commands display
the untracked files. Possible values are:
+
--
@@ -57,12 +57,14 @@
--
+
If this variable is not specified, it defaults to 'normal'.
+All usual spellings for Boolean value `true` are taken as `normal`
+and `false` as `no`.
This variable can be overridden with the -u|--untracked-files option
of linkgit:git-status[1] and linkgit:git-commit[1].
status.submoduleSummary::
Defaults to false.
- If this is set to a non zero number or true (identical to -1 or an
+ If this is set to a non-zero number or true (identical to -1 or an
unlimited number), the submodule summary will be enabled and a
summary of commits for modified submodules will be shown (see
--summary-limit option of linkgit:git-submodule[1]). Please note
diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt
index 6490527..0672d99 100644
--- a/Documentation/config/submodule.txt
+++ b/Documentation/config/submodule.txt
@@ -2,7 +2,7 @@
The URL for a submodule. This variable is copied from the .gitmodules
file to the git config via 'git submodule init'. The user can change
the configured URL before obtaining the submodule via 'git submodule
- update'. If neither submodule.<name>.active or submodule.active are
+ update'. If neither submodule.<name>.active nor submodule.active are
set, the presence of this variable is used as a fallback to indicate
whether the submodule is of interest to git commands.
See linkgit:git-submodule[1] and linkgit:gitmodules[5] for details.
@@ -35,7 +35,7 @@
a submodule as modified. When set to "all", it will never be considered
modified (but it will nonetheless show up in the output of status and
commit when it has been staged), "dirty" will ignore all changes
- to the submodules work tree and
+ to the submodule's work tree and
takes only differences between the HEAD of the submodule and the commit
recorded in the superproject into account. "untracked" will additionally
let submodules with modified tracked files in their work tree show up.
diff --git a/Documentation/config/trace2.txt b/Documentation/config/trace2.txt
index fe1642f..3b6bca2 100644
--- a/Documentation/config/trace2.txt
+++ b/Documentation/config/trace2.txt
@@ -66,6 +66,6 @@
trace2.maxFiles::
Integer. When writing trace files to a target directory, do not
- write additional traces if we would exceed this many files. Instead,
+ write additional traces if doing so would exceed this many files. Instead,
write a sentinel file that will block further tracing to this
directory. Defaults to 0, which disables this check.
diff --git a/Documentation/config/transfer.txt b/Documentation/config/transfer.txt
index c3ac767..f1ce50f 100644
--- a/Documentation/config/transfer.txt
+++ b/Documentation/config/transfer.txt
@@ -7,7 +7,7 @@
and any other direct use of the configured URL.
+
Note that this is currently limited to detecting credentials in
-`remote.<name>.url` configuration, it won't detect 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
@@ -21,12 +21,12 @@
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 other
- users on OS's or systems that allow other users to see the full
+ unprivileged users on systems that allow them 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
+concerned about credentials exposure due to storing sensitive
data in git's configuration files. If you do want to use this, set
`transfer.credentialsInUrl` to one of these values:
+
@@ -121,3 +121,7 @@
information from the remote server (if advertised) and download
bundles before continuing the clone through the Git protocol.
Defaults to `false`.
+
+transfer.advertiseObjectInfo::
+ When `true`, the `object-info` capability is advertised by
+ servers. Defaults to false.
diff --git a/Documentation/config/user.txt b/Documentation/config/user.txt
index ec9233b..2ffc38d 100644
--- a/Documentation/config/user.txt
+++ b/Documentation/config/user.txt
@@ -5,14 +5,14 @@
committer.name::
committer.email::
The `user.name` and `user.email` variables determine what ends
- up in the `author` and `committer` field of commit
+ up in the `author` and `committer` fields of commit
objects.
If you need the `author` or `committer` to be different, the
- `author.name`, `author.email`, `committer.name` or
+ `author.name`, `author.email`, `committer.name`, or
`committer.email` variables can be set.
- Also, all of these can be overridden by the `GIT_AUTHOR_NAME`,
+ All of these can be overridden by the `GIT_AUTHOR_NAME`,
`GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME`,
- `GIT_COMMITTER_EMAIL` and `EMAIL` environment variables.
+ `GIT_COMMITTER_EMAIL`, and `EMAIL` environment variables.
+
Note that the `name` forms of these variables conventionally refer to
some form of a personal name. See linkgit:git-commit[1] and the
@@ -40,7 +40,7 @@
your private ssh key or the public key when ssh-agent is used.
Alternatively it can contain a public key prefixed with `key::`
directly (e.g.: "key::ssh-rsa XXXXXX identifier"). The private key
- needs to be available via ssh-agent. If not set git will call
+ needs to be available via ssh-agent. If not set Git will call
gpg.ssh.defaultKeyCommand (e.g.: "ssh-add -L") and try to use the
first key available. For backward compatibility, a raw key which
begins with "ssh-", such as "ssh-rsa XXXXXX identifier", is treated
diff --git a/Documentation/config/versionsort.txt b/Documentation/config/versionsort.txt
index 6c7cc05..0cff090 100644
--- a/Documentation/config/versionsort.txt
+++ b/Documentation/config/versionsort.txt
@@ -19,14 +19,14 @@
configuration, then all "1.0-preX" tags will be listed before any
"1.0-rcX" tags. The placement of the main release tag relative to tags
with various suffixes can be determined by specifying the empty suffix
-among those other suffixes. E.g. if the suffixes "-rc", "", "-ck" and
+among those other suffixes. E.g. if the suffixes "-rc", "", "-ck", and
"-bfs" appear in the configuration in this order, then all "v4.8-rcX" tags
are listed first, followed by "v4.8", then "v4.8-ckX" and finally
"v4.8-bfsX".
+
-If more than one suffixes match the same tagname, then that tagname will
+If more than one suffix matches the same tagname, then that tagname will
be sorted according to the suffix which starts at the earliest position in
-the tagname. If more than one different matching suffixes start at
+the tagname. If more than one different matching suffix starts at
that earliest position, then that tagname will be sorted according to the
longest of those suffixes.
The sorting order between different suffixes is undefined if they are
diff --git a/Documentation/date-formats.txt b/Documentation/date-formats.txt
index 67645ca..e24517c 100644
--- a/Documentation/date-formats.txt
+++ b/Documentation/date-formats.txt
@@ -11,7 +11,7 @@
For example CET (which is 1 hour ahead of UTC) is `+0100`.
RFC 2822::
- The standard email format as described by RFC 2822, for example
+ The standard date format as described by RFC 2822, for example
`Thu, 07 Apr 2005 22:13:13 +0200`.
ISO 8601::
diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt
index 546adf7..4b5aa5c 100644
--- a/Documentation/diff-generate-patch.txt
+++ b/Documentation/diff-generate-patch.txt
@@ -17,7 +17,7 @@
What the -p option produces is slightly different from the traditional
diff format:
-1. It is preceded with a "git diff" header that looks like this:
+1. It is preceded by a "git diff" header that looks like this:
diff --git a/file1 b/file2
+
@@ -25,9 +25,9 @@
involved. Especially, even for a creation or a deletion,
`/dev/null` is _not_ used in place of the `a/` or `b/` filenames.
+
-When rename/copy is involved, `file1` and `file2` show the
+When a rename/copy is involved, `file1` and `file2` show the
name of the source file of the rename/copy and the name of
-the file that rename/copy produces, respectively.
+the file that the rename/copy produces, respectively.
2. It is followed by one or more extended header lines:
@@ -77,7 +77,7 @@
5. Hunk headers mention the name of the function to which the hunk
applies. See "Defining a custom hunk-header" in
- linkgit:gitattributes[5] for details of how to tailor to this to
+ linkgit:gitattributes[5] for details of how to tailor this to
specific languages.
@@ -89,7 +89,7 @@
format when showing merges with linkgit:git-diff[1] or
linkgit:git-show[1]. Note also that you can give suitable
`--diff-merges` option to any of these commands to force generation of
-diffs in specific format.
+diffs in a specific format.
A "combined diff" format looks like this:
@@ -123,7 +123,7 @@
for_each_ref(get_name);
------------
-1. It is preceded with a "git diff" header, that looks like
+1. It is preceded by a "git diff" header, that looks like
this (when the `-c` option is used):
diff --combined file
@@ -142,22 +142,22 @@
+
The `mode <mode>,<mode>..<mode>` line appears only if at least one of
the <mode> is different from the rest. Extended headers with
-information about detected contents movement (renames and
-copying detection) are designed to work with diff of two
+information about detected content movement (renames and
+copying detection) are designed to work with the diff of two
<tree-ish> and are not used by combined diff format.
-3. It is followed by two-line from-file/to-file header
+3. It is followed by a two-line from-file/to-file header:
--- a/file
+++ b/file
+
-Similar to two-line header for traditional 'unified' diff
+Similar to the two-line header for the traditional 'unified' diff
format, `/dev/null` is used to signal created or deleted
files.
+
However, if the --combined-all-paths option is provided, instead of a
-two-line from-file/to-file you get a N+1 line from-file/to-file header,
-where N is the number of parents in the merge commit
+two-line from-file/to-file, you get an N+1 line from-file/to-file header,
+where N is the number of parents in the merge commit:
--- a/file
--- a/file
@@ -197,7 +197,7 @@
In the above example output, the function signature was changed
from both files (hence two `-` removals from both file1 and
file2, plus `++` to mean one line that was added does not appear
-in either file1 or file2). Also eight other lines are the same
+in either file1 or file2). Also, eight other lines are the same
from file1 but do not appear in file2 (hence prefixed with `+`).
When shown by `git diff-tree -c`, it compares the parents of a
diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index c07488b..c7df20e 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -37,66 +37,79 @@
endif::git-format-patch[]
ifdef::git-log[]
---diff-merges=(off|none|on|first-parent|1|separate|m|combined|c|dense-combined|cc|remerge|r)::
+-m::
+ Show diffs for merge commits in the default format. This is
+ similar to '--diff-merges=on', except `-m` will
+ produce no output unless `-p` is given as well.
+
+-c::
+ Produce combined diff output for merge commits.
+ Shortcut for '--diff-merges=combined -p'.
+
+--cc::
+ Produce dense combined diff output for merge commits.
+ Shortcut for '--diff-merges=dense-combined -p'.
+
+--dd::
+ Produce diff with respect to first parent for both merge and
+ regular commits.
+ Shortcut for '--diff-merges=first-parent -p'.
+
+--remerge-diff::
+ Produce remerge-diff output for merge commits.
+ Shortcut for '--diff-merges=remerge -p'.
+
--no-diff-merges::
+ Synonym for '--diff-merges=off'.
+
+--diff-merges=<format>::
Specify diff format to be used for merge commits. Default is
- {diff-merges-default} unless `--first-parent` is in use, in which case
- `first-parent` is the default.
+ {diff-merges-default} unless `--first-parent` is in use, in
+ which case `first-parent` is the default.
+
---diff-merges=(off|none):::
---no-diff-merges:::
+The following formats are supported:
++
+--
+off, none::
Disable output of diffs for merge commits. Useful to override
implied value.
+
---diff-merges=on:::
---diff-merges=m:::
--m:::
- This option makes diff output for merge commits to be shown in
- the default format. `-m` will produce the output only if `-p`
- is given as well. The default format could be changed using
- `log.diffMerges` configuration parameter, which default value
+on, m::
+ Make diff output for merge commits to be shown in the default
+ format. The default format can be changed using
+ `log.diffMerges` configuration variable, whose default value
is `separate`.
+
---diff-merges=first-parent:::
---diff-merges=1:::
- This option makes merge commits show the full diff with
- respect to the first parent only.
+first-parent, 1::
+ Show full diff with respect to first parent. This is the same
+ format as `--patch` produces for non-merge commits.
+
---diff-merges=separate:::
- This makes merge commits show the full diff with respect to
- each of the parents. Separate log entry and diff is generated
- for each parent.
+separate::
+ Show full diff with respect to each of parents.
+ Separate log entry and diff is generated for each parent.
+
---diff-merges=remerge:::
---diff-merges=r:::
---remerge-diff:::
- With this option, two-parent merge commits are remerged to
- create a temporary tree object -- potentially containing files
- with conflict markers and such. A diff is then shown between
- that temporary tree and the actual merge commit.
+combined, c::
+ Show differences from each of the parents to the merge
+ result simultaneously instead of showing pairwise diff between
+ a parent and the result one at a time. Furthermore, it lists
+ only files which were modified from all parents.
++
+dense-combined, cc::
+ Further compress output produced by `--diff-merges=combined`
+ by omitting uninteresting hunks whose contents in the parents
+ have only two variants and the merge result picks one of them
+ without modification.
++
+remerge, r::
+ Remerge two-parent merge commits to create a temporary tree
+ object--potentially containing files with conflict markers
+ and such. A diff is then shown between that temporary tree
+ and the actual merge commit.
+
The output emitted when this option is used is subject to change, and
so is its interaction with other options (unless explicitly
documented).
-+
---diff-merges=combined:::
---diff-merges=c:::
--c:::
- With this option, diff output for a merge commit shows the
- differences from each of the parents to the merge result
- simultaneously instead of showing pairwise diff between a
- parent and the result one at a time. Furthermore, it lists
- only files which were modified from all parents. `-c` implies
- `-p`.
-+
---diff-merges=dense-combined:::
---diff-merges=cc:::
---cc:::
- With this option the output produced by
- `--diff-merges=combined` is further compressed by omitting
- uninteresting hunks whose contents in the parents have only
- two variants and the merge result picks one of them without
- modification. `--cc` implies `-p`.
+--
--combined-all-paths::
This flag causes combined diffs (used for merge commits) to
@@ -204,14 +217,15 @@
part. Maximum width defaults to terminal width, or 80 columns
if not connected to a terminal, and can be overridden by
`<width>`. The width of the filename part can be limited by
- giving another width `<name-width>` after a comma. The width
- of the graph part can be limited by using
- `--stat-graph-width=<width>` (affects all commands generating
- a stat graph) or by setting `diff.statGraphWidth=<width>`
- (does not affect `git format-patch`).
- By giving a third parameter `<count>`, you can limit the
- output to the first `<count>` lines, followed by `...` if
- there are more.
+ giving another width `<name-width>` after a comma or by setting
+ `diff.statNameWidth=<width>`. The width of the graph part can be
+ limited by using `--stat-graph-width=<width>` or by setting
+ `diff.statGraphWidth=<width>`. Using `--stat` or
+ `--stat-graph-width` affects all commands generating a stat graph,
+ while setting `diff.statNameWidth` or `diff.statGraphWidth`
+ does not affect `git format-patch`.
+ By giving a third parameter `<count>`, you can limit the output to
+ the first `<count>` lines, followed by `...` if there are more.
+
These parameters can also be set individually with `--stat-width=<width>`,
`--stat-name-width=<name-width>` and `--stat-count=<count>`.
@@ -285,7 +299,7 @@
Synonym for --dirstat=cumulative
--dirstat-by-file[=<param1,param2>...]::
- Synonym for --dirstat=files,param1,param2...
+ Synonym for --dirstat=files,<param1>,<param2>...
--summary::
Output a condensed summary of extended header information
@@ -300,7 +314,7 @@
-z::
ifdef::git-log[]
- Separate the commits with NULs instead of with new newlines.
+ Separate the commits with NULs instead of newlines.
+
Also, when `--raw` or `--numstat` has been given, do not munge
pathnames and use NULs as output field terminators.
@@ -315,12 +329,13 @@
linkgit:git-config[1]).
--name-only::
- Show only names of changed files. The file names are often encoded in UTF-8.
+ Show only the name of each changed file in the post-image tree.
+ The file names are often encoded in UTF-8.
For more information see the discussion about encoding in the linkgit:git-log[1]
manual page.
--name-status::
- Show only names and status of changed files. See the description
+ Show only the name(s) and status of each changed file. See the description
of the `--diff-filter` option on what the status letters mean.
Just like `--name-only` the file names are often encoded in UTF-8.
@@ -732,7 +747,7 @@
--rotate-to=<file>::
Discard the files before the named <file> from the output
(i.e. 'skip to'), or move them to the end of the output
- (i.e. 'rotate to'). These were invented primarily for use
+ (i.e. 'rotate to'). These options were invented primarily for the use
of the `git difftool` command, and may not be very useful
otherwise.
@@ -851,8 +866,9 @@
--default-prefix::
Use the default source and destination prefixes ("a/" and "b/").
- This is usually the default already, but may be used to override
- config such as `diff.noprefix`.
+ This overrides configuration variables such as `diff.noprefix`,
+ `diff.srcPrefix`, `diff.dstPrefix`, and `diff.mnemonicPrefix`
+ (see `git-config`(1)).
--line-prefix=<prefix>::
Prepend an additional prefix to every line of output.
diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index 41fc7ca..e22b217 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt
@@ -1,5 +1,6 @@
---all::
- Fetch all remotes.
+--[no-]all::
+ Fetch all remotes. This overrides the configuration variable
+ `fetch.all`.
-a::
--append::
@@ -43,7 +44,7 @@
--update-shallow::
By default when fetching from a shallow repository,
`git fetch` refuses refs that require updating
- .git/shallow. This option updates .git/shallow and accept such
+ .git/shallow. This option updates .git/shallow and accepts such
refs.
--negotiation-tip=<commit|glob>::
@@ -96,7 +97,7 @@
-f::
--force::
- When 'git fetch' is used with `<src>:<dst>` refspec it may
+ When 'git fetch' is used with `<src>:<dst>` refspec, it may
refuse to update the local branch as discussed
ifdef::git-pull[]
in the `<refspec>` part of the linkgit:git-fetch[1]
@@ -201,7 +202,7 @@
destination of an explicit refspec; see `--prune`).
ifndef::git-pull[]
---recurse-submodules[=yes|on-demand|no]::
+--recurse-submodules[=(yes|on-demand|no)]::
This option controls if and under what conditions new commits of
submodules should be fetched too. When recursing through submodules,
`git fetch` always attempts to fetch "changed" submodules, that is, a
diff --git a/Documentation/fsck-msgids.txt b/Documentation/fsck-msgids.txt
index 12eae8a..f643585 100644
--- a/Documentation/fsck-msgids.txt
+++ b/Documentation/fsck-msgids.txt
@@ -103,6 +103,13 @@
`hasDotgit`::
(WARN) A tree contains an entry named `.git`.
+`largePathname`::
+ (WARN) A tree contains an entry with a very long path name. If
+ the value of `fsck.largePathname` contains a colon, that value
+ is used as the maximum allowable length (e.g., "warn:10" would
+ complain about any path component of 11 or more bytes). The
+ default value is 4096.
+
`mailmapSymlink`::
(INFO) `.mailmap` is a symlink.
@@ -125,7 +132,7 @@
(ERROR) Missing space before date in an author/committer line.
`missingSpaceBeforeEmail`::
- (ERROR) Missing space before the email in author/committer line.
+ (ERROR) Missing space before the email in an author/committer line.
`missingTag`::
(ERROR) Unexpected end after `type` line in a tag object.
@@ -167,7 +174,7 @@
(FATAL) Missing end-of-line in the object header.
`zeroPaddedDate`::
- (ERROR) Found a zero padded date in an author/commiter line.
+ (ERROR) Found a zero padded date in an author/committer line.
`zeroPaddedFilemode`::
(WARN) Found a zero padded filemode in a tree.
diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index ed44c1c..aceaa02 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -9,7 +9,7 @@
--------
[verse]
'git add' [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [--patch | -p]
- [--edit | -e] [--[no-]all | --[no-]ignore-removal | [--update | -u]] [--sparse]
+ [--edit | -e] [--[no-]all | -A | --[no-]ignore-removal | [--update | -u]] [--sparse]
[--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing] [--renormalize]
[--chmod=(+|-)x] [--pathspec-from-file=<file> [--pathspec-file-nul]]
[--] [<pathspec>...]
@@ -63,7 +63,7 @@
to ignore removed files; use `--no-all` option if you want
to add modified or new files but ignore removed ones.
+
-For more details about the <pathspec> syntax, see the 'pathspec' entry
+For more details about the _<pathspec>_ syntax, see the 'pathspec' entry
in linkgit:gitglossary[7].
-n::
@@ -119,10 +119,10 @@
-u::
--update::
Update the index just where it already has an entry matching
- <pathspec>. This removes as well as modifies index entries to
+ _<pathspec>_. This removes as well as modifies index entries to
match the working tree, but adds no new files.
+
-If no <pathspec> is given when `-u` option is used, all
+If no _<pathspec>_ is given when `-u` option is used, all
tracked files in the entire working tree are updated (old versions
of Git used to limit the update to the current directory and its
subdirectories).
@@ -131,11 +131,11 @@
--all::
--no-ignore-removal::
Update the index not only where the working tree has a file
- matching <pathspec> but also where the index already has an
+ matching _<pathspec>_ but also where the index already has an
entry. This adds, modifies, and removes index entries to
match the working tree.
+
-If no <pathspec> is given when `-A` option is used, all
+If no _<pathspec>_ is given when `-A` option is used, all
files in the entire working tree are updated (old versions
of Git used to limit the update to the current directory and its
subdirectories).
@@ -145,11 +145,11 @@
Update the index by adding new files that are unknown to the
index and files modified in the working tree, but ignore
files that have been removed from the working tree. This
- option is a no-op when no <pathspec> is used.
+ option is a no-op when no _<pathspec>_ is used.
+
This option is primarily to help users who are used to older
-versions of Git, whose "git add <pathspec>..." was a synonym
-for "git add --no-all <pathspec>...", i.e. ignored removed files.
+versions of Git, whose "git add _<pathspec>_..." was a synonym
+for "git add --no-all _<pathspec>_...", i.e. ignored removed files.
-N::
--intent-to-add::
@@ -198,8 +198,8 @@
unchanged.
--pathspec-from-file=<file>::
- Pathspec is passed in `<file>` instead of commandline args. If
- `<file>` is exactly `-` then standard input is used. Pathspec
+ Pathspec is passed in _<file>_ instead of commandline args. If
+ _<file>_ is exactly `-` then standard input is used. Pathspec
elements are separated by LF or CR/LF. Pathspec elements can be
quoted as explained for the configuration variable `core.quotePath`
(see linkgit:git-config[1]). See also `--pathspec-file-nul` and
@@ -348,6 +348,7 @@
K - leave this hunk undecided, see previous hunk
s - split the current hunk into smaller hunks
e - manually edit the current hunk
+ p - print the current hunk
? - print help
+
After deciding the fate for all hunks, if there is any hunk
diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
index 82dadbe..624a6e6 100644
--- a/Documentation/git-am.txt
+++ b/Documentation/git-am.txt
@@ -22,8 +22,8 @@
DESCRIPTION
-----------
-Splits mail messages in a mailbox into commit log message,
-authorship information and patches, and applies them to the
+Splits mail messages in a mailbox into commit log messages,
+authorship information, and patches, and applies them to the
current branch. You could think of it as a reverse operation
of linkgit:git-format-patch[1] run on a branch with a straight
history without merges.
@@ -66,13 +66,19 @@
--quoted-cr=<action>::
This flag will be passed down to 'git mailinfo' (see linkgit:git-mailinfo[1]).
---empty=(stop|drop|keep)::
- By default, or when the option is set to 'stop', the command
- errors out on an input e-mail message lacking a patch
- and stops into the middle of the current am session. When this
- option is set to 'drop', skip such an e-mail message instead.
- When this option is set to 'keep', create an empty commit,
- recording the contents of the e-mail message as its log.
+--empty=(drop|keep|stop)::
+ How to handle an e-mail message lacking a patch:
++
+--
+`drop`;;
+ The e-mail message will be skipped.
+`keep`;;
+ An empty commit will be created, with the contents of the e-mail
+ message as its log.
+`stop`;;
+ The command will fail, stopping in the middle of the current `am`
+ session. This is the default behavior.
+--
-m::
--message-id::
@@ -94,7 +100,7 @@
Pass `-u` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]).
The proposed commit log message taken from the e-mail
is re-coded into UTF-8 encoding (configuration variable
- `i18n.commitEncoding` can be used to specify project's
+ `i18n.commitEncoding` can be used to specify the project's
preferred encoding if it is not UTF-8).
+
This was optional in prior versions of git, but now it is the
@@ -128,13 +134,16 @@
These flags are passed to the 'git apply' (see linkgit:git-apply[1])
program that applies
the patch.
++
+Valid <action> for the `--whitespace` option are:
+`nowarn`, `warn`, `fix`, `error`, and `error-all`.
--patch-format::
By default the command will try to detect the patch format
automatically. This option allows the user to bypass the automatic
detection and specify the patch format that the patch(es) should be
interpreted as. Valid formats are mbox, mboxrd,
- stgit, stgit-series and hg.
+ stgit, stgit-series, and hg.
-i::
--interactive::
@@ -192,7 +201,7 @@
--abort::
Restore the original branch and abort the patching operation.
- Revert contents of files involved in the am operation to their
+ Revert the contents of files involved in the am operation to their
pre-am state.
--quit::
diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt
index 5e16e6d..9cce68a 100644
--- a/Documentation/git-apply.txt
+++ b/Documentation/git-apply.txt
@@ -23,8 +23,8 @@
Reads the supplied diff output (i.e. "a patch") and applies it to files.
When running from a subdirectory in a repository, patched paths
outside the directory are ignored.
-With the `--index` option the patch is also applied to the index, and
-with the `--cached` option the patch is only applied to the index.
+With the `--index` option, the patch is also applied to the index, and
+with the `--cached` option, the patch is only applied to the index.
Without these options, the command applies the patch only to files,
and does not require them to be in a Git repository.
@@ -52,7 +52,7 @@
--summary::
Instead of applying the patch, output a condensed
summary of information obtained from git diff extended
- headers, such as creations, renames and mode changes.
+ headers, such as creations, renames, and mode changes.
Turns off "apply".
--check::
@@ -140,7 +140,7 @@
applying a diff generated with `--unified=0`. To bypass these
checks use `--unidiff-zero`.
+
-Note, for the reasons stated above usage of context-free patches is
+Note, for the reasons stated above, the usage of context-free patches is
discouraged.
--apply::
@@ -159,9 +159,9 @@
--allow-binary-replacement::
--binary::
- Historically we did not allow binary patch applied
+ Historically we did not allow binary patch application
without an explicit permission from the user, and this
- flag was the way to do so. Currently we always allow binary
+ flag was the way to do so. Currently, we always allow binary
patch application, so this is a no-op.
--exclude=<path-pattern>::
@@ -257,7 +257,7 @@
has no effect when `--index` or `--cached` is in use.
--allow-empty::
- Don't return error for patches containing no diff. This includes
+ Don't return an error for patches containing no diff. This includes
empty patches and patches with commit text only.
CONFIGURATION
diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt
index 6bab201..98526f2 100644
--- a/Documentation/git-archive.txt
+++ b/Documentation/git-archive.txt
@@ -21,14 +21,14 @@
output. If <prefix> is specified it is
prepended to the filenames in the archive.
-'git archive' behaves differently when given a tree ID versus when
-given a commit ID or tag ID. In the first case the current time is
-used as the modification time of each file in the archive. In the latter
-case the commit time as recorded in the referenced commit object is
-used instead. Additionally the commit ID is stored in a global
-extended pax header if the tar format is used; it can be extracted
-using 'git get-tar-commit-id'. In ZIP files it is stored as a file
-comment.
+'git archive' behaves differently when given a tree ID as opposed to a
+commit ID or tag ID. When a tree ID is provided, the current time is
+used as the modification time of each file in the archive. On the
+other hand, when a commit ID or tag ID is provided, the commit time as
+recorded in the referenced commit object is used instead.
+Additionally the commit ID is stored in a global extended pax header
+if the tar format is used; it can be extracted using 'git
+get-tar-commit-id'. In ZIP files it is stored as a file comment.
OPTIONS
-------
diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt
index 7872dba..82f944d 100644
--- a/Documentation/git-bisect.txt
+++ b/Documentation/git-bisect.txt
@@ -16,17 +16,17 @@
The command takes various subcommands, and different options depending
on the subcommand:
- git bisect start [--term-{new,bad}=<term> --term-{old,good}=<term>]
- [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<paths>...]
+ git bisect start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]
+ [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...]
git bisect (bad|new|<term-new>) [<rev>]
git bisect (good|old|<term-old>) [<rev>...]
- git bisect terms [--term-good | --term-bad]
+ git bisect terms [--term-(good|old) | --term-(bad|new)]
git bisect skip [(<rev>|<range>)...]
git bisect reset [<commit>]
git bisect (visualize|view)
git bisect replay <logfile>
git bisect log
- git bisect run <cmd>...
+ git bisect run <cmd> [<arg>...]
git bisect help
This command uses a binary search algorithm to find which commit in
@@ -165,8 +165,10 @@
git bisect terms
------------------------------------------------
-You can get just the old (respectively new) term with `git bisect terms
---term-old` or `git bisect terms --term-good`.
+You can get just the old term with `git bisect terms --term-old`
+or `git bisect terms --term-good`; `git bisect terms --term-new`
+and `git bisect terms --term-bad` can be used to learn how to call
+the commits more recent than the sought change.
If you would like to use your own terms instead of "bad"/"good" or
"new"/"old", you can choose any names you like (except existing bisect
@@ -299,7 +301,7 @@
You can further cut down the number of trials, if you know what part of
the tree is involved in the problem you are tracking down, by specifying
-path parameters when issuing the `bisect start` command:
+pathspec parameters when issuing the `bisect start` command:
------------
$ git bisect start -- arch/i386 include/asm-i386
@@ -362,7 +364,7 @@
--no-checkout::
+
Do not checkout the new working tree at each iteration of the bisection
-process. Instead just update a special reference named `BISECT_HEAD` to make
+process. Instead just update the reference named `BISECT_HEAD` to make
it point to the commit that should be tested.
+
This option may be useful when the test you would perform in each step
diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt
index f69a871..b1d7fb5 100644
--- a/Documentation/git-blame.txt
+++ b/Documentation/git-blame.txt
@@ -77,7 +77,7 @@
-e::
--show-email::
- Show the author email instead of author name (Default: off).
+ Show the author email instead of the author name (Default: off).
This can also be controlled via the `blame.showEmail` config
option.
@@ -100,7 +100,7 @@
`git blame` will output annotation for each line with:
- abbreviated object name for the commit the line came from;
-- author ident (by default author name and date, unless `-s` or `-e`
+- author ident (by default the author name and date, unless `-s` or `-e`
is specified); and
- line number
@@ -128,7 +128,7 @@
- the filename in the commit that the line is attributed to.
- the first line of the commit log message ("summary").
-The contents of the actual line is output after the above
+The contents of the actual line are output after the above
header, prefixed by a TAB. This is to allow adding more
header elements later.
@@ -170,7 +170,7 @@
When you are not interested in changes older than version
v2.6.18, or changes older than 3 weeks, you can use revision
-range specifiers similar to 'git rev-list':
+range specifiers similar to 'git rev-list':
git blame v2.6.18.. -- foo
git blame --since=3.weeks -- foo
@@ -210,7 +210,7 @@
. Each blame entry always starts with a line of:
- <40-byte hex sha1> <sourceline> <resultline> <num_lines>
+ <40-byte-hex-sha1> <sourceline> <resultline> <num-lines>
+
Line numbers count from 1.
diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index d207da9..0b08442 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -312,7 +312,8 @@
option is omitted, the current HEAD will be used instead.
<oldbranch>::
- The name of an existing branch to rename.
+ The name of an existing branch. If this option is omitted,
+ the name of the current branch will be used instead.
<newbranch>::
The new name for an existing branch. The same restrictions as for
@@ -324,7 +325,7 @@
multiple times, in which case the last key becomes the primary
key. The keys supported are the same as those in `git
for-each-ref`. Sort order defaults to the value configured for the
- `branch.sort` variable if exists, or to sorting based on the
+ `branch.sort` variable if it exists, or to sorting based on the
full refname (including `refs/...` prefix). This lists
detached HEAD (if present) first, then local branches and
finally remote-tracking branches. See linkgit:git-config[1].
diff --git a/Documentation/git-bugreport.txt b/Documentation/git-bugreport.txt
index eca726e..112658b 100644
--- a/Documentation/git-bugreport.txt
+++ b/Documentation/git-bugreport.txt
@@ -8,15 +8,17 @@
SYNOPSIS
--------
[verse]
-'git bugreport' [(-o | --output-directory) <path>] [(-s | --suffix) <format>]
+'git bugreport' [(-o | --output-directory) <path>]
+ [(-s | --suffix) <format> | --no-suffix]
[--diagnose[=<mode>]]
DESCRIPTION
-----------
-Captures information about the user's machine, Git client, and repository state,
-as well as a form requesting information about the behavior the user observed,
-into a single text file which the user can then share, for example to the Git
-mailing list, in order to report an observed bug.
+Collects information about the user's machine, Git client, and repository
+state, in addition to a form requesting information about the behavior the
+user observed, and stores it in a single text file which the user can then
+share, for example to the Git mailing list, in order to report an observed
+bug.
The following information is requested from the user:
@@ -50,16 +52,19 @@
-s <format>::
--suffix <format>::
+--no-suffix::
Specify an alternate suffix for the bugreport name, to create a file
- named 'git-bugreport-<formatted suffix>'. This should take the form of a
+ named 'git-bugreport-<formatted-suffix>'. This should take the form of a
strftime(3) format string; the current local time will be used.
+ `--no-suffix` disables the suffix and the file is just named
+ `git-bugreport` without any disambiguation measure.
--no-diagnose::
--diagnose[=<mode>]::
Create a zip archive of supplemental information about the user's
machine, Git client, and repository state. The archive is written to the
same output directory as the bug report and is named
- 'git-diagnostics-<formatted suffix>'.
+ 'git-diagnostics-<formatted-suffix>'.
+
Without `mode` specified, the diagnostic archive will contain the default set of
statistics reported by `git diagnose`. An optional `mode` value may be specified
diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt
index 6e4f3aa..cb5a6c8 100644
--- a/Documentation/git-check-attr.txt
+++ b/Documentation/git-check-attr.txt
@@ -29,7 +29,7 @@
--stdin::
Read pathnames from the standard input, one per line,
- instead of from the command-line.
+ instead of from the command line.
-z::
The output format is modified to be machine-parsable.
@@ -38,7 +38,7 @@
--source=<tree-ish>::
Check attributes against the specified tree-ish. It is common to
- specify the source tree by naming a commit, branch or tag associated
+ specify the source tree by naming a commit, branch, or tag associated
with it.
\--::
@@ -60,7 +60,7 @@
<path> is the path of a file being queried, <attribute> is an attribute
-being queried and <info> can be either:
+being queried, and <info> can be either:
'unspecified';; when the attribute is not defined for the path.
'unset';; when the attribute is defined as false.
diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt
index 2892799..3e3b4e3 100644
--- a/Documentation/git-check-ignore.txt
+++ b/Documentation/git-check-ignore.txt
@@ -50,7 +50,7 @@
with a NUL character instead of a linefeed character.
-n, --non-matching::
- Show given paths which don't match any pattern. This only
+ Show given paths which don't match any pattern. This only
makes sense when `--verbose` is enabled, otherwise it would
not be possible to distinguish between paths which match a
pattern and those which don't.
diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt
index ee6a414..2aacfd1 100644
--- a/Documentation/git-check-ref-format.txt
+++ b/Documentation/git-check-ref-format.txt
@@ -48,7 +48,7 @@
. They cannot begin or end with a slash `/` or contain multiple
consecutive slashes (see the `--normalize` option below for an
- exception to this rule)
+ exception to this rule).
. They cannot end with a dot `.`.
@@ -85,7 +85,7 @@
may be stricter than what `git check-ref-format refs/heads/$name`
says (e.g. a dash may appear at the beginning of a ref component,
but it is explicitly forbidden at the beginning of a branch name).
-When run with `--branch` option in a repository, the input is first
+When run with the `--branch` option in a repository, the input is first
expanded for the ``previous checkout syntax''
`@{-n}`. For example, `@{-1}` is a way to refer the last thing that
was checked out using "git switch" or "git checkout" operation.
diff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt
index 01dbd5c..faf8d6c 100644
--- a/Documentation/git-checkout-index.txt
+++ b/Documentation/git-checkout-index.txt
@@ -18,7 +18,7 @@
DESCRIPTION
-----------
-Will copy all files listed from the index to the working directory
+Copies all listed files from the index to the working directory
(not overwriting existing files).
OPTIONS
@@ -53,11 +53,11 @@
--stage=<number>|all::
Instead of checking out unmerged entries, copy out the
- files from named stage. <number> must be between 1 and 3.
+ files from the named stage. <number> must be between 1 and 3.
Note: --stage=all automatically implies --temp.
--temp::
- Instead of copying the files to the working directory
+ Instead of copying the files to the working directory,
write the content to temporary files. The temporary name
associations will be written to stdout.
@@ -66,8 +66,8 @@
set.
--stdin::
- Instead of taking list of paths from the command line,
- read list of paths from the standard input. Paths are
+ Instead of taking a list of paths from the command line,
+ read the list of paths from the standard input. Paths are
separated by LF (i.e. one path per line) by default.
-z::
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 4af0904..8bdfa54 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -12,8 +12,10 @@
'git checkout' [-q] [-f] [-m] --detach [<branch>]
'git checkout' [-q] [-f] [-m] [--detach] <commit>
'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>]
-'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...
-'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]
+'git checkout' [-f] <tree-ish> [--] <pathspec>...
+'git checkout' [-f] <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]
+'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...
+'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]
'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...]
DESCRIPTION
@@ -41,7 +43,7 @@
You could omit `<branch>`, in which case the command degenerates to
"check out the current branch", which is a glorified no-op with
rather expensive side-effects to show only the tracking information,
-if exists, for the current branch.
+if it exists, for the current branch.
'git checkout' -b|-B <new-branch> [<start-point>]::
@@ -61,7 +63,9 @@
------------
+
that is to say, the branch is not reset/created unless "git checkout" is
-successful.
+successful (e.g., when the branch is in use in another worktree, not
+just the current branch stays the same, but the branch is not reset to
+the start-point, either).
'git checkout' --detach [<branch>]::
'git checkout' [--detach] <commit>::
@@ -213,7 +217,7 @@
below for details.
--orphan <new-branch>::
- Create a new 'orphan' branch, named `<new-branch>`, started from
+ Create a new unborn branch, named `<new-branch>`, started from
`<start-point>` and switch to it. The first commit made on this
new branch will have no parents and it will be the root of a new
history totally disconnected from all the other branches and
@@ -260,7 +264,8 @@
should result in deletion of the path).
+
When checking out paths from the index, this option lets you recreate
-the conflicted merge in the specified paths.
+the conflicted merge in the specified paths. This option cannot be
+used when checking out paths from a tree-ish.
+
When switching branches with `--merge`, staged changes may be lost.
diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt
index fdcad3d..81ace90 100644
--- a/Documentation/git-cherry-pick.txt
+++ b/Documentation/git-cherry-pick.txt
@@ -131,20 +131,36 @@
even without this option. Note also, that use of this option only
keeps commits that were initially empty (i.e. the commit recorded the
same tree as its parent). Commits which are made empty due to a
- previous commit are dropped. To force the inclusion of those commits
- use `--keep-redundant-commits`.
+ previous commit will cause the cherry-pick to fail. To force the
+ inclusion of those commits, use `--empty=keep`.
--allow-empty-message::
By default, cherry-picking a commit with an empty message will fail.
This option overrides that behavior, allowing commits with empty
messages to be cherry picked.
+--empty=(drop|keep|stop)::
+ How to handle commits being cherry-picked that are redundant with
+ changes already in the current history.
++
+--
+`drop`;;
+ The commit will be dropped.
+`keep`;;
+ The commit will be kept. Implies `--allow-empty`.
+`stop`;;
+ The cherry-pick will stop when the commit is applied, allowing
+ you to examine the commit. This is the default behavior.
+--
++
+Note that `--empty=drop` and `--empty=stop` only specify how to handle a
+commit that was not initially empty, but rather became empty due to a previous
+commit. Commits that were initially empty will still cause the cherry-pick to
+fail unless one of `--empty=keep` or `--allow-empty` are specified.
++
+
--keep-redundant-commits::
- If a commit being cherry picked duplicates a commit already in the
- current history, it will become empty. By default these
- redundant commits cause `cherry-pick` to stop so the user can
- examine the commit. This option overrides that behavior and
- creates an empty commit object. Implies `--allow-empty`.
+ Deprecated synonym for `--empty=keep`.
--strategy=<strategy>::
Use the given merge strategy. Should only be used once.
diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt
index 5e1a3d5..fd17165 100644
--- a/Documentation/git-clean.txt
+++ b/Documentation/git-clean.txt
@@ -37,7 +37,7 @@
--force::
If the Git configuration variable clean.requireForce is not set
to false, 'git clean' will refuse to delete files or directories
- unless given -f or -i. Git will refuse to modify untracked
+ unless given -f. Git will refuse to modify untracked
nested git repositories (directories with a .git subdirectory)
unless a second -f is given.
@@ -45,10 +45,14 @@
--interactive::
Show what would be done and clean files interactively. See
``Interactive mode'' for details.
+ Configuration variable `clean.requireForce` is ignored, as
+ this mode gives its own safety protection by going interactive.
-n::
--dry-run::
Don't actually remove anything, just show what would be done.
+ Configuration variable `clean.requireForce` is ignored, as
+ nothing will be deleted anyway.
-q::
--quiet::
@@ -103,7 +107,7 @@
This shows the files and directories to be deleted and issues an
"Input ignore patterns>>" prompt. You can input space-separated
patterns to exclude files and directories from deletion.
- E.g. "*.c *.h" will excludes files end with ".c" and ".h" from
+ E.g. "*.c *.h" will exclude files ending with ".c" and ".h" from
deletion. When you are satisfied with the filtered result, press
ENTER (empty) back to the main menu.
diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index c37c4a3..5de18de 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -9,15 +9,15 @@
SYNOPSIS
--------
[verse]
-'git clone' [--template=<template-directory>]
- [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror]
- [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>]
- [--dissociate] [--separate-git-dir <git-dir>]
- [--depth <depth>] [--[no-]single-branch] [--no-tags]
- [--recurse-submodules[=<pathspec>]] [--[no-]shallow-submodules]
- [--[no-]remote-submodules] [--jobs <n>] [--sparse] [--[no-]reject-shallow]
- [--filter=<filter> [--also-filter-submodules]] [--] <repository>
- [<directory>]
+`git clone` [++--template=++__<template-directory>__]
+ [`-l`] [`-s`] [`--no-hardlinks`] [`-q`] [`-n`] [`--bare`] [`--mirror`]
+ [`-o` _<name>_] [`-b` _<name>_] [`-u` _<upload-pack>_] [`--reference` _<repository>_]
+ [`--dissociate`] [`--separate-git-dir` _<git-dir>_]
+ [`--depth` _<depth>_] [`--`[`no-`]`single-branch`] [`--no-tags`]
+ [++--recurse-submodules++[++=++__<pathspec>__]] [`--`[`no-`]`shallow-submodules`]
+ [`--`[`no-`]`remote-submodules`] [`--jobs` _<n>_] [`--sparse`] [`--`[`no-`]`reject-shallow`]
+ [++--filter=++__<filter-spec>__] [`--also-filter-submodules`]] [`--`] _<repository>_
+ [_<directory>_]
DESCRIPTION
-----------
@@ -31,7 +31,7 @@
After the clone, a plain `git fetch` without arguments will update
all the remote-tracking branches, and a `git pull` without
arguments will in addition merge the remote master branch into the
-current master branch, if any (this is untrue when "--single-branch"
+current master branch, if any (this is untrue when `--single-branch`
is given; see below).
This default configuration is achieved by creating references to
@@ -42,12 +42,12 @@
OPTIONS
-------
--l::
---local::
+`-l`::
+`--local`::
When the repository to clone from is on a local machine,
this flag bypasses the normal "Git aware" transport
mechanism and clones the repository by making a copy of
- HEAD and everything under objects and refs directories.
+ `HEAD` and everything under objects and refs directories.
The files under `.git/objects/` directory are hardlinked
to save space when possible.
+
@@ -67,14 +67,14 @@
source repository, similar to running `cp -r src dst` while modifying
`src`.
---no-hardlinks::
+`--no-hardlinks`::
Force the cloning process from a repository on a local
filesystem to copy the files under the `.git/objects`
directory instead of using hardlinks. This may be desirable
if you are trying to make a back-up of your repository.
--s::
---shared::
+`-s`::
+`--shared`::
When the repository to clone is on the local machine,
instead of using hard links, automatically setup
`.git/objects/info/alternates` to share the objects
@@ -101,10 +101,10 @@
its source repository, you can simply run `git repack -a` to copy all
objects from the source repository into a pack in the cloned repository.
---reference[-if-able] <repository>::
- If the reference repository is on the local machine,
+`--reference`[`-if-able`] _<repository>_::
+ If the reference _<repository>_ is on the local machine,
automatically setup `.git/objects/info/alternates` to
- obtain objects from the reference repository. Using
+ obtain objects from the reference _<repository>_. Using
an already existing repository as an alternate will
require fewer objects to be copied from the repository
being cloned, reducing network and local storage costs.
@@ -115,7 +115,7 @@
*NOTE*: see the NOTE for the `--shared` option, and also the
`--dissociate` option.
---dissociate::
+`--dissociate`::
Borrow the objects from reference repositories specified
with the `--reference` options only to reduce network
transfer, and stop borrowing from them after a clone is made
@@ -126,43 +126,43 @@
same repository, and this option can be used to stop the
borrowing.
--q::
---quiet::
+`-q`::
+`--quiet`::
Operate quietly. Progress is not reported to the standard
error stream.
--v::
---verbose::
+`-v`::
+`--verbose`::
Run verbosely. Does not affect the reporting of progress status
to the standard error stream.
---progress::
+`--progress`::
Progress status is reported on the standard error stream
by default when it is attached to a terminal, unless `--quiet`
is specified. This flag forces progress status even if the
standard error stream is not directed to a terminal.
---server-option=<option>::
+++--server-option=++__<option>__::
Transmit the given string to the server when communicating using
protocol version 2. The given string must not contain a NUL or LF
character. The server's handling of server options, including
unknown ones, is server-specific.
- When multiple `--server-option=<option>` are given, they are all
+ When multiple ++--server-option=++__<option>__ are given, they are all
sent to the other side in the order listed on the command line.
--n::
---no-checkout::
+`-n`::
+`--no-checkout`::
No checkout of HEAD is performed after the clone is complete.
---[no-]reject-shallow::
+`--`[`no-`]`reject-shallow`::
Fail if the source repository is a shallow repository.
- The 'clone.rejectShallow' configuration variable can be used to
+ The `clone.rejectShallow` configuration variable can be used to
specify the default.
---bare::
+`--bare`::
Make a 'bare' Git repository. That is, instead of
- creating `<directory>` and placing the administrative
- files in `<directory>/.git`, make the `<directory>`
+ creating _<directory>_ and placing the administrative
+ files in _<directory>_`/.git`, make the _<directory>_
itself the `$GIT_DIR`. This obviously implies the `--no-checkout`
because there is nowhere to check out the working tree.
Also the branch heads at the remote are copied directly
@@ -171,28 +171,28 @@
used, neither remote-tracking branches nor the related
configuration variables are created.
---sparse::
+`--sparse`::
Employ a sparse-checkout, with only files in the toplevel
directory initially being present. The
linkgit:git-sparse-checkout[1] command can be used to grow the
working directory as needed.
---filter=<filter-spec>::
+++--filter=++__<filter-spec>__::
Use the partial clone feature and request that the server sends
a subset of reachable objects according to a given object filter.
- When using `--filter`, the supplied `<filter-spec>` is used for
+ When using `--filter`, the supplied _<filter-spec>_ is used for
the partial clone filter. For example, `--filter=blob:none` will
filter out all blobs (file contents) until needed by Git. Also,
- `--filter=blob:limit=<size>` will filter out all blobs of size
- at least `<size>`. For more details on filter specifications, see
+ ++--filter=blob:limit=++__<size>__ will filter out all blobs of size
+ at least _<size>_. For more details on filter specifications, see
the `--filter` option in linkgit:git-rev-list[1].
---also-filter-submodules::
+`--also-filter-submodules`::
Also apply the partial clone filter to any submodules in the repository.
Requires `--filter` and `--recurse-submodules`. This can be turned on by
default by setting the `clone.filterSubmodules` config option.
---mirror::
+`--mirror`::
Set up a mirror of the source repository. This implies `--bare`.
Compared to `--bare`, `--mirror` not only maps local branches of the
source to local branches of the target, it maps all refs (including
@@ -200,37 +200,37 @@
that all these refs are overwritten by a `git remote update` in the
target repository.
--o <name>::
---origin <name>::
+`-o` _<name>_::
+`--origin` _<name>_::
Instead of using the remote name `origin` to keep track of the upstream
- repository, use `<name>`. Overrides `clone.defaultRemoteName` from the
+ repository, use _<name>_. Overrides `clone.defaultRemoteName` from the
config.
--b <name>::
---branch <name>::
+`-b` _<name>_::
+`--branch` _<name>_::
Instead of pointing the newly created HEAD to the branch pointed
- to by the cloned repository's HEAD, point to `<name>` branch
+ to by the cloned repository's HEAD, point to _<name>_ branch
instead. In a non-bare repository, this is the branch that will
be checked out.
`--branch` can also take tags and detaches the HEAD at that commit
in the resulting repository.
--u <upload-pack>::
---upload-pack <upload-pack>::
+`-u` _<upload-pack>_::
+`--upload-pack` _<upload-pack>_::
When given, and the repository to clone from is accessed
via ssh, this specifies a non-default path for the command
run on the other end.
---template=<template-directory>::
+++--template=++__<template-directory>__::
Specify the directory from which templates will be used;
(See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].)
--c <key>=<value>::
---config <key>=<value>::
+`-c` __<key>__++=++__<value>__::
+`--config` __<key>__++=++__<value>__::
Set a configuration variable in the newly-created repository;
this takes effect immediately after the repository is
initialized, but before the remote history is fetched or any
- files checked out. The key is in the same format as expected by
+ files checked out. The _<key>_ is in the same format as expected by
linkgit:git-config[1] (e.g., `core.eol=true`). If multiple
values are given for the same key, each value will be written to
the config file. This makes it safe, for example, to add
@@ -239,35 +239,35 @@
Due to limitations of the current implementation, some configuration
variables do not take effect until after the initial fetch and checkout.
Configuration variables known to not take effect are:
-`remote.<name>.mirror` and `remote.<name>.tagOpt`. Use the
+++remote.++__<name>__++.mirror++ and ++remote.++__<name>__++.tagOpt++. Use the
corresponding `--mirror` and `--no-tags` options instead.
---depth <depth>::
+`--depth` _<depth>_::
Create a 'shallow' clone with a history truncated to the
specified number of commits. Implies `--single-branch` unless
`--no-single-branch` is given to fetch the histories near the
tips of all branches. If you want to clone submodules shallowly,
also pass `--shallow-submodules`.
---shallow-since=<date>::
+++--shallow-since=++__<date>__::
Create a shallow clone with a history after the specified time.
---shallow-exclude=<revision>::
+++--shallow-exclude=++__<revision>__::
Create a shallow clone with a history, excluding commits
reachable from a specified remote branch or tag. This option
can be specified multiple times.
---[no-]single-branch::
+`--`[`no-`]`single-branch`::
Clone only the history leading to the tip of a single branch,
either specified by the `--branch` option or the primary
branch remote's `HEAD` points at.
Further fetches into the resulting repository will only update the
remote-tracking branch for the branch this option was used for the
- initial cloning. If the HEAD at the remote did not point at any
+ initial cloning. If the `HEAD` at the remote did not point at any
branch when `--single-branch` clone was made, no remote-tracking
branch is created.
---no-tags::
+`--no-tags`::
Don't clone any tags, and set
`remote.<remote>.tagOpt=--no-tags` in the config, ensuring
that future `git pull` and `git fetch` operations won't follow
@@ -279,9 +279,9 @@
branch. This is useful e.g. to maintain minimal clones of the default
branch of some repository for search indexing.
---recurse-submodules[=<pathspec>]::
+`--recurse-submodules`[`=`{empty}__<pathspec>__]::
After the clone is created, initialize and clone submodules
- within based on the provided pathspec. If no pathspec is
+ within based on the provided _<pathspec>_. If no _=<pathspec>_ is
provided, all submodules are initialized and cloned.
This option can be given multiple times for pathspecs consisting
of multiple entries. The resulting clone has `submodule.active` set to
@@ -295,42 +295,48 @@
not have a worktree/checkout (i.e. if any of `--no-checkout`/`-n`, `--bare`,
or `--mirror` is given)
---[no-]shallow-submodules::
+`--`[`no-`]`shallow-submodules`::
All submodules which are cloned will be shallow with a depth of 1.
---[no-]remote-submodules::
+`--`[`no-`]`remote-submodules`::
All submodules which are cloned will use the status of the submodule's
remote-tracking branch to update the submodule, rather than the
superproject's recorded SHA-1. Equivalent to passing `--remote` to
`git submodule update`.
---separate-git-dir=<git-dir>::
+`--separate-git-dir=`{empty}__<git-dir>__::
Instead of placing the cloned repository where it is supposed
to be, place the cloned repository at the specified directory,
then make a filesystem-agnostic Git symbolic link to there.
The result is Git repository can be separated from working
tree.
--j <n>::
---jobs <n>::
+`--ref-format=`{empty}__<ref-format>__::
+
+Specify the given ref storage format for the repository. The valid values are:
++
+include::ref-storage-format.txt[]
+
+`-j` _<n>_::
+`--jobs` _<n>_::
The number of submodules fetched at the same time.
Defaults to the `submodule.fetchJobs` option.
-<repository>::
- The (possibly remote) repository to clone from. See the
+_<repository>_::
+ The (possibly remote) _<repository>_ to clone from. See the
<<URLS,GIT URLS>> section below for more information on specifying
repositories.
-<directory>::
+_<directory>_::
The name of a new directory to clone into. The "humanish"
- part of the source repository is used if no directory is
+ part of the source repository is used if no _<directory>_ is
explicitly given (`repo` for `/path/to/repo.git` and `foo`
for `host.xz:foo/.git`). Cloning into an existing directory
is only allowed if the directory is empty.
---bundle-uri=<uri>::
+`--bundle-uri=`{empty}__<uri>__::
Before fetching from the remote, fetch a bundle from the given
- `<uri>` and unbundle the data into the local repository. The refs
+ _<uri>_ and unbundle the data into the local repository. The refs
in the bundle will be stored under the hidden `refs/bundle/*`
namespace. This option is incompatible with `--depth`,
`--shallow-since`, and `--shallow-exclude`.
diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt
index c8dbceb..903b168 100644
--- a/Documentation/git-commit-graph.txt
+++ b/Documentation/git-commit-graph.txt
@@ -13,7 +13,7 @@
'git commit-graph write' [--object-dir <dir>] [--append]
[--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]
[--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]
- <split options>
+ <split-options>
DESCRIPTION
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 225c6c9..89ecfc6 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -347,6 +347,8 @@
- 'normal' - Shows untracked files and directories
- 'all' - Also shows individual files in untracked directories.
+All usual spellings for Boolean value `true` are taken as `normal`
+and `false` as `no`.
The default can be changed using the status.showUntrackedFiles
configuration variable documented in linkgit:git-config[1].
--
@@ -541,7 +543,7 @@
----------
Though not required, it's a good idea to begin the commit message
-with a single short (less than 50 character) line summarizing the
+with a single short (no more than 50 characters) line summarizing the
change, followed by a blank line and then a more thorough description.
The text up to the first blank line in a commit message is treated
as the commit title, and that title is used throughout Git.
diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
index b1caac8..ac61113 100644
--- a/Documentation/git-config.txt
+++ b/Documentation/git-config.txt
@@ -9,9 +9,9 @@
SYNOPSIS
--------
[verse]
-'git config' [<file-option>] [--type=<type>] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] <name> [<value> [<value-pattern>]]
-'git config' [<file-option>] [--type=<type>] --add <name> <value>
-'git config' [<file-option>] [--type=<type>] [--fixed-value] --replace-all <name> <value> [<value-pattern>]
+'git config' [<file-option>] [--type=<type>] [--comment=<message>] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] <name> [<value> [<value-pattern>]]
+'git config' [<file-option>] [--type=<type>] [--comment=<message>] --add <name> <value>
+'git config' [<file-option>] [--type=<type>] [--comment=<message>] [--fixed-value] --replace-all <name> <value> [<value-pattern>]
'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get <name> [<value-pattern>]
'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all <name> [<value-pattern>]
'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp <name-regex> [<value-pattern>]
@@ -87,6 +87,18 @@
values. This is the same as providing '^$' as the `value-pattern`
in `--replace-all`.
+--comment <message>::
+ Append a comment at the end of new or modified lines.
+
+ If _<message>_ begins with one or more whitespaces followed
+ by "#", it is used as-is. If it begins with "#", a space is
+ prepended before it is used. Otherwise, a string " # " (a
+ space followed by a hash followed by a space) is prepended
+ to it. And the resulting string is placed immediately after
+ the value defined for the variable. The _<message>_ must
+ not contain linefeed characters (no multi-line comments are
+ permitted).
+
--get::
Get the value for a given key (optionally filtered by a regex
matching the value). Returns error code 1 if the key was not
@@ -103,11 +115,11 @@
names are not.
--get-urlmatch <name> <URL>::
- When given a two-part name section.key, the value for
- section.<URL>.key whose <URL> part matches the best to the
+ When given a two-part <name> as <section>.<key>, the value for
+ <section>.<URL>.<key> whose <URL> part matches the best to the
given URL is returned (if no such key exists, the value for
- section.key is used as a fallback). When given just the
- section as name, do so for all the keys in the section and
+ <section>.<key> is used as a fallback). When given just the
+ <section> as name, do so for all the keys in the section and
list them. Returns error code 1 if no value is found.
--global::
@@ -275,7 +287,8 @@
-e::
--edit::
Opens an editor to modify the specified config file; either
- `--system`, `--global`, or repository (default).
+ `--system`, `--global`, `--local` (default), `--worktree`, or
+ `--file <config-file>`.
--[no-]includes::
Respect `include.*` directives in config files when looking up
@@ -285,7 +298,7 @@
--default <value>::
When using `--get`, and the requested variable is not found, behave as if
- <value> were the value assigned to the that variable.
+ <value> were the value assigned to that variable.
CONFIGURATION
-------------
diff --git a/Documentation/git-count-objects.txt b/Documentation/git-count-objects.txt
index cb9b4d2..97f9f12 100644
--- a/Documentation/git-count-objects.txt
+++ b/Documentation/git-count-objects.txt
@@ -12,7 +12,7 @@
DESCRIPTION
-----------
-This counts the number of unpacked object files and disk space consumed by
+Counts the number of unpacked object files and disk space consumed by
them, to help you decide when it is a good time to repack.
@@ -20,7 +20,7 @@
-------
-v::
--verbose::
- Report in more detail:
+ Provide more detailed reports:
+
count: the number of loose objects
+
@@ -33,7 +33,7 @@
prune-packable: the number of loose objects that are also present in
the packs. These objects could be pruned using `git prune-packed`.
+
-garbage: the number of files in object database that are neither valid loose
+garbage: the number of files in the object database that are neither valid loose
objects nor valid packs
+
size-garbage: disk space consumed by garbage files, in KiB (unless -H is
diff --git a/Documentation/git-credential-cache.txt b/Documentation/git-credential-cache.txt
index f473994..487cc55 100644
--- a/Documentation/git-credential-cache.txt
+++ b/Documentation/git-credential-cache.txt
@@ -16,7 +16,7 @@
This command caches credentials for use by future Git programs.
The stored credentials are kept in memory of the cache-daemon
-process (instead of written to a file) and are forgotten after a
+process (instead of being written to a file) and are forgotten after a
configurable timeout. Credentials are forgotten sooner if the
cache-daemon dies, for example if the system restarts. The cache
is accessible over a Unix domain socket, restricted to the current
diff --git a/Documentation/git-credential-store.txt b/Documentation/git-credential-store.txt
index 76b0798..71864a8 100644
--- a/Documentation/git-credential-store.txt
+++ b/Documentation/git-credential-store.txt
@@ -33,7 +33,7 @@
Use `<path>` to lookup and store credentials. The file will have its
filesystem permissions set to prevent other users on the system
- from reading it, but will not be encrypted or otherwise
+ from reading it, but it will not be encrypted or otherwise
protected. If not specified, credentials will be searched for from
`~/.git-credentials` and `$XDG_CONFIG_HOME/git/credentials`, and
credentials will be written to `~/.git-credentials` if it exists, or
diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt
index a220afe..918a0aa 100644
--- a/Documentation/git-credential.txt
+++ b/Documentation/git-credential.txt
@@ -94,7 +94,7 @@
that `git credential` will ask for a new password in its next
invocation. In either case, `git credential` should be fed with
the credential description obtained from step (2) (which also
- contain the ones provided in step (1)).
+ contains the fields provided in step (1)).
[[IOFMT]]
INPUT/OUTPUT FORMAT
diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt
index b3f2767..90fdc25 100644
--- a/Documentation/git-cvsimport.txt
+++ b/Documentation/git-cvsimport.txt
@@ -22,7 +22,7 @@
deprecated; it does not work with cvsps version 3 and later. If you are
performing a one-shot import of a CVS repository consider using
http://cvs2svn.tigris.org/cvs2git.html[cvs2git] or
-http://www.catb.org/esr/cvs-fast-export/[cvs-fast-export].
+https://gitlab.com/esr/cvs-fast-export[cvs-fast-export].
Imports a CVS repository into Git. It will either create a new
repository, or incrementally import into an existing one.
@@ -221,7 +221,7 @@
If you suspect that any of these issues may apply to the repository you
want to import, consider using cvs2git:
-* cvs2git (part of cvs2svn), `http://subversion.apache.org/`
+* cvs2git (part of cvs2svn), `https://subversion.apache.org/`
GIT
---
diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt
index cf4a5a2..4c475ef 100644
--- a/Documentation/git-cvsserver.txt
+++ b/Documentation/git-cvsserver.txt
@@ -197,7 +197,7 @@
5. Clients should now be able to check out the project. Use the CVS 'module'
name to indicate what Git 'head' you want to check out. This also sets the
name of your newly checked-out directory, unless you tell it otherwise with
- `-d <dir_name>`. For example, this checks out 'master' branch to the
+ `-d <dir-name>`. For example, this checks out 'master' branch to the
`project-master` directory:
+
------
@@ -224,7 +224,7 @@
that the database is up to date any time 'git-cvsserver' is executed).
By default it uses SQLite databases in the Git directory, named
-`gitcvs.<module_name>.sqlite`. Note that the SQLite backend creates
+`gitcvs.<module-name>.sqlite`. Note that the SQLite backend creates
temporary files in the same directory as the database file on
write so it might not be enough to grant the users using
'git-cvsserver' write access to the database file without granting
diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt
index 236df51..ede7b93 100644
--- a/Documentation/git-daemon.txt
+++ b/Documentation/git-daemon.txt
@@ -18,7 +18,7 @@
[--allow-override=<service>] [--forbid-override=<service>]
[--access-hook=<path>] [--[no-]informative-errors]
[--inetd |
- [--listen=<host_or_ipaddr>] [--port=<n>]
+ [--listen=<host-or-ipaddr>] [--port=<n>]
[--user=<user> [--group=<group>]]]
[--log-destination=(stderr|syslog|none)]
[<directory>...]
@@ -86,10 +86,10 @@
Incompatible with --detach, --port, --listen, --user and --group
options.
---listen=<host_or_ipaddr>::
+--listen=<host-or-ipaddr>::
Listen on a specific IP address or hostname. IP addresses can
be either an IPv4 address or an IPv6 address if supported. If IPv6
- is not supported, then --listen=hostname is also not supported and
+ is not supported, then --listen=<hostname> is also not supported and
--listen must be given an IPv4 address.
Can be given more than once.
Incompatible with `--inetd` option.
@@ -138,11 +138,11 @@
--user-path::
--user-path=<path>::
Allow {tilde}user notation to be used in requests. When
- specified with no parameter, requests to
+ specified with no parameter, a request to
git://host/{tilde}alice/foo is taken as a request to access
'foo' repository in the home directory of user `alice`.
- If `--user-path=path` is specified, the same request is
- taken as a request to access `path/foo` repository in
+ If `--user-path=<path>` is specified, the same request is
+ taken as a request to access `<path>/foo` repository in
the home directory of user `alice`.
--verbose::
diff --git a/Documentation/git-diagnose.txt b/Documentation/git-diagnose.txt
index 3ec8cc7..0711959 100644
--- a/Documentation/git-diagnose.txt
+++ b/Documentation/git-diagnose.txt
@@ -45,7 +45,7 @@
-s <format>::
--suffix <format>::
Specify an alternate suffix for the diagnostics archive name, to create
- a file named 'git-diagnostics-<formatted suffix>'. This should take the
+ a file named 'git-diagnostics-<formatted-suffix>'. This should take the
form of a strftime(3) format string; the current local time will be
used.
diff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt
index 591e380..bf78e31 100644
--- a/Documentation/git-diff-files.txt
+++ b/Documentation/git-diff-files.txt
@@ -26,7 +26,7 @@
-2 --ours::
-3 --theirs::
-0::
- Diff against the "base" version, "our branch" or "their
+ Diff against the "base" version, "our branch", or "their
branch" respectively. With these options, diffs for
merged entries are not shown.
+
@@ -37,12 +37,12 @@
-c::
--cc::
This compares stage 2 (our branch), stage 3 (their
- branch) and the working tree file and outputs a combined
+ branch), and the working tree file and outputs a combined
diff, similar to the way 'diff-tree' shows a merge
commit with these flags.
-q::
- Remain silent even on nonexistent files
+ Remain silent even for nonexistent files
include::diff-format.txt[]
diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt
index c30d8f0..4de1d4c 100644
--- a/Documentation/git-diff-index.txt
+++ b/Documentation/git-diff-index.txt
@@ -13,10 +13,10 @@
DESCRIPTION
-----------
-Compares the content and mode of the blobs found in a tree object
+Compare the content and mode of the blobs found in a tree object
with the corresponding tracked files in the working tree, or with the
corresponding paths in the index. When <path> arguments are present,
-compares only paths matching those patterns. Otherwise all tracked
+compare only paths matching those patterns. Otherwise all tracked
files are compared.
OPTIONS
diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt
index 274d5ea..143318c 100644
--- a/Documentation/git-diff-tree.txt
+++ b/Documentation/git-diff-tree.txt
@@ -15,7 +15,7 @@
DESCRIPTION
-----------
-Compares the content and mode of the blobs found via two tree objects.
+Compare the content and mode of blobs found via two tree objects.
If there is only one <tree-ish> given, the commit is compared with its parents
(see --stdin below).
@@ -34,10 +34,10 @@
matching one of the provided pathspecs.
-r::
- recurse into sub-trees
+ Recurse into sub-trees.
-t::
- show tree entry itself as well as subtrees. Implies -r.
+ Show tree entry itself as well as subtrees. Implies -r.
--root::
When `--root` is specified the initial commit will be shown as a big
@@ -78,7 +78,7 @@
By default, 'git diff-tree --stdin' shows differences,
either in machine-readable form (without `-p`) or in patch
form (with `-p`). This output can be suppressed. It is
- only useful with `-v` flag.
+ only useful with the `-v` flag.
-v::
This flag causes 'git diff-tree --stdin' to also show
@@ -104,10 +104,10 @@
This flag changes the way a merge commit patch is displayed,
in a similar way to the `-c` option. It implies the `-c`
and `-p` options and further compresses the patch output
- by omitting uninteresting hunks whose the contents in the parents
+ by omitting uninteresting hunks whose contents in the parents
have only two variants and the merge result picks one of them
without modification. When all hunks are uninteresting, the commit
- itself and the commit log message is not shown, just like in any other
+ itself and the commit log message are not shown, just like in any other
"empty diff" case.
--combined-all-paths::
diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index 08087ff..c065f02 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -103,7 +103,7 @@
noted that all of the <commit> in the above description, except
in the `--merge-base` case and in the last two forms that use `..`
notations, can be any <tree>. A tree of interest is the one pointed to
-by the special ref `AUTO_MERGE`, which is written by the 'ort' merge
+by the ref named `AUTO_MERGE`, which is written by the 'ort' merge
strategy upon hitting merge conflicts (see linkgit:git-merge[1]).
Comparing the working tree with `AUTO_MERGE` shows changes you've made
so far to resolve textual conflicts (see the examples below).
diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt
index ac0ac6f..a616f8b 100644
--- a/Documentation/git-difftool.txt
+++ b/Documentation/git-difftool.txt
@@ -36,7 +36,7 @@
--rotate-to=<file>::
Start showing the diff for the given path,
- the paths before it will move to end and output.
+ the paths before it will move to the end and output.
--skip-to=<file>::
Start showing the diff for the given path, skipping all
@@ -78,7 +78,7 @@
Print a list of diff tools that may be used with `--tool`.
--[no-]symlinks::
- 'git difftool''s default behavior is create symlinks to the
+ 'git difftool''s default behavior is to create symlinks to the
working tree when run in `--dir-diff` mode and the right-hand
side of the comparison yields the same content as the file in
the working tree.
@@ -90,7 +90,7 @@
--extcmd=<command>::
Specify a custom command for viewing diffs.
'git-difftool' ignores the configured defaults and runs
- `$command $LOCAL $REMOTE` when this option is specified.
+ `<command> $LOCAL $REMOTE` when this option is specified.
Additionally, `$BASE` is set in the environment.
-g::
@@ -105,7 +105,6 @@
`merge.tool` until a tool is found.
--[no-]trust-exit-code::
- 'git-difftool' invokes a diff tool individually on each file.
Errors reported by the diff tool are ignored by default.
Use `--trust-exit-code` to make 'git-difftool' exit when an
invoked diff tool returns a non-zero exit code.
diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt
index 4643ddb..752e4b9 100644
--- a/Documentation/git-fast-export.txt
+++ b/Documentation/git-fast-export.txt
@@ -48,7 +48,7 @@
when encountering such a tag. With 'drop' it will omit such tags from
the output. With 'rewrite', if the tagged object is a commit, it will
rewrite the tag to tag an ancestor commit (via parent rewriting; see
-linkgit:git-rev-list[1])
+linkgit:git-rev-list[1]).
-M::
-C::
diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt
index 8b5dd6a..3d43515 100644
--- a/Documentation/git-fast-import.txt
+++ b/Documentation/git-fast-import.txt
@@ -303,7 +303,7 @@
with e.g. bogus timezone values.
`rfc2822`::
- This is the standard email format as described by RFC 2822.
+ This is the standard date format as described by RFC 2822.
+
An example value is ``Tue Feb 6 11:22:18 2007 -0500''. The Git
parser is accurate, but a little on the lenient side. It is the
@@ -622,7 +622,7 @@
* `100755` or `755`: A normal, but executable, file.
* `120000`: A symlink, the content of the file will be the link target.
* `160000`: A gitlink, SHA-1 of the object refers to a commit in
- another repository. Git links can only be specified by SHA or through
+ another repository. Git links can only be specified either by SHA or through
a commit mark. They are used to implement submodules.
* `040000`: A subdirectory. Subdirectories can only be specified by
SHA or through a tree mark set with `--import-marks`.
@@ -630,18 +630,28 @@
In both formats `<path>` is the complete path of the file to be added
(if not already existing) or modified (if already existing).
-A `<path>` string must use UNIX-style directory separators (forward
-slash `/`), may contain any byte other than `LF`, and must not
-start with double quote (`"`).
+A `<path>` can be written as unquoted bytes or a C-style quoted string.
-A path can use C-style string quoting; this is accepted in all cases
-and mandatory if the filename starts with double quote or contains
-`LF`. In C-style quoting, the complete name should be surrounded with
-double quotes, and any `LF`, backslash, or double quote characters
-must be escaped by preceding them with a backslash (e.g.,
-`"path/with\n, \\ and \" in it"`).
+When a `<path>` does not start with a double quote (`"`), it is an
+unquoted string and is parsed as literal bytes without any escape
+sequences. However, if the filename contains `LF` or starts with double
+quote, it cannot be represented as an unquoted string and must be
+quoted. Additionally, the source `<path>` in `filecopy` or `filerename`
+must be quoted if it contains SP.
-The value of `<path>` must be in canonical form. That is it must not:
+When a `<path>` starts with a double quote (`"`), it is a C-style quoted
+string, where the complete filename is enclosed in a pair of double
+quotes and escape sequences are used. Certain characters must be escaped
+by preceding them with a backslash: `LF` is written as `\n`, backslash
+as `\\`, and double quote as `\"`. Some characters may optionally be
+written with escape sequences: `\a` for bell, `\b` for backspace, `\f`
+for form feed, `\n` for line feed, `\r` for carriage return, `\t` for
+horizontal tab, and `\v` for vertical tab. Any byte can be written with
+3-digit octal codes (e.g., `\033`). All filenames can be represented as
+quoted strings.
+
+A `<path>` must use UNIX-style directory separators (forward slash `/`)
+and its value must be in canonical form. That is it must not:
* contain an empty directory component (e.g. `foo//bar` is invalid),
* end with a directory separator (e.g. `foo/` is invalid),
@@ -651,6 +661,7 @@
The root of the tree can be represented by an empty string as `<path>`.
+`<path>` cannot contain NUL, either literally or escaped as `\000`.
It is recommended that `<path>` always be encoded using UTF-8.
`filedelete`
@@ -745,11 +756,11 @@
`notemodify`
^^^^^^^^^^^^
-Included in a `commit` `<notes_ref>` command to add a new note
+Included in a `commit` `<notes-ref>` command to add a new note
annotating a `<commit-ish>` or change this annotation contents.
Internally it is similar to filemodify 100644 on `<commit-ish>`
path (maybe split into subdirectories). It's not advised to
-use any other commands to write to the `<notes_ref>` tree except
+use any other commands to write to the `<notes-ref>` tree except
`filedeleteall` to delete all existing notes in this tree.
This command has two different means of specifying the content
of the note.
@@ -1353,7 +1364,7 @@
accuracy and completeness of the import by comparing each Git
commit to the corresponding source revision.
-Coming from a system such as Perforce or Subversion this should be
+Coming from a system such as Perforce or Subversion, this should be
quite simple, as the fast-import mark can also be the Perforce changeset
number or the Subversion revision number.
diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt
index 46747d5..b346766 100644
--- a/Documentation/git-fetch-pack.txt
+++ b/Documentation/git-fetch-pack.txt
@@ -69,7 +69,7 @@
--upload-pack=<git-upload-pack>::
Use this to specify the path to 'git-upload-pack' on the
- remote side, if is not found on your $PATH.
+ remote side, if it is not found on your $PATH.
Installations of sshd ignores the user's environment
setup scripts for login shells (e.g. .bash_profile) and
your privately installed git may not be found on the system
diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt
index f123139..50900a5 100644
--- a/Documentation/git-fetch.txt
+++ b/Documentation/git-fetch.txt
@@ -186,8 +186,8 @@
------------------------------------------------
$ git fetch origin --prune --prune-tags
$ git fetch origin --prune 'refs/tags/*:refs/tags/*'
-$ git fetch <url of origin> --prune --prune-tags
-$ git fetch <url of origin> --prune 'refs/tags/*:refs/tags/*'
+$ git fetch <url-of-origin> --prune --prune-tags
+$ git fetch <url-of-origin> --prune 'refs/tags/*:refs/tags/*'
------------------------------------------------
OUTPUT
diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt
index 62e482a..5a4f853 100644
--- a/Documentation/git-filter-branch.txt
+++ b/Documentation/git-filter-branch.txt
@@ -14,7 +14,7 @@
[--msg-filter <command>] [--commit-filter <command>]
[--tag-name-filter <command>] [--prune-empty]
[--original <namespace>] [-d <directory>] [-f | --force]
- [--state-branch <branch>] [--] [<rev-list options>...]
+ [--state-branch <branch>] [--] [<rev-list-options>...]
WARNING
-------
@@ -32,7 +32,7 @@
DESCRIPTION
-----------
Lets you rewrite Git revision history by rewriting the branches mentioned
-in the <rev-list options>, applying custom filters on each revision.
+in the <rev-list-options>, applying custom filters on each revision.
Those filters can modify each tree (e.g. removing a file or running
a perl rewrite on all files) or information about each commit.
Otherwise, all information (including original commit times or merge
@@ -624,7 +624,7 @@
real backup; it dereferences tags first.)
** Running git-filter-branch with either --tags or --all in your
- <rev-list options>. In order to retain annotated tags as
+ <rev-list-options>. In order to retain annotated tags as
annotated, you must use --tag-name-filter (and must not have
restored from refs/original/ in a previously botched rewrite).
diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
index 11b2bc3..c1dd12b 100644
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.txt
@@ -10,7 +10,7 @@
[verse]
'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl]
[(--sort=<key>)...] [--format=<format>]
- [ --stdin | <pattern>... ]
+ [--include-root-refs] [ --stdin | <pattern>... ]
[--points-at=<object>]
[--merged[=<object>]] [--no-merged[=<object>]]
[--contains[=<object>]] [--no-contains[=<object>]]
@@ -51,17 +51,14 @@
key.
--format=<format>::
- A string that interpolates `%(fieldname)` from a ref being shown
- and the object it points at. If `fieldname`
- is prefixed with an asterisk (`*`) and the ref points
- at a tag object, use the value for the field in the object
- which the tag object refers to (instead of the field in the tag object).
- When unspecified, `<format>` defaults to
- `%(objectname) SPC %(objecttype) TAB %(refname)`.
- It also interpolates `%%` to `%`, and `%xx` where `xx`
- are hex digits interpolates to character with hex code
- `xx`; for example `%00` interpolates to `\0` (NUL),
- `%09` to `\t` (TAB) and `%0a` to `\n` (LF).
+ A string that interpolates `%(fieldname)` from a ref being shown and
+ the object it points at. In addition, the string literal `%%`
+ renders as `%` and `%xx` - where `xx` are hex digits - renders as
+ the character with hex code `xx`. For example, `%00` interpolates to
+ `\0` (NUL), `%09` to `\t` (TAB), and `%0a` to `\n` (LF).
++
+When unspecified, `<format>` defaults to `%(objectname) SPC %(objecttype)
+TAB %(refname)`.
--color[=<when>]::
Respect any colors specified in the `--format` option. The
@@ -108,6 +105,9 @@
any excluded pattern(s) are shown. Matching is done using the
same rules as `<pattern>` above.
+--include-root-refs::
+ List root refs (HEAD and pseudorefs) apart from regular refs.
+
FIELD NAMES
-----------
@@ -298,12 +298,20 @@
from the `committer` or `tagger` fields depending on the object type.
These are intended for working on a mix of annotated and lightweight tags.
+For tag objects, a `fieldname` prefixed with an asterisk (`*`) expands to
+the `fieldname` value of the peeled object, rather than that of the tag
+object itself.
+
Fields that have name-email-date tuple as its value (`author`,
`committer`, and `tagger`) can be suffixed with `name`, `email`,
and `date` to extract the named component. For email fields (`authoremail`,
`committeremail` and `taggeremail`), `:trim` can be appended to get the email
without angle brackets, and `:localpart` to get the part before the `@` symbol
-out of the trimmed email.
+out of the trimmed email. In addition to these, the `:mailmap` option and the
+corresponding `:mailmap,trim` and `:mailmap,localpart` can be used (order does
+not matter) to get values of the name and email according to the .mailmap file
+or according to the file set in the mailmap.file or mailmap.blob configuration
+variable (see linkgit:gitmailmap[5]).
The raw data in an object is `raw`.
@@ -354,9 +362,11 @@
the object referred by the ref does not cause an error. It
returns an empty string instead.
-As a special case for the date-type fields, you may specify a format for
-the date by adding `:` followed by date format name (see the
-values the `--date` option to linkgit:git-rev-list[1] takes).
+As a special case for the date-type fields, you may specify a format for the
+date by adding `:` followed by date format name (see the values the `--date`
+option to linkgit:git-rev-list[1] takes). If this formatting is provided in
+a `--sort` key, references will be sorted according to the byte-value of the
+formatted string rather than the numeric value of the underlying timestamp.
Some atoms like %(align) and %(if) always require a matching %(end).
We call them "opening atoms" and sometimes denote them as %($open).
diff --git a/Documentation/git-for-each-repo.txt b/Documentation/git-for-each-repo.txt
index 94bd19d..abe3527 100644
--- a/Documentation/git-for-each-repo.txt
+++ b/Documentation/git-for-each-repo.txt
@@ -42,6 +42,15 @@
as available. If `git for-each-repo` is run in a directory that is not a
Git repository, then only the system and global config is used.
+--keep-going::
+ Continue with the remaining repositories if the command failed
+ on a repository. The exit code will still indicate that the
+ overall operation was not successful.
++
+Note that the exact exit code of the failing command is not passed
+through as the exit code of the `for-each-repo` command: If the command
+failed in any of the specified repositories, the overall exit code will
+be 1.
SUBPROCESS BEHAVIOR
-------------------
diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index 373b46f..728bb38 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -17,10 +17,10 @@
[--signature-file=<file>]
[-n | --numbered | -N | --no-numbered]
[--start-number <n>] [--numbered-files]
- [--in-reply-to=<message id>] [--suffix=.<sfx>]
+ [--in-reply-to=<message-id>] [--suffix=.<sfx>]
[--ignore-if-in-upstream] [--always]
[--cover-from-description=<mode>]
- [--rfc] [--subject-prefix=<subject prefix>]
+ [--rfc] [--subject-prefix=<subject-prefix>]
[(--reroll-count|-v) <n>]
[--to=<email>] [--cc=<email>]
[--[no-]cover-letter] [--quiet]
@@ -30,8 +30,8 @@
[--range-diff=<previous> [--creation-factor=<percent>]]
[--filename-max-length=<n>]
[--progress]
- [<common diff options>]
- [ <since> | <revision range> ]
+ [<common-diff-options>]
+ [ <since> | <revision-range> ]
DESCRIPTION
-----------
@@ -55,7 +55,7 @@
* The "patch", which is the "diff -p --stat" output (see
linkgit:git-diff[1]) between the commit and its parent.
-The log message and the patch is separated by a line with a
+The log message and the patch are separated by a line with a
three-dash line.
There are two ways to specify which commits to operate on.
@@ -64,7 +64,7 @@
to the tip of the current branch that are not in the history
that leads to the <since> to be output.
-2. Generic <revision range> expression (see "SPECIFYING
+2. Generic <revision-range> expression (see "SPECIFYING
REVISIONS" section in linkgit:gitrevisions[7]) means the
commits in the specified range.
@@ -179,9 +179,9 @@
itself. If you want `git format-patch` to take care of threading, you
will want to ensure that threading is disabled for `git send-email`.
---in-reply-to=<message id>::
+--in-reply-to=<message-id>::
Make the first mail (or all the mails with `--no-thread`) appear as a
- reply to the given <message id>, which avoids breaking threads to
+ reply to the given <message-id>, which avoids breaking threads to
provide a new patch series.
--ignore-if-in-upstream::
@@ -215,11 +215,21 @@
If `<mode>` is `none`, both the cover letter subject and body will be
populated with placeholder text.
---subject-prefix=<subject prefix>::
+--description-file=<file>::
+ Use the contents of <file> instead of the branch's description
+ for generating the cover letter.
+
+--subject-prefix=<subject-prefix>::
Instead of the standard '[PATCH]' prefix in the subject
- line, instead use '[<subject prefix>]'. This
- allows for useful naming of a patch series, and can be
- combined with the `--numbered` option.
+ line, instead use '[<subject-prefix>]'. This can be used
+ to name a patch series, and can be combined with the
+ `--numbered` option.
++
+The configuration variable `format.subjectPrefix` may also be used
+to configure a subject prefix to apply to a given repository for
+all patches. This is often useful on mailing lists which receive
+patches for several repositories and can be used to disambiguate
+the patches (with a value of e.g. "PATCH my-project").
--filename-max-length=<n>::
Instead of the standard 64 bytes, chomp the generated output
@@ -229,9 +239,9 @@
variable, or 64 if unconfigured.
--rfc::
- Alias for `--subject-prefix="RFC PATCH"`. RFC means "Request For
- Comments"; use this when sending an experimental patch for
- discussion rather than application.
+ Prepends "RFC" to the subject prefix (producing "RFC PATCH" by
+ default). RFC means "Request For Comments"; use this when sending
+ an experimental patch for discussion rather than application.
-v <n>::
--reroll-count=<n>::
@@ -393,7 +403,7 @@
`format.useAutoBase` configuration.
--root::
- Treat the revision argument as a <revision range>, even if it
+ Treat the revision argument as a <revision-range>, even if it
is just a single commit (that would normally be treated as a
<since>). Note that root commits included in the specified
range are always formatted as creation patches, independently
@@ -600,8 +610,8 @@
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following Thunderbird extensions are needed:
-AboutConfig from http://aboutconfig.mozdev.org/ and
-External Editor from http://globs.org/articles.php?lng=en&pg=8
+AboutConfig from https://mjg.github.io/AboutConfig/ and
+External Editor from https://globs.org/articles.php?lng=en&pg=8
1. Prepare the patch as a text file using your method of choice.
diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt
index b6a0f8a..5b82e46 100644
--- a/Documentation/git-fsck.txt
+++ b/Documentation/git-fsck.txt
@@ -24,7 +24,7 @@
An object to treat as the head of an unreachability trace.
+
If no objects are given, 'git fsck' defaults to using the
-index file, all SHA-1 references in `refs` namespace, and all reflogs
+index file, all SHA-1 references in the `refs` namespace, and all reflogs
(unless --no-reflogs is given) as heads.
--unreachable::
@@ -64,7 +64,7 @@
--connectivity-only::
Check only the connectivity of reachable objects, making sure
that any objects referenced by a reachable tag, commit, or tree
- is present. This speeds up the operation by avoiding reading
+ are present. This speeds up the operation by avoiding reading
blobs entirely (though it does still check that referenced blobs
exist). This will detect corruption in commits and trees, but
not do any semantic checks (e.g., for format errors). Corruption
@@ -79,7 +79,7 @@
recorded with g+w bit set, which was created by older
versions of Git. Existing repositories, including the
Linux kernel, Git itself, and sparse repository have old
- objects that triggers this check, but it is recommended
+ objects that trigger this check, but it is recommended
to check new projects with this flag.
--verbose::
diff --git a/Documentation/git-fsmonitor--daemon.txt b/Documentation/git-fsmonitor--daemon.txt
index 8238ead..8585d19 100644
--- a/Documentation/git-fsmonitor--daemon.txt
+++ b/Documentation/git-fsmonitor--daemon.txt
@@ -70,10 +70,10 @@
will properly ignore these extra events, so performance may be affected
but it will not cause an incorrect result.
-By default, the fsmonitor daemon refuses to work against network-mounted
+By default, the fsmonitor daemon refuses to work with network-mounted
repositories; this may be overridden by setting `fsmonitor.allowRemote` to
`true`. Note, however, that the fsmonitor daemon is not guaranteed to work
-correctly with all network-mounted repositories and such use is considered
+correctly with all network-mounted repositories, so such use is considered
experimental.
On Mac OS, the inter-process communication (IPC) between various Git
@@ -83,10 +83,10 @@
may or may not have the needed support; the fsmonitor daemon is not guaranteed
to work with these filesystems and such use is considered experimental.
-By default, the socket is created in the `.git` directory, however, if the
-`.git` directory is on a network-mounted filesystem, it will be instead be
+By default, the socket is created in the `.git` directory. However, if the
+`.git` directory is on a network-mounted filesystem, it will instead be
created at `$HOME/.git-fsmonitor-*` unless `$HOME` itself is on a
-network-mounted filesystem in which case you must set the configuration
+network-mounted filesystem, in which case you must set the configuration
variable `fsmonitor.socketDir` to the path of a directory on a Mac OS native
filesystem in which to create the socket file.
diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt
index 90806fd..b5561c4 100644
--- a/Documentation/git-gc.txt
+++ b/Documentation/git-gc.txt
@@ -59,6 +59,13 @@
cruft pack instead of storing them as loose objects. `--cruft`
is on by default.
+--max-cruft-size=<n>::
+ When packing unreachable objects into a cruft pack, limit the
+ size of new cruft packs to be at most `<n>` bytes. Overrides any
+ value specified via the `gc.maxCruftSize` configuration. See
+ the `--max-cruft-size` option of linkgit:git-repack[1] for
+ more.
+
--prune=<date>::
Prune loose objects older than date (default is 2 weeks ago,
overridable by the config variable `gc.pruneExpire`).
diff --git a/Documentation/git-get-tar-commit-id.txt b/Documentation/git-get-tar-commit-id.txt
index ac44d85..b537bb4 100644
--- a/Documentation/git-get-tar-commit-id.txt
+++ b/Documentation/git-get-tar-commit-id.txt
@@ -20,7 +20,7 @@
1024 bytes of input, thus its runtime is not influenced by the size
of the tar archive very much.
-If no commit ID is found, 'git get-tar-commit-id' quietly exists with a
+If no commit ID is found, 'git get-tar-commit-id' quietly exits with a
return code of 1. This can happen if the archive had not been created
using 'git archive' or if the first parameter of 'git archive' had been
a tree ID instead of a commit ID or tag.
diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index dabdbe8..1e6d7b6 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -28,7 +28,7 @@
[-f <file>] [-e] <pattern>
[--and|--or|--not|(|)|-e <pattern>...]
[--recurse-submodules] [--parent-basename <basename>]
- [ [--[no-]exclude-standard] [--cached | --no-index | --untracked] | <tree>...]
+ [ [--[no-]exclude-standard] [--cached | --untracked | --no-index] | <tree>...]
[--] [<pathspec>...]
DESCRIPTION
@@ -45,13 +45,21 @@
Instead of searching tracked files in the working tree, search
blobs registered in the index file.
---no-index::
- Search files in the current directory that is not managed by Git.
-
--untracked::
In addition to searching in the tracked files in the working
tree, search also in untracked files.
+--no-index::
+ Search files in the current directory that is not managed by Git,
+ or by ignoring that the current directory is managed by Git. This
+ is rather similar to running the regular `grep(1)` utility with its
+ `-r` option specified, but with some additional benefits, such as
+ using pathspec patterns to limit paths; see the 'pathspec' entry
+ in linkgit:gitglossary[7] for more information.
++
+This option cannot be used together with `--cached` or `--untracked`.
+See also `grep.fallbackToNoIndex` in 'CONFIGURATION' below.
+
--no-exclude-standard::
Also search in ignored files by not honoring the `.gitignore`
mechanism. Only useful with `--untracked`.
@@ -64,9 +72,9 @@
--recurse-submodules::
Recursively search in each submodule that is active and
checked out in the repository. When used in combination with the
- <tree> option the prefix of all submodule output will be the name of
- the parent project's <tree> object. This option has no effect
- if `--no-index` is given.
+ _<tree>_ option the prefix of all submodule output will be the name of
+ the parent project's _<tree>_ object. This option cannot be used together
+ with `--untracked`, and it has no effect if `--no-index` is specified.
-a::
--text::
@@ -178,7 +186,7 @@
Use \0 as the delimiter for pathnames in the output, and print
them verbatim. Without this option, pathnames with "unusual"
characters are quoted as explained for the configuration
- variable core.quotePath (see linkgit:git-config[1]).
+ variable `core.quotePath` (see linkgit:git-config[1]).
-o::
--only-matching::
@@ -248,8 +256,8 @@
a non-zero status.
--threads <num>::
- Number of grep worker threads to use.
- See `grep.threads` in 'CONFIGURATION' for more information.
+ Number of `grep` worker threads to use. See 'NOTES ON THREADS'
+ and `grep.threads` in 'CONFIGURATION' for more information.
-f <file>::
Read patterns from <file>, one per line.
@@ -332,13 +340,13 @@
NOTES ON THREADS
----------------
-The `--threads` option (and the grep.threads configuration) will be ignored when
+The `--threads` option (and the `grep.threads` configuration) will be ignored when
`--open-files-in-pager` is used, forcing a single-threaded execution.
When grepping the object store (with `--cached` or giving tree objects), running
-with multiple threads might perform slower than single threaded if `--textconv`
-is given and there're too many text conversions. So if you experience low
-performance in this case, it might be desirable to use `--threads=1`.
+with multiple threads might perform slower than single-threaded if `--textconv`
+is given and there are too many text conversions. Thus, if low performance is
+experienced in this case, it might be desirable to use `--threads=1`.
CONFIGURATION
-------------
diff --git a/Documentation/git-gui.txt b/Documentation/git-gui.txt
index e8f3ccb..f5b02ef 100644
--- a/Documentation/git-gui.txt
+++ b/Documentation/git-gui.txt
@@ -114,7 +114,7 @@
The official repository of the 'git gui' project can be found at:
- https://github.com/prati0100/git-gui.git/
+ https://github.com/j6t/git-gui
GIT
---
diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt
index 8577f7a..ef4719a 100644
--- a/Documentation/git-hash-object.txt
+++ b/Documentation/git-hash-object.txt
@@ -39,10 +39,10 @@
of from the command-line.
--path::
- Hash object as it were located at the given path. The location of
- file does not directly influence on the hash value, but path is
- used to determine what Git filters should be applied to the object
- before it can be placed to the object database, and, as result of
+ Hash object as if it were located at the given path. The location of
+ the file does not directly influence the hash value, but the path is
+ used to determine which Git filters should be applied to the object
+ before it can be placed in the object database. As a result of
applying filters, the actual blob put into the object database may
differ from the given file. This option is mainly useful for hashing
temporary files located outside of the working directory or files
diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt
index 2b0b5e3..f0bedc1 100644
--- a/Documentation/git-help.txt
+++ b/Documentation/git-help.txt
@@ -42,13 +42,13 @@
To display the linkgit:git[1] man page, use `git help git`.
-This page can be displayed with 'git help help' or `git help --help`
+This page can be displayed with 'git help help' or `git help --help`.
OPTIONS
-------
-a::
--all::
- Prints all the available commands on the standard output.
+ Print all the available commands on the standard output.
--no-external-commands::
When used with `--all`, exclude the listing of external "git-*"
@@ -59,7 +59,7 @@
aliases.
--verbose::
- When used with `--all` print description for all recognized
+ When used with `--all`, print description for all recognized
commands. This is the default.
-c::
@@ -69,10 +69,10 @@
-g::
--guides::
- Prints a list of the Git concept guides on the standard output.
+ Print a list of the Git concept guides on the standard output.
--user-interfaces::
- Prints a list of the repository, command and file interfaces
+ Print a list of the repository, command and file interfaces
documentation on the standard output.
+
In-repository file interfaces such as `.git/info/exclude` are
@@ -85,7 +85,7 @@
described in linkgit:githooks[5].
--developer-interfaces::
- Print list of file formats, protocols and other developer
+ Print a list of file formats, protocols and other developer
interfaces documentation on the standard output.
-i::
@@ -109,7 +109,7 @@
format. A web browser will be used for that purpose.
+
The web browser can be specified using the configuration variable
-`help.browser`, or `web.browser` if the former is not set. If none of
+`help.browser`, or `web.browser` if the former is not set. If neither of
these config variables is set, the 'git web{litdd}browse' helper script
(called by 'git help') will pick a suitable default. See
linkgit:git-web{litdd}browse[1] for more information about this.
@@ -129,8 +129,8 @@
* "info" corresponds to '-i|--info',
* "web" or "html" correspond to '-w|--web'.
-help.browser, web.browser and browser.<tool>.path
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+help.browser, web.browser, and browser.<tool>.path
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The `help.browser`, `web.browser` and `browser.<tool>.path` will also
be checked if the 'web' format is chosen (either by command-line
diff --git a/Documentation/git-hook.txt b/Documentation/git-hook.txt
index 3407f3c..f6cc72d 100644
--- a/Documentation/git-hook.txt
+++ b/Documentation/git-hook.txt
@@ -13,7 +13,7 @@
DESCRIPTION
-----------
-A command interface to running git hooks (see linkgit:githooks[5]),
+A command interface for running git hooks (see linkgit:githooks[5]),
for use by other scripted git commands.
SUBCOMMANDS
@@ -32,7 +32,7 @@
-------
--to-stdin::
- For "run"; Specify a file which will be streamed into the
+ For "run"; specify a file which will be streamed into the
hook's stdin. The hook will receive the entire file from
beginning to EOF.
diff --git a/Documentation/git-http-backend.txt b/Documentation/git-http-backend.txt
index 0c5c0dd..f37ddad 100644
--- a/Documentation/git-http-backend.txt
+++ b/Documentation/git-http-backend.txt
@@ -23,7 +23,7 @@
It verifies that the directory has the magic file
"git-daemon-export-ok", and it will refuse to export any Git directory
that hasn't explicitly been marked for export this way (unless the
-`GIT_HTTP_EXPORT_ALL` environmental variable is set).
+`GIT_HTTP_EXPORT_ALL` environment variable is set).
By default, only the `upload-pack` service is enabled, which serves
'git fetch-pack' and 'git ls-remote' clients, which are invoked from
@@ -42,12 +42,12 @@
any file within the repository, including objects that are
no longer reachable from a branch but are still present.
It is enabled by default, but a repository can disable it
- by setting this configuration item to `false`.
+ by setting this configuration value to `false`.
http.uploadpack::
This serves 'git fetch-pack' and 'git ls-remote' clients.
It is enabled by default, but a repository can disable it
- by setting this configuration item to `false`.
+ by setting this configuration value to `false`.
http.receivepack::
This serves 'git send-pack' clients, allowing push. It is
@@ -265,12 +265,12 @@
* QUERY_STRING
* REQUEST_METHOD
-The `GIT_HTTP_EXPORT_ALL` environmental variable may be passed to
+The `GIT_HTTP_EXPORT_ALL` environment variable may be passed to
'git-http-backend' to bypass the check for the "git-daemon-export-ok"
file in each repository before allowing export of that repository.
The `GIT_HTTP_MAX_REQUEST_BUFFER` environment variable (or the
-`http.maxRequestBuffer` config variable) may be set to change the
+`http.maxRequestBuffer` config option) may be set to change the
largest ref negotiation request that git will handle during a fetch; any
fetch requiring a larger buffer will not succeed. This value should not
normally need to be changed, but may be helpful if you are fetching from
diff --git a/Documentation/git-http-fetch.txt b/Documentation/git-http-fetch.txt
index 319062c..4ec7c68 100644
--- a/Documentation/git-http-fetch.txt
+++ b/Documentation/git-http-fetch.txt
@@ -31,7 +31,7 @@
Report what is downloaded.
-w <filename>::
- Writes the commit-id into the filename under $GIT_DIR/refs/<filename> on
+ Writes the commit-id into the specified filename under $GIT_DIR/refs/<filename> on
the local end after the transfer is complete.
--stdin::
diff --git a/Documentation/git-http-push.txt b/Documentation/git-http-push.txt
index 7c6a6dd..ce0d808 100644
--- a/Documentation/git-http-push.txt
+++ b/Documentation/git-http-push.txt
@@ -13,12 +13,12 @@
DESCRIPTION
-----------
-Sends missing objects to remote repository, and updates the
+Sends missing objects to the remote repository, and updates the
remote branch.
*NOTE*: This command is temporarily disabled if your libcurl
is older than 7.16, as the combination has been reported
-not to work and sometimes corrupts repository.
+not to work and sometimes corrupts the repository.
OPTIONS
-------
@@ -44,7 +44,7 @@
-d::
-D::
Remove <ref> from remote repository. The specified branch
- cannot be the remote HEAD. If -d is specified the following
+ cannot be the remote HEAD. If -d is specified, the following
other conditions must also be met:
- Remote HEAD must resolve to an object that exists locally
@@ -83,8 +83,8 @@
Without `--force`, the <src> ref is stored at the remote only if
<dst> does not exist, or <dst> is a proper subset (i.e. an
ancestor) of <src>. This check, known as "fast-forward check",
-is performed in order to avoid accidentally overwriting the
-remote ref and lose other peoples' commits from there.
+is performed to avoid accidentally overwriting the
+remote ref and losing other peoples' commits from there.
With `--force`, the fast-forward check is disabled for all refs.
diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt
index f7b1851..c8a89d7 100644
--- a/Documentation/git-imap-send.txt
+++ b/Documentation/git-imap-send.txt
@@ -135,7 +135,7 @@
Thunderbird in particular is known to be problematic. Thunderbird
users may wish to visit this web page for more information:
- http://kb.mozillazine.org/Plain_text_e-mail_-_Thunderbird#Completely_plain_email
+ https://kb.mozillazine.org/Plain_text_e-mail_-_Thunderbird#Completely_plain_email
SEE ALSO
--------
diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt
index 4e71c25..5a20dee 100644
--- a/Documentation/git-index-pack.txt
+++ b/Documentation/git-index-pack.txt
@@ -16,10 +16,10 @@
DESCRIPTION
-----------
-Reads a packed archive (.pack) from the specified file, and
-builds a pack index file (.idx) for it. Optionally writes a
+Reads a packed archive (.pack) from the specified file,
+builds a pack index file (.idx) for it, and optionally writes a
reverse-index (.rev) for the specified pack. The packed
-archive together with the pack index can then be placed in
+archive, together with the pack index, can then be placed in
the objects/pack/ directory of a Git repository.
@@ -68,8 +68,8 @@
updated to use objects contained in the pack.
--keep=<msg>::
- Like --keep create a .keep file before moving the index into
- its final destination, but rather than creating an empty file
+ Like --keep, create a .keep file before moving the index into
+ its final destination. However, instead of creating an empty file
place '<msg>' followed by an LF into the .keep file. The '<msg>'
message can later be searched for within all .keep files to
locate any which have outlived their usefulness.
@@ -79,8 +79,13 @@
to force the version for the generated pack index, and to force
64-bit index entries on objects located above the given offset.
---strict::
- Die, if the pack contains broken objects or links.
+--strict[=<msg-id>=<severity>...]::
+ Die, if the pack contains broken objects or links. An optional
+ comma-separated list of `<msg-id>=<severity>` can be passed to change
+ the severity of some possible issues, e.g.,
+ `--strict="missingEmail=ignore,badTagName=error"`. See the entry for the
+ `fsck.<msg-id>` configuration options in linkgit:git-fsck[1] for more
+ information on the possible values of `<msg-id>` and `<severity>`.
--progress-title::
For internal use only.
@@ -91,13 +96,18 @@
--check-self-contained-and-connected::
Die if the pack contains broken links. For internal use only.
---fsck-objects::
- For internal use only.
+--fsck-objects[=<msg-id>=<severity>...]::
+ Die if the pack contains broken objects, but unlike `--strict`, don't
+ choke on broken links. If the pack contains a tree pointing to a
+ .gitmodules blob that does not exist, prints the hash of that blob
+ (for the caller to check) after the hash that goes into the name of the
+ pack/idx file (see "Notes").
+
-Die if the pack contains broken objects. If the pack contains a tree
-pointing to a .gitmodules blob that does not exist, prints the hash of
-that blob (for the caller to check) after the hash that goes into the
-name of the pack/idx file (see "Notes").
+An optional comma-separated list of `<msg-id>=<severity>` can be passed to
+change the severity of some possible issues, e.g.,
+`--fsck-objects="missingEmail=ignore,badTagName=ignore"`. See the entry for the
+`fsck.<msg-id>` configuration options in linkgit:git-fsck[1] for more
+information on the possible values of `<msg-id>` and `<severity>`.
--threads=<n>::
Specifies the number of threads to spawn when resolving
diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index 160dea1..daff93b 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -9,10 +9,11 @@
SYNOPSIS
--------
[verse]
-'git init' [-q | --quiet] [--bare] [--template=<template-directory>]
- [--separate-git-dir <git-dir>] [--object-format=<format>]
- [-b <branch-name> | --initial-branch=<branch-name>]
- [--shared[=<permissions>]] [<directory>]
+`git init` [`-q` | `--quiet`] [`--bare`] [++--template=++__<template-directory>__]
+ [`--separate-git-dir` _<git-dir>_] [++--object-format=++__<format>__]
+ [++--ref-format=++__<format>__]
+ [`-b` _<branch-name>_ | ++--initial-branch=++__<branch-name>__]
+ [++--shared++[++=++__<permissions>__]] [_<directory>_]
DESCRIPTION
@@ -29,94 +30,104 @@
If the object storage directory is specified via the
`$GIT_OBJECT_DIRECTORY` environment variable then the sha1 directories
-are created underneath - otherwise the default `$GIT_DIR/objects`
+are created underneath; otherwise, the default `$GIT_DIR/objects`
directory is used.
-Running 'git init' in an existing repository is safe. It will not
+Running `git init` in an existing repository is safe. It will not
overwrite things that are already there. The primary reason for
-rerunning 'git init' is to pick up newly added templates (or to move
-the repository to another place if --separate-git-dir is given).
+rerunning `git init` is to pick up newly added templates (or to move
+the repository to another place if `--separate-git-dir` is given).
OPTIONS
-------
--q::
---quiet::
+`-q`::
+`--quiet`::
Only print error and warning messages; all other output will be suppressed.
---bare::
+`--bare`::
Create a bare repository. If `GIT_DIR` environment is not set, it is set to the
current working directory.
---object-format=<format>::
+++--object-format=++__<format>__::
-Specify the given object format (hash algorithm) for the repository. The valid
-values are 'sha1' and (if enabled) 'sha256'. 'sha1' is the default.
+Specify the given object _<format>_ (hash algorithm) for the repository. The valid
+values are `sha1` and (if enabled) `sha256`. `sha1` is the default.
+
include::object-format-disclaimer.txt[]
---template=<template-directory>::
+++--ref-format=++__<format>__::
+
+Specify the given ref storage _<format>_ for the repository. The valid values are:
++
+include::ref-storage-format.txt[]
+
+++--template=++__<template-directory>__::
Specify the directory from which templates will be used. (See the "TEMPLATE
DIRECTORY" section below.)
---separate-git-dir=<git-dir>::
+++--separate-git-dir=++__<git-dir>__::
Instead of initializing the repository as a directory to either `$GIT_DIR` or
`./.git/`, create a text file there containing the path to the actual
-repository. This file acts as filesystem-agnostic Git symbolic link to the
+repository. This file acts as a filesystem-agnostic Git symbolic link to the
repository.
+
-If this is reinitialization, the repository will be moved to the specified path.
+If this is a reinitialization, the repository will be moved to the specified path.
--b <branch-name>::
---initial-branch=<branch-name>::
+`-b` _<branch-name>_::
+++--initial-branch=++__<branch-name>__::
-Use the specified name for the initial branch in the newly created
+Use _<branch-name>_ for the initial branch in the newly created
repository. If not specified, fall back to the default name (currently
`master`, but this is subject to change in the future; the name can be
customized via the `init.defaultBranch` configuration variable).
---shared[=(false|true|umask|group|all|world|everybody|<perm>)]::
+++--shared++[++=++(`false`|`true`|`umask`|`group`|`all`|`world`|`everybody`|_<perm>_)]::
Specify that the Git repository is to be shared amongst several users. This
allows users belonging to the same group to push into that
-repository. When specified, the config variable "core.sharedRepository" is
+repository. When specified, the config variable `core.sharedRepository` is
set so that files and directories under `$GIT_DIR` are created with the
requested permissions. When not specified, Git will use permissions reported
-by umask(2).
+by `umask`(2).
+
-The option can have the following values, defaulting to 'group' if no value
+The option can have the following values, defaulting to `group` if no value
is given:
+
--
-'umask' (or 'false')::
+`umask`::
+`false`::
-Use permissions reported by umask(2). The default, when `--shared` is not
+Use permissions reported by `umask`(2). The default, when `--shared` is not
specified.
-'group' (or 'true')::
+`group`::
+`true`::
-Make the repository group-writable, (and g+sx, since the git group may be not
+Make the repository group-writable, (and `g+sx`, since the git group may not be
the primary group of all users). This is used to loosen the permissions of an
-otherwise safe umask(2) value. Note that the umask still applies to the other
-permission bits (e.g. if umask is '0022', using 'group' will not remove read
-privileges from other (non-group) users). See '0xxx' for how to exactly specify
+otherwise safe `umask`(2) value. Note that the umask still applies to the other
+permission bits (e.g. if umask is `0022`, using `group` will not remove read
+privileges from other (non-group) users). See `0xxx` for how to exactly specify
the repository permissions.
-'all' (or 'world' or 'everybody')::
+`all`::
+`world`::
+`everybody`::
-Same as 'group', but make the repository readable by all users.
+Same as `group`, but make the repository readable by all users.
-'<perm>'::
+_<perm>_::
-'<perm>' is a 3-digit octal number prefixed with `0` and each file
-will have mode '<perm>'. '<perm>' will override users' umask(2)
-value (and not only loosen permissions as 'group' and 'all'
-does). '0640' will create a repository which is group-readable, but
-not group-writable or accessible to others. '0660' will create a repo
+_<perm>_ is a 3-digit octal number prefixed with `0` and each file
+will have mode _<perm>_. _<perm>_ will override users' `umask`(2)
+value (and not only loosen permissions as `group` and `all`
+do). `0640` will create a repository which is group-readable, but
+not group-writable or accessible to others. `0660` will create a repo
that is readable and writable to the current user and group, but
inaccessible to others (directories and executable files get their
`x` bit from the `r` bit for corresponding classes of users).
@@ -126,7 +137,7 @@
in shared repositories, so that you cannot force a non fast-forwarding push
into it.
-If you provide a 'directory', the command is run inside it. If this directory
+If you provide a _<directory>_, the command is run inside it. If this directory
does not exist, it will be created.
TEMPLATE DIRECTORY
@@ -165,7 +176,7 @@
$ git commit <3>
----------------
+
-<1> Create a /path/to/my/codebase/.git directory.
+<1> Create a `/path/to/my/codebase/.git` directory.
<2> Add all existing files to the index.
<3> Record the pristine state as the first commit in the history.
@@ -174,6 +185,8 @@
include::includes/cmd-config-section-all.txt[]
+:git-init:
+
include::config/init.txt[]
GIT
diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 55d8961..d9dfb75 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -9,7 +9,7 @@
--------
[verse]
'git interpret-trailers' [--in-place] [--trim-empty]
- [(--trailer <token>[(=|:)<value>])...]
+ [(--trailer (<key>|<key-alias>)[(=|:)<value>])...]
[--parse] [<file>...]
DESCRIPTION
@@ -31,10 +31,15 @@
This command reads commit messages from either the
<file> arguments or the standard input if no <file> is specified.
-If `--parse` is specified, the output consists of the parsed trailers.
-Otherwise, this command applies the arguments passed using the
-`--trailer` option, if any, to each input file. The result is emitted on the
-standard output.
+If `--parse` is specified, the output consists of the parsed trailers
+coming from the input, without influencing them with any command line
+options or configuration variables.
+
+Otherwise, this command applies `trailer.*` configuration variables
+(which could potentially add new trailers, as well as reposition them),
+as well as any command line arguments that can override configuration
+variables (such as `--trailer=...` which could also add new trailers),
+to each input file. The result is emitted on the standard output.
This command can also operate on the output of linkgit:git-format-patch[1],
which is more elaborate than a plain commit message. Namely, such output
@@ -48,22 +53,32 @@
the input is changed. They also make it possible to
automatically add some trailers.
-By default, a '<token>=<value>' or '<token>:<value>' argument given
+By default, a '<key>=<value>' or '<key>:<value>' argument given
using `--trailer` will be appended after the existing trailers only if
-the last trailer has a different (<token>, <value>) pair (or if there
-is no existing trailer). The <token> and <value> parts will be trimmed
+the last trailer has a different (<key>, <value>) pair (or if there
+is no existing trailer). The <key> and <value> parts will be trimmed
to remove starting and trailing whitespace, and the resulting trimmed
-<token> and <value> will appear in the output like this:
+<key> and <value> will appear in the output like this:
------------------------------------------------
-token: value
+key: value
------------------------------------------------
-This means that the trimmed <token> and <value> will be separated by
-`': '` (one colon followed by one space). For convenience, the <token> can be a
-shortened string key (e.g., "sign") instead of the full string which should
-appear before the separator on the output (e.g., "Signed-off-by"). This can be
-configured using the 'trailer.<token>.key' configuration variable.
+This means that the trimmed <key> and <value> will be separated by
+`': '` (one colon followed by one space).
+
+For convenience, a <key-alias> can be configured to make using `--trailer`
+shorter to type on the command line. This can be configured using the
+'trailer.<key-alias>.key' configuration variable. The <keyAlias> must be a prefix
+of the full <key> string, although case sensitivity does not matter. For
+example, if you have
+
+------------------------------------------------
+trailer.sign.key "Signed-off-by: "
+------------------------------------------------
+
+in your configuration, you only need to specify `--trailer="sign: foo"`
+on the command line instead of `--trailer="Signed-off-by: foo"`.
By default the new trailer will appear at the end of all the existing
trailers. If there is no existing trailer, the new trailer will appear
@@ -80,14 +95,14 @@
space or the end of the line).
When reading trailers, there can be no whitespace before or inside the
-<token>, but any number of regular space and tab characters are allowed
-between the <token> and the separator. There can be whitespaces before,
+<key>, but any number of regular space and tab characters are allowed
+between the <key> and the separator. There can be whitespaces before,
inside or after the <value>. The <value> may be split over multiple lines
with each subsequent line starting with at least one whitespace, like
the "folding" in RFC 822. Example:
------------------------------------------------
-token: This is a very long value, with spaces and
+key: This is a very long value, with spaces and
newlines in it.
------------------------------------------------
@@ -104,35 +119,44 @@
the whole trailer will be removed from the output.
This applies to existing trailers as well as new trailers.
---trailer <token>[(=|:)<value>]::
- Specify a (<token>, <value>) pair that should be applied as a
+--trailer <key>[(=|:)<value>]::
+ Specify a (<key>, <value>) pair that should be applied as a
trailer to the inputs. See the description of this
command.
--where <placement>::
--no-where::
Specify where all new trailers will be added. A setting
- provided with '--where' overrides all configuration variables
+ provided with '--where' overrides the `trailer.where` and any
+ applicable `trailer.<keyAlias>.where` configuration variables
and applies to all '--trailer' options until the next occurrence of
- '--where' or '--no-where'. Possible values are `after`, `before`,
- `end` or `start`.
+ '--where' or '--no-where'. Upon encountering '--no-where', clear the
+ effect of any previous use of '--where', such that the relevant configuration
+ variables are no longer overridden. Possible placements are `after`,
+ `before`, `end` or `start`.
--if-exists <action>::
--no-if-exists::
Specify what action will be performed when there is already at
- least one trailer with the same <token> in the input. A setting
- provided with '--if-exists' overrides all configuration variables
+ least one trailer with the same <key> in the input. A setting
+ provided with '--if-exists' overrides the `trailer.ifExists` and any
+ applicable `trailer.<keyAlias>.ifExists` configuration variables
and applies to all '--trailer' options until the next occurrence of
- '--if-exists' or '--no-if-exists'. Possible actions are `addIfDifferent`,
+ '--if-exists' or '--no-if-exists'. Upon encountering '--no-if-exists, clear the
+ effect of any previous use of '--if-exists, such that the relevant configuration
+ variables are no longer overridden. Possible actions are `addIfDifferent`,
`addIfDifferentNeighbor`, `add`, `replace` and `doNothing`.
--if-missing <action>::
--no-if-missing::
Specify what action will be performed when there is no other
- trailer with the same <token> in the input. A setting
- provided with '--if-missing' overrides all configuration variables
+ trailer with the same <key> in the input. A setting
+ provided with '--if-missing' overrides the `trailer.ifMissing` and any
+ applicable `trailer.<keyAlias>.ifMissing` configuration variables
and applies to all '--trailer' options until the next occurrence of
- '--if-missing' or '--no-if-missing'. Possible actions are `doNothing`
+ '--if-missing' or '--no-if-missing'. Upon encountering '--no-if-missing,
+ clear the effect of any previous use of '--if-missing, such that the relevant
+ configuration variables are no longer overridden. Possible actions are `doNothing`
or `add`.
--only-trailers::
@@ -140,16 +164,19 @@
--only-input::
Output only trailers that exist in the input; do not add any
- from the command-line or by following configured `trailer.*`
- rules.
+ from the command-line or by applying `trailer.*` configuration
+ variables.
--unfold::
- Remove any whitespace-continuation in trailers, so that each
- trailer appears on a line by itself with its full content.
+ If a trailer has a value that runs over multiple lines (aka "folded"),
+ reformat the value into a single line.
--parse::
A convenience alias for `--only-trailers --only-input
- --unfold`.
+ --unfold`. This makes it easier to only see the trailers coming from the
+ input without influencing them with any command line options or
+ configuration variables, while also making the output machine-friendly with
+ --unfold.
--no-divider::
Do not treat `---` as the end of the commit message. Use this
@@ -170,11 +197,11 @@
trailer.
+
For example, if the value for this option is "%=$", then only lines
-using the format '<token><sep><value>' with <sep> containing '%', '='
+using the format '<key><sep><value>' with <sep> containing '%', '='
or '$' and then spaces will be considered trailers. And '%' will be
the default separator used, so by default trailers will appear like:
-'<token>% <value>' (one percent sign and one space will appear between
-the token and the value).
+'<key>% <value>' (one percent sign and one space will appear between
+the key and the value).
trailer.where::
This option tells where a new trailer will be added.
@@ -188,41 +215,41 @@
instead of the end, of the existing trailers.
+
If it is `after`, then each new trailer will appear just after the
-last trailer with the same <token>.
+last trailer with the same <key>.
+
If it is `before`, then each new trailer will appear just before the
-first trailer with the same <token>.
+first trailer with the same <key>.
trailer.ifexists::
This option makes it possible to choose what action will be
performed when there is already at least one trailer with the
- same <token> in the input.
+ same <key> in the input.
+
The valid values for this option are: `addIfDifferentNeighbor` (this
is the default), `addIfDifferent`, `add`, `replace` or `doNothing`.
+
With `addIfDifferentNeighbor`, a new trailer will be added only if no
-trailer with the same (<token>, <value>) pair is above or below the line
+trailer with the same (<key>, <value>) pair is above or below the line
where the new trailer will be added.
+
With `addIfDifferent`, a new trailer will be added only if no trailer
-with the same (<token>, <value>) pair is already in the input.
+with the same (<key>, <value>) pair is already in the input.
+
With `add`, a new trailer will be added, even if some trailers with
-the same (<token>, <value>) pair are already in the input.
+the same (<key>, <value>) pair are already in the input.
+
-With `replace`, an existing trailer with the same <token> will be
+With `replace`, an existing trailer with the same <key> will be
deleted and the new trailer will be added. The deleted trailer will be
-the closest one (with the same <token>) to the place where the new one
+the closest one (with the same <key>) to the place where the new one
will be added.
+
With `doNothing`, nothing will be done; that is no new trailer will be
-added if there is already one with the same <token> in the input.
+added if there is already one with the same <key> in the input.
trailer.ifmissing::
This option makes it possible to choose what action will be
performed when there is not yet any trailer with the same
- <token> in the input.
+ <key> in the input.
+
The valid values for this option are: `add` (this is the default) and
`doNothing`.
@@ -231,34 +258,40 @@
+
With `doNothing`, nothing will be done.
-trailer.<token>.key::
- This `key` will be used instead of <token> in the trailer. At
- the end of this key, a separator can appear and then some
- space characters. By default the only valid separator is ':',
- but this can be changed using the `trailer.separators` config
- variable.
+trailer.<keyAlias>.key::
+ Defines a <keyAlias> for the <key>. The <keyAlias> must be a
+ prefix (case does not matter) of the <key>. For example, in `git
+ config trailer.ack.key "Acked-by"` the "Acked-by" is the <key> and
+ the "ack" is the <keyAlias>. This configuration allows the shorter
+ `--trailer "ack:..."` invocation on the command line using the "ack"
+ <keyAlias> instead of the longer `--trailer "Acked-by:..."`.
+
-If there is a separator, then the key will be used instead of both the
-<token> and the default separator when adding the trailer.
+At the end of the <key>, a separator can appear and then some
+space characters. By default the only valid separator is ':',
+but this can be changed using the `trailer.separators` config
+variable.
++
+If there is a separator in the key, then it overrides the default
+separator when adding the trailer.
-trailer.<token>.where::
+trailer.<keyAlias>.where::
This option takes the same values as the 'trailer.where'
configuration variable and it overrides what is specified by
- that option for trailers with the specified <token>.
+ that option for trailers with the specified <keyAlias>.
-trailer.<token>.ifexists::
+trailer.<keyAlias>.ifexists::
This option takes the same values as the 'trailer.ifexists'
configuration variable and it overrides what is specified by
- that option for trailers with the specified <token>.
+ that option for trailers with the specified <keyAlias>.
-trailer.<token>.ifmissing::
+trailer.<keyAlias>.ifmissing::
This option takes the same values as the 'trailer.ifmissing'
configuration variable and it overrides what is specified by
- that option for trailers with the specified <token>.
+ that option for trailers with the specified <keyAlias>.
-trailer.<token>.command::
- Deprecated in favor of 'trailer.<token>.cmd'.
- This option behaves in the same way as 'trailer.<token>.cmd', except
+trailer.<keyAlias>.command::
+ Deprecated in favor of 'trailer.<keyAlias>.cmd'.
+ This option behaves in the same way as 'trailer.<keyAlias>.cmd', except
that it doesn't pass anything as argument to the specified command.
Instead the first occurrence of substring $ARG is replaced by the
<value> that would be passed as argument.
@@ -266,29 +299,29 @@
Note that $ARG in the user's command is
only replaced once and that the original way of replacing $ARG is not safe.
+
-When both 'trailer.<token>.cmd' and 'trailer.<token>.command' are given
-for the same <token>, 'trailer.<token>.cmd' is used and
-'trailer.<token>.command' is ignored.
+When both 'trailer.<keyAlias>.cmd' and 'trailer.<keyAlias>.command' are given
+for the same <keyAlias>, 'trailer.<keyAlias>.cmd' is used and
+'trailer.<keyAlias>.command' is ignored.
-trailer.<token>.cmd::
+trailer.<keyAlias>.cmd::
This option can be used to specify a shell command that will be called
- once to automatically add a trailer with the specified <token>, and then
- called each time a '--trailer <token>=<value>' argument is specified to
+ once to automatically add a trailer with the specified <keyAlias>, and then
+ called each time a '--trailer <keyAlias>=<value>' argument is specified to
modify the <value> of the trailer that this option would produce.
+
When the specified command is first called to add a trailer
-with the specified <token>, the behavior is as if a special
-'--trailer <token>=<value>' argument was added at the beginning
+with the specified <keyAlias>, the behavior is as if a special
+'--trailer <keyAlias>=<value>' argument was added at the beginning
of the "git interpret-trailers" command, where <value>
is taken to be the standard output of the command with any
leading and trailing whitespace trimmed off.
+
-If some '--trailer <token>=<value>' arguments are also passed
+If some '--trailer <keyAlias>=<value>' arguments are also passed
on the command line, the command is called again once for each
-of these arguments with the same <token>. And the <value> part
+of these arguments with the same <keyAlias>. And the <value> part
of these arguments, if any, will be passed to the command as its
first argument. This way the command can produce a <value> computed
-from the <value> passed in the '--trailer <token>=<value>' argument.
+from the <value> passed in the '--trailer <keyAlias>=<value>' argument.
EXAMPLES
--------
diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index 2a66cf8..5796821 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -120,11 +120,11 @@
below can be used to show the changes made by each commit.
Note that unless one of `--diff-merges` variants (including short
-`-m`, `-c`, and `--cc` options) is explicitly given, merge commits
+`-m`, `-c`, `--cc`, and `--dd` options) is explicitly given, merge commits
will not show a diff, even if a diff format like `--patch` is
selected, nor will they match search options like `-S`. The exception
is when `--first-parent` is in use, in which case `first-parent` is
-the default format.
+the default format for merge commits.
:git-log: 1
:diff-merges-default: `off`
diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 1bc0328..d08c7da 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -25,12 +25,12 @@
DESCRIPTION
-----------
-This merges the file listing in the index with the actual working
+This command merges the file listing in the index with the actual working
directory list, and shows different combinations of the two.
-One or more of the options below may be used to determine the files
+Several flags can be used to determine which files are
shown, and each file may be printed multiple times if there are
-multiple entries in the index or multiple statuses are applicable for
+multiple entries in the index or if multiple statuses are applicable for
the relevant file selection options.
OPTIONS
@@ -62,7 +62,7 @@
matching an exclude pattern. When showing "other" files
(i.e. when used with '-o'), show only those matched by an
exclude pattern. Standard ignore rules are not automatically
- activated, therefore at least one of the `--exclude*` options
+ activated; therefore, at least one of the `--exclude*` options
is required.
-s::
@@ -119,8 +119,10 @@
--exclude-per-directory=<file>::
Read additional exclude patterns that apply only to the
- directory and its subdirectories in <file>. Deprecated; use
- --exclude-standard instead.
+ directory and its subdirectories in <file>. If you are
+ trying to emulate the way Porcelain commands work, using
+ the `--exclude-standard` option instead is easier and more
+ thorough.
--exclude-standard::
Add the standard Git exclusions: .git/info/exclude, .gitignore
@@ -141,7 +143,7 @@
Show status tags together with filenames. Note that for
scripting purposes, linkgit:git-status[1] `--porcelain` and
linkgit:git-diff-files[1] `--name-status` are almost always
- superior alternatives, and users should look at
+ superior alternatives; users should look at
linkgit:git-status[1] `--short` or linkgit:git-diff[1]
`--name-status` for more user-friendly alternatives.
+
@@ -298,9 +300,8 @@
flags --others or --ignored are specified. linkgit:gitignore[5]
specifies the format of exclude patterns.
-Generally, you should just use --exclude-standard, but for historical
-reasons the exclude patterns can be specified from the following
-places, in order:
+These exclude patterns can be specified from the following places,
+in order:
1. The command-line flag --exclude=<pattern> specifies a
single pattern. Patterns are ordered in the same order
@@ -322,6 +323,18 @@
by --exclude-per-directory is relative to the directory that the
pattern file appears in.
+Generally, you should be able to use `--exclude-standard` when you
+want the exclude rules applied the same way as what Porcelain
+commands do. To emulate what `--exclude-standard` specifies, you
+can give `--exclude-per-directory=.gitignore`, and then specify:
+
+ 1. The file specified by the `core.excludesfile` configuration
+ variable, if exists, or the `$XDG_CONFIG_HOME/git/ignore` file.
+
+ 2. The `$GIT_DIR/info/exclude` file.
+
+via the `--exclude-from=` option.
+
SEE ALSO
--------
linkgit:git-read-tree[1], linkgit:gitignore[5]
diff --git a/Documentation/git-mailsplit.txt b/Documentation/git-mailsplit.txt
index e3b2a88..3f0a666 100644
--- a/Documentation/git-mailsplit.txt
+++ b/Documentation/git-mailsplit.txt
@@ -34,7 +34,7 @@
-b::
If any file doesn't begin with a From line, assume it is a
- single mail message instead of signaling error.
+ single mail message instead of signaling an error.
-d<prec>::
Instead of the default 4 digits with leading zeros,
diff --git a/Documentation/git-maintenance.txt b/Documentation/git-maintenance.txt
index 805e5a2..51d0f7e 100644
--- a/Documentation/git-maintenance.txt
+++ b/Documentation/git-maintenance.txt
@@ -102,9 +102,9 @@
requested refs within `refs/prefetch/`. Also, tags are not updated.
+
This is done to avoid disrupting the remote-tracking branches. The end users
-expect these refs to stay unmoved unless they initiate a fetch. With prefetch
-task, however, the objects necessary to complete a later real fetch would
-already be obtained, so the real fetch would go faster. In the ideal case,
+expect these refs to stay unmoved unless they initiate a fetch. However,
+with the prefetch task, the objects necessary to complete a later real fetch
+would already be obtained, making the real fetch faster. In the ideal case,
it will just become an update to a bunch of remote-tracking branches without
any object transfer.
diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt
index b01ba3d..5ab957c 100644
--- a/Documentation/git-merge-base.txt
+++ b/Documentation/git-merge-base.txt
@@ -18,7 +18,7 @@
DESCRIPTION
-----------
-'git merge-base' finds best common ancestor(s) between two commits to use
+'git merge-base' finds the best common ancestor(s) between two commits to use
in a three-way merge. One common ancestor is 'better' than another common
ancestor if the latter is an ancestor of the former. A common ancestor
that does not have any better common ancestor is a 'best common
@@ -28,7 +28,7 @@
OPERATION MODES
---------------
-As the most common special case, specifying only two commits on the
+In the most common special case, specifying only two commits on the
command line means computing the merge base between the given two commits.
More generally, among the two commits to compute the merge base from,
@@ -64,7 +64,7 @@
the two commits, but also takes into account the reflog of
<ref> to see if the history leading to <commit> forked from
an earlier incarnation of the branch <ref> (see discussion
- on this mode below).
+ of this mode below).
OPTIONS
-------
@@ -88,7 +88,7 @@
the merge base between 'A' and 'B' is '1'.
-Given three commits 'A', 'B' and 'C', `git merge-base A B C` will compute the
+Given three commits 'A', 'B', and 'C', `git merge-base A B C` will compute the
merge base between 'A' and a hypothetical commit 'M', which is a merge
between 'B' and 'C'. For example, with this topology:
@@ -130,7 +130,7 @@
---2---o---o---B
....
-both '1' and '2' are merge-bases of A and B. Neither one is better than
+both '1' and '2' are merge bases of A and B. Neither one is better than
the other (both are 'best' merge bases). When the `--all` option is not given,
it is unspecified which best one is output.
@@ -204,7 +204,7 @@
$ git rebase --onto origin/master $fork_point topic
-will replay D0, D1 and D on top of B to create a new history of this
+will replay D0, D1, and D on top of B to create a new history of this
shape:
....
diff --git a/Documentation/git-merge-file.txt b/Documentation/git-merge-file.txt
index 7e9093f..71915a0 100644
--- a/Documentation/git-merge-file.txt
+++ b/Documentation/git-merge-file.txt
@@ -11,19 +11,20 @@
[verse]
'git merge-file' [-L <current-name> [-L <base-name> [-L <other-name>]]]
[--ours|--theirs|--union] [-p|--stdout] [-q|--quiet] [--marker-size=<n>]
- [--[no-]diff3] <current-file> <base-file> <other-file>
+ [--[no-]diff3] [--object-id] <current> <base> <other>
DESCRIPTION
-----------
-'git merge-file' incorporates all changes that lead from the `<base-file>`
-to `<other-file>` into `<current-file>`. The result ordinarily goes into
-`<current-file>`. 'git merge-file' is useful for combining separate changes
-to an original. Suppose `<base-file>` is the original, and both
-`<current-file>` and `<other-file>` are modifications of `<base-file>`,
+Given three files `<current>`, `<base>` and `<other>`,
+'git merge-file' incorporates all changes that lead from `<base>`
+to `<other>` into `<current>`. The result ordinarily goes into
+`<current>`. 'git merge-file' is useful for combining separate changes
+to an original. Suppose `<base>` is the original, and both
+`<current>` and `<other>` are modifications of `<base>`,
then 'git merge-file' combines both changes.
-A conflict occurs if both `<current-file>` and `<other-file>` have changes
+A conflict occurs if both `<current>` and `<other>` have changes
in a common segment of lines. If a conflict is found, 'git merge-file'
normally outputs a warning and brackets the conflict with lines containing
<<<<<<< and >>>>>>> markers. A typical conflict will look like this:
@@ -36,10 +37,14 @@
If there are conflicts, the user should edit the result and delete one of
the alternatives. When `--ours`, `--theirs`, or `--union` option is in effect,
-however, these conflicts are resolved favouring lines from `<current-file>`,
-lines from `<other-file>`, or lines from both respectively. The length of the
+however, these conflicts are resolved favouring lines from `<current>`,
+lines from `<other>`, or lines from both respectively. The length of the
conflict markers can be given with the `--marker-size` option.
+If `--object-id` is specified, exactly the same behavior occurs, except that
+instead of specifying what to merge as files, it is specified as a list of
+object IDs referring to blobs.
+
The exit value of this program is negative on error, and the number of
conflicts otherwise (truncated to 127 if there are more than that many
conflicts). If the merge was clean, the exit value is 0.
@@ -52,6 +57,14 @@
OPTIONS
-------
+--object-id::
+ Specify the contents to merge as blobs in the current repository instead of
+ files. In this case, the operation must take place within a valid repository.
++
+If the `-p` option is specified, the merged file (including conflicts, if any)
+goes to standard output as normal; otherwise, the merged file is written to the
+object store and the object ID of its blob is written to standard output.
+
-L <label>::
This option may be given up to three times, and
specifies labels to be used in place of the
@@ -62,7 +75,7 @@
-p::
Send results to standard output instead of overwriting
- `<current-file>`.
+ `<current>`.
-q::
Quiet; do not warn about conflicts.
@@ -79,6 +92,12 @@
Instead of leaving conflicts in the file, resolve conflicts
favouring our (or their or both) side of the lines.
+--diff-algorithm={patience|minimal|histogram|myers}::
+ Use a different diff algorithm while merging. The current default is "myers",
+ but selecting more recent algorithm such as "histogram" can help
+ avoid mismerges that occur due to unimportant matching lines
+ (such as braces from distinct functions). See also
+ linkgit:git-diff[1] `--diff-algorithm`.
EXAMPLES
--------
@@ -93,6 +112,11 @@
merges tmp/a123 and tmp/c345 with the base tmp/b234, but uses labels
`a` and `c` instead of `tmp/a123` and `tmp/c345`.
+`git merge-file -p --object-id abc1234 def567 890abcd`::
+
+ combines the changes of the blob abc1234 and 890abcd since def567,
+ tries to merge them and writes the result to standard output
+
GIT
---
Part of the linkgit:git[1] suite
diff --git a/Documentation/git-merge-tree.txt b/Documentation/git-merge-tree.txt
index ffc4fbf..84cb2ed 100644
--- a/Documentation/git-merge-tree.txt
+++ b/Documentation/git-merge-tree.txt
@@ -19,12 +19,12 @@
This command has a modern `--write-tree` mode and a deprecated
`--trivial-merge` mode. With the exception of the
<<DEPMERGE,DEPRECATED DESCRIPTION>> section at the end, the rest of
-this documentation describes modern `--write-tree` mode.
+this documentation describes the modern `--write-tree` mode.
Performs a merge, but does not make any new commits and does not read
from or write to either the working tree or index.
-The performed merge will use the same feature as the "real"
+The performed merge will use the same features as the "real"
linkgit:git-merge[1], including:
* three way content merges of individual files
@@ -64,10 +64,18 @@
share no common history. This flag can be given to override that
check and make the merge proceed anyway.
---merge-base=<commit>::
+--merge-base=<tree-ish>::
Instead of finding the merge-bases for <branch1> and <branch2>,
specify a merge-base for the merge, and specifying multiple bases is
currently not supported. This option is incompatible with `--stdin`.
++
+As the merge-base is provided directly, <branch1> and <branch2> do not need
+to specify commits; trees are enough.
+
+-X<option>::
+--strategy-option=<option>::
+ Pass the merge strategy-specific option through to the merge strategy.
+ See linkgit:git-merge[1] for details.
[[OUTPUT]]
OUTPUT
@@ -253,7 +261,7 @@
the <<CFI,Conflicted file info>> list. The information there is
insufficient to do so. For example: Rename/rename(1to2) conflicts (both
sides renamed the same file differently) will result in three different
-file having higher order stages (but each only has one higher order
+files having higher order stages (but each only has one higher order
stage), with no way (short of the <<IM,Informational messages>> section)
to determine which three files are related. File/directory conflicts
also result in a file with exactly one higher order stage.
@@ -263,7 +271,7 @@
<<IM,Informational messages>> section has the necessary info, though it
is not designed to be machine parseable.
-Do NOT assume that each paths from <<CFI,Conflicted file info>>, and
+Do NOT assume that each path from <<CFI,Conflicted file info>>, and
the logical conflicts in the <<IM,Informational messages>> have a
one-to-one mapping, nor that there is a one-to-many mapping, nor a
many-to-one mapping. Many-to-many mappings exist, meaning that each
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 8625c5c..1ab69f6 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -20,12 +20,12 @@
-----------
Incorporates changes from the named commits (since the time their
histories diverged from the current branch) into the current
-branch. This command is used by 'git pull' to incorporate changes
+branch. This command is used by `git pull` to incorporate changes
from another repository and can be used by hand to merge changes
from one branch into another.
Assume the following history exists and the current branch is
-"`master`":
+`master`:
------------
A---B---C topic
@@ -33,7 +33,7 @@
D---E---F---G master
------------
-Then "`git merge topic`" will replay the changes made on the
+Then `git merge topic` will replay the changes made on the
`topic` branch since it diverged from `master` (i.e., `E`) until
its current commit (`C`) on top of `master`, and record the result
in a new commit along with the names of the two parent commits and
@@ -46,21 +46,21 @@
D---E---F---G---H master
------------
-The second syntax ("`git merge --abort`") can only be run after the
-merge has resulted in conflicts. 'git merge --abort' will abort the
-merge process and try to reconstruct the pre-merge state. However,
-if there were uncommitted changes when the merge started (and
-especially if those changes were further modified after the merge
-was started), 'git merge --abort' will in some cases be unable to
-reconstruct the original (pre-merge) changes. Therefore:
+A merge stops if there's a conflict that cannot be resolved
+automatically or if `--no-commit` was provided when initiating the
+merge. At that point you can run `git merge --abort` or `git merge
+--continue`.
-*Warning*: Running 'git merge' with non-trivial uncommitted changes is
+`git merge --abort` will abort the merge process and try to reconstruct
+the pre-merge state. However, if there were uncommitted changes when the
+merge started (and especially if those changes were further modified
+after the merge was started), `git merge --abort` will in some cases be
+unable to reconstruct the original (pre-merge) changes. Therefore:
+
+*Warning*: Running `git merge` with non-trivial uncommitted changes is
discouraged: while possible, it may leave you in a state that is hard to
back out of in the case of a conflict.
-The third syntax ("`git merge --continue`") can only be run after the
-merge has resulted in conflicts.
-
OPTIONS
-------
:git-merge: 1
@@ -74,8 +74,8 @@
If `--log` is specified, a shortlog of the commits being merged
will be appended to the specified message.
+
-The 'git fmt-merge-msg' command can be
-used to give a good default for automated 'git merge'
+The `git fmt-merge-msg` command can be
+used to give a good default for automated `git merge`
invocations. The automated message can include the branch description.
--into-name <branch>::
@@ -104,14 +104,14 @@
present, apply it to the worktree.
+
If there were uncommitted worktree changes present when the merge
-started, 'git merge --abort' will in some cases be unable to
+started, `git merge --abort` will in some cases be unable to
reconstruct these changes. It is therefore recommended to always
-commit or stash your changes before running 'git merge'.
+commit or stash your changes before running `git merge`.
+
-'git merge --abort' is equivalent to 'git reset --merge' when
+`git merge --abort` is equivalent to `git reset --merge` when
`MERGE_HEAD` is present unless `MERGE_AUTOSTASH` is also present in
-which case 'git merge --abort' applies the stash entry to the worktree
-whereas 'git reset --merge' will save the stashed changes in the stash
+which case `git merge --abort` applies the stash entry to the worktree
+whereas `git reset --merge` will save the stashed changes in the stash
list.
--quit::
@@ -120,8 +120,8 @@
stash entry will be saved to the stash list.
--continue::
- After a 'git merge' stops due to conflicts you can conclude the
- merge by running 'git merge --continue' (see "HOW TO RESOLVE
+ After a `git merge` stops due to conflicts you can conclude the
+ merge by running `git merge --continue` (see "HOW TO RESOLVE
CONFLICTS" section below).
<commit>...::
@@ -144,25 +144,25 @@
Before applying outside changes, you should get your own work in
good shape and committed locally, so it will not be clobbered if
there are conflicts. See also linkgit:git-stash[1].
-'git pull' and 'git merge' will stop without doing anything when
-local uncommitted changes overlap with files that 'git pull'/'git
-merge' may need to update.
+`git pull` and `git merge` will stop without doing anything when
+local uncommitted changes overlap with files that `git pull`/`git
+merge` may need to update.
To avoid recording unrelated changes in the merge commit,
-'git pull' and 'git merge' will also abort if there are any changes
+`git pull` and `git merge` will also abort if there are any changes
registered in the index relative to the `HEAD` commit. (Special
narrow exceptions to this rule may exist depending on which merge
strategy is in use, but generally, the index must match HEAD.)
-If all named commits are already ancestors of `HEAD`, 'git merge'
+If all named commits are already ancestors of `HEAD`, `git merge`
will exit early with the message "Already up to date."
FAST-FORWARD MERGE
------------------
Often the current branch head is an ancestor of the named commit.
-This is the most common case especially when invoked from 'git
-pull': you are tracking an upstream repository, you have committed
+This is the most common case especially when invoked from `git
+pull`: you are tracking an upstream repository, you have committed
no local changes, and now you want to update to a newer upstream
revision. In this case, a new commit is not needed to store the
combined history; instead, the `HEAD` (along with the index) is
@@ -196,7 +196,7 @@
can inspect the stages with `git ls-files -u`). The working
tree files contain the result of the merge operation; i.e. 3-way
merge results with familiar conflict markers `<<<` `===` `>>>`.
-5. A special ref `AUTO_MERGE` is written, pointing to a tree
+5. A ref named `AUTO_MERGE` is written, pointing to a tree
corresponding to the current content of the working tree (including
conflict markers for textual conflicts). Note that this ref is only
written when the 'ort' merge strategy is used (the default).
@@ -269,7 +269,7 @@
side wants to say it is hard and you'd prefer to go shopping, while the
other side wants to claim it is easy.
-An alternative style can be used by setting the "merge.conflictStyle"
+An alternative style can be used by setting the `merge.conflictStyle`
configuration variable to either "diff3" or "zdiff3". In "diff3"
style, the above conflict may look like this:
@@ -328,15 +328,15 @@
* Resolve the conflicts. Git will mark the conflicts in
the working tree. Edit the files into shape and
- 'git add' them to the index. Use 'git commit' or
- 'git merge --continue' to seal the deal. The latter command
+ `git add` them to the index. Use `git commit` or
+ `git merge --continue` to seal the deal. The latter command
checks whether there is a (interrupted) merge in progress
- before calling 'git commit'.
+ before calling `git commit`.
You can work through the conflict with a number of tools:
* Use a mergetool. `git mergetool` to launch a graphical
- mergetool which will work you through the merge.
+ mergetool which will work through the merge with you.
* Look at the diffs. `git diff` will show a three-way diff,
highlighting changes from both the `HEAD` and `MERGE_HEAD`
@@ -392,7 +392,7 @@
branch.<name>.mergeOptions::
Sets default options for merging into branch <name>. The syntax and
- supported options are the same as those of 'git merge', but option
+ supported options are the same as those of `git merge`, but option
values containing whitespace characters are currently not supported.
include::includes/cmd-config-section-rest.txt[]
diff --git a/Documentation/git-mergetool--lib.txt b/Documentation/git-mergetool--lib.txt
index 3e8f59a..0726b56 100644
--- a/Documentation/git-mergetool--lib.txt
+++ b/Documentation/git-mergetool--lib.txt
@@ -28,22 +28,22 @@
FUNCTIONS
---------
get_merge_tool::
- returns a merge tool. the return code is 1 if we returned a guessed
+ Returns a merge tool. The return code is 1 if we returned a guessed
merge tool, else 0. '$GIT_MERGETOOL_GUI' may be set to 'true' to
search for the appropriate guitool.
get_merge_tool_cmd::
- returns the custom command for a merge tool.
+ Returns the custom command for a merge tool.
get_merge_tool_path::
- returns the custom path for a merge tool.
+ Returns the custom path for a merge tool.
initialize_merge_tool::
- bring merge tool specific functions into scope so they can be used or
+ Brings merge tool specific functions into scope so they can be used or
overridden.
run_merge_tool::
- launches a merge tool given the tool name and a true/false
+ Launches a merge tool given the tool name and a true/false
flag to indicate whether a merge base is present.
'$MERGED', '$LOCAL', '$REMOTE', and '$BASE' must be defined
for use by the merge tool.
diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt
index 07535f6..b9e20c5 100644
--- a/Documentation/git-mergetool.txt
+++ b/Documentation/git-mergetool.txt
@@ -17,7 +17,7 @@
merge conflicts. It is typically run after 'git merge'.
If one or more <file> parameters are given, the merge tool program will
-be run to resolve differences on each file (skipping those without
+be run to resolve differences in each file (skipping those without
conflicts). Specifying a directory will include all unresolved files in
that path. If no <file> names are specified, 'git mergetool' will run
the merge tool program on every file with merge conflicts.
@@ -49,7 +49,7 @@
+
When 'git mergetool' is invoked with this tool (either through the
`-t` or `--tool` option or the `merge.tool` configuration
-variable) the configured command line will be invoked with `$BASE`
+variable), the configured command line will be invoked with `$BASE`
set to the name of a temporary file containing the common base for
the merge, if available; `$LOCAL` set to the name of a temporary
file containing the contents of the file on the current branch;
@@ -81,7 +81,7 @@
-g::
--gui::
- When 'git-mergetool' is invoked with the `-g` or `--gui` option
+ When 'git-mergetool' is invoked with the `-g` or `--gui` option,
the default merge tool will be read from the configured
`merge.guitool` variable instead of `merge.tool`. If
`merge.guitool` is not set, we will fallback to the tool
@@ -115,7 +115,7 @@
`git mergetool` session has completed.
Setting the `mergetool.keepBackup` configuration variable to `false`
-causes `git mergetool` to automatically remove the backup as files
+causes `git mergetool` to automatically remove the backup files as files
are successfully merged.
BACKEND SPECIFIC HINTS
diff --git a/Documentation/git-mktag.txt b/Documentation/git-mktag.txt
index b2a2e80..006d759 100644
--- a/Documentation/git-mktag.txt
+++ b/Documentation/git-mktag.txt
@@ -14,7 +14,7 @@
DESCRIPTION
-----------
-Reads a tag contents on standard input and creates a tag object. The
+Reads a tag's contents on standard input and creates a tag object. The
output is the new tag's <object> identifier.
This command is mostly equivalent to linkgit:git-hash-object[1]
@@ -27,7 +27,7 @@
The difference is that mktag will die before writing the tag if the
tag doesn't pass a linkgit:git-fsck[1] check.
-The "fsck" check done mktag is stricter than what linkgit:git-fsck[1]
+The "fsck" check done by mktag is stricter than what linkgit:git-fsck[1]
would run by default in that all `fsck.<msg-id>` messages are promoted
from warnings to errors (so e.g. a missing "tagger" line is an error).
@@ -56,7 +56,7 @@
tagger <tagger>
followed by some 'optional' free-form message (some tags created
-by older Git may not have `tagger` line). The message, when it
+by older Git may not have a `tagger` line). The message, when it
exists, is separated by a blank line from the header. The
message part may contain a signature that Git itself doesn't
care about, but that can be verified with gpg.
diff --git a/Documentation/git-mktree.txt b/Documentation/git-mktree.txt
index 76b44f4..383f09d 100644
--- a/Documentation/git-mktree.txt
+++ b/Documentation/git-mktree.txt
@@ -25,13 +25,13 @@
--missing::
Allow missing objects. The default behaviour (without this option)
- is to verify that each tree entry's sha1 identifies an existing
+ is to verify that each tree entry's hash identifies an existing
object. This option has no effect on the treatment of gitlink entries
(aka "submodules") which are always allowed to be missing.
--batch::
Allow building of more than one tree object before exiting. Each
- tree is separated by a single blank line. The final new-line is
+ tree is separated by a single blank line. The final newline is
optional. Note - if the `-z` option is used, lines are terminated
with NUL.
diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt
index fb0220f..dc1bf61 100644
--- a/Documentation/git-mv.txt
+++ b/Documentation/git-mv.txt
@@ -13,10 +13,10 @@
DESCRIPTION
-----------
-Move or rename a file, directory or symlink.
+Move or rename a file, directory, or symlink.
git mv [-v] [-f] [-n] [-k] <source> <destination>
- git mv [-v] [-f] [-n] [-k] <source> ... <destination directory>
+ git mv [-v] [-f] [-n] [-k] <source> ... <destination-directory>
In the first form, it renames <source>, which must exist and be either
a file, symlink or directory, to <destination>.
diff --git a/Documentation/git-name-rev.txt b/Documentation/git-name-rev.txt
index 5c56c87..d4f1c4d 100644
--- a/Documentation/git-name-rev.txt
+++ b/Documentation/git-name-rev.txt
@@ -26,7 +26,7 @@
--refs=<pattern>::
Only use refs whose names match a given shell pattern. The pattern
- can be one of branch name, tag name or fully qualified ref name. If
+ can be a branch name, a tag name, or a fully qualified ref name. If
given multiple times, use refs whose names match any of the given shell
patterns. Use `--no-refs` to clear any previous ref patterns given.
diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index f8310e5..c9221a6 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -56,7 +56,7 @@
list::
List the notes object for a given object. If no object is
given, show a list of all note objects and the objects they
- annotate (in the format "<note object> <annotated object>").
+ annotate (in the format "<note-object> <annotated-object>").
This is the default subcommand if no subcommand is given.
add::
diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt
index a9995a9..e32404c 100644
--- a/Documentation/git-pack-objects.txt
+++ b/Documentation/git-pack-objects.txt
@@ -116,9 +116,7 @@
+
Incompatible with `--unpack-unreachable`, `--keep-unreachable`,
`--pack-loose-unreachable`, `--stdin-packs`, as well as any other
-options which imply `--revs`. Also incompatible with `--max-pack-size`;
-when this option is set, the maximum pack size is not inferred from
-`pack.packSizeLimit`.
+options which imply `--revs`.
--cruft-expiration=<approxidate>::
If specified, objects are eliminated from the cruft pack if they
@@ -298,8 +296,8 @@
nevertheless.
--filter=<filter-spec>::
- Requires `--stdout`. Omits certain objects (usually blobs) from
- the resulting packfile. See linkgit:git-rev-list[1] for valid
+ Omits certain objects (usually blobs) from the resulting
+ packfile. See linkgit:git-rev-list[1] for valid
`<filter-spec>` forms.
--no-filter::
diff --git a/Documentation/git-pack-refs.txt b/Documentation/git-pack-refs.txt
index 284956a..2dcabaf 100644
--- a/Documentation/git-pack-refs.txt
+++ b/Documentation/git-pack-refs.txt
@@ -8,7 +8,7 @@
SYNOPSIS
--------
[verse]
-'git pack-refs' [--all] [--no-prune] [--include <pattern>] [--exclude <pattern>]
+'git pack-refs' [--all] [--no-prune] [--auto] [--include <pattern>] [--exclude <pattern>]
DESCRIPTION
-----------
@@ -60,6 +60,19 @@
The command usually removes loose refs under `$GIT_DIR/refs`
hierarchy after packing them. This option tells it not to.
+--auto::
+
+Pack refs as needed depending on the current state of the ref database. The
+behavior depends on the ref format used by the repository and may change in the
+future.
++
+ - "files": No special handling for `--auto` has been implemented.
++
+ - "reftable": Tables are compacted such that they form a geometric
+ sequence. For two tables N and N+1, where N+1 is newer, this
+ maintains the property that N is at least twice as big as N+1. Only
+ tables that violate this property are compacted.
+
--include <pattern>::
Pack refs based on a `glob(7)` pattern. Repetitions of this option
diff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt
index 844d6f8..db742dc 100644
--- a/Documentation/git-prune-packed.txt
+++ b/Documentation/git-prune-packed.txt
@@ -15,7 +15,7 @@
DESCRIPTION
-----------
This program searches the `$GIT_OBJECT_DIRECTORY` for all objects that currently
-exist in a pack file as well as the independent object directories.
+exist in a pack file as well as in the independent object directories.
All such extra objects are removed.
diff --git a/Documentation/git-prune.txt b/Documentation/git-prune.txt
index 03552dd..9a45571 100644
--- a/Documentation/git-prune.txt
+++ b/Documentation/git-prune.txt
@@ -18,7 +18,7 @@
'git prune'. See the section "NOTES", below.
This runs 'git fsck --unreachable' using all the refs
-available in `refs/`, optionally with additional set of
+available in `refs/`, optionally with an additional set of
objects specified on the command line, and prunes all unpacked
objects unreachable from any of these head objects from the object database.
In addition, it
diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index 0e14f8b..b2ae496 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -87,7 +87,7 @@
--verbose::
Pass --verbose to git-fetch and git-merge.
---[no-]recurse-submodules[=yes|on-demand|no]::
+--[no-]recurse-submodules[=(yes|on-demand|no)]::
This option controls if new commits of populated submodules should
be fetched, and if the working trees of active submodules should be
updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and
@@ -105,7 +105,7 @@
include::merge-options.txt[]
-r::
---rebase[=false|true|merges|interactive]::
+--rebase[=(false|true|merges|interactive)]::
When true, rebase the current branch on top of the upstream
branch after fetching. If there is a remote-tracking branch
corresponding to the upstream branch and the upstream branch
diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 003bc7d..9b7cfbc 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -48,7 +48,7 @@
OPTIONS[[OPTIONS]]
------------------
<repository>::
- The "remote" repository that is destination of a push
+ The "remote" repository that is the destination of a push
operation. This parameter can be either a URL
(see the section <<URLS,GIT URLS>> below) or the name
of a remote (see the section <<REMOTES,REMOTES>> below).
diff --git a/Documentation/git-quiltimport.txt b/Documentation/git-quiltimport.txt
index 70562dc..40e02d9 100644
--- a/Documentation/git-quiltimport.txt
+++ b/Documentation/git-quiltimport.txt
@@ -38,14 +38,14 @@
a patch. At the time of this writing only missing author
information is warned about.
---author Author Name <Author Email>::
+--author 'Author Name <Author Email>'::
The author name and email address to use when no author
information can be found in the patch description.
--patches <dir>::
The directory to find the quilt patches.
+
-The default for the patch directory is patches
+The default for the patch directory is 'patches'
or the value of the `$QUILT_PATCHES` environment
variable.
diff --git a/Documentation/git-range-diff.txt b/Documentation/git-range-diff.txt
index 0b39371..fbdbe0b 100644
--- a/Documentation/git-range-diff.txt
+++ b/Documentation/git-range-diff.txt
@@ -70,7 +70,7 @@
Defaults to 60. Try a larger value if `git range-diff` erroneously
considers a large change a total rewrite (deletion of one commit
and addition of another), and a smaller one in the reverse case.
- See the ``Algorithm`` section below for an explanation why this is
+ See the ``Algorithm`` section below for an explanation of why this is
needed.
--left-only::
@@ -166,7 +166,7 @@
In this example, there are 3 old and 3 new commits, where the developer
removed the 3rd, added a new one before the first two, and modified the
-commit message of the 2nd commit as well its diff.
+commit message of the 2nd commit as well as its diff.
When the output goes to a terminal, it is color-coded by default, just
like regular `git diff`'s output. In addition, the first line (adding a
diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
index b097074..1c48c28 100644
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.txt
@@ -25,15 +25,15 @@
flag. When used with `-m`, the `-u` flag causes it to also update
the files in the work tree with the result of the merge.
-Trivial merges are done by 'git read-tree' itself. Only conflicting paths
-will be in unmerged state when 'git read-tree' returns.
+Only trivial merges are done by 'git read-tree' itself. Only conflicting paths
+will be in an unmerged state when 'git read-tree' returns.
OPTIONS
-------
-m::
Perform a merge, not just a read. The command will
refuse to run if your index file has unmerged entries,
- indicating that you have not finished previous merge you
+ indicating that you have not finished a previous merge you
started.
--reset::
diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index e7b39ad..74df345 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -12,7 +12,7 @@
[--onto <newbase> | --keep-base] [<upstream> [<branch>]]
'git rebase' [-i | --interactive] [<options>] [--exec <cmd>] [--onto <newbase>]
--root [<branch>]
-'git rebase' (--continue | --skip | --abort | --quit | --edit-todo | --show-current-patch)
+'git rebase' (--continue|--skip|--abort|--quit|--edit-todo|--show-current-patch)
DESCRIPTION
-----------
@@ -289,17 +289,25 @@
+
See also INCOMPATIBLE OPTIONS below.
---empty={drop,keep,ask}::
+--empty=(drop|keep|stop)::
How to handle commits that are not empty to start and are not
clean cherry-picks of any upstream commit, but which become
empty after rebasing (because they contain a subset of already
- upstream changes). With drop (the default), commits that
- become empty are dropped. With keep, such commits are kept.
- With ask (implied by `--interactive`), the rebase will halt when
- an empty commit is applied allowing you to choose whether to
- drop it, edit files more, or just commit the empty changes.
- Other options, like `--exec`, will use the default of drop unless
- `-i`/`--interactive` is explicitly specified.
+ upstream changes):
++
+--
+`drop`;;
+ The commit will be dropped. This is the default behavior.
+`keep`;;
+ The commit will be kept. This option is implied when `--exec` is
+ specified unless `-i`/`--interactive` is also specified.
+`stop`;;
+`ask`;;
+ The rebase will halt when the commit is applied, allowing you to
+ choose whether to drop it, edit files more, or just commit the empty
+ changes. This option is implied when `-i`/`--interactive` is
+ specified. `ask` is a deprecated synonym of `stop`.
+--
+
Note that commits which start empty are kept (unless `--no-keep-empty`
is specified), and commits which are clean cherry-picks (as determined
@@ -523,7 +531,7 @@
+
The commit list format can be changed by setting the configuration option
rebase.instructionFormat. A customized instruction format will automatically
-have the long commit hash prepended to the format.
+have the commit hash prepended to the format.
+
See also INCOMPATIBLE OPTIONS below.
@@ -589,21 +597,27 @@
--autosquash::
--no-autosquash::
- When the commit log message begins with "squash! ..." or "fixup! ..."
- or "amend! ...", and there is already a commit in the todo list that
- matches the same `...`, automatically modify the todo list of
- `rebase -i`, so that the commit marked for squashing comes right after
- the commit to be modified, and change the action of the moved commit
- from `pick` to `squash` or `fixup` or `fixup -C` respectively. A commit
- matches the `...` if the commit subject matches, or if the `...` refers
- to the commit's hash. As a fall-back, partial matches of the commit
- subject work, too. The recommended way to create fixup/amend/squash
- commits is by using the `--fixup`, `--fixup=amend:` or `--fixup=reword:`
- and `--squash` options respectively of linkgit:git-commit[1].
+ Automatically squash commits with specially formatted messages into
+ previous commits being rebased. If a commit message starts with
+ "squash! ", "fixup! " or "amend! ", the remainder of the subject line
+ is taken as a commit specifier, which matches a previous commit if it
+ matches the subject line or the hash of that commit. If no commit
+ matches fully, matches of the specifier with the start of commit
+ subjects are considered.
+
-If the `--autosquash` option is enabled by default using the
-configuration variable `rebase.autoSquash`, this option can be
-used to override and disable this setting.
+In the rebase todo list, the actions of squash, fixup and amend commits are
+changed from `pick` to `squash`, `fixup` or `fixup -C`, respectively, and they
+are moved right after the commit they modify. The `--interactive` option can
+be used to review and edit the todo list before proceeding.
++
+The recommended way to create commits with squash markers is by using the
+`--squash`, `--fixup`, `--fixup=amend:` or `--fixup=reword:` options of
+linkgit:git-commit[1], which take the target commit as an argument and
+automatically fill in the subject line of the new commit from that.
++
+Setting configuration variable `rebase.autoSquash` to true enables
+auto-squashing by default for interactive rebase. The `--no-autosquash`
+option can be used to override that setting.
+
See also INCOMPATIBLE OPTIONS below.
@@ -620,13 +634,16 @@
Automatically reschedule `exec` commands that failed. This only makes
sense in interactive mode (or when an `--exec` option was provided).
+
-Even though this option applies once a rebase is started, it's set for
-the whole rebase at the start based on either the
-`rebase.rescheduleFailedExec` configuration (see linkgit:git-config[1]
-or "CONFIGURATION" below) or whether this option is
-provided. Otherwise an explicit `--no-reschedule-failed-exec` at the
-start would be overridden by the presence of
-`rebase.rescheduleFailedExec=true` configuration.
+This option applies once a rebase is started. It is preserved for the whole
+rebase based on, in order, the command line option provided to the initial `git
+rebase`, the `rebase.rescheduleFailedExec` configuration (see
+linkgit:git-config[1] or "CONFIGURATION" below), or it defaults to false.
++
+Recording this option for the whole rebase is a convenience feature. Otherwise
+an explicit `--no-reschedule-failed-exec` at the start would be overridden by
+the presence of a `rebase.rescheduleFailedExec=true` configuration when `git
+rebase --continue` is invoked. Currently, you cannot pass
+`--[no-]reschedule-failed-exec` to `git rebase --continue`.
--update-refs::
--no-update-refs::
@@ -695,7 +712,7 @@
Similar to the apply backend, by default the merge backend drops
commits that become empty unless `-i`/`--interactive` is specified (in
which case it stops and asks the user what to do). The merge backend
-also has an `--empty={drop,keep,ask}` option for changing the behavior
+also has an `--empty=(drop|keep|stop)` option for changing the behavior
of handling commits that become empty.
Directory rename detection
@@ -957,10 +974,9 @@
non-0 status) to give you an opportunity to fix the problem. You can
continue with `git rebase --continue`.
-The "exec" command launches the command in a shell (the one specified
-in `$SHELL`, or the default shell if `$SHELL` is not set), so you can
-use shell features (like "cd", ">", ";" ...). The command is run from
-the root of the working tree.
+The "exec" command launches the command in a shell (the default one, usually
+/bin/sh), so you can use shell features (like "cd", ">", ";" ...). The command
+is run from the root of the working tree.
----------------------------------
$ git rebase -i --exec "make test"
diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt
index 65ff518..20aca92 100644
--- a/Documentation/git-receive-pack.txt
+++ b/Documentation/git-receive-pack.txt
@@ -18,10 +18,10 @@
This command is usually not invoked directly by the end user.
The UI for the protocol is on the 'git send-pack' side, and the
-program pair is meant to be used to push updates to remote
+program pair is meant to be used to push updates to a remote
repository. For pull operations, see linkgit:git-fetch-pack[1].
-The command allows for creation and fast-forwarding of sha1 refs
+The command allows for the creation and fast-forwarding of sha1 refs
(heads/tags) on the remote end (strictly speaking, it is the
local end 'git-receive-pack' runs, but to the user who is sitting at
the send-pack end, it is updating the remote. Confused?)
diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt
index ec64cbf..a929c52 100644
--- a/Documentation/git-reflog.txt
+++ b/Documentation/git-reflog.txt
@@ -10,6 +10,7 @@
--------
[verse]
'git reflog' [show] [<log-options>] [<ref>]
+'git reflog list'
'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>]
[--rewrite] [--updateref] [--stale-fix]
[--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...]
@@ -39,6 +40,8 @@
`git reflog show` is an alias for `git log -g --abbrev-commit
--pretty=oneline`; see linkgit:git-log[1] for more information.
+The "list" subcommand lists all refs which have a corresponding reflog.
+
The "expire" subcommand prunes older reflog entries. Entries older
than `expire` time, or entries older than `expire-unreachable` time
and not reachable from the current tip, are removed from the reflog.
diff --git a/Documentation/git-remote-ext.txt b/Documentation/git-remote-ext.txt
index 88ea7e1..b33ee3c 100644
--- a/Documentation/git-remote-ext.txt
+++ b/Documentation/git-remote-ext.txt
@@ -44,15 +44,15 @@
This argument will not be passed to '<command>'. Instead, it
will cause the helper to start by sending git:// service requests to
the remote side with the service field set to an appropriate value and
- the repository field set to rest of the argument. Default is not to send
+ the repository field set to the rest of the argument. Default is not to send
such a request.
+
-This is useful if remote side is git:// server accessed over
+This is useful if the remote side is git:// server accessed over
some tunnel.
'%V' (must be first characters in argument)::
This argument will not be passed to '<command>'. Instead it sets
- the vhost field in the git:// service request (to rest of the argument).
+ the vhost field in the git:// service request (to the rest of the argument).
Default is not to send vhost in such request (if sent).
ENVIRONMENT VARIABLES
@@ -82,12 +82,12 @@
"ext::ssh -i /home/foo/.ssh/somekey user@host.example %S 'foo/repo'"::
Like host.example:foo/repo, but use /home/foo/.ssh/somekey as
- keypair and user as user on remote side. This avoids needing to
+ keypair and user as the user on the remote side. This avoids the need to
edit .ssh/config.
"ext::socat -t3600 - ABSTRACT-CONNECT:/git-server %G/somerepo"::
Represents repository with path /somerepo accessible over
- git protocol at abstract namespace address /git-server.
+ git protocol at the abstract namespace address /git-server.
"ext::git-server-alias foo %G/repo"::
Represents a repository with path /repo accessed using the
diff --git a/Documentation/git-remote-fd.txt b/Documentation/git-remote-fd.txt
index 0451ceb..1dd2648 100644
--- a/Documentation/git-remote-fd.txt
+++ b/Documentation/git-remote-fd.txt
@@ -13,19 +13,19 @@
-----------
This helper uses specified file descriptors to connect to a remote Git server.
This is not meant for end users but for programs and scripts calling git
-fetch, push or archive.
+fetch, push, or archive.
If only <infd> is given, it is assumed to be a bidirectional socket connected
-to remote Git server (git-upload-pack, git-receive-pack or
+to a remote Git server (git-upload-pack, git-receive-pack, or
git-upload-archive). If both <infd> and <outfd> are given, they are assumed
to be pipes connected to a remote Git server (<infd> being the inbound pipe
-and <outfd> being the outbound pipe.
+and <outfd> being the outbound pipe).
It is assumed that any handshaking procedures have already been completed
(such as sending service request for git://) before this helper is started.
<anything> can be any string. It is ignored. It is meant for providing
-information to user in the URL in case that URL is displayed in some
+information to the user in the URL in case that URL is displayed in some
context.
ENVIRONMENT VARIABLES
@@ -45,7 +45,7 @@
`git push fd::7,8 master (as URL)`::
Push master, using file descriptor #7 to read data from
git-receive-pack and file descriptor #8 to write data to
- same service.
+ the same service.
`git push fd::7,8/bar master`::
Same as above.
diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt
index 1dec314..932a5c3 100644
--- a/Documentation/git-remote.txt
+++ b/Documentation/git-remote.txt
@@ -35,7 +35,7 @@
-v::
--verbose::
Be a little more verbose and show remote url after name.
- For promisor remotes, also show which filter (`blob:none` etc.)
+ For promisor remotes, also show which filters (`blob:none` etc.)
are configured.
NOTE: This must be placed between `remote` and subcommand.
diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt
index b63e8ab..c902512 100644
--- a/Documentation/git-repack.txt
+++ b/Documentation/git-repack.txt
@@ -74,6 +74,17 @@
immediately instead of waiting for the next `git gc` invocation.
Only useful with `--cruft -d`.
+--max-cruft-size=<n>::
+ Repack cruft objects into packs as large as `<n>` bytes before
+ creating new packs. As long as there are enough cruft packs
+ smaller than `<n>`, repacking will cause a new cruft pack to
+ be created containing objects from any combined cruft packs,
+ along with any new unreachable objects. Cruft packs larger than
+ `<n>` will not be modified. When the new cruft pack is larger
+ than `<n>` bytes, it will be split into multiple packs, all of
+ which are guaranteed to be at most `<n>` bytes in size. Only
+ useful with `--cruft -d`.
+
--expire-to=<dir>::
Write a cruft pack containing pruned objects (if any) to the
directory `<dir>`. This option is useful for keeping a copy of
@@ -143,6 +154,29 @@
a larger and slower repository; see the discussion in
`pack.packSizeLimit`.
+--filter=<filter-spec>::
+ Remove objects matching the filter specification from the
+ resulting packfile and put them into a separate packfile. Note
+ that objects used in the working directory are not filtered
+ out. So for the split to fully work, it's best to perform it
+ in a bare repo and to use the `-a` and `-d` options along with
+ this option. Also `--no-write-bitmap-index` (or the
+ `repack.writebitmaps` config option set to `false`) should be
+ used otherwise writing bitmap index will fail, as it supposes
+ a single packfile containing all the objects. See
+ linkgit:git-rev-list[1] for valid `<filter-spec>` forms.
+
+--filter-to=<dir>::
+ Write the pack containing filtered out objects to the
+ directory `<dir>`. Only useful with `--filter`. This can be
+ used for putting the pack on a separate object directory that
+ is accessed through the Git alternates mechanism. **WARNING:**
+ If the packfile containing the filtered out objects is not
+ accessible, the repo can become corrupt as it might not be
+ possible to access the objects in that packfile. See the
+ `objects` and `objects/info/alternates` sections of
+ linkgit:gitrepository-layout[5].
+
-b::
--write-bitmap-index::
Write a reachability bitmap index as part of the repack. This
@@ -165,7 +199,7 @@
Exclude the given pack from repacking. This is the equivalent
of having `.keep` file on the pack. `<pack-name>` is the
pack file name without leading directory (e.g. `pack-123.pack`).
- The option could be specified multiple times to keep multiple
+ The option can be specified multiple times to keep multiple
packs.
--unpack-unreachable=<when>::
diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt
index f271d75..0a65460 100644
--- a/Documentation/git-replace.txt
+++ b/Documentation/git-replace.txt
@@ -35,7 +35,7 @@
except those doing reachability traversal (prune, pack transfer and
fsck).
-It is possible to disable use of replacement references for any
+It is possible to disable the use of replacement references for any
command using the `--no-replace-objects` option just after 'git'.
For example if commit 'foo' has been replaced by commit 'bar':
@@ -111,14 +111,14 @@
FORMATS
-------
-The following format are available:
+The following formats are available:
* 'short':
- <replaced sha1>
+ <replaced-sha1>
* 'medium':
- <replaced sha1> -> <replacement sha1>
+ <replaced-sha1> -> <replacement-sha1>
* 'long':
- <replaced sha1> (<replaced type>) -> <replacement sha1> (<replacement type>)
+ <replaced-sha1> (<replaced-type>) -> <replacement-sha1> (<replacement-type>)
CREATING REPLACEMENT OBJECTS
----------------------------
diff --git a/Documentation/git-replay.txt b/Documentation/git-replay.txt
new file mode 100644
index 0000000..8f3300c
--- /dev/null
+++ b/Documentation/git-replay.txt
@@ -0,0 +1,127 @@
+git-replay(1)
+=============
+
+NAME
+----
+git-replay - EXPERIMENTAL: Replay commits on a new base, works with bare repos too
+
+
+SYNOPSIS
+--------
+[verse]
+(EXPERIMENTAL!) 'git replay' ([--contained] --onto <newbase> | --advance <branch>) <revision-range>...
+
+DESCRIPTION
+-----------
+
+Takes ranges of commits and replays them onto a new location. Leaves
+the working tree and the index untouched, and updates no references.
+The output of this command is meant to be used as input to
+`git update-ref --stdin`, which would update the relevant branches
+(see the OUTPUT section below).
+
+THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.
+
+OPTIONS
+-------
+
+--onto <newbase>::
+ Starting point at which to create the new commits. May be any
+ valid commit, and not just an existing branch name.
++
+When `--onto` is specified, the update-ref command(s) in the output will
+update the branch(es) in the revision range to point at the new
+commits, similar to the way how `git rebase --update-refs` updates
+multiple branches in the affected range.
+
+--advance <branch>::
+ Starting point at which to create the new commits; must be a
+ branch name.
++
+When `--advance` is specified, the update-ref command(s) in the output
+will update the branch passed as an argument to `--advance` to point at
+the new commits (in other words, this mimics a cherry-pick operation).
+
+<revision-range>::
+ Range of commits to replay. More than one <revision-range> can
+ be passed, but in `--advance <branch>` mode, they should have
+ a single tip, so that it's clear where <branch> should point
+ to. See "Specifying Ranges" in linkgit:git-rev-parse[1] and the
+ "Commit Limiting" options below.
+
+include::rev-list-options.txt[]
+
+OUTPUT
+------
+
+When there are no conflicts, the output of this command is usable as
+input to `git update-ref --stdin`. It is of the form:
+
+ update refs/heads/branch1 ${NEW_branch1_HASH} ${OLD_branch1_HASH}
+ update refs/heads/branch2 ${NEW_branch2_HASH} ${OLD_branch2_HASH}
+ update refs/heads/branch3 ${NEW_branch3_HASH} ${OLD_branch3_HASH}
+
+where the number of refs updated depends on the arguments passed and
+the shape of the history being replayed. When using `--advance`, the
+number of refs updated is always one, but for `--onto`, it can be one
+or more (rebasing multiple branches simultaneously is supported).
+
+EXIT STATUS
+-----------
+
+For a successful, non-conflicted replay, the exit status is 0. When
+the replay has conflicts, the exit status is 1. If the replay is not
+able to complete (or start) due to some kind of error, the exit status
+is something other than 0 or 1.
+
+EXAMPLES
+--------
+
+To simply rebase `mybranch` onto `target`:
+
+------------
+$ git replay --onto target origin/main..mybranch
+update refs/heads/mybranch ${NEW_mybranch_HASH} ${OLD_mybranch_HASH}
+------------
+
+To cherry-pick the commits from mybranch onto target:
+
+------------
+$ git replay --advance target origin/main..mybranch
+update refs/heads/target ${NEW_target_HASH} ${OLD_target_HASH}
+------------
+
+Note that the first two examples replay the exact same commits and on
+top of the exact same new base, they only differ in that the first
+provides instructions to make mybranch point at the new commits and
+the second provides instructions to make target point at them.
+
+What if you have a stack of branches, one depending upon another, and
+you'd really like to rebase the whole set?
+
+------------
+$ git replay --contained --onto origin/main origin/main..tipbranch
+update refs/heads/branch1 ${NEW_branch1_HASH} ${OLD_branch1_HASH}
+update refs/heads/branch2 ${NEW_branch2_HASH} ${OLD_branch2_HASH}
+update refs/heads/tipbranch ${NEW_tipbranch_HASH} ${OLD_tipbranch_HASH}
+------------
+
+When calling `git replay`, one does not need to specify a range of
+commits to replay using the syntax `A..B`; any range expression will
+do:
+
+------------
+$ git replay --onto origin/main ^base branch1 branch2 branch3
+update refs/heads/branch1 ${NEW_branch1_HASH} ${OLD_branch1_HASH}
+update refs/heads/branch2 ${NEW_branch2_HASH} ${OLD_branch2_HASH}
+update refs/heads/branch3 ${NEW_branch3_HASH} ${OLD_branch3_HASH}
+------------
+
+This will simultaneously rebase `branch1`, `branch2`, and `branch3`,
+all commits they have since `base`, playing them on top of
+`origin/main`. These three branches may have commits on top of `base`
+that they have in common, but that does not need to be the case.
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/git-request-pull.txt b/Documentation/git-request-pull.txt
index fa5a426..15dcbb6 100644
--- a/Documentation/git-request-pull.txt
+++ b/Documentation/git-request-pull.txt
@@ -16,7 +16,7 @@
Generate a request asking your upstream project to pull changes into
their tree. The request, printed to the standard output,
begins with the branch description, summarizes
-the changes and indicates from where they can be pulled.
+the changes, and indicates from where they can be pulled.
The upstream project is expected to have the commit named by
`<start>` and the output asks it to integrate the changes you made
@@ -50,7 +50,7 @@
--------
Imagine that you built your work on your `master` branch on top of
-the `v1.0` release, and want it to be integrated to the project.
+the `v1.0` release, and want it to be integrated into the project.
First you push that change to your public repository for others to
see:
diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt
index 5964810..975825b 100644
--- a/Documentation/git-restore.txt
+++ b/Documentation/git-restore.txt
@@ -78,6 +78,8 @@
--theirs::
When restoring files in the working tree from the index, use
stage #2 ('ours') or #3 ('theirs') for unmerged paths.
+ This option cannot be used when checking out paths from a
+ tree-ish (i.e. with the `--source` option).
+
Note that during `git rebase` and `git pull --rebase`, 'ours' and
'theirs' may appear swapped. See the explanation of the same options
@@ -87,6 +89,8 @@
--merge::
When restoring files on the working tree from the index,
recreate the conflicted merge in the unmerged paths.
+ This option cannot be used when checking out paths from a
+ tree-ish (i.e. with the `--source` option).
--conflict=<style>::
The same as `--merge` option above, but changes the way the
@@ -101,7 +105,7 @@
specified. Unmerged paths on the working tree are left alone.
--ignore-skip-worktree-bits::
- In sparse checkout mode, by default is to only update entries
+ In sparse checkout mode, the default is to only update entries
matched by `<pathspec>` and sparse patterns in
$GIT_DIR/info/sparse-checkout. This option ignores the sparse
patterns and unconditionally restores any files in
@@ -195,7 +199,7 @@
$ git restore --staged hello.c
------------
-or you can restore both the index and the working tree (this the same
+or you can restore both the index and the working tree (this is the same
as using linkgit:git-checkout[1])
------------
diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt
index 51029a2..2e05c4b 100644
--- a/Documentation/git-rev-list.txt
+++ b/Documentation/git-rev-list.txt
@@ -17,9 +17,9 @@
:git-rev-list: 1
include::rev-list-description.txt[]
-'rev-list' is a very essential Git command, since it
+'rev-list' is an essential Git command, since it
provides the ability to build and traverse commit ancestry graphs. For
-this reason, it has a lot of different options that enables it to be
+this reason, it has a lot of different options that enable it to be
used by commands as different as 'git bisect' and
'git repack'.
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index f26a759..dc12d38 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -9,17 +9,24 @@
SYNOPSIS
--------
[verse]
-'git rev-parse' [<options>] <args>...
+'git rev-parse' [<options>] <arg>...
DESCRIPTION
-----------
-Many Git porcelainish commands take mixture of flags
+Many Git porcelainish commands take a mixture of flags
(i.e. parameters that begin with a dash '-') and parameters
meant for the underlying 'git rev-list' command they use internally
and flags and parameters for the other commands they use
-downstream of 'git rev-list'. This command is used to
-distinguish between them.
+downstream of 'git rev-list'. The primary purpose of this command
+is to allow calling programs to distinguish between them. There are
+a few other operation modes that have nothing to do with the above
+"help parse command line options".
+
+Unless otherwise specified, most of the options and operation modes
+require you to run this command inside a git repository or a working
+tree that is under the control of a git repository, and will give you
+a fatal error otherwise.
OPTIONS
@@ -32,11 +39,15 @@
--parseopt::
Use 'git rev-parse' in option parsing mode (see PARSEOPT section below).
+ The command in this mode can be used outside a repository or
+ a working tree controlled by a repository.
--sq-quote::
Use 'git rev-parse' in shell quoting mode (see SQ-QUOTE
section below). In contrast to the `--sq` option below, this
- mode does only quoting. Nothing else is done to command input.
+ mode only does quoting. Nothing else is done to command input.
+ The command in this mode can be used outside a repository or
+ a working tree controlled by a repository.
Options for --parseopt
~~~~~~~~~~~~~~~~~~~~~~
@@ -130,7 +141,7 @@
'git diff-{asterisk}'). In contrast to the `--sq-quote` option,
the command input is still interpreted as usual.
---short[=length]::
+--short[=<length>]::
Same as `--verify` but shortens the object name to a unique
prefix with at least `length` characters. The minimum length
is 4, the default is the effective value of the `core.abbrev`
@@ -156,18 +167,30 @@
are not refs (i.e. branch or tag names; or more
explicitly disambiguating "heads/master" form, when you
want to name the "master" branch when there is an
- unfortunately named tag "master"), and show them as full
+ unfortunately named tag "master"), and shows them as full
refnames (e.g. "refs/heads/master").
+--output-object-format=(sha1|sha256|storage)::
+
+ Allow oids to be input from any object format that the current
+ repository supports.
+
+ Specifying "sha1" translates if necessary and returns a sha1 oid.
+
+ Specifying "sha256" translates if necessary and returns a sha256 oid.
+
+ Specifying "storage" translates if necessary and returns an oid in
+ encoded in the storage hash algorithm.
+
Options for Objects
~~~~~~~~~~~~~~~~~~~
--all::
Show all refs found in `refs/`.
---branches[=pattern]::
---tags[=pattern]::
---remotes[=pattern]::
+--branches[=<pattern>]::
+--tags[=<pattern>]::
+--remotes[=<pattern>]::
Show all branches, tags, or remote-tracking branches,
respectively (i.e., refs found in `refs/heads`,
`refs/tags`, or `refs/remotes`, respectively).
@@ -176,7 +199,7 @@
shown. If the pattern does not contain a globbing character (`?`,
`*`, or `[`), it is turned into a prefix match by appending `/*`.
---glob=pattern::
+--glob=<pattern>::
Show all refs matching the shell glob pattern `pattern`. If
the pattern does not start with `refs/`, this is automatically
prepended. If the pattern does not contain a globbing
@@ -197,7 +220,7 @@
or `--all`. If a trailing '/{asterisk}' is intended, it must be given
explicitly.
---exclude-hidden=[fetch|receive|uploadpack]::
+--exclude-hidden=(fetch|receive|uploadpack)::
Do not include refs that would be hidden by `git-fetch`,
`git-receive-pack` or `git-upload-pack` by consulting the appropriate
`fetch.hideRefs`, `receive.hideRefs` or `uploadpack.hideRefs`
@@ -307,21 +330,24 @@
input, multiple algorithms may be printed, space-separated.
If not specified, the default is "storage".
+--show-ref-format::
+ Show the reference storage format used for the repository.
+
Other Options
~~~~~~~~~~~~~
---since=datestring::
---after=datestring::
+--since=<datestring>::
+--after=<datestring>::
Parse the date string, and output the corresponding
--max-age= parameter for 'git rev-list'.
---until=datestring::
---before=datestring::
+--until=<datestring>::
+--before=<datestring>::
Parse the date string, and output the corresponding
--min-age= parameter for 'git rev-list'.
-<args>...::
+<arg>...::
Flags and parameters to be parsed.
@@ -383,7 +409,7 @@
dash to separate words in a multi-word argument hint.
The remainder of the line, after stripping the spaces, is used
-as the help associated to the option.
+as the help associated with the option.
Blank lines are ignored, and lines that don't match this specification are used
as option group headers (start the line with a space to create such
@@ -398,7 +424,7 @@
some-command does foo and bar!
--
-h,help show the help
+h,help! show the help
foo some nifty option --foo
bar= some cool option --bar with an argument
@@ -424,10 +450,10 @@
some-command does foo and bar!
-h, --help show the help
- --foo some nifty option --foo
- --bar ... some cool option --bar with an argument
- --baz <arg> another cool option --baz with a named argument
- --qux[=<path>] qux may take a path argument but has meaning by itself
+ --[no-]foo some nifty option --foo
+ --[no-]bar ... some cool option --bar with an argument
+ --[no-]baz <arg> another cool option --baz with a named argument
+ --[no-]qux[=<path>] qux may take a path argument but has meaning by itself
An option group Header
-C[...] option C with an optional argument
diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt
index d2e10d3..568925d 100644
--- a/Documentation/git-revert.txt
+++ b/Documentation/git-revert.txt
@@ -116,7 +116,7 @@
--reference::
Instead of starting the body of the log message with "This
- reverts <full object name of the commit being reverted>.",
+ reverts <full-object-name-of-the-commit-being-reverted>.",
refer to the commit using "--pretty=reference" format
(cf. linkgit:git-log[1]). The `revert.reference`
configuration variable can be used to enable this option by
@@ -142,6 +142,16 @@
changes. The revert only modifies the working tree and the
index.
+DISCUSSION
+----------
+
+While git creates a basic commit message automatically, it is
+_strongly_ recommended to explain why the original commit is being
+reverted.
+In addition, repeatedly reverting reverts will result in increasingly
+unwieldy subject lines, for example 'Reapply "Reapply "<original-subject>""'.
+Please consider rewording these to be shorter and more unique.
+
CONFIGURATION
-------------
diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt
index 81bc23f..363a269 100644
--- a/Documentation/git-rm.txt
+++ b/Documentation/git-rm.txt
@@ -163,7 +163,7 @@
A submodule is considered up to date when the HEAD is the same as
recorded in the index, no tracked files are modified and no untracked
-files that aren't ignored are present in the submodules work tree.
+files that aren't ignored are present in the submodule's work tree.
Ignored files are deemed expendable and won't stop a submodule's work
tree from being removed.
diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index 492a823..c5d664f 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -9,8 +9,8 @@
SYNOPSIS
--------
[verse]
-'git send-email' [<options>] <file|directory>...
-'git send-email' [<options>] <format-patch options>
+'git send-email' [<options>] (<file>|<directory>)...
+'git send-email' [<options>] <format-patch-options>
'git send-email' --dump-aliases
@@ -68,11 +68,12 @@
Invoke a text editor (see GIT_EDITOR in linkgit:git-var[1])
to edit an introductory message for the patch series.
+
-When `--compose` is used, git send-email will use the From, Subject, and
-In-Reply-To headers specified in the message. If the body of the message
-(what you type after the headers and a blank line) only contains blank
-(or Git: prefixed) lines, the summary won't be sent, but From, Subject,
-and In-Reply-To headers will be used unless they are removed.
+When `--compose` is used, git send-email will use the From, To, Cc, Bcc,
+Subject, Reply-To, and In-Reply-To headers specified in the message. If
+the body of the message (what you type after the headers and a blank
+line) only contains blank (or Git: prefixed) lines, the summary won't be
+sent, but the headers mentioned above will be used unless they are
+removed.
+
Missing From or In-Reply-To headers will be prompted for.
+
@@ -137,7 +138,7 @@
--compose-encoding=<encoding>::
Specify encoding of compose message. Default is the value of the
- 'sendemail.composeencoding'; if that is unspecified, UTF-8 is assumed.
+ 'sendemail.composeEncoding'; if that is unspecified, UTF-8 is assumed.
--transfer-encoding=(7bit|8bit|quoted-printable|base64|auto)::
Specify the transfer encoding to be used to send the message over SMTP.
@@ -173,7 +174,7 @@
Specify a command to run to send the email. The command should
be sendmail-like; specifically, it must support the `-i` option.
The command will be executed in the shell if necessary. Default
- is the value of `sendemail.sendmailcmd`. If unspecified, and if
+ is the value of `sendemail.sendmailCmd`. If unspecified, and if
--smtp-server is also unspecified, git-send-email will search
for `sendmail` in `/usr/sbin`, `/usr/lib` and $PATH.
@@ -268,7 +269,7 @@
certificates concatenated together: see verify(1) -CAfile and
-CApath for more information on these). Set it to an empty string
to disable certificate verification. Defaults to the value of the
- `sendemail.smtpsslcertpath` configuration variable, if set, or the
+ `sendemail.smtpSSLCertPath` configuration variable, if set, or the
backing SSL library's compiled-in default otherwise (which should
be the best choice on most platforms).
@@ -277,7 +278,7 @@
if a username is not specified (with `--smtp-user` or `sendemail.smtpUser`),
then authentication is not attempted.
---smtp-debug=0|1::
+--smtp-debug=(0|1)::
Enable (1) or disable (0) debug output. If enabled, SMTP
commands and replies will be printed. Useful to debug TLS
connection and authentication problems.
@@ -300,7 +301,9 @@
Automating
~~~~~~~~~~
---no-[to|cc|bcc]::
+--no-to::
+--no-cc::
+--no-bcc::
Clears any list of "To:", "Cc:", "Bcc:" addresses previously
set via config.
@@ -312,7 +315,7 @@
Specify a command to execute once per patch file which
should generate patch file specific "To:" entries.
Output of this command must be single email address per line.
- Default is the value of 'sendemail.tocmd' configuration value.
+ Default is the value of 'sendemail.toCmd' configuration value.
--cc-cmd=<command>::
Specify a command to execute once per patch file which
@@ -347,19 +350,19 @@
--[no-]signed-off-by-cc::
If this is set, add emails found in the `Signed-off-by` trailer or Cc: lines to the
- cc list. Default is the value of `sendemail.signedoffbycc` configuration
+ cc list. Default is the value of `sendemail.signedOffByCc` configuration
value; if that is unspecified, default to --signed-off-by-cc.
--[no-]cc-cover::
If this is set, emails found in Cc: headers in the first patch of
the series (typically the cover letter) are added to the cc list
- for each email set. Default is the value of 'sendemail.cccover'
+ for each email set. Default is the value of 'sendemail.ccCover'
configuration value; if that is unspecified, default to --no-cc-cover.
--[no-]to-cover::
If this is set, emails found in To: headers in the first patch of
the series (typically the cover letter) are added to the to list
- for each email set. Default is the value of 'sendemail.tocover'
+ for each email set. Default is the value of 'sendemail.toCover'
configuration value; if that is unspecified, default to --no-to-cover.
--suppress-cc=<category>::
@@ -383,7 +386,7 @@
- 'all' will suppress all auto cc values.
--
+
-Default is the value of `sendemail.suppresscc` configuration value; if
+Default is the value of `sendemail.suppressCc` configuration value; if
that is unspecified, default to 'self' if --suppress-from is
specified, as well as 'body' if --no-signed-off-cc is specified.
@@ -453,7 +456,7 @@
998 characters unless a suitable transfer encoding
('auto', 'base64', or 'quoted-printable') is used;
this is due to SMTP limits as described by
- http://www.ietf.org/rfc/rfc5322.txt.
+ https://www.ietf.org/rfc/rfc5322.txt.
--
+
Default is the value of `sendemail.validate`; if this is not set,
@@ -468,9 +471,9 @@
--dump-aliases::
Instead of the normal operation, dump the shorthand alias names from
- the configured alias file(s), one per line in alphabetical order. Note,
- this only includes the alias name and not its expanded email addresses.
- See 'sendemail.aliasesfile' for more information about aliases.
+ the configured alias file(s), one per line in alphabetical order. Note
+ that this only includes the alias name and not its expanded email addresses.
+ See 'sendemail.aliasesFile' for more information about aliases.
CONFIGURATION
diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt
index 595b002..b9e73f2 100644
--- a/Documentation/git-send-pack.txt
+++ b/Documentation/git-send-pack.txt
@@ -55,7 +55,7 @@
--force::
Usually, the command refuses to update a remote ref that
is not an ancestor of the local ref used to overwrite it.
- This flag disables the check. What this means is that
+ This flag disables the check. This means that
the remote repository can lose commits; use it with
care.
@@ -106,7 +106,7 @@
There are three ways to specify which refs to update on the
remote end.
-With `--all` flag, all refs that exist locally are transferred to
+With the `--all` flag, all refs that exist locally are transferred to
the remote side. You cannot specify any '<ref>' if you use
this flag.
@@ -115,9 +115,9 @@
When one or more '<ref>' are specified explicitly (whether on the
command line or via `--stdin`), it can be either a
-single pattern, or a pair of such pattern separated by a colon
+single pattern, or a pair of such patterns separated by a colon
":" (this means that a ref name cannot have a colon in it). A
-single pattern '<name>' is just a shorthand for '<name>:<name>'.
+single pattern '<name>' is just shorthand for '<name>:<name>'.
Each pattern pair consists of the source side (before the colon)
and the destination side (after the colon). The ref to be
@@ -130,7 +130,7 @@
- It is an error if <src> does not match exactly one of the
local refs.
- - It is an error if <dst> matches more than one remote refs.
+ - It is an error if <dst> matches more than one remote ref.
- If <dst> does not match any remote ref, either
@@ -143,9 +143,9 @@
Without `--force`, the <src> ref is stored at the remote only if
<dst> does not exist, or <dst> is a proper subset (i.e. an
-ancestor) of <src>. This check, known as "fast-forward check",
-is performed in order to avoid accidentally overwriting the
-remote ref and lose other peoples' commits from there.
+ancestor) of <src>. This check, known as the "fast-forward check",
+is performed to avoid accidentally overwriting the
+remote ref and losing other people's commits from there.
With `--force`, the fast-forward check is disabled for all refs.
diff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt
index 8632612..bdaf6e5 100644
--- a/Documentation/git-sh-setup.txt
+++ b/Documentation/git-sh-setup.txt
@@ -22,7 +22,7 @@
the normal Git directories and a few helper shell functions.
Before sourcing it, your script should set up a few variables;
-`USAGE` (and `LONG_USAGE`, if any) is used to define message
+`USAGE` (and `LONG_USAGE`, if any) is used to define the message
given by `usage()` shell function. `SUBDIRECTORY_OK` can be set
if the script can run from a subdirectory of the working tree
(some commands do not).
diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt
index 58cf621..c771c89 100644
--- a/Documentation/git-show-branch.txt
+++ b/Documentation/git-show-branch.txt
@@ -50,7 +50,7 @@
--current::
With this option, the command includes the current
- branch to the list of revs to be shown when it is not
+ branch in the list of revs to be shown when it is not
given on the command line.
--topo-order::
@@ -125,7 +125,7 @@
default to color output.
Same as `--color=never`.
-Note that --more, --list, --independent and --merge-base options
+Note that --more, --list, --independent, and --merge-base options
are mutually exclusive.
@@ -137,14 +137,14 @@
$GIT_DIR/HEAD is prefixed with an asterisk `*` character while other
heads are prefixed with a `!` character.
-Following these N lines, one-line log for each commit is
+Following these N lines, a one-line log for each commit is
displayed, indented N places. If a commit is on the I-th
branch, the I-th indentation character shows a `+` sign;
otherwise it shows a space. Merge commits are denoted by
a `-` sign. Each commit shows a short name that
can be used as an extended SHA-1 to name that commit.
-The following example shows three branches, "master", "fixes"
+The following example shows three branches, "master", "fixes",
and "mhf":
------------------------------------------------
@@ -154,7 +154,7 @@
! [mhf] Allow "+remote:local" refspec to cause --force when fetching.
---
+ [mhf] Allow "+remote:local" refspec to cause --force when fetching.
- + [mhf~1] Use git-octopus when pulling more than one heads.
+ + [mhf~1] Use git-octopus when pulling more than one head.
+ [fixes] Introduce "reset type" flag to "git reset"
+ [mhf~2] "git fetch --force".
+ [mhf~3] Use .git/remote/origin, not .git/branches/origin.
@@ -197,7 +197,7 @@
shows 10 reflog entries going back from the tip as of 1 hour ago.
Without `--list`, the output also shows how these tips are
-topologically related with each other.
+topologically related to each other.
CONFIGURATION
-------------
diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt
index 2fe274b..ba75747 100644
--- a/Documentation/git-show-ref.txt
+++ b/Documentation/git-show-ref.txt
@@ -8,10 +8,14 @@
SYNOPSIS
--------
[verse]
-'git show-ref' [-q | --quiet] [--verify] [--head] [-d | --dereference]
+'git show-ref' [--head] [-d | --dereference]
[-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags]
[--heads] [--] [<pattern>...]
+'git show-ref' --verify [-q | --quiet] [-d | --dereference]
+ [-s | --hash[=<n>]] [--abbrev[=<n>]]
+ [--] [<ref>...]
'git show-ref' --exclude-existing[=<pattern>]
+'git show-ref' --exists <ref>
DESCRIPTION
-----------
@@ -27,6 +31,10 @@
refs from stdin, one ref per line, and shows those that don't exist in
the local repository.
+The `--exists` form can be used to check for the existence of a single
+references. This form does not verify whether the reference resolves to an
+actual object.
+
Use of this utility is encouraged in favor of directly accessing files under
the `.git` directory.
@@ -62,6 +70,12 @@
Aside from returning an error code of 1, it will also print an error
message if `--quiet` was not specified.
+--exists::
+
+ Check whether the given reference exists. Returns an exit code of 0 if
+ it does, 2 if it is missing, and 1 in case looking up the reference
+ failed with an error other than the reference being missing.
+
--abbrev[=<n>]::
Abbreviate the object name. When using `--hash`, you do
@@ -70,8 +84,8 @@
-q::
--quiet::
- Do not print any results to stdout. When combined with `--verify`, this
- can be used to silently check if a reference exists.
+ Do not print any results to stdout. Can be used with `--verify` to
+ silently check if a reference exists.
--exclude-existing[=<pattern>]::
@@ -144,7 +158,7 @@
-----------------------------------------------------------------------------
This will show "refs/heads/master" but also "refs/remote/other-repo/master",
-if such references exists.
+if such references exist.
When using the `--verify` flag, the command requires an exact path:
diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt
index 03c0634..5eb6743 100644
--- a/Documentation/git-show.txt
+++ b/Documentation/git-show.txt
@@ -61,7 +61,7 @@
--------
`git show v1.0.0`::
- Shows the tag `v1.0.0`, along with the object the tags
+ Shows the tag `v1.0.0`, along with the object the tag
points at.
`git show v1.0.0^{tree}`::
diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index a051b1e..9a37688 100644
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -79,6 +79,8 @@
`git update-index --untracked-cache` and `git update-index
--split-index`), Otherwise you can use `no` to have `git status`
return more quickly without showing untracked files.
+All usual spellings for Boolean value `true` are taken as `normal`
+and `false` as `no`.
The default can be changed using the status.showUntrackedFiles
configuration variable documented in linkgit:git-config[1].
@@ -245,11 +247,12 @@
....
Submodules have more state and instead report
- M the submodule has a different HEAD than
- recorded in the index
- m the submodule has modified content
- ? the submodule has untracked files
-since modified content or untracked files in a submodule cannot be added
+
+* 'M' = the submodule has a different HEAD than recorded in the index
+* 'm' = the submodule has modified content
+* '?' = the submodule has untracked files
+
+This is since modified content or untracked files in a submodule cannot be added
via `git add` in the superproject to prepare a commit.
'm' and '?' are applied recursively. For example if a nested submodule
@@ -308,7 +311,7 @@
------------------------------------------------------------
# branch.oid <commit> | (initial) Current commit.
# branch.head <branch> | (detached) Current branch.
-# branch.upstream <upstream_branch> If upstream is set.
+# branch.upstream <upstream-branch> If upstream is set.
# branch.ab +<ahead> -<behind> If upstream is set and
the commit is present.
------------------------------------------------------------
@@ -471,7 +474,7 @@
results, so it could be faster on subsequent runs.
* The `--untracked-files=no` flag or the
- `status.showUntrackedfiles=false` config (see above for both):
+ `status.showUntrackedFiles=no` config (see above for both):
indicate that `git status` should not report untracked
files. This is the fastest option. `git status` will not list
the untracked files, so you need to be careful to remember if
@@ -501,7 +504,7 @@
usually worth the additional size.
* `core.untrackedCache=true` and `core.fsmonitor=true` or
- `core.fsmonitor=<hook_command_pathname>` (see
+ `core.fsmonitor=<hook-command-pathname>` (see
linkgit:git-update-index[1]): enable both the untracked cache
and FSMonitor features and only search directories that have
been modified since the previous `git status` command. This
diff --git a/Documentation/git-stripspace.txt b/Documentation/git-stripspace.txt
index 2438f76..a293327 100644
--- a/Documentation/git-stripspace.txt
+++ b/Documentation/git-stripspace.txt
@@ -29,7 +29,7 @@
In the case where the input consists entirely of whitespace characters, no
output will be produced.
-*NOTE*: This is intended for cleaning metadata, prefer the `--whitespace=fix`
+*NOTE*: This is intended for cleaning metadata. Prefer the `--whitespace=fix`
mode of linkgit:git-apply[1] for correcting whitespace of patches or files in
the repository.
@@ -37,11 +37,11 @@
-------
-s::
--strip-comments::
- Skip and remove all lines starting with comment character (default '#').
+ Skip and remove all lines starting with a comment character (default '#').
-c::
--comment-lines::
- Prepend comment character and blank to each line. Lines will automatically
+ Prepend the comment character and a blank space to each line. Lines will automatically
be terminated with a newline. On empty lines, only the comment character
will be prepended.
diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 6957306..ca0347a 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -136,7 +136,7 @@
that use linkgit:git-rm[1] instead. See linkgit:gitsubmodules[7] for removal
options.
-update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--depth <depth>] [--recursive] [--jobs <n>] [--[no-]single-branch] [--filter <filter spec>] [--] [<path>...]::
+update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--depth <depth>] [--recursive] [--jobs <n>] [--[no-]single-branch] [--filter <filter-spec>] [--] [<path>...]::
+
--
Update the registered submodules to match what the superproject
@@ -185,7 +185,7 @@
If `--recursive` is specified, this command will recurse into the
registered submodules, and update any nested submodules within.
-If `--filter <filter spec>` is specified, the given partial clone filter will be
+If `--filter <filter-spec>` is specified, the given partial clone filter will be
applied to the submodule. See linkgit:git-rev-list[1] for details on filter
specifications.
--
diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 4e92308..43c68c2 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -37,12 +37,12 @@
argument. Normally this command initializes the current
directory.
--T<trunk_subdir>;;
---trunk=<trunk_subdir>;;
--t<tags_subdir>;;
---tags=<tags_subdir>;;
--b<branches_subdir>;;
---branches=<branches_subdir>;;
+-T<trunk-subdir>;;
+--trunk=<trunk-subdir>;;
+-t<tags-subdir>;;
+--tags=<tags-subdir>;;
+-b<branches-subdir>;;
+--branches=<branches-subdir>;;
-s;;
--stdlayout;;
These are optional command-line options for init. Each of
@@ -726,9 +726,9 @@
when tracking a single URL. The 'log' and 'dcommit' commands
no longer require this switch as an argument.
--R<remote name>::
---svn-remote <remote name>::
- Specify the [svn-remote "<remote name>"] section to use,
+-R<remote-name>::
+--svn-remote <remote-name>::
+ Specify the [svn-remote "<remote-name>"] section to use,
this allows SVN multiple repositories to be tracked.
Default: "svn"
diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt
index c60fc9c..f38e4c8 100644
--- a/Documentation/git-switch.txt
+++ b/Documentation/git-switch.txt
@@ -59,13 +59,18 @@
-c <new-branch>::
--create <new-branch>::
Create a new branch named `<new-branch>` starting at
- `<start-point>` before switching to the branch. This is a
- convenient shortcut for:
+ `<start-point>` before switching to the branch. This is the
+ transactional equivalent of
+
------------
$ git branch <new-branch>
$ git switch <new-branch>
------------
++
+that is to say, the branch is not reset/created unless "git switch" is
+successful (e.g., when the branch is in use in another worktree, not
+just the current branch stays the same, but the branch is not reset to
+the start-point, either).
-C <new-branch>::
--force-create <new-branch>::
@@ -171,7 +176,7 @@
`branch.autoSetupMerge` configuration variable is true.
--orphan <new-branch>::
- Create a new 'orphan' branch, named `<new-branch>`. All
+ Create a new unborn branch, named `<new-branch>`. All
tracked files are removed.
--ignore-other-worktrees::
diff --git a/Documentation/git-symbolic-ref.txt b/Documentation/git-symbolic-ref.txt
index 102c83e..761b154 100644
--- a/Documentation/git-symbolic-ref.txt
+++ b/Documentation/git-symbolic-ref.txt
@@ -27,7 +27,7 @@
A symbolic ref is a regular file that stores a string that
begins with `ref: refs/`. For example, your `.git/HEAD` is
-a regular file whose contents is `ref: refs/heads/master`.
+a regular file whose content is `ref: refs/heads/master`.
OPTIONS
-------
diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index d42efb3..5fe519c 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -224,7 +224,7 @@
-------------------------------------
[user]
- signingKey = <gpg-key_id>
+ signingKey = <gpg-key-id>
-------------------------------------
`pager.tag` is only respected when listing tags, i.e., when `-l` is
diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
index f4bb9c5..7128aed 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -25,6 +25,7 @@
[--really-refresh] [--unresolve] [--again | -g]
[--info-only] [--index-info]
[-z] [--stdin] [--index-version <n>]
+ [--show-index-version]
[--verbose]
[--] [<file>...]
@@ -49,7 +50,7 @@
--remove::
If a specified file is in the index but is missing then it's
removed.
- Default behavior is to ignore removed file.
+ Default behavior is to ignore removed files.
--refresh::
Looks at the current index and checks to see if merges or
@@ -95,7 +96,7 @@
the index. If you want to change the working tree file,
you need to unset the bit to tell Git. This is
sometimes helpful when working with a big project on a
- filesystem that has very slow lstat(2) system call
+ filesystem that has a very slow lstat(2) system call
(e.g. cifs).
+
Git will fail (gracefully) in case it needs to modify this file
@@ -108,7 +109,7 @@
without regard to the "assume unchanged" setting.
--[no-]skip-worktree::
- When one of these flags is specified, the object name recorded
+ When one of these flags is specified, the object names recorded
for the paths are not updated. Instead, these options
set and unset the "skip-worktree" bit for the paths. See
section "Skip-worktree bit" below for more information.
@@ -119,7 +120,7 @@
the `--remove` option was specified.
--[no-]fsmonitor-valid::
- When one of these flags is specified, the object name recorded
+ When one of these flags is specified, the object names recorded
for the paths are not updated. Instead, these options
set and unset the "fsmonitor valid" bit for the paths. See
section "File System Monitor" below for more information.
@@ -127,7 +128,7 @@
-g::
--again::
Runs 'git update-index' itself on the paths whose index
- entries are different from those from the `HEAD` commit.
+ entries are different from those of the `HEAD` commit.
--unresolve::
Restores the 'unmerged' or 'needs updating' state of a
@@ -151,24 +152,30 @@
automatically removed with warning messages.
--stdin::
- Instead of taking list of paths from the command line,
- read list of paths from the standard input. Paths are
+ Instead of taking a list of paths from the command line,
+ read a list of paths from the standard input. Paths are
separated by LF (i.e. one path per line) by default.
--verbose::
- Report what is being added and removed from index.
+ Report what is being added and removed from the index.
--index-version <n>::
Write the resulting index out in the named on-disk format version.
- Supported versions are 2, 3 and 4. The current default version is 2
+ Supported versions are 2, 3, and 4. The current default version is 2
or 3, depending on whether extra features are used, such as
- `git add -N`.
+ `git add -N`. With `--verbose`, also report the version the index
+ file uses before and after this command.
+
Version 4 performs a simple pathname compression that reduces index
size by 30%-50% on large repositories, which results in faster load
-time. Version 4 is relatively young (first released in 1.8.0 in
-October 2012). Other Git implementations such as JGit and libgit2
-may not support it yet.
+time. Git supports it since version 1.8.0, released in October 2012,
+and support for it was added to libgit2 in 2016 and to JGit in 2020.
+Older versions of this manual page called it "relatively young", but
+it should be considered mature technology these days.
+
+--show-index-version::
+ Report the index format version used by the on-disk index file.
+ See `--index-version` above.
-z::
Only meaningful with `--stdin` or `--index-info`; paths are
diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt
index 48b6683..374a2eb 100644
--- a/Documentation/git-update-ref.txt
+++ b/Documentation/git-update-ref.txt
@@ -8,21 +8,21 @@
SYNOPSIS
--------
[verse]
-'git update-ref' [-m <reason>] [--no-deref] (-d <ref> [<oldvalue>] | [--create-reflog] <ref> <newvalue> [<oldvalue>] | --stdin [-z])
+'git update-ref' [-m <reason>] [--no-deref] (-d <ref> [<old-oid>] | [--create-reflog] <ref> <new-oid> [<old-oid>] | --stdin [-z])
DESCRIPTION
-----------
-Given two arguments, stores the <newvalue> in the <ref>, possibly
+Given two arguments, stores the <new-oid> in the <ref>, possibly
dereferencing the symbolic refs. E.g. `git update-ref HEAD
-<newvalue>` updates the current branch head to the new object.
+<new-oid>` updates the current branch head to the new object.
-Given three arguments, stores the <newvalue> in the <ref>,
+Given three arguments, stores the <new-oid> in the <ref>,
possibly dereferencing the symbolic refs, after verifying that
-the current value of the <ref> matches <oldvalue>.
-E.g. `git update-ref refs/heads/master <newvalue> <oldvalue>`
-updates the master branch head to <newvalue> only if its current
-value is <oldvalue>. You can specify 40 "0" or an empty string
-as <oldvalue> to make sure that the ref you are creating does
+the current value of the <ref> matches <old-oid>.
+E.g. `git update-ref refs/heads/master <new-oid> <old-oid>`
+updates the master branch head to <new-oid> only if its current
+value is <old-oid>. You can specify 40 "0" or an empty string
+as <old-oid> to make sure that the ref you are creating does
not exist.
It also allows a "ref" file to be a symbolic pointer to another
@@ -56,15 +56,15 @@
archive by creating a symlink tree).
With `-d` flag, it deletes the named <ref> after verifying it
-still contains <oldvalue>.
+still contains <old-oid>.
With `--stdin`, update-ref reads instructions from standard input and
performs all modifications together. Specify commands of the form:
- update SP <ref> SP <newvalue> [SP <oldvalue>] LF
- create SP <ref> SP <newvalue> LF
- delete SP <ref> [SP <oldvalue>] LF
- verify SP <ref> [SP <oldvalue>] LF
+ update SP <ref> SP <new-oid> [SP <old-oid>] LF
+ create SP <ref> SP <new-oid> LF
+ delete SP <ref> [SP <old-oid>] LF
+ verify SP <ref> [SP <old-oid>] LF
option SP <opt> LF
start LF
prepare LF
@@ -82,10 +82,10 @@
Alternatively, use `-z` to specify in NUL-terminated format, without
quoting:
- update SP <ref> NUL <newvalue> NUL [<oldvalue>] NUL
- create SP <ref> NUL <newvalue> NUL
- delete SP <ref> NUL [<oldvalue>] NUL
- verify SP <ref> NUL [<oldvalue>] NUL
+ update SP <ref> NUL <new-oid> NUL [<old-oid>] NUL
+ create SP <ref> NUL <new-oid> NUL
+ delete SP <ref> NUL [<old-oid>] NUL
+ verify SP <ref> NUL [<old-oid>] NUL
option SP <opt> NUL
start NUL
prepare NUL
@@ -100,25 +100,25 @@
repeated <ref> produce an error. Command meanings are:
update::
- Set <ref> to <newvalue> after verifying <oldvalue>, if given.
- Specify a zero <newvalue> to ensure the ref does not exist
- after the update and/or a zero <oldvalue> to make sure the
+ Set <ref> to <new-oid> after verifying <old-oid>, if given.
+ Specify a zero <new-oid> to ensure the ref does not exist
+ after the update and/or a zero <old-oid> to make sure the
ref does not exist before the update.
create::
- Create <ref> with <newvalue> after verifying it does not
- exist. The given <newvalue> may not be zero.
+ Create <ref> with <new-oid> after verifying it does not
+ exist. The given <new-oid> may not be zero.
delete::
- Delete <ref> after verifying it exists with <oldvalue>, if
- given. If given, <oldvalue> may not be zero.
+ Delete <ref> after verifying it exists with <old-oid>, if
+ given. If given, <old-oid> may not be zero.
verify::
- Verify <ref> against <oldvalue> but do not change it. If
- <oldvalue> is zero or missing, the ref must not exist.
+ Verify <ref> against <old-oid> but do not change it. If
+ <old-oid> is zero or missing, the ref must not exist.
option::
- Modify behavior of the next command naming a <ref>.
+ Modify the behavior of the next command naming a <ref>.
The only valid option is `no-deref` to avoid dereferencing
a symbolic ref.
@@ -141,7 +141,7 @@
Abort the transaction, releasing all locks if the transaction is in
prepared state.
-If all <ref>s can be locked with matching <oldvalue>s
+If all <ref>s can be locked with matching <old-oid>s
simultaneously, all modifications are performed. Otherwise, no
modifications are performed. Note that while each individual
<ref> is updated or deleted atomically, a concurrent reader may
@@ -161,7 +161,7 @@
Where "oldsha1" is the 40 character hexadecimal value previously
stored in <ref>, "newsha1" is the 40 character hexadecimal value of
-<newvalue> and "committer" is the committer's name, email address
+<new-oid> and "committer" is the committer's name, email address
and date in the standard Git committer ident format.
Optionally with -m:
diff --git a/Documentation/git-update-server-info.txt b/Documentation/git-update-server-info.txt
index 17e429d..6bc9b50 100644
--- a/Documentation/git-update-server-info.txt
+++ b/Documentation/git-update-server-info.txt
@@ -23,13 +23,13 @@
-------
-f::
--force::
- update the info files from scratch.
+ Update the info files from scratch.
OUTPUT
------
Currently the command updates the following files. Please see
-linkgit:gitrepository-layout[5] for description of
+linkgit:gitrepository-layout[5] for a description of
what they are for:
* objects/info/packs
diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt
index b656b47..516d163 100644
--- a/Documentation/git-upload-pack.txt
+++ b/Documentation/git-upload-pack.txt
@@ -26,7 +26,7 @@
-------
--[no-]strict::
- Do not try <directory>/.git/ if <directory> is no Git directory.
+ Do not try <directory>/.git/ if <directory> is not a Git directory.
--timeout=<n>::
Interrupt transfer after <n> seconds of inactivity.
@@ -55,6 +55,37 @@
admins may need to configure some transports to allow this
variable to be passed. See the discussion in linkgit:git[1].
+`GIT_NO_LAZY_FETCH`::
+ When cloning or fetching from a partial repository (i.e., one
+ itself cloned with `--filter`), the server-side `upload-pack`
+ may need to fetch extra objects from its upstream in order to
+ complete the request. By default, `upload-pack` will refuse to
+ perform such a lazy fetch, because `git fetch` may run arbitrary
+ commands specified in configuration and hooks of the source
+ repository (and `upload-pack` tries to be safe to run even in
+ untrusted `.git` directories).
++
+This is implemented by having `upload-pack` internally set the
+`GIT_NO_LAZY_FETCH` variable to `1`. If you want to override it
+(because you are fetching from a partial clone, and you are sure
+you trust it), you can explicitly set `GIT_NO_LAZY_FETCH` to
+`0`.
+
+SECURITY
+--------
+
+Most Git commands should not be run in an untrusted `.git` directory
+(see the section `SECURITY` in linkgit:git[1]). `upload-pack` tries to
+avoid any dangerous configuration options or hooks from the repository
+it's serving, making it safe to clone an untrusted directory and run
+commands on the resulting clone.
+
+For an extra level of safety, you may be able to run `upload-pack` as an
+alternate user. The details will be platform dependent, but on many
+systems you can run:
+
+ git clone --no-local --upload-pack='sudo -u nobody git-upload-pack' ...
+
SEE ALSO
--------
linkgit:gitnamespaces[7]
diff --git a/Documentation/git-var.txt b/Documentation/git-var.txt
index c38fb39..0680568 100644
--- a/Documentation/git-var.txt
+++ b/Documentation/git-var.txt
@@ -19,7 +19,7 @@
OPTIONS
-------
-l::
- Cause the logical variables to be listed. In addition, all the
+ Display the logical variables. In addition, all the
variables of the Git configuration file .git/config are listed
as well. (However, the configuration variables listing functionality
is deprecated in favor of `git config -l`.)
diff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt
index b8720dc..d7e8869 100644
--- a/Documentation/git-verify-pack.txt
+++ b/Documentation/git-verify-pack.txt
@@ -15,7 +15,7 @@
DESCRIPTION
-----------
Reads given idx file for packed Git archive created with the
-'git pack-objects' command and verifies idx file and the
+'git pack-objects' command and verifies the idx file and the
corresponding pack file.
OPTIONS
@@ -25,13 +25,13 @@
-v::
--verbose::
- After verifying the pack, show list of objects contained
+ After verifying the pack, show the list of objects contained
in the pack and a histogram of delta chain length.
-s::
--stat-only::
Do not verify the pack contents; only show the histogram of delta
- chain length. With `--verbose`, list of objects is also shown.
+ chain length. With `--verbose`, the list of objects is also shown.
\--::
Do not interpret any more arguments as options.
diff --git a/Documentation/git-whatchanged.txt b/Documentation/git-whatchanged.txt
index 8b63ceb..8e55e0b 100644
--- a/Documentation/git-whatchanged.txt
+++ b/Documentation/git-whatchanged.txt
@@ -3,7 +3,7 @@
NAME
----
-git-whatchanged - Show logs with difference each commit introduces
+git-whatchanged - Show logs with differences each commit introduces
SYNOPSIS
@@ -18,11 +18,11 @@
New users are encouraged to use linkgit:git-log[1] instead. The
`whatchanged` command is essentially the same as linkgit:git-log[1]
-but defaults to show the raw format diff output and to skip merges.
+but defaults to showing the raw format diff output and skipping merges.
-The command is kept primarily for historical reasons; fingers of
+The command is primarily kept for historical reasons; fingers of
many people who learned Git long before `git log` was invented by
-reading Linux kernel mailing list are trained to type it.
+reading the Linux kernel mailing list are trained to type it.
Examples
diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index 93d76f5..2a240f5 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt
@@ -99,7 +99,7 @@
If `<commit-ish>` is omitted, neither `--detach`, or `--orphan` is
used, and there are no valid local branches (or remote branches if
`--guess-remote` is specified) then, as a convenience, the new worktree is
-associated with a new orphan branch named `<branch>` (after
+associated with a new unborn branch named `<branch>` (after
`$(basename <path>)` if neither `-b` or `-B` is used) as if `--orphan` was
passed to the command. In the event the repository has a remote and
`--guess-remote` is used, but no remote or local branches exist, then the
@@ -234,7 +234,7 @@
--orphan::
With `add`, make the new worktree and index empty, associating
- the worktree with a new orphan/unborn branch named `<new-branch>`.
+ the worktree with a new unborn branch named `<new-branch>`.
--porcelain::
With `list`, output in an easy-to-parse format for scripts.
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 1122895..024a01d 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -96,9 +96,9 @@
to avoid ambiguity with `<name>` containing one.
+
This is useful for cases where you want to pass transitory
-configuration options to git, but are doing so on OS's where
-other processes might be able to read your cmdline
-(e.g. `/proc/self/cmdline`), but not your environ
+configuration options to git, but are doing so on operating systems
+where other processes might be able to read your command line
+(e.g. `/proc/self/cmdline`), but not your environment
(e.g. `/proc/self/environ`). That behavior is the default on
Linux, but may not be on your system.
+
@@ -174,8 +174,17 @@
directory.
--no-replace-objects::
- Do not use replacement refs to replace Git objects. See
- linkgit:git-replace[1] for more information.
+ Do not use replacement refs to replace Git objects.
+ This is equivalent to exporting the `GIT_NO_REPLACE_OBJECTS`
+ environment variable with any value.
+ See linkgit:git-replace[1] for more information.
+
+--no-lazy-fetch::
+ Do not fetch missing objects from the promisor remote on
+ demand. Useful together with `git cat-file -e <object>` to
+ see if the object is locally available.
+ This is equivalent to setting the `GIT_NO_LAZY_FETCH`
+ environment variable to `1`.
--literal-pathspecs::
Treat pathspecs literally (i.e. no globbing, no pathspec magic).
@@ -202,7 +211,7 @@
Do not perform optional operations that require locks. This is
equivalent to setting the `GIT_OPTIONAL_LOCKS` to `0`.
---list-cmds=group[,group...]::
+--list-cmds=<group>[,<group>...]::
List commands by group. This is an internal/experimental
option and may change or be removed in the future. Supported
groups are: builtins, parseopt (builtin commands that use
@@ -556,6 +565,11 @@
is always used. The default is "sha1".
See `--object-format` in linkgit:git-init[1].
+`GIT_DEFAULT_REF_FORMAT`::
+ If this variable is set, the default reference backend format for new
+ repositories will be set to this value. The default is "files".
+ See `--ref-format` in linkgit:git-init[1].
+
Git Commits
~~~~~~~~~~~
`GIT_AUTHOR_NAME`::
@@ -724,13 +738,12 @@
waiting for someone with sufficient permissions to fix it.
`GIT_FLUSH`::
-// NEEDSWORK: make it into a usual Boolean environment variable
- If this environment variable is set to "1", then commands such
+ If this Boolean environment variable is set to true, then commands such
as 'git blame' (in incremental mode), 'git rev-list', 'git log',
'git check-attr' and 'git check-ignore' will
force a flush of the output stream after each record have been
flushed. If this
- variable is set to "0", the output of these commands will be done
+ variable is set to false, the output of these commands will be done
using completely buffered I/O. If this environment variable is
not set, Git will choose buffered or record-oriented flushing
based on whether stdout appears to be redirected to a file or not.
@@ -838,7 +851,7 @@
collisions).
+
In addition, if the variable is set to
-`af_unix:[<socket_type>:]<absolute-pathname>`, Git will try
+`af_unix:[<socket-type>:]<absolute-pathname>`, Git will try
to open the path as a Unix Domain Socket. The socket type
can be either `stream` or `dgram`.
+
@@ -868,6 +881,10 @@
header and packfile URIs. Set this Boolean environment variable to false to prevent this
redaction.
+`GIT_NO_REPLACE_OBJECTS`::
+ Setting and exporting this environment variable tells Git to
+ ignore replacement refs and do not replace Git objects.
+
`GIT_LITERAL_PATHSPECS`::
Setting this Boolean environment variable to true will cause Git to treat all
pathspecs literally, rather than as glob patterns. For example,
@@ -889,6 +906,11 @@
Setting this Boolean environment variable to true will cause Git to treat all
pathspecs as case-insensitive.
+`GIT_NO_LAZY_FETCH`::
+ Setting this Boolean environment variable to true tells Git
+ not to lazily fetch missing objects from the promisor remote
+ on demand.
+
`GIT_REFLOG_ACTION`::
When a ref is updated, reflog entries are created to keep
track of the reason why the ref was updated (which is
@@ -911,6 +933,16 @@
should not normally need to set this to `0`, but it may be
useful when trying to salvage data from a corrupted repository.
+`GIT_COMMIT_GRAPH_PARANOIA`::
+ When loading a commit object from the commit-graph, Git performs an
+ existence check on the object in the object database. This is done to
+ avoid issues with stale commit-graphs that contain references to
+ already-deleted commits, but comes with a performance penalty.
++
+The default is "false", which disables the aforementioned behavior.
+Setting this to "true" enables the existence check so that stale commits
+will never be returned from the commit-graph at the cost of performance.
+
`GIT_ALLOW_PROTOCOL`::
If set to a colon-separated list of protocols, behave as if
`protocol.allow` is set to `never`, and each of the listed
@@ -928,7 +960,7 @@
`GIT_PROTOCOL`::
For internal use only. Used in handshaking the wire protocol.
Contains a colon ':' separated list of keys with optional values
- 'key[=value]'. Presence of unknown keys and values must be
+ '<key>[=<value>]'. Presence of unknown keys and values must be
ignored.
+
Note that servers may need to be configured to allow this variable to
@@ -1015,10 +1047,11 @@
efficiency may later be compressed together into "pack files".
Named pointers called refs mark interesting points in history. A ref
-may contain the SHA-1 name of an object or the name of another ref. Refs
-with names beginning `ref/head/` contain the SHA-1 name of the most
+may contain the SHA-1 name of an object or the name of another ref (the
+latter is called a "symbolic ref").
+Refs with names beginning `refs/head/` contain the SHA-1 name of the most
recent commit (or "head") of a branch under development. SHA-1 names of
-tags of interest are stored under `ref/tags/`. A special ref named
+tags of interest are stored under `refs/tags/`. A symbolic ref named
`HEAD` contains the name of the currently checked-out branch.
The index file is initialized with a list of all paths and, for each
@@ -1034,6 +1067,37 @@
for a given pathname. These stages are used to hold the various
unmerged version of a file when a merge is in progress.
+SECURITY
+--------
+
+Some configuration options and hook files may cause Git to run arbitrary
+shell commands. Because configuration and hooks are not copied using
+`git clone`, it is generally safe to clone remote repositories with
+untrusted content, inspect them with `git log`, and so on.
+
+However, it is not safe to run Git commands in a `.git` directory (or
+the working tree that surrounds it) when that `.git` directory itself
+comes from an untrusted source. The commands in its config and hooks
+are executed in the usual way.
+
+By default, Git will refuse to run when the repository is owned by
+someone other than the user running the command. See the entry for
+`safe.directory` in linkgit:git-config[1]. While this can help protect
+you in a multi-user environment, note that you can also acquire
+untrusted repositories that are owned by you (for example, if you
+extract a zip file or tarball from an untrusted source). In such cases,
+you'd need to "sanitize" the untrusted repository first.
+
+If you have an untrusted `.git` directory, you should first clone it
+with `git clone --no-local` to obtain a clean copy. Git does restrict
+the set of options and hooks that will be run by `upload-pack`, which
+handles the server side of a clone or fetch, but beware that the
+surface area for attack against `upload-pack` is large, so this does
+carry some risk. The safest thing is to serve the repository as an
+unprivileged user (either via linkgit:git-daemon[1], ssh, or using
+other tools to change user ids). See the discussion in the `SECURITY`
+section of linkgit:git-upload-pack[1].
+
FURTHER DOCUMENTATION
---------------------
@@ -1061,7 +1125,7 @@
-------
Git was started by Linus Torvalds, and is currently maintained by Junio
C Hamano. Numerous contributions have come from the Git mailing list
-<git@vger.kernel.org>. http://www.openhub.net/p/git/contributors/summary
+<git@vger.kernel.org>. https://openhub.net/p/git/contributors/summary
gives you a more complete list of contributors.
If you have a clone of git.git itself, the
diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index 6deb89a..4338d02 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -100,6 +100,21 @@
the name of the attribute prefixed with an exclamation point `!`.
+RESERVED BUILTIN_* ATTRIBUTES
+-----------------------------
+
+builtin_* is a reserved namespace for builtin attribute values. Any
+user defined attributes under this namespace will be ignored and
+trigger a warning.
+
+`builtin_objectmode`
+~~~~~~~~~~~~~~~~~~~~
+This attribute is for filtering files by their file bit modes (40000,
+120000, 160000, 100755, 100644). e.g. ':(attr:builtin_objectmode=160000)'.
+You may also check these values with `git check-attr builtin_objectmode -- <file>`.
+If the object is not in the index `git check-attr --cached` will return unspecified.
+
+
EFFECTS
-------
@@ -1122,11 +1137,11 @@
name.
The `merge.*.driver` variable's value is used to construct a
-command to run to merge ancestor's version (`%O`), current
+command to run to common ancestor's version (`%O`), current
version (`%A`) and the other branches' version (`%B`). These
three tokens are replaced with the names of temporary files that
hold the contents of these versions when the command line is
-built. Additionally, %L will be replaced with the conflict marker
+built. Additionally, `%L` will be replaced with the conflict marker
size (see below).
The merge driver is expected to leave the result of the merge in
@@ -1144,15 +1159,16 @@
internal merge and the final merge.
The merge driver can learn the pathname in which the merged result
-will be stored via placeholder `%P`.
-
+will be stored via placeholder `%P`. The conflict labels to be used
+for the common ancestor, local head and other head can be passed by
+using '%S', '%X' and '%Y` respectively.
`conflict-marker-size`
^^^^^^^^^^^^^^^^^^^^^^
This attribute controls the length of conflict markers left in
-the work tree file during a conflicted merge. Only setting to
-the value to a positive integer has any meaningful effect.
+the work tree file during a conflicted merge. Only a positive
+integer has a meaningful effect.
For example, this line in `.gitattributes` can be used to tell the merge
machinery to leave much longer (instead of the usual 7-character-long)
diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt
index 1819a5a..7c70932 100644
--- a/Documentation/gitcli.txt
+++ b/Documentation/gitcli.txt
@@ -23,10 +23,10 @@
A subcommand may take dashed options (which may take their own
arguments, e.g. "--max-parents 2") and arguments. You SHOULD
give dashed options first and then arguments. Some commands may
- accept dashed options after you have already gave non-option
+ accept dashed options after you have already given non-option
arguments (which may make the command ambiguous), but you should
not rely on it (because eventually we may find a way to fix
- these ambiguity by enforcing the "options then args" rule).
+ these ambiguities by enforcing the "options then args" rule).
* Revisions come first and then paths.
E.g. in `git diff v1.0 v2.0 arch/x86 include/asm-x86`,
@@ -37,12 +37,12 @@
they can be disambiguated by placing `--` between them.
E.g. `git diff -- HEAD` is, "I have a file called HEAD in my work
tree. Please show changes between the version I staged in the index
- and what I have in the work tree for that file", not "show difference
+ and what I have in the work tree for that file", not "show the difference
between the HEAD commit and the work tree as a whole". You can say
`git diff HEAD --` to ask for the latter.
* Without disambiguating `--`, Git makes a reasonable guess, but errors
- out and asking you to disambiguate when ambiguous. E.g. if you have a
+ out and asks you to disambiguate when ambiguous. E.g. if you have a
file called HEAD in your work tree, `git diff HEAD` is ambiguous, and
you have to say either `git diff HEAD --` or `git diff -- HEAD` to
disambiguate.
@@ -81,9 +81,6 @@
Here are the rules regarding the "flags" that you should follow when you are
scripting Git:
- * It's preferred to use the non-dashed form of Git commands, which means that
- you should prefer `git foo` to `git-foo`.
-
* Splitting short options to separate words (prefer `git foo -a -b`
to `git foo -ab`, the latter may not even work).
diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt
index c0b9525..2122aeb 100644
--- a/Documentation/gitcore-tutorial.txt
+++ b/Documentation/gitcore-tutorial.txt
@@ -1089,7 +1089,7 @@
like this:
------------------------------------------------
-$ git config remote.linus.url http://www.kernel.org/pub/scm/git/git.git/
+$ git config remote.linus.url https://git.kernel.org/pub/scm/git/git.git/
------------------------------------------------
and use the "linus" keyword with 'git pull' instead of the full URL.
diff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt
index 0d57f86..642c512 100644
--- a/Documentation/gitdiffcore.txt
+++ b/Documentation/gitdiffcore.txt
@@ -173,7 +173,7 @@
detection are off, rename detection adds a preliminary step that first
checks if files are moved across directories while keeping their
filename the same. If there is a file added to a directory whose
-contents is sufficiently similar to a file with the same name that got
+contents are sufficiently similar to a file with the same name that got
deleted from a different directory, it will mark them as renames and
exclude them from the later quadratic step (the one that pairwise
compares all unmatched files to find the "best" matches, determined by
@@ -213,7 +213,7 @@
only 10 lines from a 100-line document, even if you added 910
new lines to make a new 1000-line document, you did not do a
complete rewrite. diffcore-break breaks such a case in order to
-help diffcore-rename to consider such filepairs as candidate of
+help diffcore-rename to consider such filepairs as a candidate of
rename/copy detection, but if filepairs broken that way were not
matched with other filepairs to create rename/copy, then this
transformation merges them back into the original
@@ -230,13 +230,13 @@
* -B/60 (the same as above, since diffcore-break defaults to 50%).
-Note that earlier implementation left a broken pair as a separate
-creation and deletion patches. This was an unnecessary hack and
+Note that earlier implementation left a broken pair as separate
+creation and deletion patches. This was an unnecessary hack, and
the latest implementation always merges all the broken pairs
back into modifications, but the resulting patch output is
formatted differently for easier review in case of such
-a complete rewrite by showing the entire contents of old version
-prefixed with '-', followed by the entire contents of new
+a complete rewrite by showing the entire contents of the old version
+prefixed with '-', followed by the entire contents of the new
version prefixed with '+'.
@@ -245,25 +245,25 @@
This transformation limits the set of filepairs to those that change
specified strings between the preimage and the postimage in a certain
-way. -S<block of text> and -G<regular expression> options are used to
+way. -S<block-of-text> and -G<regular-expression> options are used to
specify different ways these strings are sought.
-"-S<block of text>" detects filepairs whose preimage and postimage
+"-S<block-of-text>" detects filepairs whose preimage and postimage
have different number of occurrences of the specified block of text.
By definition, it will not detect in-file moves. Also, when a
changeset moves a file wholesale without affecting the interesting
string, diffcore-rename kicks in as usual, and `-S` omits the filepair
(since the number of occurrences of that string didn't change in that
rename-detected filepair). When used with `--pickaxe-regex`, treat
-the <block of text> as an extended POSIX regular expression to match,
+the <block-of-text> as an extended POSIX regular expression to match,
instead of a literal string.
-"-G<regular expression>" (mnemonic: grep) detects filepairs whose
+"-G<regular-expression>" (mnemonic: grep) detects filepairs whose
textual diff has an added or a deleted line that matches the given
regular expression. This means that it will detect in-file (or what
rename-detection considers the same file) moves, which is noise. The
implementation runs diff twice and greps, and this can be quite
-expensive. To speed things up binary files without textconv filters
+expensive. To speed things up, binary files without textconv filters
will be ignored.
When `-S` or `-G` are used without `--pickaxe-all`, only filepairs
diff --git a/Documentation/giteveryday.txt b/Documentation/giteveryday.txt
index faba2ef..6cfdd0e 100644
--- a/Documentation/giteveryday.txt
+++ b/Documentation/giteveryday.txt
@@ -14,7 +14,7 @@
-----------
Git users can broadly be grouped into four categories for the purposes of
-describing here a small set of useful command for everyday Git.
+describing here a small set of useful commands for everyday Git.
* <<STANDALONE,Individual Developer (Standalone)>> commands are essential
for anybody who makes a commit, even for somebody who works alone.
@@ -229,7 +229,7 @@
git am -3 -k`
An alternate participant submission mechanism is using the
-`git request-pull` or pull-request mechanisms (e.g as used on
+`git request-pull` or pull-request mechanisms (e.g. as used on
GitHub (www.github.com) to notify your upstream of your
contribution.
diff --git a/Documentation/gitformat-bundle.txt b/Documentation/gitformat-bundle.txt
index 00e0a20..1b75cf7 100644
--- a/Documentation/gitformat-bundle.txt
+++ b/Documentation/gitformat-bundle.txt
@@ -67,7 +67,7 @@
* "Capabilities", which are only in the v3 format, indicate functionality that
the bundle requires to be read properly.
-* "Prerequisites" lists the objects that are NOT included in the bundle and the
+* "Prerequisites" list the objects that are NOT included in the bundle and the
reader of the bundle MUST already have, in order to use the data in the
bundle. The objects stored in the bundle may refer to prerequisite objects and
anything reachable from them (e.g. a tree object in the bundle can reference
@@ -86,10 +86,10 @@
This is a comment and it has no specific meaning. The writer of the bundle MAY
put any string here. The reader of the bundle MUST ignore the comment.
-Note on the shallow clone and a Git bundle
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Note on shallow clones and Git bundles
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Note that the prerequisites does not represent a shallow-clone boundary. The
+Note that the prerequisites do not represent a shallow-clone boundary. The
semantics of the prerequisites and the shallow-clone boundaries are different,
and the Git bundle v2 format cannot represent a shallow clone repository.
diff --git a/Documentation/gitformat-chunk.txt b/Documentation/gitformat-chunk.txt
index 57202ed..3315df6 100644
--- a/Documentation/gitformat-chunk.txt
+++ b/Documentation/gitformat-chunk.txt
@@ -42,7 +42,7 @@
Each integer is stored in network-byte order.
The chunk identifier `ID[i]` is a label for the data stored within this
-fill from `OFFSET[i]` (inclusive) to `OFFSET[i+1]` (exclusive). Thus, the
+file from `OFFSET[i]` (inclusive) to `OFFSET[i+1]` (exclusive). Thus, the
size of the `i`th chunk is equal to the difference between `OFFSET[i+1]`
and `OFFSET[i]`. This requires that the chunk data appears contiguously
in the same order as the table of contents.
@@ -67,7 +67,7 @@
information so the file format is identifiable before the chunk-based
format begins.
-Then, call `add_chunk()` for each chunk that is intended for write. This
+Then, call `add_chunk()` for each chunk that is intended for writing. This
populates the `chunkfile` with information about the order and size of
each chunk to write. Provide a `chunk_write_fn` function pointer to
perform the write of the chunk data upon request.
diff --git a/Documentation/gitformat-index.txt b/Documentation/gitformat-index.txt
index 0773e5c..145cace 100644
--- a/Documentation/gitformat-index.txt
+++ b/Documentation/gitformat-index.txt
@@ -386,8 +386,8 @@
long, "REUC" extension that is M-bytes long, followed by "EOIE",
then the hash would be:
- Hash("TREE" + <binary representation of N> +
- "REUC" + <binary representation of M>)
+ Hash("TREE" + <binary-representation-of-N> +
+ "REUC" + <binary-representation-of-M>)
== Index Entry Offset Table
diff --git a/Documentation/gitformat-pack.txt b/Documentation/gitformat-pack.txt
index 0c1be2d..d6ae229 100644
--- a/Documentation/gitformat-pack.txt
+++ b/Documentation/gitformat-pack.txt
@@ -17,8 +17,8 @@
DESCRIPTION
-----------
-The Git pack format is now Git stores most of its primary repository
-data. Over the lietime af a repository loose objects (if any) and
+The Git pack format is how Git stores most of its primary repository
+data. Over the lifetime of a repository, loose objects (if any) and
smaller packs are consolidated into larger pack(s). See
linkgit:git-gc[1] and linkgit:git-pack-objects[1].
@@ -48,7 +48,7 @@
Observation: we cannot have more than 4G versions ;-) and
more than 4G objects in a pack.
- - The header is followed by number of object entries, each of
+ - The header is followed by a number of object entries, each of
which looks like this:
(undeltified representation)
@@ -62,7 +62,7 @@
is an OBJ_OFS_DELTA object
compressed delta data
- Observation: length of each object is encoded in a variable
+ Observation: the length of each object is encoded in a variable
length format and is not constrained to 32-bit or anything.
- The trailer records a pack checksum of all of the above.
@@ -117,7 +117,7 @@
from the base object. If the base object is deltified, it must be
converted to canonical form first. Each instruction appends more and
more data to the target object until it's complete. There are two
-supported instructions so far: one for copy a byte range from the
+supported instructions so far: one for copying a byte range from the
source object and one for inserting new data embedded in the
instruction itself.
@@ -137,7 +137,7 @@
All offset and size bytes are optional. This is to reduce the
instruction size when encoding small offsets or sizes. The first seven
-bits in the first octet determines which of the next seven octets is
+bits in the first octet determine which of the next seven octets is
present. If bit zero is set, offset1 is present. If bit one is set
offset2 is present and so on.
@@ -161,9 +161,9 @@
| 0xxxxxxx | data |
+----------+============+
-This is the instruction to construct target object without the base
+This is the instruction to construct the target object without the base
object. The following data is appended to the target object. The first
-seven bits of the first octet determines the size of data in
+seven bits of the first octet determine the size of data in
bytes. The size must be non-zero.
==== Reserved instruction
@@ -294,7 +294,7 @@
- The same trailer as a v1 pack file:
- A copy of the pack checksum at the end of
+ A copy of the pack checksum at the end of the
corresponding packfile.
Index checksum of all of the above.
@@ -390,10 +390,20 @@
CHUNK DATA:
Packfile Names (ID: {'P', 'N', 'A', 'M'})
- Stores the packfile names as concatenated, null-terminated strings.
- Packfiles must be listed in lexicographic order for fast lookups by
- name. This is the only chunk not guaranteed to be a multiple of four
- bytes in length, so should be the last chunk for alignment reasons.
+ Store the names of packfiles as a sequence of NUL-terminated
+ strings. There is no extra padding between the filenames,
+ and they are listed in lexicographic order. The chunk itself
+ is padded at the end with between 0 and 3 NUL bytes to make the
+ chunk size a multiple of 4 bytes.
+
+ Bitmapped Packfiles (ID: {'B', 'T', 'M', 'P'})
+ Stores a table of two 4-byte unsigned integers in network order.
+ Each table entry corresponds to a single pack (in the order that
+ they appear above in the `PNAM` chunk). The values for each table
+ entry are as follows:
+ - The first bit position (in pseudo-pack order, see below) to
+ contain an object from that pack.
+ - The number of bits whose objects are selected from that pack.
OID Fanout (ID: {'O', 'I', 'D', 'F'})
The ith entry, F[i], stores the number of OIDs with first
@@ -508,6 +518,73 @@
The MIDX's reverse index is stored in the optional 'RIDX' chunk within
the MIDX itself.
+=== `BTMP` chunk
+
+The Bitmapped Packfiles (`BTMP`) chunk encodes additional information
+about the objects in the multi-pack index's reachability bitmap. Recall
+that objects from the MIDX are arranged in "pseudo-pack" order (see
+above) for reachability bitmaps.
+
+From the example above, suppose we have packs "a", "b", and "c", with
+10, 15, and 20 objects, respectively. In pseudo-pack order, those would
+be arranged as follows:
+
+ |a,0|a,1|...|a,9|b,0|b,1|...|b,14|c,0|c,1|...|c,19|
+
+When working with single-pack bitmaps (or, equivalently, multi-pack
+reachability bitmaps with a preferred pack), linkgit:git-pack-objects[1]
+performs ``verbatim'' reuse, attempting to reuse chunks of the bitmapped
+or preferred packfile instead of adding objects to the packing list.
+
+When a chunk of bytes is reused from an existing pack, any objects
+contained therein do not need to be added to the packing list, saving
+memory and CPU time. But a chunk from an existing packfile can only be
+reused when the following conditions are met:
+
+ - The chunk contains only objects which were requested by the caller
+ (i.e. does not contain any objects which the caller didn't ask for
+ explicitly or implicitly).
+
+ - All objects stored in non-thin packs as offset- or reference-deltas
+ also include their base object in the resulting pack.
+
+The `BTMP` chunk encodes the necessary information in order to implement
+multi-pack reuse over a set of packfiles as described above.
+Specifically, the `BTMP` chunk encodes three pieces of information (all
+32-bit unsigned integers in network byte-order) for each packfile `p`
+that is stored in the MIDX, as follows:
+
+`bitmap_pos`:: The first bit position (in pseudo-pack order) in the
+ multi-pack index's reachability bitmap occupied by an object from `p`.
+
+`bitmap_nr`:: The number of bit positions (including the one at
+ `bitmap_pos`) that encode objects from that pack `p`.
+
+For example, the `BTMP` chunk corresponding to the above example (with
+packs ``a'', ``b'', and ``c'') would look like:
+
+[cols="1,2,2"]
+|===
+| |`bitmap_pos` |`bitmap_nr`
+
+|packfile ``a''
+|`0`
+|`10`
+
+|packfile ``b''
+|`10`
+|`15`
+
+|packfile ``c''
+|`25`
+|`20`
+|===
+
+With this information in place, we can treat each packfile as
+individually reusable in the same fashion as verbatim pack reuse is
+performed on individual packs prior to the implementation of the `BTMP`
+chunk.
+
== cruft packs
The cruft packs feature offer an alternative to Git's traditional mechanism of
@@ -588,51 +665,17 @@
It is linkgit:git-gc[1] that is typically responsible for removing expired
unreachable objects.
-=== Caution for mixed-version environments
-
-Repositories that have cruft packs in them will continue to work with any older
-version of Git. Note, however, that previous versions of Git which do not
-understand the `.mtimes` file will use the cruft pack's mtime as the mtime for
-all of the objects in it. In other words, do not expect older (pre-cruft pack)
-versions of Git to interpret or even read the contents of the `.mtimes` file.
-
-Note that having mixed versions of Git GC-ing the same repository can lead to
-unreachable objects never being completely pruned. This can happen under the
-following circumstances:
-
- - An older version of Git running GC explodes the contents of an existing
- cruft pack loose, using the cruft pack's mtime.
- - A newer version running GC collects those loose objects into a cruft pack,
- where the .mtime file reflects the loose object's actual mtimes, but the
- cruft pack mtime is "now".
-
-Repeating this process will lead to unreachable objects not getting pruned as a
-result of repeatedly resetting the objects' mtimes to the present time.
-
-If you are GC-ing repositories in a mixed version environment, consider omitting
-the `--cruft` option when using linkgit:git-repack[1] and linkgit:git-gc[1], and
-setting the `gc.cruftPacks` configuration to "false" until all writers
-understand cruft packs.
-
=== Alternatives
Notable alternatives to this design include:
- - The location of the per-object mtime data, and
- - Storing unreachable objects in multiple cruft packs.
+ - The location of the per-object mtime data.
On the location of mtime data, a new auxiliary file tied to the pack was chosen
to avoid complicating the `.idx` format. If the `.idx` format were ever to gain
support for optional chunks of data, it may make sense to consolidate the
`.mtimes` format into the `.idx` itself.
-Storing unreachable objects among multiple cruft packs (e.g., creating a new
-cruft pack during each repacking operation including only unreachable objects
-which aren't already stored in an earlier cruft pack) is significantly more
-complicated to construct, and so aren't pursued here. The obvious drawback to
-the current implementation is that the entire cruft pack must be re-written from
-scratch.
-
GIT
---
Part of the linkgit:git[1] suite
diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
index 86f8047..ee9b92c 100644
--- a/Documentation/githooks.txt
+++ b/Documentation/githooks.txt
@@ -80,7 +80,7 @@
committed after applying the patch.
It can be used to inspect the current working tree and refuse to
-make a commit if it does not pass certain test.
+make a commit if it does not pass certain tests.
The default 'pre-applypatch' hook, when enabled, runs the
'pre-commit' hook, if the latter is enabled.
@@ -157,7 +157,7 @@
The purpose of the hook is to edit the message file in place, and
it is not suppressed by the `--no-verify` option. A non-zero exit
means a failure of the hook and aborts the commit. It should not
-be used as replacement for pre-commit hook.
+be used as a replacement for the pre-commit hook.
The sample `prepare-commit-msg` hook that comes with Git removes the
help message found in the commented portion of the commit template.
@@ -243,7 +243,7 @@
Information about what is to be pushed is provided on the hook's standard
input with lines of the form:
- <local ref> SP <local object name> SP <remote ref> SP <remote object name> LF
+ <local-ref> SP <local-object-name> SP <remote-ref> SP <remote-object-name> LF
For instance, if the command +git push origin master:foreign+ were run the
hook would receive a line like the following:
@@ -251,9 +251,9 @@
refs/heads/master 67890 refs/heads/foreign 12345
although the full object name would be supplied. If the foreign ref does not
-yet exist the `<remote object name>` will be the all-zeroes object name. If a
-ref is to be deleted, the `<local ref>` will be supplied as `(delete)` and the
-`<local object name>` will be the all-zeroes object name. If the local commit
+yet exist the `<remote-object-name>` will be the all-zeroes object name. If a
+ref is to be deleted, the `<local-ref>` will be supplied as `(delete)` and the
+`<local-object-name>` will be the all-zeroes object name. If the local commit
was specified by something other than a name which could be expanded (such as
`HEAD~`, or an object name) it will be supplied as it was originally given.
@@ -275,12 +275,12 @@
arguments, but for each ref to be updated it receives on standard
input a line of the format:
- <old-value> SP <new-value> SP <ref-name> LF
+ <old-oid> SP <new-oid> SP <ref-name> LF
-where `<old-value>` is the old object name stored in the ref,
-`<new-value>` is the new object name to be stored in the ref and
+where `<old-oid>` is the old object name stored in the ref,
+`<new-oid>` is the new object name to be stored in the ref and
`<ref-name>` is the full name of the ref.
-When creating a new ref, `<old-value>` is the all-zeroes object name.
+When creating a new ref, `<old-oid>` is the all-zeroes object name.
If the hook exits with non-zero status, none of the refs will be
updated. If the hook exits with zero, updating of individual refs can
@@ -345,7 +345,7 @@
The default 'update' hook, when enabled--and with
`hooks.allowunannotated` config option unset or set to false--prevents
-unannotated tags to be pushed.
+unannotated tags from being pushed.
[[proc-receive]]
proc-receive
@@ -379,12 +379,12 @@
S: ... ...
S: flush-pkt
- # Receive result from the hook.
+ # Receive results from the hook.
# OK, run this command successfully.
H: PKT-LINE(ok <ref>)
# NO, I reject it.
H: PKT-LINE(ng <ref> <reason>)
- # Fall through, let 'receive-pack' to execute it.
+ # Fall through, let 'receive-pack' execute it.
H: PKT-LINE(ok <ref>)
H: PKT-LINE(option fall-through)
# OK, but has an alternate reference. The alternate reference name
@@ -503,13 +503,13 @@
For each reference update that was added to the transaction, the hook
receives on standard input a line of the format:
- <old-value> SP <new-value> SP <ref-name> LF
+ <old-oid> SP <new-oid> SP <ref-name> LF
-where `<old-value>` is the old object name passed into the reference
-transaction, `<new-value>` is the new object name to be stored in the
+where `<old-oid>` is the old object name passed into the reference
+transaction, `<new-oid>` is the new object name to be stored in the
ref and `<ref-name>` is the full name of the ref. When force updating
the reference regardless of its current value or when the reference is
-to be created anew, `<old-value>` is the all-zeroes object name. To
+to be created anew, `<old-oid>` is the all-zeroes object name. To
distinguish these cases, you can inspect the current value of
`<ref-name>` via `git rev-parse`.
diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt
index d50e9ed..35b3996 100644
--- a/Documentation/gitk.txt
+++ b/Documentation/gitk.txt
@@ -8,7 +8,7 @@
SYNOPSIS
--------
[verse]
-'gitk' [<options>] [<revision range>] [--] [<path>...]
+'gitk' [<options>] [<revision-range>] [--] [<path>...]
DESCRIPTION
-----------
@@ -26,7 +26,7 @@
gitk-specific options.
gitk generally only understands options with arguments in the
-'sticked' form (see linkgit:gitcli[7]) due to limitations in the
+'stuck' form (see linkgit:gitcli[7]) due to limitations in the
command-line parser.
rev-list options and arguments
@@ -124,7 +124,7 @@
range to show. The command is expected to print on its
standard output a list of additional revisions to be shown,
one per line. Use this instead of explicitly specifying a
- '<revision range>' if the set of commits to show may vary
+ '<revision-range>' if the set of commits to show may vary
between refreshes.
--select-commit=<ref>::
diff --git a/Documentation/gitprotocol-capabilities.txt b/Documentation/gitprotocol-capabilities.txt
index 0fb5ea0..2cf7735 100644
--- a/Documentation/gitprotocol-capabilities.txt
+++ b/Documentation/gitprotocol-capabilities.txt
@@ -30,7 +30,7 @@
did not say it supports.
Server MUST diagnose and abort if capabilities it does not understand
-was sent. Server MUST NOT ignore capabilities that client requested
+were sent. Server MUST NOT ignore capabilities that client requested
and server advertised. As a consequence of these rules, server MUST
NOT advertise capabilities it does not understand.
@@ -61,8 +61,8 @@
Without multi_ack, a client sends have lines in --date-order until
the server has found a common base. That means the client will send
have lines that are already known by the server to be common, because
-they overlap in time with another branch that the server hasn't found
-a common base on yet.
+they overlap in time with another branch on which the server hasn't found
+a common base yet.
For example suppose the client has commits in caps that the server
doesn't and the server has commits in lower case that the client
@@ -88,7 +88,7 @@
multi_ack_detailed
------------------
-This is an extension of multi_ack that permits client to better
+This is an extension of multi_ack that permits the client to better
understand the server's in-memory state. See linkgit:gitprotocol-pack[5],
section "Packfile Negotiation" for more information.
@@ -135,7 +135,7 @@
side-band, side-band-64k
------------------------
-This capability means that server can send, and client understand multiplexed
+This capability means that the server can send, and the client can understand, multiplexed
progress reports and error info interleaved with the packfile itself.
These two options are mutually exclusive. A modern client always
@@ -163,14 +163,14 @@
same deal, you have up to 65519 bytes of data and 1 byte for the stream
code.
-The client MUST send only maximum of one of "side-band" and "side-
-band-64k". Server MUST diagnose it as an error if client requests
+The client MUST send only one of "side-band" and "side-
+band-64k". The server MUST diagnose it as an error if client requests
both.
ofs-delta
---------
-Server can send, and client understand PACKv2 with delta referring to
+The server can send, and the client can understand, PACKv2 with delta referring to
its base by position in pack rather than by an obj-id. That is, they can
send/read OBJ_OFS_DELTA (aka type 6) in a packfile.
@@ -252,7 +252,7 @@
no-progress
-----------
-The client was started with "git clone -q" or something, and doesn't
+The client was started with "git clone -q" or something similar, and doesn't
want that side band 2. Basically the client just says "I do not
wish to receive stream 2 on sideband, so do not send it to me, and if
you did, I will drop it on the floor anyway". However, the sideband
@@ -273,7 +273,7 @@
data, whether or not a server had advertised objects in the
refs/tags/* namespace.
-Servers MUST pack the tags if their referrant is packed and the client
+Servers MUST pack the tags if their referent is packed and the client
has requested include-tags.
Clients MUST be prepared for the case where a server has ignored
@@ -378,7 +378,7 @@
or partial fetch and request that the server omit various objects
from the packfile.
-session-id=<session id>
+session-id=<session-id>
-----------------------
The server may advertise a session ID that can be used to identify this process
diff --git a/Documentation/gitprotocol-common.txt b/Documentation/gitprotocol-common.txt
index 1486651..cdc9d6e 100644
--- a/Documentation/gitprotocol-common.txt
+++ b/Documentation/gitprotocol-common.txt
@@ -13,7 +13,7 @@
DESCRIPTION
-----------
-This document sets defines things common to various over-the-wire
+This document defines things common to various over-the-wire
protocols and file formats used in Git.
ABNF Notation
diff --git a/Documentation/gitprotocol-http.txt b/Documentation/gitprotocol-http.txt
index ccc13f0..ec40a55 100644
--- a/Documentation/gitprotocol-http.txt
+++ b/Documentation/gitprotocol-http.txt
@@ -42,7 +42,7 @@
by appending additional path components onto the end of the user
supplied `$GIT_URL` string.
-An example of a dumb client requesting for a loose object:
+An example of a dumb client requesting a loose object:
$GIT_URL: http://example.com:8080/git/repo.git
URL request: http://example.com:8080/git/repo.git/objects/d0/49f6c27a2244e12041955e262a404c7faba355
@@ -379,7 +379,7 @@
C: Build an empty set, `common`, to hold the objects that are later
determined to be on both ends.
-C: Build a set, `want`, of the objects from `advertised` the client
+C: Build a set, `want`, of the objects from `advertised` that the client
wants to fetch, based on what it saw during ref discovery.
C: Start a queue, `c_pending`, ordered by commit time (popping newest
@@ -391,14 +391,14 @@
C: Send one `$GIT_URL/git-upload-pack` request:
- C: 0032want <want #1>...............................
- C: 0032want <want #2>...............................
+ C: 0032want <want-#1>...............................
+ C: 0032want <want-#2>...............................
....
- C: 0032have <common #1>.............................
- C: 0032have <common #2>.............................
+ C: 0032have <common-#1>.............................
+ C: 0032have <common-#2>.............................
....
- C: 0032have <have #1>...............................
- C: 0032have <have #2>...............................
+ C: 0032have <have-#1>...............................
+ C: 0032have <have-#2>...............................
....
C: 0000
@@ -423,7 +423,7 @@
negotiated through the `object-format` capability (default SHA-1).
The `have` list is created by popping the first 32 commits
-from `c_pending`. Less can be supplied if `c_pending` empties.
+from `c_pending`. Fewer can be supplied if `c_pending` empties.
If the client has sent 256 "have" commits and has not yet
received one of those back from `s_common`, or the client has
@@ -512,7 +512,7 @@
the id obtained through ref discovery as old_id.
update_request = command_list
- "PACK" <binary data>
+ "PACK" <binary-data>
command_list = PKT-LINE(command NUL cap_list LF)
*(command_pkt)
@@ -529,8 +529,8 @@
REFERENCES
----------
-http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]
-http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]
+https://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]
+https://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]
SEE ALSO
--------
diff --git a/Documentation/gitprotocol-pack.txt b/Documentation/gitprotocol-pack.txt
index dd4108b..837b691 100644
--- a/Documentation/gitprotocol-pack.txt
+++ b/Documentation/gitprotocol-pack.txt
@@ -30,7 +30,7 @@
---------------
The descriptions below build on the pkt-line format described in
-linkgit:gitprotocol-common[5]. When the grammar indicate `PKT-LINE(...)`, unless
+linkgit:gitprotocol-common[5]. When the grammar indicates `PKT-LINE(...)`, unless
otherwise noted the usual pkt-line LF rules apply: the sender SHOULD
include a LF, but the receiver MUST NOT complain if it is not present.
@@ -137,7 +137,7 @@
v
ssh user@example.com "git-upload-pack '/project.git'"
-In a "user@host:path" format URI, its relative to the user's home
+In a "user@host:path" format URI, it's relative to the user's home
directory, because the Git client will run:
git clone user@example.com:project.git
@@ -325,7 +325,7 @@
If the client has requested a positive depth, the server will compute
the set of commits which are no deeper than the desired depth. The set
-of commits start at the client's wants.
+of commits starts at the client's wants.
The server writes 'shallow' lines for each
commit whose parents will not be sent as a result. The server writes
diff --git a/Documentation/gitprotocol-v2.txt b/Documentation/gitprotocol-v2.txt
index acb97ad..414bc62 100644
--- a/Documentation/gitprotocol-v2.txt
+++ b/Documentation/gitprotocol-v2.txt
@@ -29,7 +29,7 @@
semantics the http remote helper can simply act as a proxy
In protocol v2 communication is command oriented. When first contacting a
-server a list of capabilities will advertised. Some of these capabilities
+server a list of capabilities will be advertised. Some of these capabilities
will be commands which a client can request be executed. Once a command
has completed, a client can reuse the connection and request that other
commands be executed.
@@ -199,7 +199,7 @@
Additional features not supported in the base command will be advertised
as the value of the command in the capability advertisement in the form
-of a space separated list of features: "<command>=<feature 1> <feature 2>"
+of a space separated list of features: "<command>=<feature-1> <feature-2>"
ls-refs takes in the following arguments:
@@ -245,7 +245,7 @@
Additional features not supported in the base command will be advertised
as the value of the command in the capability advertisement in the form
-of a space separated list of features: "<command>=<feature 1> <feature 2>"
+of a space separated list of features: "<command>=<feature-1> <feature-2>"
A `fetch` request can take the following arguments:
@@ -346,7 +346,8 @@
want-ref <ref>
Indicates to the server that the client wants to retrieve a
particular ref, where <ref> is the full name of a ref on the
- server.
+ server. It is a protocol error to send want-ref for the
+ same ref more than once.
If the 'sideband-all' feature is advertised, the following argument can be
included in the client's request:
@@ -361,9 +362,10 @@
If the 'packfile-uris' feature is advertised, the following argument
can be included in the client's request as well as the potential
addition of the 'packfile-uris' section in the server's response as
-explained below.
+explained below. Note that at most one `packfile-uris` line can be sent
+to the server.
- packfile-uris <comma-separated list of protocols>
+ packfile-uris <comma-separated-list-of-protocols>
Indicates to the server that the client is willing to receive
URIs of any of the given protocols in place of objects in the
sent packfile. Before performing the connectivity check, the
@@ -534,7 +536,7 @@
only handle SHA-1. If the client would like to use a hash algorithm other than
SHA-1, it should specify its object-format string.
-session-id=<session id>
+session-id=<session-id>
~~~~~~~~~~~~~~~~~~~~~~~
The server may advertise a session ID that can be used to identify this process
diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt
index ed8da42..d0be008 100644
--- a/Documentation/gitremote-helpers.txt
+++ b/Documentation/gitremote-helpers.txt
@@ -479,14 +479,14 @@
'option depth' <depth>::
Deepens the history of a shallow repository.
-'option deepen-since <timestamp>::
+'option deepen-since' <timestamp>::
Deepens the history of a shallow repository based on time.
-'option deepen-not <ref>::
+'option deepen-not' <ref>::
Deepens the history of a shallow repository excluding ref.
Multiple options add up.
-'option deepen-relative {'true'|'false'}::
+'option deepen-relative' {'true'|'false'}::
Deepens the history of a shallow repository relative to
current boundary. Only valid when used with "option depth".
@@ -526,7 +526,7 @@
'option pushcert' {'true'|'false'}::
GPG sign pushes.
-'option push-option <string>::
+'option push-option' <string>::
Transmit <string> as a push option. As the push option
must not contain LF or NUL characters, the string is not encoded.
@@ -542,13 +542,10 @@
transaction. If successful, all refs will be updated, or none will. If the
remote side does not support this capability, the push will fail.
-'option object-format' {'true'|algorithm}::
- If 'true', indicate that the caller wants hash algorithm information
+'option object-format true'::
+ Indicate that the caller wants hash algorithm information
to be passed back from the remote. This mode is used when fetching
refs.
-+
-If set to an algorithm, indicate that the caller wants to interact with
-the remote side using that algorithm.
SEE ALSO
--------
diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt
index 1a2ef4c..949cd8a 100644
--- a/Documentation/gitrepository-layout.txt
+++ b/Documentation/gitrepository-layout.txt
@@ -23,7 +23,9 @@
*Note*: Also you can have a plain text file `.git` at the root of
your working tree, containing `gitdir: <path>` to point at the real
-directory that has the repository. This mechanism is often used for
+directory that has the repository.
+This mechanism is called a 'gitfile' and is usually managed via the
+`git submodule` and `git worktree` commands. It is often used for
a working tree of a submodule checkout, to allow you in the
containing superproject to `git checkout` a branch that does not
have the submodule. The `checkout` has to remove the entire
diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt
index 941858a..f7b5a25 100644
--- a/Documentation/gitsubmodules.txt
+++ b/Documentation/gitsubmodules.txt
@@ -78,7 +78,7 @@
* The command line for those commands that support taking submodules
as part of their pathspecs. Most commands have a boolean flag
- `--recurse-submodules` which specify whether to recurse into submodules.
+ `--recurse-submodules` which specifies whether to recurse into submodules.
Examples are `grep` and `checkout`.
Some commands take enums, such as `fetch` and `push`, where you can
specify how submodules are affected.
@@ -151,7 +151,7 @@
is not affected. This can be undone using `git submodule init`.
* Deleted submodule: A submodule can be deleted by running
-`git rm <submodule path> && git commit`. This can be undone
+`git rm <submodule-path> && git commit`. This can be undone
using `git revert`.
+
The deletion removes the superproject's tracking data, which are
@@ -192,7 +192,7 @@
[submodule "baz"]
url = https://example.org/baz
-In the above config only the submodule 'bar' and 'baz' are active,
+In the above config only the submodules 'bar' and 'baz' are active,
'bar' due to (1) and 'baz' due to (3). 'foo' is inactive because
(1) takes precedence over (3)
@@ -229,7 +229,7 @@
git submodule add <URL> <path>
# Occasionally update the submodule to a new version:
- git -C <path> checkout <new version>
+ git -C <path> checkout <new-version>
git add <path>
git commit -m "update submodule to new version"
@@ -274,7 +274,7 @@
into submodules. The `init` and `update` subcommands of `git submodule`
will maintain submodules checked out and at an appropriate revision in
your working tree. Alternatively you can set `submodule.recurse` to have
-`checkout` recursing into submodules (note that `submodule.recurse` also
+`checkout` recurse into submodules (note that `submodule.recurse` also
affects other Git commands, see linkgit:git-config[1] for a complete list).
diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt
index c7cadd8..4759408 100644
--- a/Documentation/gittutorial.txt
+++ b/Documentation/gittutorial.txt
@@ -137,10 +137,10 @@
them to the index, and commit, all in one step.
A note on commit messages: Though not required, it's a good idea to
-begin the commit message with a single short (less than 50 character)
-line summarizing the change, followed by a blank line and then a more
-thorough description. The text up to the first blank line in a commit
-message is treated as the commit title, and that title is used
+begin the commit message with a single short (no more than 50
+characters) line summarizing the change, followed by a blank line and
+then a more thorough description. The text up to the first blank line in
+a commit message is treated as the commit title, and that title is used
throughout Git. For example, linkgit:git-format-patch[1] turns a
commit into email, and it uses the title on the Subject line and the
rest of the commit in the body.
diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt
index 34b1d6e..8598358 100644
--- a/Documentation/gitweb.conf.txt
+++ b/Documentation/gitweb.conf.txt
@@ -53,7 +53,7 @@
`/etc/gitweb-common.conf`),
* either per-instance configuration file (defaults to 'gitweb_config.perl'
- in the same directory as the installed gitweb), or if it does not exists
+ in the same directory as the installed gitweb), or if it does not exist
then fallback system-wide configuration file (defaults to `/etc/gitweb.conf`).
Values obtained in later configuration files override values obtained earlier
@@ -242,7 +242,7 @@
$highlight_bin::
Path to the highlight executable to use (it must be the one from
- http://www.andre-simon.de[] due to assumptions about parameters and output).
+ http://andre-simon.de/zip/download.php[] due to assumptions about parameters and output).
By default set to 'highlight'; set it to full path to highlight
executable if it is not installed on your web server's PATH.
Note that 'highlight' feature must be set for gitweb to actually
@@ -343,7 +343,7 @@
Label for the "home link" at the top of all pages, leading to `$home_link`
(usually the main gitweb page, which contains the projects list). It is
used as the first component of gitweb's "breadcrumb trail":
- `<home link> / <project> / <action>`. Can be set at build time using
+ `<home-link> / <project> / <action>`. Can be set at build time using
the `GITWEB_HOME_LINK_STR` variable. By default it is set to "projects",
as this link leads to the list of projects. Another popular choice is to
set it to the name of site. Note that it is treated as raw HTML so it
@@ -604,9 +604,9 @@
Each `%feature` hash element is a hash reference and has the following
structure:
----------------------------------------------------------------------
-"<feature_name>" => {
- "sub" => <feature-sub (subroutine)>,
- "override" => <allow-override (boolean)>,
+"<feature-name>" => {
+ "sub" => <feature-sub-(subroutine)>,
+ "override" => <allow-override-(boolean)>,
"default" => [ <options>... ]
},
----------------------------------------------------------------------
@@ -614,7 +614,7 @@
features the structure of appropriate `%feature` hash element has a simpler
form:
----------------------------------------------------------------------
-"<feature_name>" => {
+"<feature-name>" => {
"override" => 0,
"default" => [ <options>... ]
},
@@ -820,7 +820,7 @@
(\'h' gitweb parameter) and `%b` to the current hash base
(\'hb' gitweb parameter); `%%` expands to \'%'.
+
-For example, at the time this page was written, the http://repo.or.cz[]
+For example, at the time this page was written, the https://repo.or.cz[]
Git hosting site set it to the following to enable graphical log
(using the third party tool *git-browser*):
+
diff --git a/Documentation/gitweb.txt b/Documentation/gitweb.txt
index af6bf3c..56d24a3 100644
--- a/Documentation/gitweb.txt
+++ b/Documentation/gitweb.txt
@@ -8,7 +8,7 @@
SYNOPSIS
--------
To get started with gitweb, run linkgit:git-instaweb[1] from a Git repository.
-This would configure and start your web server, and run web browser pointing to
+This will configure and start your web server, and run a web browser pointing to
gitweb.
@@ -20,15 +20,15 @@
* Browsing every revision of the repository.
* Viewing the contents of files in the repository at any revision.
* Viewing the revision log of branches, history of files and directories,
- see what was changed when, by who.
+ seeing what was changed, when, and by whom.
* Viewing the blame/annotation details of any file (if enabled).
* Generating RSS and Atom feeds of commits, for any branch.
The feeds are auto-discoverable in modern web browsers.
-* Viewing everything that was changed in a revision, and step through
+* Viewing everything that was changed in a revision, and stepping through
revisions one at a time, viewing the history of the repository.
-* Finding commits which commit messages matches given search term.
+* Finding commits whose commit messages match a given search term.
-See http://repo.or.cz/w/git.git/tree/HEAD:/gitweb/[] for gitweb source code,
+See https://repo.or.cz/w/git.git/tree/HEAD:/gitweb/[] for gitweb source code,
browsed using gitweb itself.
@@ -41,9 +41,9 @@
Repositories
~~~~~~~~~~~~
Gitweb can show information from one or more Git repositories. These
-repositories have to be all on local filesystem, and have to share common
+repositories have to be all on local filesystem, and have to share a common
repository root, i.e. be all under a single parent repository (but see also
-"Advanced web server setup" section, "Webserver configuration with multiple
+the "Advanced web server setup" section, "Webserver configuration with multiple
projects' root" subsection).
-----------------------------------------------------------------------
@@ -51,7 +51,7 @@
-----------------------------------------------------------------------
The default value for `$projectroot` is `/pub/git`. You can change it during
-building gitweb via `GITWEB_PROJECTROOT` build configuration variable.
+building gitweb via the `GITWEB_PROJECTROOT` build configuration variable.
By default all Git repositories under `$projectroot` are visible and available
to gitweb. The list of projects is generated by default by scanning the
@@ -66,7 +66,7 @@
Projects list file format
~~~~~~~~~~~~~~~~~~~~~~~~~
-Instead of having gitweb find repositories by scanning filesystem
+Instead of having gitweb find repositories by scanning the filesystem
starting from $projectroot, you can provide a pre-generated list of
visible projects by setting `$projects_list` to point to a plain text
file with a list of projects (with some additional info).
@@ -305,7 +305,7 @@
looks like this:
-----------------------------------------------------------------------
-.../gitweb.cgi/<repo>/<action>/<revision_from>:/<path_from>..<revision_to>:/<path_to>?<arguments>
+.../gitweb.cgi/<repo>/<action>/<revision-from>:/<path-from>..<revision-to>:/<path-to>?<arguments>
-----------------------------------------------------------------------
diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
index 5a53726..d71b199 100644
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt
@@ -98,9 +98,8 @@
revision.
[[def_commit-ish]]commit-ish (also committish)::
- A <<def_commit_object,commit object>> or an
- <<def_object,object>> that can be recursively dereferenced to
- a commit object.
+ A <<def_commit_object,commit object>> or an <<def_object,object>> that
+ can be recursively <<def_dereference,dereferenced>> to a commit object.
The following are all commit-ishes:
a commit object,
a <<def_tag_object,tag object>> that points to a commit
@@ -125,6 +124,25 @@
dangling object has no references to it from any
reference or <<def_object,object>> in the <<def_repository,repository>>.
+[[def_dereference]]dereference::
+ Referring to a <<def_symref,symbolic ref>>: the action of accessing the
+ <<def_ref,reference>> pointed at by a symbolic ref. Recursive
+ dereferencing involves repeating the aforementioned process on the
+ resulting ref until a non-symbolic reference is found.
++
+Referring to a <<def_tag_object,tag object>>: the action of accessing the
+<<def_object,object>> a tag points at. Tags are recursively dereferenced by
+repeating the operation on the result object until the result has either a
+specified <<def_object_type,object type>> (where applicable) or any non-"tag"
+object type. A synonym for "recursive dereference" in the context of tags is
+"<<def_peel,peel>>".
++
+Referring to a <<def_commit_object,commit object>>: the action of accessing
+the commit's tree object. Commits cannot be dereferenced recursively.
++
+Unless otherwise specified, "dereferencing" as it used in the context of Git
+commands or protocols is implicitly recursive.
+
[[def_detached_HEAD]]detached HEAD::
Normally the <<def_HEAD,HEAD>> stores the name of a
<<def_branch,branch>>, and commands that operate on the
@@ -184,9 +202,11 @@
[[def_gitfile]]gitfile::
A plain file `.git` at the root of a working tree that
points at the directory that is the real repository.
+ For proper use see linkgit:git-worktree[1] or linkgit:git-submodule[1].
+ For syntax see linkgit:gitrepository-layout[5].
[[def_grafts]]grafts::
- Grafts enables two otherwise different lines of development to be joined
+ Grafts enable two otherwise different lines of development to be joined
together by recording fake ancestry information for commits. This way
you can make Git pretend the set of <<def_parent,parents>> a <<def_commit,commit>> has
is different from what was recorded when the commit was
@@ -294,6 +314,12 @@
[[def_octopus]]octopus::
To <<def_merge,merge>> more than two <<def_branch,branches>>.
+[[def_orphan]]orphan::
+ The act of getting on a <<def_branch,branch>> that does not
+ exist yet (i.e., an <<def_unborn,unborn>> branch). After
+ such an operation, the commit first created becomes a commit
+ without a parent, starting a new history.
+
[[def_origin]]origin::
The default upstream <<def_repository,repository>>. Most projects have
at least one upstream project which they track. By default
@@ -444,6 +470,10 @@
of the logical predecessor(s) in the line of development, i.e. its
parents.
+[[def_peel]]peel::
+ The action of recursively <<def_dereference,dereferencing>> a
+ <<def_tag_object,tag object>>.
+
[[def_pickaxe]]pickaxe::
The term <<def_pickaxe,pickaxe>> refers to an option to the diffcore
routines that help select changes that add or delete a given text
@@ -608,6 +638,20 @@
An <<def_object,object>> used to temporarily store the contents of a
<<def_dirty,dirty>> working directory and the index for future reuse.
+[[def_special_ref]]special ref::
+ A ref that has different semantics than normal refs. These refs can be
+ accessed via normal Git commands but may not behave the same as a
+ normal ref in some cases.
++
+The following special refs are known to Git:
+
+ - "`FETCH_HEAD`" is written by linkgit:git-fetch[1] or linkgit:git-pull[1]. It
+ may refer to multiple object IDs. Each object ID is annotated with metadata
+ indicating where it was fetched from and its fetch status.
+
+ - "`MERGE_HEAD`" is written by linkgit:git-merge[1] when resolving merge
+ conflicts. It contains all commit IDs which are being merged.
+
[[def_submodule]]submodule::
A <<def_repository,repository>> that holds the history of a
separate project inside another repository (the latter of
@@ -620,12 +664,11 @@
copies of) commit objects of the contained submodules.
[[def_symref]]symref::
- Symbolic reference: instead of containing the <<def_SHA1,SHA-1>>
- id itself, it is of the format 'ref: refs/some/thing' and when
- referenced, it recursively dereferences to this reference.
- '<<def_HEAD,HEAD>>' is a prime example of a symref. Symbolic
- references are manipulated with the linkgit:git-symbolic-ref[1]
- command.
+ Symbolic reference: instead of containing the <<def_SHA1,SHA-1>> id
+ itself, it is of the format 'ref: refs/some/thing' and when referenced,
+ it recursively <<def_dereference,dereferences>> to this reference.
+ '<<def_HEAD,HEAD>>' is a prime example of a symref. Symbolic references
+ are manipulated with the linkgit:git-symbolic-ref[1] command.
[[def_tag]]tag::
A <<def_ref,ref>> under `refs/tags/` namespace that points to an
@@ -661,11 +704,11 @@
<<def_tree,tree>> is equivalent to a <<def_directory,directory>>.
[[def_tree-ish]]tree-ish (also treeish)::
- A <<def_tree_object,tree object>> or an <<def_object,object>>
- that can be recursively dereferenced to a tree object.
- Dereferencing a <<def_commit_object,commit object>> yields the
- tree object corresponding to the <<def_revision,revision>>'s
- top <<def_directory,directory>>.
+ A <<def_tree_object,tree object>> or an <<def_object,object>> that can
+ be recursively <<def_dereference,dereferenced>> to a tree object.
+ Dereferencing a <<def_commit_object,commit object>> yields the tree
+ object corresponding to the <<def_revision,revision>>'s top
+ <<def_directory,directory>>.
The following are all tree-ishes:
a <<def_commit-ish,commit-ish>>,
a tree object,
@@ -674,6 +717,18 @@
object,
etc.
+[[def_unborn]]unborn::
+ The <<def_HEAD,HEAD>> can point at a <<def_branch,branch>>
+ that does not yet exist and that does not have any commit on
+ it yet, and such a branch is called an unborn branch. The
+ most typical way users encounter an unborn branch is by
+ creating a repository anew without cloning from elsewhere.
+ The HEAD would point at the 'main' (or 'master', depending
+ on your configuration) branch that is yet to be born. Also
+ some operations can get you on an unborn branch with their
+ <<def_orphan,orphan>> option.
+
+
[[def_unmerged_index]]unmerged index::
An <<def_index,index>> which contains unmerged
<<def_index_entry,index entries>>.
diff --git a/Documentation/howto/coordinate-embargoed-releases.txt b/Documentation/howto/coordinate-embargoed-releases.txt
index e653775..b9cb95e 100644
--- a/Documentation/howto/coordinate-embargoed-releases.txt
+++ b/Documentation/howto/coordinate-embargoed-releases.txt
@@ -145,7 +145,7 @@
The first step is to https://github.com/git/git/security/advisories/new[open
an advisory]. Technically, this is not necessary. However, it is the most
-convenient way to obtain the CVE number and it give us a private repository
+convenient way to obtain the CVE number and it gives us a private repository
associated with it that can be used to collaborate on a fix.
Notifying the Linux distributions
diff --git a/Documentation/howto/keep-canonical-history-correct.txt b/Documentation/howto/keep-canonical-history-correct.txt
index 35d48ef..5f800fd 100644
--- a/Documentation/howto/keep-canonical-history-correct.txt
+++ b/Documentation/howto/keep-canonical-history-correct.txt
@@ -213,4 +213,4 @@
B0--B1---------B2
------------
-See also http://git-blame.blogspot.com/2013/09/fun-with-first-parent-history.html
+See also https://git-blame.blogspot.com/2013/09/fun-with-first-parent-history.html
diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt
index d07c6d4..013014b 100644
--- a/Documentation/howto/maintain-git.txt
+++ b/Documentation/howto/maintain-git.txt
@@ -104,7 +104,7 @@
files in mbox format).
- Write his own patches to address issues raised on the list but
- nobody has stepped up solving. Send it out just like other
+ nobody has stepped up to solve. Send it out just like other
contributors do, and pick them up just like patches from other
contributors (see above).
@@ -411,13 +411,13 @@
A merge of two topics may not textually conflict but still have
conflict at the semantic level. A classic example is for one topic
-to rename an variable and all its uses, while another topic adds a
+to rename a variable and all its uses, while another topic adds a
new use of the variable under its old name. When these two topics
are merged together, the reference to the variable newly added by
the latter topic will still use the old name in the result.
The Meta/Reintegrate script that is used by redo-jch and redo-seen
-scripts implements a crude but usable way to work this issue around.
+scripts implements a crude but usable way to work around this issue.
When the script merges branch $X, it checks if "refs/merge-fix/$X"
exists, and if so, the effect of it is squashed into the result of
the mechanical merge. In other words,
diff --git a/Documentation/howto/update-hook-example.txt b/Documentation/howto/update-hook-example.txt
index 151ee84..4e727de 100644
--- a/Documentation/howto/update-hook-example.txt
+++ b/Documentation/howto/update-hook-example.txt
@@ -100,7 +100,7 @@
if test -f "$allowed_users_file"
then
- rc=$(cat $allowed_users_file | grep -v '^#' | grep -v '^$' |
+ rc=$(grep -Ev '^(#|$)' $allowed_users_file |
while read heads user_patterns
do
# does this rule apply to us?
@@ -138,7 +138,7 @@
if test -f "$allowed_groups_file"
then
- rc=$(cat $allowed_groups_file | grep -v '^#' | grep -v '^$' |
+ rc=$(grep -Ev '^(#|$)' $allowed_groups_file |
while read heads group_patterns
do
# does this rule apply to us?
diff --git a/Documentation/howto/use-git-daemon.txt b/Documentation/howto/use-git-daemon.txt
index 7af2e52..2cad9b3 100644
--- a/Documentation/howto/use-git-daemon.txt
+++ b/Documentation/howto/use-git-daemon.txt
@@ -4,7 +4,7 @@
=====================
Git can be run in inetd mode and in stand alone mode. But all you want is
-let a coworker pull from you, and therefore need to set up a Git server
+to let a coworker pull from you, and therefore need to set up a Git server
real quick, right?
Note that git-daemon is not really chatty at the moment, especially when
diff --git a/Documentation/howto/using-merge-subtree.txt b/Documentation/howto/using-merge-subtree.txt
index a499a94..3bd581a 100644
--- a/Documentation/howto/using-merge-subtree.txt
+++ b/Documentation/howto/using-merge-subtree.txt
@@ -11,7 +11,7 @@
How to use the subtree merge strategy
=====================================
-There are situations where you want to include contents in your project
+There are situations where you want to include content in your project
from an independently developed project. You can just pull from the
other project as long as there are no conflicting paths.
diff --git a/Documentation/i18n.txt b/Documentation/i18n.txt
index 6c6baee..3a866af 100644
--- a/Documentation/i18n.txt
+++ b/Documentation/i18n.txt
@@ -34,7 +34,7 @@
does not forbid it. However, there are a few things to keep in
mind.
-. 'git commit' and 'git commit-tree' issues
+. 'git commit' and 'git commit-tree' issue
a warning if the commit log message given to it does not look
like a valid UTF-8 string, unless you explicitly say your
project uses a legacy encoding. The way to say this is to
@@ -46,7 +46,7 @@
------------
+
Commit objects created with the above setting record the value
-of `i18n.commitEncoding` in its `encoding` header. This is to
+of `i18n.commitEncoding` in their `encoding` header. This is to
help other people who look at them later. Lack of this header
implies that the commit log message is encoded in UTF-8.
diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt
index d8f7cd7..3eaefc4 100644
--- a/Documentation/merge-options.txt
+++ b/Documentation/merge-options.txt
@@ -191,7 +191,7 @@
--autostash::
--no-autostash::
Automatically create a temporary stash entry before the operation
- begins, record it in the special ref `MERGE_AUTOSTASH`
+ begins, record it in the ref `MERGE_AUTOSTASH`
and apply it after the operation ends. This means
that you can run the operation on a dirty worktree. However, use
with care: the final stash application after a successful
diff --git a/Documentation/mergetools/vimdiff.txt b/Documentation/mergetools/vimdiff.txt
index 2d631e9..befa86d 100644
--- a/Documentation/mergetools/vimdiff.txt
+++ b/Documentation/mergetools/vimdiff.txt
@@ -32,10 +32,10 @@
- `+` is used to "open a new tab"
- `,` is used to "open a new vertical split"
- `/` is used to "open a new horizontal split"
- - `@` is used to indicate which is the file containing the final version after
+ - `@` is used to indicate the file containing the final version after
solving the conflicts. If not present, `MERGED` will be used by default.
-The precedence of the operators is this one (you can use parentheses to change
+The precedence of the operators is as follows (you can use parentheses to change
it):
`@` > `+` > `/` > `,`
@@ -162,7 +162,7 @@
| REMOTE | |
---------------------------------------------
....
-Note how in the third tab definition we need to use parenthesis to make `,`
+Note how in the third tab definition we need to use parentheses to make `,`
have precedence over `/`.
--
@@ -177,7 +177,8 @@
When using these variants, in order to specify a custom layout you will have to
set configuration variables `mergetool.gvimdiff.layout` and
-`mergetool.nvimdiff.layout` instead of `mergetool.vimdiff.layout`
+`mergetool.nvimdiff.layout` instead of `mergetool.vimdiff.layout` (though the
+latter will be used as fallback if the variant-specific one is not set).
In addition, for backwards compatibility with previous Git versions, you can
also append `1`, `2` or `3` to either `vimdiff` or any of the variants (ex:
diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index 3b71334..8ee940b 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -122,7 +122,9 @@
- Placeholders that expand to a single literal character:
'%n':: newline
'%%':: a raw '%'
-'%x00':: print a byte from a hex code
+'%x00':: '%x' followed by two hexadecimal digits is replaced with a
+ byte with the hexadecimal digits' value (we will call this
+ "literal formatting code" in the rest of this document).
- Placeholders that affect formatting of later placeholders:
'%Cred':: switch color to red
@@ -222,13 +224,30 @@
linkgit:git-rev-list[1])
'%d':: ref names, like the --decorate option of linkgit:git-log[1]
'%D':: ref names without the " (", ")" wrapping.
-'%(describe[:options])':: human-readable name, like
- linkgit:git-describe[1]; empty string for
- undescribable commits. The `describe` string
- may be followed by a colon and zero or more
- comma-separated options. Descriptions can be
- inconsistent when tags are added or removed at
- the same time.
+'%(decorate[:<options>])'::
+ref names with custom decorations. The `decorate` string may be followed by a
+colon and zero or more comma-separated options. Option values may contain
+literal formatting codes. These must be used for commas (`%x2C`) and closing
+parentheses (`%x29`), due to their role in the option syntax.
++
+** 'prefix=<value>': Shown before the list of ref names. Defaults to "{nbsp}`(`".
+** 'suffix=<value>': Shown after the list of ref names. Defaults to "`)`".
+** 'separator=<value>': Shown between ref names. Defaults to "`,`{nbsp}".
+** 'pointer=<value>': Shown between HEAD and the branch it points to, if any.
+ Defaults to "{nbsp}`->`{nbsp}".
+** 'tag=<value>': Shown before tag names. Defaults to "`tag:`{nbsp}".
+
++
+For example, to produce decorations with no wrapping
+or tag annotations, and spaces as separators:
++
+`%(decorate:prefix=,suffix=,tag=,separator= )`
+
+'%(describe[:<options>])'::
+human-readable name, like linkgit:git-describe[1]; empty string for
+undescribable commits. The `describe` string may be followed by a colon and
+zero or more comma-separated options. Descriptions can be inconsistent when
+tags are added or removed at the same time.
+
** 'tags[=<bool-value>]': Instead of only considering annotated tags,
consider lightweight tags as well.
@@ -281,13 +300,11 @@
'%gE':: reflog identity email (respecting .mailmap, see
linkgit:git-shortlog[1] or linkgit:git-blame[1])
'%gs':: reflog subject
-'%(trailers[:options])':: display the trailers of the body as
- interpreted by
- linkgit:git-interpret-trailers[1]. The
- `trailers` string may be followed by a colon
- and zero or more comma-separated options.
- If any option is provided multiple times the
- last occurrence wins.
+'%(trailers[:<options>])'::
+display the trailers of the body as interpreted by
+linkgit:git-interpret-trailers[1]. The `trailers` string may be followed by
+a colon and zero or more comma-separated options. If any option is provided
+multiple times, the last occurrence wins.
+
** 'key=<key>': only show trailers with specified <key>. Matching is done
case-insensitively and trailing colon is optional. If option is
@@ -299,9 +316,8 @@
`Reviewed-by`.
** 'only[=<bool>]': select whether non-trailer lines from the trailer
block should be included.
-** 'separator=<sep>': specify a separator inserted between trailer
- lines. When this option is not given each trailer line is
- terminated with a line feed character. The string <sep> may contain
+** 'separator=<sep>': specify the separator inserted between trailer
+ lines. Defaults to a line feed character. The string <sep> may contain
the literal formatting codes described above. To use comma as
separator one must use `%x2C` as it would otherwise be parsed as
next option. E.g., `%(trailers:key=Ticket,separator=%x2C )`
@@ -312,10 +328,9 @@
`%(trailers:only,unfold=true)` unfolds and shows all trailer lines.
** 'keyonly[=<bool>]': only show the key part of the trailer.
** 'valueonly[=<bool>]': only show the value part of the trailer.
-** 'key_value_separator=<sep>': specify a separator inserted between
- trailer lines. When this option is not given each trailer key-value
- pair is separated by ": ". Otherwise it shares the same semantics
- as 'separator=<sep>' above.
+** 'key_value_separator=<sep>': specify the separator inserted between
+ the key and value of each trailer. Defaults to ": ". Otherwise it
+ shares the same semantics as 'separator=<sep>' above.
NOTE: Some placeholders may depend on other options given to the
revision traversal engine. For example, the `%g*` reflog options will
diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt
index dc685be..23888cd 100644
--- a/Documentation/pretty-options.txt
+++ b/Documentation/pretty-options.txt
@@ -48,7 +48,7 @@
--expand-tabs::
--no-expand-tabs::
Perform a tab expansion (replace each tab with enough spaces
- to fill to the next display column that is multiple of '<n>')
+ to fill to the next display column that is a multiple of '<n>')
in the log message before showing it in the output.
`--expand-tabs` is a short-hand for `--expand-tabs=8`, and
`--no-expand-tabs` is a short-hand for `--expand-tabs=0`,
@@ -73,7 +73,7 @@
With an optional '<ref>' argument, use the ref to find the notes
to display. The ref can specify the full refname when it begins
with `refs/notes/`; when it begins with `notes/`, `refs/` and otherwise
-`refs/notes/` is prefixed to form a full name of the ref.
+`refs/notes/` is prefixed to form the full name of the ref.
+
Multiple --notes options can be combined to control which notes are
being displayed. Examples: "--notes=foo" will show only notes from
@@ -87,6 +87,10 @@
"--notes --notes=foo --no-notes --notes=bar" will only show notes
from "refs/notes/bar".
+--show-notes-by-default::
+ Show the default notes unless options for displaying specific
+ notes are given.
+
--show-notes[=<ref>]::
--[no-]standard-notes::
These options are deprecated. Use the above --notes/--no-notes
diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt
index 95a7390..c718f79 100644
--- a/Documentation/pull-fetch-param.txt
+++ b/Documentation/pull-fetch-param.txt
@@ -71,7 +71,7 @@
Unlike when pushing with linkgit:git-push[1], any updates outside of
`refs/{tags,heads}/*` will be accepted without `+` in the refspec (or
`--force`), whether that's swapping e.g. a tree object for a blob, or
-a commit for another commit that's doesn't have the previous commit as
+a commit for another commit that doesn't have the previous commit as
an ancestor etc.
+
Unlike when pushing with linkgit:git-push[1], there is no
@@ -80,7 +80,7 @@
+
As with pushing with linkgit:git-push[1], all of the rules described
above about what's not allowed as an update can be overridden by
-adding an the optional leading `+` to a refspec (or using `--force`
+adding an optional leading `+` to a refspec (or using the `--force`
command line option). The only exception to this is that no amount of
forcing will make the `refs/heads/*` namespace accept a non-commit
object.
@@ -88,7 +88,7 @@
[NOTE]
When the remote branch you want to fetch is known to
be rewound and rebased regularly, it is expected that
-its new tip will not be descendant of its previous tip
+its new tip will not be a descendant of its previous tip
(as stored in your remote-tracking branch the last time
you fetched). You would want
to use the `+` sign to indicate non-fast-forward updates
diff --git a/Documentation/ref-storage-format.txt b/Documentation/ref-storage-format.txt
new file mode 100644
index 0000000..14fff8a
--- /dev/null
+++ b/Documentation/ref-storage-format.txt
@@ -0,0 +1,3 @@
+* `files` for loose files with packed-refs. This is the default.
+* `reftable` for the reftable format. This format is experimental and its
+ internals are subject to change.
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index a4a0cb9..00ccf68 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -56,7 +56,7 @@
error to use this option unless `--walk-reflogs` is in use.
--grep=<pattern>::
- Limit the commits output to ones with log message that
+ Limit the commits output to ones with a log message that
matches the specified pattern (regular expression). With
more than one `--grep=<pattern>`, commits whose message
matches any of the given patterns are chosen (but see
@@ -72,7 +72,7 @@
instead of ones that match at least one.
--invert-grep::
- Limit the commits output to ones with log message that do not
+ Limit the commits output to ones with a log message that do not
match the pattern specified with `--grep=<pattern>`.
-i::
@@ -151,6 +151,10 @@
--not::
Reverses the meaning of the '{caret}' prefix (or lack thereof)
for all following revision specifiers, up to the next `--not`.
+ When used on the command line before --stdin, the revisions passed
+ through stdin will not be affected by it. Conversely, when passed
+ via standard input, the revisions passed on the command line will
+ not be affected by it.
--all::
Pretend as if all the refs in `refs/`, along with `HEAD`, are
@@ -240,7 +244,9 @@
them from standard input as well. This accepts commits and
pseudo-options like `--all` and `--glob=`. When a `--` separator
is seen, the following input is treated as paths and used to
- limit the result.
+ limit the result. Flags like `--not` which are read via standard input
+ are only respected for arguments passed in the same way and will not
+ influence any subsequent command line arguments.
ifdef::git-rev-list[]
--quiet::
@@ -310,12 +316,12 @@
With `--pretty` format other than `oneline` and `reference` (for obvious reasons),
this causes the output to have two extra lines of information
taken from the reflog. The reflog designator in the output may be shown
-as `ref@{Nth}` (where `Nth` is the reverse-chronological index in the
-reflog) or as `ref@{timestamp}` (with the timestamp for that entry),
+as `ref@{<Nth>}` (where _<Nth>_ is the reverse-chronological index in the
+reflog) or as `ref@{<timestamp>}` (with the _<timestamp>_ for that entry),
depending on a few rules:
+
--
-1. If the starting point is specified as `ref@{Nth}`, show the index
+1. If the starting point is specified as `ref@{<Nth>}`, show the index
format.
+
2. If the starting point was specified as `ref@{now}`, show the
@@ -335,8 +341,11 @@
Under `--pretty=reference`, this information will not be shown at all.
--merge::
- After a failed merge, show refs that touch files having a
- conflict and don't exist on all heads to merge.
+ Show commits touching conflicted paths in the range `HEAD...<other>`,
+ where `<other>` is the first existing pseudoref in `MERGE_HEAD`,
+ `CHERRY_PICK_HEAD`, `REVERT_HEAD` or `REBASE_HEAD`. Only works
+ when the index has unmerged entries. This option can be used to show
+ relevant commits when resolving conflicts from a 3-way merge.
--boundary::
Output excluded boundary commits. Boundary commits are
@@ -941,10 +950,10 @@
+
The form '--filter=blob:none' omits all blobs.
+
-The form '--filter=blob:limit=<n>[kmg]' omits blobs larger than n bytes
-or units. n may be zero. The suffixes k, m, and g can be used to name
-units in KiB, MiB, or GiB. For example, 'blob:limit=1k' is the same
-as 'blob:limit=1024'.
+The form '--filter=blob:limit=<n>[kmg]' omits blobs of size at least n
+bytes or units. n may be zero. The suffixes k, m, and g can be used
+to name units in KiB, MiB, or GiB. For example, 'blob:limit=1k'
+is the same as 'blob:limit=1024'.
+
The form '--filter=object:type=(tag|commit|tree|blob)' omits all objects
which are not of the requested type.
@@ -1013,6 +1022,10 @@
+
The form '--missing=print' is like 'allow-any', but will also print a
list of the missing objects. Object IDs are prefixed with a ``?'' character.
++
+If some tips passed to the traversal are missing, they will be
+considered as missing too, and the traversal will ignore them. In case
+we cannot get their Object ID though, an error will be raised.
--exclude-promisor-objects::
(For internal use only.) Prefilter object traversal at
diff --git a/Documentation/signoff-option.txt b/Documentation/signoff-option.txt
index 12aa233..d98758f 100644
--- a/Documentation/signoff-option.txt
+++ b/Documentation/signoff-option.txt
@@ -9,7 +9,7 @@
the committer has the rights to submit the work under the
project's license or agrees to some contributor representation,
such as a Developer Certificate of Origin.
- (See http://developercertificate.org for the one used by the
+ (See https://developercertificate.org for the one used by the
Linux kernel and Git projects.) Consult the documentation or
leadership of the project to which you're contributing to
understand how the signoffs are used in that project.
diff --git a/Documentation/technical/api-index-skel.txt b/Documentation/technical/api-index-skel.txt
index eda8c19..7780a76 100644
--- a/Documentation/technical/api-index-skel.txt
+++ b/Documentation/technical/api-index-skel.txt
@@ -1,7 +1,7 @@
Git API Documents
=================
-Git has grown a set of internal API over time. This collection
+Git has grown a set of internal APIs over time. This collection
documents them.
////////////////////////////////////////////////////////////////
diff --git a/Documentation/technical/api-simple-ipc.txt b/Documentation/technical/api-simple-ipc.txt
index d44ada9..c4fb152 100644
--- a/Documentation/technical/api-simple-ipc.txt
+++ b/Documentation/technical/api-simple-ipc.txt
@@ -2,7 +2,7 @@
==============
The Simple-IPC API is a collection of `ipc_` prefixed library routines
-and a basic communication protocol that allow an IPC-client process to
+and a basic communication protocol that allows an IPC-client process to
send an application-specific IPC-request message to an IPC-server
process and receive an application-specific IPC-response message.
@@ -20,12 +20,12 @@
The IPC-client routines within a client application process connect
to the IPC-server and send a request message and wait for a response.
-When received, the response is returned back the caller.
+When received, the response is returned back to the caller.
For example, the `fsmonitor--daemon` feature will be built as a server
application on top of the IPC-server library routines. It will have
threads watching for file system events and a thread pool waiting for
-client connections. Clients, such as `git status` will request a list
+client connections. Clients, such as `git status`, will request a list
of file system events since a point in time and the server will
respond with a list of changed files and directories. The formats of
the request and response are application-specific; the IPC-client and
@@ -37,7 +37,7 @@
The Simple-IPC mechanism differs from the existing `sub-process.c`
model (Documentation/technical/long-running-process-protocol.txt) and
-used by applications like Git-LFS. In the LFS-style sub-process model
+used by applications like Git-LFS. In the LFS-style sub-process model,
the helper is started by the foreground process, communication happens
via a pair of file descriptors bound to the stdin/stdout of the
sub-process, the sub-process only serves the current foreground
@@ -102,4 +102,4 @@
response, and disconnect. It is a one round trip facility for
querying the server. The Simple-IPC routines hide the socket,
named pipe, and thread pool details and allow the application
-layer to focus on the application at hand.
+layer to focus on the task at hand.
diff --git a/Documentation/technical/bitmap-format.txt b/Documentation/technical/bitmap-format.txt
index c2e652b..f5d2009 100644
--- a/Documentation/technical/bitmap-format.txt
+++ b/Documentation/technical/bitmap-format.txt
@@ -114,7 +114,7 @@
* N entries with compressed bitmaps, one for each indexed commit
+
-Where `N` is the total amount of entries in this bitmap index.
+Where `N` is the total number of entries in this bitmap index.
Each entry contains the following:
** {empty}
@@ -126,7 +126,7 @@
** {empty}
1-byte XOR-offset: ::
The xor offset used to compress this bitmap. For an entry
- in position `x`, a XOR offset of `y` means that the actual
+ in position `x`, an XOR offset of `y` means that the actual
bitmap representing this commit is composed by XORing the
bitmap for this entry with the bitmap in entry `x-y` (i.e.
the bitmap `y` entries before this one).
@@ -239,7 +239,7 @@
For a `.bitmap` containing `nr_entries` reachability bitmaps, the table
contains a list of `nr_entries` <commit_pos, offset, xor_row> triplets
-(sorted in the ascending order of `commit_pos`). The content of i'th
+(sorted in the ascending order of `commit_pos`). The content of the i'th
triplet is -
* {empty}
diff --git a/Documentation/technical/commit-graph.txt b/Documentation/technical/commit-graph.txt
index 86fed0d..2c26e95 100644
--- a/Documentation/technical/commit-graph.txt
+++ b/Documentation/technical/commit-graph.txt
@@ -136,7 +136,7 @@
- Commit grafts and replace objects can change the shape of the commit
history. The latter can also be enabled/disabled on the fly using
- `--no-replace-objects`. This leads to difficultly storing both possible
+ `--no-replace-objects`. This leads to difficulty storing both possible
interpretations of a commit id, especially when computing generation
numbers. The commit-graph will not be read or written when
replace-objects or grafts are present.
diff --git a/Documentation/technical/parallel-checkout.txt b/Documentation/technical/parallel-checkout.txt
index 47c9b61..b4a144e 100644
--- a/Documentation/technical/parallel-checkout.txt
+++ b/Documentation/technical/parallel-checkout.txt
@@ -63,7 +63,7 @@
contention. A `perf` profiling indicated that around 20% of the runtime
during a local Linux clone (on an SSD) was spent in locking functions.
For this reason this approach was rejected in favor of using multiple
-child processes, which led to a better performance.
+child processes, which led to better performance.
Multi-Process Solution
----------------------
@@ -126,7 +126,7 @@
* W5: Writes the result to the file descriptor opened at W2.
-* W6: Calls `fstat()` or lstat()` on the just-written path, and sends
+* W6: Calls `fstat()` or `lstat()` on the just-written path, and sends
the result back to the main process, together with the end status of
the operation and the item's identification number.
@@ -148,7 +148,7 @@
- First, it updates the in-memory index with the `lstat()` information
sent by the workers. (This must be done first as this information
- might me required in the following step.)
+ might be required in the following step.)
- Then it writes the items which collided on disk (i.e. items marked
with `PC_ITEM_COLLIDED`). More on this below.
@@ -185,7 +185,7 @@
process must remove all files that prevent this entry from being written
(before enqueueing it). This includes any non-directory file in the
leading path of the entry. Later, when a worker gets assigned the entry,
-it looks again for the non-directories files and for an already existing
+it looks again for the non-directory files and for an already existing
file at the entry's path. If any of these checks finds something, the
worker knows that there was a path collision.
@@ -232,7 +232,7 @@
Ineligible entries are checked out by the classic sequential codepath
*before* spawning workers.
-Note: submodules's files are also eligible for parallel checkout (as
+Note: submodules' files are also eligible for parallel checkout (as
long as they don't fall into any of the excluding categories mentioned
above). But since each submodule is checked out in its own child
process, we don't mix the superproject's and the submodules' files in
diff --git a/Documentation/technical/partial-clone.txt b/Documentation/technical/partial-clone.txt
index 92fcee2..cd948b0 100644
--- a/Documentation/technical/partial-clone.txt
+++ b/Documentation/technical/partial-clone.txt
@@ -3,7 +3,7 @@
The "Partial Clone" feature is a performance optimization for Git that
allows Git to function without having a complete copy of the repository.
-The goal of this work is to allow Git better handle extremely large
+The goal of this work is to allow Git to better handle extremely large
repositories.
During clone and fetch operations, Git downloads the complete contents
@@ -256,7 +256,7 @@
- Dynamic object fetching currently uses the existing pack protocol V0
which means that each object is requested via fetch-pack. The server
will send a full set of info/refs when the connection is established.
- If there are large number of refs, this may incur significant overhead.
+ If there are a large number of refs, this may incur significant overhead.
Future Work
@@ -265,7 +265,7 @@
- Improve the way to specify the order in which promisor remotes are
tried.
+
-For example this could allow to specify explicitly something like:
+For example this could allow specifying explicitly something like:
"When fetching from this remote, I want to use these promisor remotes
in this order, though, when pushing or fetching to that remote, I want
to use those promisor remotes in that order."
@@ -322,7 +322,7 @@
[a] expensive-to-modify list of missing objects: Earlier in the design of
partial clone we discussed the need for a single list of missing objects.
- This would essentially be a sorted linear list of OIDs that the were
+ This would essentially be a sorted linear list of OIDs that were
omitted by the server during a clone or subsequent fetches.
This file would need to be loaded into memory on every object lookup.
diff --git a/Documentation/technical/racy-git.txt b/Documentation/technical/racy-git.txt
index ceda4bb..59bea66 100644
--- a/Documentation/technical/racy-git.txt
+++ b/Documentation/technical/racy-git.txt
@@ -11,7 +11,7 @@
"virtual" in the sense that it does not necessarily have to, and
often does not, match the files in the working tree.
-There are cases Git needs to examine the differences between the
+There are cases where Git needs to examine the differences between the
virtual working tree state in the index and the files in the
working tree. The most obvious case is when the user asks `git
diff` (or its low level implementation, `git diff-files`) or
@@ -165,9 +165,9 @@
In order to avoid the above runtime penalty, post 1.4.2 Git used
to have a code that made sure the index file
-got timestamp newer than the youngest files in the index when
-there are many young files with the same timestamp as the
-resulting index file would otherwise would have by waiting
+got a timestamp newer than the youngest files in the index when
+there were many young files with the same timestamp as the
+resulting index file otherwise would have by waiting
before finishing writing the index file out.
I suspected that in practice the situation where many paths in the
@@ -190,7 +190,7 @@
however, the initial computation of all object names in the
index takes more than one second, and the index file is written
out after all that happens. Therefore the timestamp of the
-index file will be more than one seconds later than the
+index file will be more than one second later than the
youngest file in the working tree. This means that in these
cases there actually will not be any racily clean entry in
the resulting index.
diff --git a/Documentation/technical/reftable.txt b/Documentation/technical/reftable.txt
index 6a67cc4..dd0b37c 100644
--- a/Documentation/technical/reftable.txt
+++ b/Documentation/technical/reftable.txt
@@ -46,7 +46,7 @@
Storage in the file is organized into variable sized blocks. Prefix
compression is used within a single block to reduce disk space. Block
-size and alignment is tunable by the writer.
+size and alignment are tunable by the writer.
Performance
^^^^^^^^^^^
@@ -115,7 +115,7 @@
Varint encoding is identical to the ofs-delta encoding method used
within pack files.
-Decoder works such as:
+Decoder works as follows:
....
val = buf[ptr] & 0x7f
@@ -175,7 +175,7 @@
footer
....
-in a log-only file the first log block immediately follows the file
+In a log-only file, the first log block immediately follows the file
header, without padding to block alignment.
Block size
@@ -247,7 +247,7 @@
....
The header is identical to `version_number=1`, with the 4-byte hash ID
-("sha1" for SHA1 and "s256" for SHA-256) append to the header.
+("sha1" for SHA1 and "s256" for SHA-256) appended to the header.
For maximum backward compatibility, it is recommended to use version 1 when
writing SHA1 reftables.
@@ -288,7 +288,7 @@
`restart_count` to binary search between restarts before starting a
linear scan.
-Exactly `restart_count` 3-byte `restart_offset` values precedes the
+Exactly `restart_count` 3-byte `restart_offset` values precede the
`restart_count`. Offsets are relative to the start of the block and
refer to the first byte of any `ref_record` whose name has not been
prefix compressed. Entries in the `restart_offset` list must be sorted,
diff --git a/Documentation/technical/repository-version.txt b/Documentation/technical/repository-version.txt
index 8ef664b..4728142 100644
--- a/Documentation/technical/repository-version.txt
+++ b/Documentation/technical/repository-version.txt
@@ -96,7 +96,13 @@
==== `worktreeConfig`
If set, by default "git config" reads from both "config" and
-"config.worktree" file from GIT_DIR in that order. In
+"config.worktree" files from GIT_DIR in that order. In
multiple working directory mode, "config" file is shared while
"config.worktree" is per-working directory (i.e., it's in
GIT_COMMON_DIR/worktrees/<id>/config.worktree)
+
+==== `refStorage`
+
+Specifies the file format for the ref database. The valid values are
+`files` (loose references with a packed-refs file) and `reftable` (see
+Documentation/technical/reftable.txt).
diff --git a/Documentation/technical/rerere.txt b/Documentation/technical/rerere.txt
index be58f1b..580f233 100644
--- a/Documentation/technical/rerere.txt
+++ b/Documentation/technical/rerere.txt
@@ -60,7 +60,7 @@
what AB and AC wanted to do.
As branch AC2 refers to the same commit as AC, the above implies that
-this is also compatible what AB and AC2 wanted to do.
+this is also compatible with what AB and AC2 wanted to do.
By extension, this means that rerere should recognize that the above
conflicts are the same. To do this, the labels on the conflict
@@ -76,7 +76,7 @@
Sorting hunks
~~~~~~~~~~~~~
-As before, lets imagine that a common ancestor had a file with line A
+As before, let's imagine that a common ancestor had a file with line A
its early part, and line X in its late part. And then four branches
are forked that do these things:
@@ -145,7 +145,7 @@
Nested conflicts are handled very similarly to "simple" conflicts.
Similar to simple conflicts, the conflict is first normalized by
stripping the labels from conflict markers, stripping the common ancestor
-version, and the sorting the conflict hunks, both for the outer and the
+version, and sorting the conflict hunks, both for the outer and the
inner conflict. This is done recursively, so any number of nested
conflicts can be handled.
diff --git a/Documentation/technical/unit-tests.txt b/Documentation/technical/unit-tests.txt
new file mode 100644
index 0000000..206037f
--- /dev/null
+++ b/Documentation/technical/unit-tests.txt
@@ -0,0 +1,240 @@
+= Unit Testing
+
+In our current testing environment, we spend a significant amount of effort
+crafting end-to-end tests for error conditions that could easily be captured by
+unit tests (or we simply forgo some hard-to-setup and rare error conditions).
+Unit tests additionally provide stability to the codebase and can simplify
+debugging through isolation. Writing unit tests in pure C, rather than with our
+current shell/test-tool helper setup, simplifies test setup, simplifies passing
+data around (no shell-isms required), and reduces testing runtime by not
+spawning a separate process for every test invocation.
+
+We believe that a large body of unit tests, living alongside the existing test
+suite, will improve code quality for the Git project.
+
+== Definitions
+
+For the purposes of this document, we'll use *test framework* to refer to
+projects that support writing test cases and running tests within the context
+of a single executable. *Test harness* will refer to projects that manage
+running multiple executables (each of which may contain multiple test cases) and
+aggregating their results.
+
+In reality, these terms are not strictly defined, and many of the projects
+discussed below contain features from both categories.
+
+For now, we will evaluate projects solely on their framework features. Since we
+are relying on having TAP output (see below), we can assume that any framework
+can be made to work with a harness that we can choose later.
+
+
+== Summary
+
+We believe the best way forward is to implement a custom TAP framework for the
+Git project. We use a version of the framework originally proposed in
+https://lore.kernel.org/git/c902a166-98ce-afba-93f2-ea6027557176@gmail.com/[1].
+
+See the <<framework-selection,Framework Selection>> section below for the
+rationale behind this decision.
+
+
+== Choosing a test harness
+
+During upstream discussion, it was occasionally noted that `prove` provides many
+convenient features, such as scheduling slower tests first, or re-running
+previously failed tests.
+
+While we already support the use of `prove` as a test harness for the shell
+tests, it is not strictly required. The t/Makefile allows running shell tests
+directly (though with interleaved output if parallelism is enabled). Git
+developers who wish to use `prove` as a more advanced harness can do so by
+setting DEFAULT_TEST_TARGET=prove in their config.mak.
+
+We will follow a similar approach for unit tests: by default the test
+executables will be run directly from the t/Makefile, but `prove` can be
+configured with DEFAULT_UNIT_TEST_TARGET=prove.
+
+
+[[framework-selection]]
+== Framework selection
+
+There are a variety of features we can use to rank the candidate frameworks, and
+those features have different priorities:
+
+* Critical features: we probably won't consider a framework without these
+** Can we legally / easily use the project?
+*** <<license,License>>
+*** <<vendorable-or-ubiquitous,Vendorable or ubiquitous>>
+*** <<maintainable-extensible,Maintainable / extensible>>
+*** <<major-platform-support,Major platform support>>
+** Does the project support our bare-minimum needs?
+*** <<tap-support,TAP support>>
+*** <<diagnostic-output,Diagnostic output>>
+*** <<runtime-skippable-tests,Runtime-skippable tests>>
+* Nice-to-have features:
+** <<parallel-execution,Parallel execution>>
+** <<mock-support,Mock support>>
+** <<signal-error-handling,Signal & error-handling>>
+* Tie-breaker stats
+** <<project-kloc,Project KLOC>>
+** <<adoption,Adoption>>
+
+[[license]]
+=== License
+
+We must be able to legally use the framework in connection with Git. As Git is
+licensed only under GPLv2, we must eliminate any LGPLv3, GPLv3, or Apache 2.0
+projects.
+
+[[vendorable-or-ubiquitous]]
+=== Vendorable or ubiquitous
+
+We want to avoid forcing Git developers to install new tools just to run unit
+tests. Any prospective frameworks and harnesses must either be vendorable
+(meaning, we can copy their source directly into Git's repository), or so
+ubiquitous that it is reasonable to expect that most developers will have the
+tools installed already.
+
+[[maintainable-extensible]]
+=== Maintainable / extensible
+
+It is unlikely that any pre-existing project perfectly fits our needs, so any
+project we select will need to be actively maintained and open to accepting
+changes. Alternatively, assuming we are vendoring the source into our repo, it
+must be simple enough that Git developers can feel comfortable making changes as
+needed to our version.
+
+In the comparison table below, "True" means that the framework seems to have
+active developers, that it is simple enough that Git developers can make changes
+to it, and that the project seems open to accepting external contributions (or
+that it is vendorable). "Partial" means that at least one of the above
+conditions holds.
+
+[[major-platform-support]]
+=== Major platform support
+
+At a bare minimum, unit-testing must work on Linux, MacOS, and Windows.
+
+In the comparison table below, "True" means that it works on all three major
+platforms with no issues. "Partial" means that there may be annoyances on one or
+more platforms, but it is still usable in principle.
+
+[[tap-support]]
+=== TAP support
+
+The https://testanything.org/[Test Anything Protocol] is a text-based interface
+that allows tests to communicate with a test harness. It is already used by
+Git's integration test suite. Supporting TAP output is a mandatory feature for
+any prospective test framework.
+
+In the comparison table below, "True" means this is natively supported.
+"Partial" means TAP output must be generated by post-processing the native
+output.
+
+Frameworks that do not have at least Partial support will not be evaluated
+further.
+
+[[diagnostic-output]]
+=== Diagnostic output
+
+When a test case fails, the framework must generate enough diagnostic output to
+help developers find the appropriate test case in source code in order to debug
+the failure.
+
+[[runtime-skippable-tests]]
+=== Runtime-skippable tests
+
+Test authors may wish to skip certain test cases based on runtime circumstances,
+so the framework should support this.
+
+[[parallel-execution]]
+=== Parallel execution
+
+Ideally, we will build up a significant collection of unit test cases, most
+likely split across multiple executables. It will be necessary to run these
+tests in parallel to enable fast develop-test-debug cycles.
+
+In the comparison table below, "True" means that individual test cases within a
+single test executable can be run in parallel. We assume that executable-level
+parallelism can be handled by the test harness.
+
+[[mock-support]]
+=== Mock support
+
+Unit test authors may wish to test code that interacts with objects that may be
+inconvenient to handle in a test (e.g. interacting with a network service).
+Mocking allows test authors to provide a fake implementation of these objects
+for more convenient tests.
+
+[[signal-error-handling]]
+=== Signal & error handling
+
+The test framework should fail gracefully when test cases are themselves buggy
+or when they are interrupted by signals during runtime.
+
+[[project-kloc]]
+=== Project KLOC
+
+The size of the project, in thousands of lines of code as measured by
+https://dwheeler.com/sloccount/[sloccount] (rounded up to the next multiple of
+1,000). As a tie-breaker, we probably prefer a project with fewer LOC.
+
+[[adoption]]
+=== Adoption
+
+As a tie-breaker, we prefer a more widely-used project. We use the number of
+GitHub / GitLab stars to estimate this.
+
+
+=== Comparison
+
+:true: [lime-background]#True#
+:false: [red-background]#False#
+:partial: [yellow-background]#Partial#
+
+:gpl: [lime-background]#GPL v2#
+:isc: [lime-background]#ISC#
+:mit: [lime-background]#MIT#
+:expat: [lime-background]#Expat#
+:lgpl: [lime-background]#LGPL v2.1#
+
+:custom-imp
