diff options
Diffstat (limited to 'Documentation')
33 files changed, 458 insertions, 155 deletions
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index d85c9b5143..4f85a089ef 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -319,14 +319,14 @@ function body: ... git_config(git_default_config, NULL); - if (git_config_get_string_const("user.name", &cfg_name) > 0) + if (git_config_get_string_tmp("user.name", &cfg_name) > 0) printf(_("No name is found in config\n")); else printf(_("Your name: %s\n"), cfg_name); ---- `git_config()` will grab the configuration from config files known to Git and -apply standard precedence rules. `git_config_get_string_const()` will look up +apply standard precedence rules. `git_config_get_string_tmp()` will look up a specific key ("user.name") and give you the value. There are a number of single-key lookup functions like this one; you can see them all (and more info about how to use `git_config()`) in `Documentation/technical/api-config.txt`. diff --git a/Documentation/RelNotes/2.29.0.txt b/Documentation/RelNotes/2.29.0.txt index 06025e8824..a640fbc02f 100644 --- a/Documentation/RelNotes/2.29.0.txt +++ b/Documentation/RelNotes/2.29.0.txt @@ -19,6 +19,42 @@ UI, Workflows & Features configurable to selectively allow or reject object filtering specification used for partial cloning. + * Stop when "sendmail.*" configuration variables are defined, which + could be a mistaken attempt to define "sendemail.*" variables. + + * The existing backends for "git mergetool" based on variants of vim + have been refactored and then support for "nvim" has been added. + + * "git bisect" learns the "--first-parent" option to find the first + breakage along the first-parent chain. + + * "git log --first-parent -p" showed patches only for single-parent + commits on the first-parent chain; the "--first-parent" option has + been made to imply "-m". Use "--no-diff-merges" to restore the + previous behaviour to omit patches for merge commits. + + * The commit labels used to explain each side of conflicted hunks + placed by the sequencer machinery have been made more readable by + humans. + + * The "--batch-size" option of "git multi-pack-index repack" command + is now used to specify that very small packfiles are collected into + one until the total size roughly exceeds it. + + * The recent addition of SHA-256 support is marked as experimental in + the documentation. + + * "git fetch" learned --no-write-fetch-head option to avoid writing + the FETCH_HEAD file. + + * Command line completion (in contrib/) usually omits redundant, + deprecated and/or dangerous options from its output; it learned to + optionally include all of them. + + * The output from the "diff" family of the commands had abbreviated + object names of blobs involved in the patch, but its length was not + affected by the --abbrev option. Now it is. + Performance, Internal Implementation, Development Support etc. @@ -52,10 +88,46 @@ Performance, Internal Implementation, Development Support etc. to a certain degree. It has been renamed to "strvec" to reduce the barrier to adoption. - * The final leg of SHA-256 transition. + * The final leg of SHA-256 transition plus doc updates. Note that + there is no inter-operability between SHA-1 and SHA-256 + repositories yet. * CMake support to build with MSVC for Windows bypassing the Makefile. + * A new helper function has_object() has been introduced to make it + easier to mark object existence checks that do and don't want to + trigger lazy fetches, and a few such checks are converted using it. + + * A no-op replacement function implemented as a C preprocessor macro + does not perform as good a job as one implemented as a "static + inline" function in catching errors in parameters; replace the + former with the latter in <git-compat-util.h> header. + + * Test framework update. + (merge d572f52a64 es/test-cmp-typocatcher later to maint). + + * Updates to "git merge" tests, in preparation for a new merge + strategy backend. + + * midx and commit-graph files now use the byte defined in their file + format specification for identifying the hash function used for + object names. + + * The FETCH_HEAD is now always read from the filesystem regardless of + the ref backend in use, as its format is much richer than the + normal refs, and written directly by "git fetch" as a plain file.. + + * A handful of places in in-tree code still relied on being able to + execute the git subcommands, especially built-ins, in "git-foo" + form, which have been corrected. + + * An unused binary has been discarded, and and a bunch of commands + have been turned into into built-in. + + * A handful of places in in-tree code still relied on being able to + execute the git subcommands, especially built-ins, in "git-foo" + form, which have been corrected. + Fixes since v2.28 ----------------- @@ -102,6 +174,118 @@ Fixes since v2.28 * Doc cleanup around "worktree". (merge dc9c144be5 es/worktree-doc-cleanups later to maint). + * The "git blame --first-parent" option was not documented, but now + it is. + (merge 11bc12ae1e rp/blame-first-parent-doc later to maint). + + * The logic to find the ref transaction hook script attempted to + cache the path to the found hook without realizing that it needed + to keep a copied value, as the API it used returned a transitory + buffer space. This has been corrected. + (merge 09b2aa30c9 ps/ref-transaction-hook later to maint). + + * Recent versions of "git diff-files" shows a diff between the index + and the working tree for "intent-to-add" paths as a "new file" + patch; "git apply --cached" should be able to take "git diff-files" + and should act as an equivalent to "git add" for the path, but the + command failed to do so for such a path. + (merge 4c025c667e rp/apply-cached-with-i-t-a later to maint). + + * "git diff [<tree-ish>] $path" for a $path that is marked with i-t-a + bit was not showing the mode bits from the working tree. + (merge cb0dd22b82 rp/ita-diff-modefix later to maint). + + * Ring buffer with size 4 used for bin-hex translation resulted in a + wrong object name in the sequencer's todo output, which has been + corrected. + (merge 5da69c0dac ak/sequencer-fix-find-uniq-abbrev later to maint). + + * When given more than one target line ranges, "git blame -La,b + -Lc,d" was over-eager to coalesce groups of original lines and + showed incorrect results, which has been corrected. + (merge c2ebaa27d6 jk/blame-coalesce-fix later to maint). + + * The regexp to identify the function boundary for FORTRAN programs + has been updated. + (merge 75c3b6b2e8 pb/userdiff-fortran-update later to maint). + + * A few end-user facing messages have been updated to be + hash-algorithm agnostic. + (merge 4279000d3e jc/object-names-are-not-sha-1 later to maint). + + * "unlink" emulation on MinGW has been optimized. + (merge 680e0b4524 jh/mingw-unlink later to maint). + + * The purpose of "git init --separate-git-dir" is to initialize a + new project with the repository separate from the working tree, + or, in the case of an existing project, to move the repository + (the .git/ directory) out of the working tree. It does not make + sense to use --separate-git-dir with a bare repository for which + there is no working tree, so disallow its use with bare + repositories. + (merge ccf236a23a es/init-no-separate-git-dir-in-bare later to maint). + + * "ls-files -o" mishandled the top-level directory of another git + working tree that hangs in the current git working tree. + (merge ab282aa548 en/dir-nonbare-embedded later to maint). + + * Fix some incorrect UNLEAK() annotations. + (merge 3e19816dc0 jk/unleak-fixes later to maint). + + * Use more buffered I/O where we used to call many small write(2)s. + (merge a698d67b08 rs/more-buffered-io later to maint). + + * The patch-id computation did not ignore the "incomplete last line" + marker like whitespaces. + (merge 82a62015a7 rs/patch-id-with-incomplete-line later to maint). + + * Updates into a lazy/partial clone with a submodule did not work + well with transfer.fsckobjects set. + + * The parser for "git for-each-ref --format=..." was too loose when + parsing the "%(trailers...)" atom, and forgot that "trailers" and + "trailers:<modifiers>" are the only two allowed forms, which has + been corrected. + (merge 2c22e102f8 hv/ref-filter-trailers-atom-parsing-fix later to maint). + + * Long ago, we decided to use 3 threads by default when running the + index-pack task in parallel, which has been adjusted a bit upwards. + (merge fbff95b67f jk/index-pack-w-more-threads later to maint). + + * "git restore/checkout --no-overlay" with wildcarded pathspec + mistakenly removed matching paths in subdirectories, which has been + corrected. + (merge bfda204ade rs/checkout-no-overlay-pathspec-fix later to maint). + + * The description of --cached/--index options in "git apply --help" + has been updated. + (merge d064702be3 rp/apply-cached-doc later to maint). + + * Feeding "$ZERO_OID" to "git log --ignore-missing --stdin", and + running "git log --ignore-missing $ZERO_OID" fell back to start + digging from HEAD; it has been corrected to become a no-op, like + "git log --tags=no-tag-matches-this-pattern" does. + (merge 04a0e98515 jk/rev-input-given-fix later to maint). + + * Various callers of run_command API has been modernized. + (merge afbdba391e jc/run-command-use-embedded-args later to maint). + + * List of options offered and accepted by "git add -i/-p" were + inconsistent, which have been corrected. + (merge ce910287e7 pw/add-p-allowed-options-fix later to maint). + + * Various callers of run_command API has been modernized. + (merge afbdba391e jc/run-command-use-embedded-args later to maint). + + * "git diff --stat -w" showed 0-line changes for paths whose changes + were only whitespaces, which was not intuitive. We now omit such + paths from the stat output. + (merge 1cf3d5db9b mr/diff-hide-stat-wo-textual-change later to maint). + + * It was possible for xrealloc() to send a non-NULL pointer that has + been freed, which has been fixed. + (merge 6479ea4a8a jk/xrealloc-avoid-use-after-free later to maint). + * Other code cleanup, docfix, build fix, etc. (merge 84544f2ea3 sk/typofixes later to maint). (merge b17f411ab5 ar/help-guides-doc later to maint). @@ -115,3 +299,15 @@ Fixes since v2.28 (merge 7d23ff818f rs/bisect-oid-to-hex-fix later to maint). (merge de20baf2c9 ny/notes-doc-sample-update later to maint). (merge f649aaaf82 so/rev-parser-errormessage-fix later to maint). + (merge 6103d58b7f bc/sha-256-cvs-svn-updates later to maint). + (merge ac900fddb7 ma/stop-progress-null-fix later to maint). + (merge e767963ab6 rs/upload-pack-sigchain-fix later to maint). + (merge a831908599 rs/preserve-merges-unused-code-removal later to maint). + (merge 6dfefe70a9 jb/commit-graph-doc-fix later to maint). + (merge 847b37271e pb/set-url-docfix later to maint). + (merge 748f733d54 mt/checkout-entry-dead-code-removal later to maint). + (merge ce820cbd58 dl/subtree-docs later to maint). + (merge 55fe225dde jk/leakfix later to maint). + (merge ee22a29215 so/pretty-abbrev-doc later to maint). + (merge 3100fd5588 jc/post-checkout-doc later to maint). + (merge 17bae89476 pb/doc-external-diff-env later to maint). diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt index 5d122db6e9..88750af7ae 100644 --- a/Documentation/blame-options.txt +++ b/Documentation/blame-options.txt @@ -36,6 +36,12 @@ include::line-range-format.txt[] START. `git blame --reverse START` is taken as `git blame --reverse START..HEAD` for convenience. +--first-parent:: + Follow only the first parent commit upon seeing a merge + commit. This option can be used to determine when a line + was introduced to a particular integration branch, rather + than when it was introduced to the history overall. + -p:: --porcelain:: Show in a format designed for machine consumption. diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt index b20394038d..6af6f5edb2 100644 --- a/Documentation/config/fetch.txt +++ b/Documentation/config/fetch.txt @@ -60,7 +60,10 @@ fetch.negotiationAlgorithm:: sent when negotiating the contents of the packfile to be sent by the server. Set to "skipping" to use an algorithm that skips commits in an effort to converge faster, but may result in a larger-than-necessary - packfile; The default is "default" which instructs Git to use the default algorithm + packfile; or set to "noop" to not send any information at all, which + will almost certainly result in a larger-than-necessary packfile, but + will skip the negotiation step. + The default is "default" which instructs Git to use the default algorithm that never skips commits (unless the server has acknowledged it or one of its descendants). If `feature.experimental` is enabled, then this setting defaults to "skipping". diff --git a/Documentation/config/sendemail.txt b/Documentation/config/sendemail.txt index 0006faf800..cbc5af42fd 100644 --- a/Documentation/config/sendemail.txt +++ b/Documentation/config/sendemail.txt @@ -61,3 +61,8 @@ sendemail.smtpBatchSize:: sendemail.smtpReloginDelay:: Seconds wait before reconnecting to smtp server. See also the `--relogin-delay` option of linkgit:git-send-email[1]. + +sendemail.forbidSendmailVariables:: + To avoid common misconfiguration mistakes, linkgit:git-send-email[1] + will abort with a warning if any configuration options for "sendmail" + exist. Set this variable to bypass the check. diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt index e8ed6470fb..b10ff4caa6 100644 --- a/Documentation/diff-generate-patch.txt +++ b/Documentation/diff-generate-patch.txt @@ -10,7 +10,8 @@ linkgit:git-diff-tree[1], or linkgit:git-diff-files[1] with the `-p` option produces patch text. You can customize the creation of patch text via the -`GIT_EXTERNAL_DIFF` and the `GIT_DIFF_OPTS` environment variables. +`GIT_EXTERNAL_DIFF` and the `GIT_DIFF_OPTS` environment variables +(see linkgit:git[1]). What the -p option produces is slightly different from the traditional diff format: diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 7987d72b02..573fb9bb71 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -73,6 +73,11 @@ ifndef::git-format-patch[] Synonym for `-p --raw`. endif::git-format-patch[] +ifdef::git-log[] +-t:: + Show the tree objects in the diff output. +endif::git-log[] + --indent-heuristic:: Enable the heuristic that shifts diff hunk boundaries to make patches easier to read. This is the default. @@ -441,10 +446,11 @@ endif::git-format-patch[] --abbrev[=<n>]:: Instead of showing the full 40-byte hexadecimal object name in diff-raw format output and diff-tree header - lines, show only a partial prefix. This is - independent of the `--full-index` option above, which controls - the diff-patch output format. Non default number of - digits can be specified with `--abbrev=<n>`. + lines, show only a partial prefix. + In diff-patch output format, `--full-index` takes higher + precedence, i.e. if `--full-index` is specified, full blob + names will be shown regardless of `--abbrev`. + Non default number of digits can be specified with `--abbrev=<n>`. -B[<n>][/<m>]:: --break-rewrites[=[<n>][/<m>]]:: diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index 6e2a160a47..e8104c082e 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -64,6 +64,15 @@ documented in linkgit:git-config[1]. --dry-run:: Show what would be done, without making any changes. +ifndef::git-pull[] +--[no-]write-fetch-head:: + Write the list of remote refs fetched in the `FETCH_HEAD` + file directly under `$GIT_DIR`. This is the default. + Passing `--no-write-fetch-head` from the command line tells + Git not to write the file. Under `--dry-run` option, the + file is never written. +endif::git-pull[] + -f:: --force:: When 'git fetch' is used with `<src>:<dst>` refspec it may @@ -186,7 +195,7 @@ ifndef::git-pull[] endif::git-pull[] --set-upstream:: - If the remote is fetched successfully, pull and add upstream + If the remote is fetched successfully, add upstream (tracking) reference, used by argument-less linkgit:git-pull[1] and other commands. For more information, see `branch.<name>.merge` and `branch.<name>.remote` in diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt index b9aa39000f..91d9a8601c 100644 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@ -61,18 +61,18 @@ OPTIONS file and detects errors. Turns off "apply". --index:: - When `--check` is in effect, or when applying the patch - (which is the default when none of the options that - disables it is in effect), make sure the patch is - applicable to what the current index file records. If - the file to be patched in the working tree is not - up to date, it is flagged as an error. This flag also - causes the index file to be updated. + Apply the patch to both the index and the working tree (or + merely check that it would apply cleanly to both if `--check` is + in effect). Note that `--index` expects index entries and + working tree copies for relevant paths to be identical (their + contents and metadata such as file mode must match), and will + raise an error if they are not, even if the patch would apply + cleanly to both the index and the working tree in isolation. --cached:: - Apply a patch without touching the working tree. Instead take the - cached data, apply the patch, and store the result in the index - without using the working tree. This implies `--index`. + Apply the patch to just the index, without touching the working + tree. If `--check` is in effect, merely check that it would + apply cleanly to the index entry. --intent-to-add:: When applying the patch only to the working tree, mark new diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index 7586c5a843..fbb39fbdf5 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -16,8 +16,8 @@ DESCRIPTION The command takes various subcommands, and different options depending on the subcommand: - git bisect start [--term-{old,good}=<term> --term-{new,bad}=<term>] - [--no-checkout] [<bad> [<good>...]] [--] [<paths>...] + git bisect start [--term-{new,bad}=<term> --term-{old,good}=<term>] + [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<paths>...] git bisect (bad|new|<term-new>) [<rev>] git bisect (good|old|<term-old>) [<rev>...] git bisect terms [--term-good | --term-bad] @@ -365,6 +365,17 @@ does not require a checked out tree. + If the repository is bare, `--no-checkout` is assumed. +--first-parent:: ++ +Follow only the first parent commit upon seeing a merge commit. ++ +In detecting regressions introduced through the merging of a branch, the merge +commit will be identified as introduction of the bug and its ancestors will be +ignored. ++ +This option is particularly useful in avoiding false positives when a merged +branch contained broken or non-buildable commits, but the merge itself was OK. + EXAMPLES -------- diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt index 45b6d8e633..9067c2079e 100644 --- a/Documentation/git-fetch.txt +++ b/Documentation/git-fetch.txt @@ -48,6 +48,10 @@ include::fetch-options.txt[] include::pull-fetch-param.txt[] +--stdin:: + Read refspecs, one per line, from stdin in addition to those provided + as arguments. The "tag <name>" format is not supported. + include::urls-remotes.txt[] diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt index ac74d058e0..af0c26232c 100644 --- a/Documentation/git-index-pack.txt +++ b/Documentation/git-index-pack.txt @@ -100,6 +100,8 @@ OPTIONS value is set or outside a repository. + This option cannot be used with --stdin. ++ +include::object-format-disclaimer.txt[] NOTES ----- diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt index ddfe265da5..f35f70f13d 100644 --- a/Documentation/git-init.txt +++ b/Documentation/git-init.txt @@ -53,6 +53,8 @@ current working directory. 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>:: diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 3fd26d5212..2b8ac5ff88 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -114,8 +114,51 @@ include::rev-list-options.txt[] include::pretty-formats.txt[] -COMMON DIFF OPTIONS -------------------- +DIFF FORMATTING +--------------- + +By default, `git log` does not generate any diff output. The options +below can be used to show the changes made by each commit. + +Note that unless one of `-c`, `--cc`, or `-m` is given, merge commits +will never 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 merges are treated like normal +single-parent commits (this can be overridden by providing a +combined-diff option or with `--no-diff-merges`). + +-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. + +--cc:: + This flag implies the `-c` option and further compresses the + patch output by omitting uninteresting hunks whose contents in + the parents have only two variants and the merge result picks + one of them without modification. + +--combined-all-paths:: + This flag causes combined diffs (used for merge commits) to + list the name of the file from all parents. It thus only has + effect when -c or --cc are specified, and is likely only + useful if filename changes are detected (i.e. when either + rename or copy detection have been requested). + +-m:: + This flag makes the merge commits show the full diff like + regular commits; for each merge parent, a separate log entry + and diff is generated. An exception is that only diff against + the first parent is shown when `--first-parent` option is given; + in that case, the output represents the changes the merge + brought _into_ the then-current branch. + +--diff-merges=off:: +--no-diff-merges:: + Disable output of diffs for merge commits (default). Useful to + override `-m`, `-c`, or `--cc`. :git-log: 1 include::diff-options.txt[] diff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.txt index 0c6619493c..eb0caa0439 100644 --- a/Documentation/git-multi-pack-index.txt +++ b/Documentation/git-multi-pack-index.txt @@ -51,11 +51,12 @@ repack:: multi-pack-index, then divide by the total number of objects in the pack and multiply by the pack size. We select packs with expected size below the batch size until the set of packs have - total expected size at least the batch size. If the total size - does not reach the batch size, then do nothing. If a new pack- - file is created, rewrite the multi-pack-index to reference the - new pack-file. A later run of 'git multi-pack-index expire' will - delete the pack-files that were part of this batch. + total expected size at least the batch size, or all pack-files + are considered. If only one pack-file is selected, then do + nothing. If a new pack-file is created, rewrite the + multi-pack-index to reference the new pack-file. A later run of + 'git multi-pack-index expire' will delete the pack-files that + were part of this batch. + If `repack.packKeptObjects` is `false`, then any pack-files with an associated `.keep` file will not be selected for the batch to repack. diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index eaa2f2a404..54d715ead1 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -270,15 +270,18 @@ So does `git bundle` (see linkgit:git-bundle[1]) when it creates a bundle. This option specifies how missing objects are handled. + The form '--missing=error' requests that pack-objects stop with an error if -a missing object is encountered. This is the default action. +a missing object is encountered. If the repository is a partial clone, an +attempt to fetch missing objects will be made before declaring them missing. +This is the default action. + The form '--missing=allow-any' will allow object traversal to continue -if a missing object is encountered. Missing objects will silently be -omitted from the results. +if a missing object is encountered. No fetch of a missing object will occur. +Missing objects will silently be omitted from the results. + The form '--missing=allow-promisor' is like 'allow-any', but will only allow object traversal to continue for EXPECTED promisor missing objects. -Unexpected missing object will raise an error. +No fetch of a missing object will occur. An unexpected missing object will +raise an error. --exclude-promisor-objects:: Omit objects that are known to be in the promisor remote. (This diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 374d2486f7..38e15488f6 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -204,6 +204,7 @@ CONFIGURATION ------------- include::config/rebase.txt[] +include::config/sequencer.txt[] OPTIONS ------- @@ -459,17 +460,38 @@ with `--keep-base` in order to drop those commits from your branch. See also INCOMPATIBLE OPTIONS below. --ignore-whitespace:: + Ignore whitespace differences when trying to reconcile +differences. Currently, each backend implements an approximation of +this behavior: ++ +apply backend: When applying a patch, ignore changes in whitespace in +context lines. Unfortunately, this means that if the "old" lines being +replaced by the patch differ only in whitespace from the existing +file, you will get a merge conflict instead of a successful patch +application. ++ +merge backend: Treat lines with only whitespace changes as unchanged +when merging. Unfortunately, this means that any patch hunks that were +intended to modify whitespace and nothing else will be dropped, even +if the other side had no changes that conflicted. + --whitespace=<option>:: - These flags are passed to the 'git apply' program + This flag is passed to the 'git apply' program (see linkgit:git-apply[1]) that applies the patch. Implies --apply. + See also INCOMPATIBLE OPTIONS below. --committer-date-is-author-date:: + Instead of using the current time as the committer date, use + the author date of the commit being rebased as the committer + date. This option implies `--force-rebase`. + --ignore-date:: - These flags are passed to 'git am' to easily change the dates - of the rebased commits (see linkgit:git-am[1]). +--reset-author-date:: + Instead of using the author date of the original commit, use + the current time as the author date of the rebased commit. This + option implies `--force-rebase`. + See also INCOMPATIBLE OPTIONS below. @@ -607,9 +629,6 @@ INCOMPATIBLE OPTIONS The following options: * --apply - * --committer-date-is-author-date - * --ignore-date - * --ignore-whitespace * --whitespace * -C @@ -636,6 +655,9 @@ In addition, the following pairs of options are incompatible: * --preserve-merges and --signoff * --preserve-merges and --rebase-merges * --preserve-merges and --empty= + * --preserve-merges and --ignore-whitespace + * --preserve-merges and --committer-date-is-author-date + * --preserve-merges and --ignore-date * --keep-base and --onto * --keep-base and --root * --fork-point and --root diff --git a/Documentation/git-show-index.txt b/Documentation/git-show-index.txt index 39b1d8eaa1..e49318a5a0 100644 --- a/Documentation/git-show-index.txt +++ b/Documentation/git-show-index.txt @@ -44,6 +44,8 @@ OPTIONS valid values are 'sha1' and (if enabled) 'sha256'. The default is the algorithm for the current repository (set by `extensions.objectFormat`), or 'sha1' if no value is set or outside a repository.. ++ +include::object-format-disclaimer.txt[] GIT --- diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index 3e737c2360..d401234b03 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -148,12 +148,13 @@ still see a subset of the modifications. LOGGING UPDATES --------------- -If config parameter "core.logAllRefUpdates" is true and the ref is one under -"refs/heads/", "refs/remotes/", "refs/notes/", or the symbolic ref HEAD; or -the file "$GIT_DIR/logs/<ref>" exists then `git update-ref` will append -a line to the log file "$GIT_DIR/logs/<ref>" (dereferencing all -symbolic refs before creating the log name) describing the change -in ref value. Log lines are formatted as: +If config parameter "core.logAllRefUpdates" is true and the ref is one +under "refs/heads/", "refs/remotes/", "refs/notes/", or a pseudoref +like HEAD or ORIG_HEAD; or the file "$GIT_DIR/logs/<ref>" exists then +`git update-ref` will append a line to the log file +"$GIT_DIR/logs/<ref>" (dereferencing all symbolic refs before creating +the log name) describing the change in ref value. Log lines are +formatted as: oldsha1 SP newsha1 SP committer LF diff --git a/Documentation/git.txt b/Documentation/git.txt index 81349a84e7..2f72b10224 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -504,7 +504,8 @@ double-quotes and respecting backslash escapes. E.g., the value If this variable is set, the default hash algorithm for new repositories will be set to this value. This value is currently ignored when cloning; the setting of the remote repository - is used instead. The default is "sha1". + is used instead. The default is "sha1". THIS VARIABLE IS + EXPERIMENTAL! See `--object-format` in linkgit:git-init[1]. Git Commits ~~~~~~~~~~~ @@ -550,8 +551,9 @@ Git Diffs `GIT_EXTERNAL_DIFF`:: When the environment variable `GIT_EXTERNAL_DIFF` is set, the - program named by it is called, instead of the diff invocation - described above. For a path that is added, removed, or modified, + program named by it is called to generate diffs, and Git + does not use its builtin diff machinery. + For a path that is added, removed, or modified, `GIT_EXTERNAL_DIFF` is called with 7 parameters: path old-file old-hex old-mode new-file new-hex new-mode @@ -604,6 +606,12 @@ other an editor is to be launched. See also linkgit:git-var[1] and the `core.editor` option in linkgit:git-config[1]. +`GIT_SEQUENCE_EDITOR`:: + This environment variable overrides the configured Git editor + when editing the todo list of an interactive rebase. See also + linkit::git-rebase[1] and the `sequence.editor` option in + linkit::git-config[1]. + `GIT_SSH`:: `GIT_SSH_COMMAND`:: If either of these environment variables is set then 'git fetch' diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index 31b601e4bc..cf95d6d02b 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -193,7 +193,9 @@ worktree. The hook is given three parameters: the ref of the previous HEAD, the ref of the new HEAD (which may or may not have changed), and a flag indicating whether the checkout was a branch checkout (changing branches, flag=1) or a file checkout (retrieving a file from the index, flag=0). -This hook cannot affect the outcome of `git switch` or `git checkout`. +This hook cannot affect the outcome of `git switch` or `git checkout`, +other than that the hook's exit status becomes the exit status of +these two commands. It is also run after linkgit:git-clone[1], unless the `--no-checkout` (`-n`) option is used. The first parameter given to the hook is the null-ref, the second the diff --git a/Documentation/object-format-disclaimer.txt b/Documentation/object-format-disclaimer.txt new file mode 100644 index 0000000000..4cb106f0d1 --- /dev/null +++ b/Documentation/object-format-disclaimer.txt @@ -0,0 +1,6 @@ +THIS OPTION IS EXPERIMENTAL! SHA-256 support is experimental and still +in an early stage. A SHA-256 repository will in general not be able to +share work with "regular" SHA-1 repositories. It should be assumed +that, e.g., Git internal file formats in relation to SHA-256 +repositories may change in backwards-incompatible ways. Only use +`--object-format=sha256` for testing purposes. diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt index 7a6da6db78..17c5aac4b7 100644 --- a/Documentation/pretty-options.txt +++ b/Documentation/pretty-options.txt @@ -25,8 +25,8 @@ people using 80-column terminals. --no-abbrev-commit:: Show the full 40-byte hexadecimal commit object name. This negates - `--abbrev-commit` and those options which imply it such as - "--oneline". It also overrides the `log.abbrevCommit` variable. + `--abbrev-commit`, either explicit or implied by other options such + as "--oneline". It also overrides the `log.abbrevCommit` variable. --oneline:: This is a shorthand for "--pretty=oneline --abbrev-commit" diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index b01b2b6773..002379056a 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -128,8 +128,7 @@ parents) and `--max-parents=-1` (negative numbers denote no upper limit). because merges into a topic branch tend to be only about adjusting to updated upstream from time to time, and this option allows you to ignore the individual commits - brought in to your history by such a merge. Cannot be - combined with --bisect. + brought in to your history by such a merge. --not:: Reverses the meaning of the '{caret}' prefix (or lack thereof) @@ -207,7 +206,7 @@ ifndef::git-rev-list[] Pretend as if the bad bisection ref `refs/bisect/bad` was listed and as if it was followed by `--not` and the good bisection refs `refs/bisect/good-*` on the command - line. Cannot be combined with --first-parent. + line. endif::git-rev-list[] --stdin:: @@ -743,7 +742,7 @@ outputs 'midpoint', the output of the two commands would be of roughly the same length. Finding the change which introduces a regression is thus reduced to a binary search: repeatedly generate and test new 'midpoint's until the commit chain is of length -one. Cannot be combined with --first-parent. +one. --bisect-vars:: This calculates the same as `--bisect`, except that refs in @@ -1117,48 +1116,3 @@ ifdef::git-rev-list[] by a tab. endif::git-rev-list[] endif::git-shortlog[] - -ifndef::git-shortlog[] -ifndef::git-rev-list[] -Diff Formatting -~~~~~~~~~~~~~~~ - -Listed below are options that control the formatting of diff output. -Some of them are specific to linkgit:git-rev-list[1], however other diff -options may be given. See linkgit:git-diff-files[1] for more options. - --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. - ---cc:: - This flag implies the `-c` option and further compresses the - patch output by omitting uninteresting hunks whose contents in - the parents have only two variants and the merge result picks - one of them without modification. - ---combined-all-paths:: - This flag causes combined diffs (used for merge commits) to - list the name of the file from all parents. It thus only has - effect when -c or --cc are specified, and is likely only - useful if filename changes are detected (i.e. when either - rename or copy detection have been requested). - --m:: - This flag makes the merge commits show the full diff like - regular commits; for each merge parent, a separate log entry - and diff is generated. An exception is that only diff against - the first parent is shown when `--first-parent` option is given; - in that case, the output represents the changes the merge - brought _into_ the then-current branch. - --r:: - Show recursive diffs. - --t:: - Show the tree objects in the diff output. This implies `-r`. -endif::git-rev-list[] -endif::git-shortlog[] diff --git a/Documentation/technical/commit-graph-format.txt b/Documentation/technical/commit-graph-format.txt index 440541045d..6ddbceba15 100644 --- a/Documentation/technical/commit-graph-format.txt +++ b/Documentation/technical/commit-graph-format.txt @@ -42,8 +42,13 @@ HEADER: 1-byte version number: Currently, the only valid version is 1. - 1-byte Hash Version (1 = SHA-1) - We infer the hash length (H) from this value. + 1-byte Hash Version + We infer the hash length (H) from this value: + 1 => SHA-1 + 2 => SHA-256 + If the hash type does not match the repository's hash algorithm, the + commit-graph file should be ignored with a warning presented to the + user. 1-byte number (C) of "chunks" diff --git a/Documentation/technical/commit-graph.txt b/Documentation/technical/commit-graph.txt index 808fa30b99..f14a7659aa 100644 --- a/Documentation/technical/commit-graph.txt +++ b/Documentation/technical/commit-graph.txt @@ -210,12 +210,12 @@ file. +---------------------+ | | +-----------------------+ +---------------------+ - | graph-{hash2} |->| | + | graph-{hash2} |->| | +-----------------------+ +---------------------+ | | | +-----------------------+ +---------------------+ | | | | - | graph-{hash1} |->| | + | graph-{hash1} |->| | | | | | +-----------------------+ +---------------------+ | tmp_graphXXX @@ -223,7 +223,7 @@ file. | | | | | | - | graph-{hash0} | + | graph-{hash0} | | | | | | | diff --git a/Documentation/technical/hash-function-transition.txt b/Documentation/technical/hash-function-transition.txt index 5b2db3be1e..6fd20ebbc2 100644 --- a/Documentation/technical/hash-function-transition.txt +++ b/Documentation/technical/hash-function-transition.txt @@ -650,7 +650,6 @@ Some initial steps can be implemented independently of one another: The first user-visible change is the introduction of the objectFormat extension (without compatObjectFormat). This requires: -- implementing the loose-object-idx - teaching fsck about this mode of operation - using the hash function API (vtable) when computing object names - signing objects and verifying signatures @@ -658,6 +657,7 @@ extension (without compatObjectFormat). This requires: repository Next comes introduction of compatObjectFormat: +- implementing the loose-object-idx - translating object names between object formats - translating object content between object formats - generating and verifying signatures in the compat format diff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt index 51a79e63de..96d89ea9b2 100644 --- a/Documentation/technical/http-protocol.txt +++ b/Documentation/technical/http-protocol.txt @@ -401,8 +401,9 @@ at all in the request stream: The stream is terminated by a pkt-line flush (`0000`). A single "want" or "have" command MUST have one hex formatted -SHA-1 as its value. Multiple SHA-1s MUST be sent by sending -multiple commands. +object name as its value. Multiple object names MUST be sent by sending +multiple commands. Object names MUST be given using the object format +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. diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt index faa25c5c52..f9a3644711 100644 --- a/Documentation/technical/index-format.txt +++ b/Documentation/technical/index-format.txt @@ -3,8 +3,11 @@ Git index format == The Git index file has the following format - All binary numbers are in network byte order. Version 2 is described - here unless stated otherwise. + All binary numbers are in network byte order. + In a repository using the traditional SHA-1, checksums and object IDs + (object names) mentioned below are all computed using SHA-1. Similarly, + in SHA-256 repositories, these values are computed using SHA-256. + Version 2 is described here unless stated otherwise. - A 12-byte header consisting of @@ -32,8 +35,7 @@ Git index format Extension data - - 160-bit SHA-1 over the content of the index file before this - checksum. + - Hash checksum over the content of the index file before this checksum. == Index entry @@ -80,7 +82,7 @@ Git index format 32-bit file size This is the on-disk size from stat(2), truncated to 32-bit. - 160-bit SHA-1 for the represented object + Object name for the represented object A 16-bit 'flags' field split into (high to low bits) @@ -160,8 +162,8 @@ Git index format - A newline (ASCII 10); and - - 160-bit object name for the object that would result from writing - this span of index as a tree. + - Object name for the object that would result from writing this span + of index as a tree. An entry can be in an invalidated state and is represented by having a negative number in the entry_count field. In this case, there is no @@ -198,7 +200,7 @@ Git index format stage 1 to 3 (a missing stage is represented by "0" in this field); and - - At most three 160-bit object names of the entry in stages from 1 to 3 + - At most three object names of the entry in stages from 1 to 3 (nothing is written for a missing stage). === Split index @@ -211,8 +213,8 @@ Git index format The extension consists of: - - 160-bit SHA-1 of the shared index file. The shared index file path - is $GIT_DIR/sharedindex.<SHA-1>. If all 160 bits are zero, the + - Hash of the shared index file. The shared index file path + is $GIT_DIR/sharedindex.<hash>. If all bits are zero, the index does not require a shared index file. - An ewah-encoded delete bitmap, each bit represents an entry in the @@ -253,10 +255,10 @@ Git index format - 32-bit dir_flags (see struct dir_struct) - - 160-bit SHA-1 of $GIT_DIR/info/exclude. Null SHA-1 means the file + - Hash of $GIT_DIR/info/exclude. A null hash means the file does not exist. - - 160-bit SHA-1 of core.excludesfile. Null SHA-1 means the file does + - Hash of core.excludesfile. A null hash means the file does not exist. - NUL-terminated string of per-dir exclude file name. This usually @@ -285,13 +287,13 @@ The remaining data of each directory block is grouped by type: - An ewah bitmap, the n-th bit records "check-only" bit of read_directory_recursive() for the n-th directory. - - An ewah bitmap, the n-th bit indicates whether SHA-1 and stat data + - An ewah bitmap, the n-th bit indicates whether hash and stat data is valid for the n-th directory and exists in the next data. - An array of stat data. The n-th data corresponds with the n-th "one" bit in the previous ewah bitmap. - - An array of SHA-1. The n-th SHA-1 corresponds with the n-th "one" bit + - An array of hashes. The n-th hash corresponds with the n-th "one" bit in the previous ewah bitmap. - One NUL. @@ -330,12 +332,12 @@ The remaining data of each directory block is grouped by type: - 32-bit offset to the end of the index entries - - 160-bit SHA-1 over the extension types and their sizes (but not + - Hash over the extension types and their sizes (but not their contents). E.g. if we have "TREE" extension that is N-bytes long, "REUC" extension that is M-bytes long, followed by "EOIE", then the hash would be: - SHA-1("TREE" + <binary representation of N> + + Hash("TREE" + <binary representation of N> + "REUC" + <binary representation of M>) == Index Entry Offset Table diff --git a/Documentation/technical/pack-format.txt b/Documentation/technical/pack-format.txt index d3a142c652..f96b2e605f 100644 --- a/Documentation/technical/pack-format.txt +++ b/Documentation/technical/pack-format.txt @@ -1,6 +1,12 @@ Git pack format =============== +== Checksums and object IDs + +In a repository using the traditional SHA-1, pack checksums, index checksums, +and object IDs (object names) mentioned below are all computed using SHA-1. +Similarly, in SHA-256 repositories, these values are computed using SHA-256. + == pack-*.pack files have the following format: - A header appears at the beginning and consists of the following: @@ -26,7 +32,7 @@ Git pack format (deltified representation) n-byte type and length (3-bit type, (n-1)*7+4-bit length) - 20-byte base object name if OBJ_REF_DELTA or a negative relative + base object name if OBJ_REF_DELTA or a negative relative offset from the delta object's position in the pack if this is an OBJ_OFS_DELTA object compressed delta data @@ -34,7 +40,7 @@ Git pack format Observation: length of each object is encoded in a variable length format and is not constrained to 32-bit or anything. - - The trailer records 20-byte SHA-1 checksum of all of the above. + - The trailer records a pack checksum of all of the above. === Object types @@ -58,8 +64,8 @@ ofs-delta and ref-delta, which is only valid in a pack file. Both ofs-delta and ref-delta store the "delta" to be applied to another object (called 'base object') to reconstruct the object. The -difference between them is, ref-delta directly encodes 20-byte base -object name. If the base object is in the same pack, ofs-delta encodes +difference between them is, ref-delta directly encodes base object +name. If the base object is in the same pack, ofs-delta encodes the offset of the base object in the pack instead. The base object could also be deltified if it's in the same pack. @@ -143,14 +149,14 @@ This is the instruction reserved for future expansion. object is stored in the packfile as the offset from the beginning. - 20-byte object name. + one object name of the appropriate size. - The file is concluded with a trailer: - A copy of the 20-byte SHA-1 checksum at the end of - corresponding packfile. + A copy of the pack checksum at the end of the corresponding + packfile. - 20-byte SHA-1-checksum of all of the above. + Index checksum of all of the above. Pack Idx file: @@ -198,7 +204,7 @@ Pack file entry: <+ If it is not DELTA, then deflated bytes (the size above is the size before compression). If it is REF_DELTA, then - 20-byte base object name SHA-1 (the size above is the + base object name (the size above is the size of the delta data that follows). delta data, deflated. If it is OFS_DELTA, then @@ -227,9 +233,9 @@ Pack file entry: <+ - A 256-entry fan-out table just like v1. - - A table of sorted 20-byte SHA-1 object names. These are - packed together without offset values to reduce the cache - footprint of the binary search for a specific object name. + - A table of sorted object names. These are packed together + without offset values to reduce the cache footprint of the + binary search for a specific object name. - A table of 4-byte CRC32 values of the packed object data. This is new in v2 so compressed data can be copied directly @@ -248,10 +254,10 @@ Pack file entry: <+ - The same trailer as a v1 pack file: - A copy of the 20-byte SHA-1 checksum at the end of + A copy of the pack checksum at the end of corresponding packfile. - 20-byte SHA-1-checksum of all of the above. + Index checksum of all of the above. == multi-pack-index (MIDX) files have the following format: @@ -273,7 +279,12 @@ HEADER: Git only writes or recognizes version 1. 1-byte Object Id Version - Git only writes or recognizes version 1 (SHA1). + We infer the length of object IDs (OIDs) from this value: + 1 => SHA-1 + 2 => SHA-256 + If the hash type does not match the repository's hash algorithm, + the multi-pack-index file should be ignored with a warning + presented to the user. 1-byte number of "chunks" @@ -329,4 +340,4 @@ CHUNK DATA: TRAILER: - 20-byte SHA1-checksum of the above contents. + Index checksum of the above contents. diff --git a/Documentation/technical/partial-clone.txt b/Documentation/technical/partial-clone.txt index b9e17e7a28..0780d30cac 100644 --- a/Documentation/technical/partial-clone.txt +++ b/Documentation/technical/partial-clone.txt @@ -171,20 +171,13 @@ additional flag. Fetching Missing Objects ------------------------ -- Fetching of objects is done using the existing transport mechanism using - transport_fetch_refs(), setting a new transport option - TRANS_OPT_NO_DEPENDENTS to indicate that only the objects themselves are - desired, not any object that they refer to. -+ -Because some transports invoke fetch_pack() in the same process, fetch_pack() -has been updated to not use any object flags when the corresponding argument -(no_dependents) is set. +- Fetching of objects is done by invoking a "git fetch" subprocess. - The local repository sends a request with the hashes of all requested - objects as "want" lines, and does not perform any packfile negotiation. + objects, and does not perform any packfile negotiation. It then receives a packfile. -- Because we are reusing the existing fetch-pack mechanism, fetching +- Because we are reusing the existing fetch mechanism, fetching currently fetches all objects referred to by the requested objects, even though they are not necessary. diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt index 36ccd14f97..124d716807 100644 --- a/Documentation/technical/protocol-capabilities.txt +++ b/Documentation/technical/protocol-capabilities.txt @@ -324,15 +324,19 @@ allow-tip-sha1-in-want ---------------------- If the upload-pack server advertises this capability, fetch-pack may -send "want" lines with SHA-1s that exist at the server but are not -advertised by upload-pack. +send "want" lines with object names that exist at the server but are not +advertised by upload-pack. For historical reasons, the name of this +capability contains "sha1". Object names are always given using the +object format negotiated through the 'object-format' capability. allow-reachable-sha1-in-want ---------------------------- If the upload-pack server advertises this capability, fetch-pack may -send "want" lines with SHA-1s that exist at the server but are not -advertised by upload-pack. +send "want" lines with object names that exist at the server but are not +advertised by upload-pack. For historical reasons, the name of this +capability contains "sha1". Object names are always given using the +object format negotiated through the 'object-format' capability. push-cert=<nonce> ----------------- diff --git a/Documentation/technical/shallow.txt b/Documentation/technical/shallow.txt index 01dedfe9ff..f3738baa0f 100644 --- a/Documentation/technical/shallow.txt +++ b/Documentation/technical/shallow.txt @@ -13,7 +13,7 @@ pretend as if they are root commits (e.g. "git log" traversal stops after showing them; "git fsck" does not complain saying the commits listed on their "parent" lines do not exist). -Each line contains exactly one SHA-1. When read, a commit_graft +Each line contains exactly one object name. When read, a commit_graft will be constructed, which has nr_parent < 0 to make it easier to discern from user provided grafts. |