diff options
Diffstat (limited to 'Documentation')
87 files changed, 1413 insertions, 288 deletions
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index d85c9b5..60eed5e 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -249,7 +249,7 @@ component you're working on, followed by a blank line (always required) and then the body of your commit message, which should provide the bulk of the context. Remember to be explicit and provide the "Why" of your change, especially if it couldn't easily be understood from your diff. When editing your commit message, -don't remove the Signed-off-by line which was added by `-s` above. +don't remove the `Signed-off-by` trailer which was added by `-s` above. ---- psuh: add a built-in by popular demand @@ -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`. @@ -507,6 +507,9 @@ documentation is consistent with other Git and UNIX manpages; this makes life easier for your user, who can skip to the section they know contains the information they need. +NOTE: Before trying to build the docs, make sure you have the package `asciidoc` +installed. + Now that you've written your manpage, you'll need to build it explicitly. We convert your AsciiDoc to troff which is man-readable like so: @@ -522,8 +525,6 @@ $ make -C Documentation/ git-psuh.1 $ man Documentation/git-psuh.1 ---- -NOTE: You may need to install the package `asciidoc` to get this to work. - While this isn't as satisfying as running through `git help`, you can at least check that your help page looks right. diff --git a/Documentation/RelNotes/2.29.0.txt b/Documentation/RelNotes/2.29.0.txt index 783cba3..06ba2f8 100644 --- a/Documentation/RelNotes/2.29.0.txt +++ b/Documentation/RelNotes/2.29.0.txt @@ -33,6 +33,95 @@ UI, Workflows & Features 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. + + * "git worktree" gained a "repair" subcommand to help users recover + after moving the worktrees or repository manually without telling + Git. Also, "git init --separate-git-dir" no longer corrupts + administrative data related to linked worktrees. + + * The "--format=" option to the "for-each-ref" command and friends + learned a few more tricks, e.g. the ":short" suffix that applies to + "objectname" now also can be used for "parent", "tree", etc. + + * "git worktree add" learns that the "-d" is a synonym to "--detach" + option to create a new worktree without being on a branch. + + * "format-patch --range-diff=<prev> <origin>..HEAD" has been taught + not to ignore <origin> when <prev> is a single version. + + * "add -p" now allows editing paths that were only added in intent. + + * The 'meld' backend of the "git mergetool" learned to give the + underlying 'meld' the '--auto-merge' option, which would help + reduce the amount of text that requires manual merging. + + * "git for-each-ref" and friends that list refs used to allow only + one --merged or --no-merged to filter them; they learned to take + combination of both kind of filtering. + + * "git maintenance", a "git gc"'s big brother, has been introduced to + take care of more repository maintenance tasks, not limited to the + object database cleaning. + + * "git receive-pack" that accepts requests by "git push" learned to + outsource most of the ref updates to the new "proc-receive" hook. + + * "git push" that wants to be atomic and wants to send push + certificate learned not to prepare and sign the push certificate + when it fails the local check (hence due to atomicity it is known + that no certificate is needed). + + * "git commit-graph write" learned to limit the number of bloom + filters that are computed from scratch with the --max-new-filters + option. + + * The transport protocol v2 has become the default again. + + * The installation procedure learned to optionally omit "git-foo" + executable files for each 'foo' built-in subcommand, which are only + required by old timers that still rely on the age old promise that + prepending "git --exec-path" output to PATH early in their script + will keep the "git-foo" calls they wrote working. + + * The command line completion (in contrib/) learned that "git restore + -s <TAB>" is often followed by a refname. + + * "git shortlog" has been taught to group commits by the contents of + the trailer lines, like "Reviewed-by:", "Coauthored-by:", etc. + + * "git archive" learns the "--add-file" option to include untracked + files into a snapshot from a tree-ish. + + * "git fetch" and "git push" support negative refspecs. + + * "git format-patch" learns to take "whenAble" as a possible value + for the format.useAutoBase configuration variable to become no-op + when the automatically computed base does not make sense. + + * Credential helpers are now allowed to terminate lines with CRLF + line ending, as well as LF line ending. + Performance, Internal Implementation, Development Support etc. @@ -66,7 +155,9 @@ 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 interoperability between SHA-1 and SHA-256 + repositories yet. * CMake support to build with MSVC for Windows bypassing the Makefile. @@ -82,10 +173,64 @@ Performance, Internal Implementation, Development Support etc. * 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.. + + * 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. + + * When a packfile is removed by "git repack", multi-pack-index gets + cleared; the code was taught to do so less aggressively by first + checking if the midx actually refers to a pack that no longer + exists. + + * Internal API clean-up to handle two options "diff-index" and "log" + have, which happen to share the same short form, more sensibly. + + * The "add -i/-p" machinery has been written in C but it is not used + by default yet. It is made default to those who are participating + in feature.experimental experiment. + + * Allow maintainers to tweak $(TAR) invocations done while making + distribution tarballs. + + * "git index-pack" learned to resolve deltified objects with greater + parallelism. + + * "diff-highlight" (in contrib/) had a logic to flush its output upon + seeing a blank line but the way it detected a blank line was broken. + + * The logic to skip testing on the tagged commit and the tag itself + was not quite consistent which led to failure of Windows test + tasks. It has been revamped to consistently skip revisions that + have already been tested, based on the tree object of the revision. + Fixes since v2.28 ----------------- + * The "mediawiki" remote backend which lives in contrib/mw-to-git/ + and is not built with git by default, had an RCE bug allowing a + malicious MediaWiki server operator to inject arbitrary commands + for execution by a cloning client. This has been fixed. + + The bug was discovered and reported by Joern Schneeweisz of GitLab + to the git-security mailing list. Its practical impact due to the + obscurity of git-remote-mediawiki was deemed small enough to forgo + a dedicated security release. + * "git clone --separate-git-dir=$elsewhere" used to stomp on the contents of the existing directory $elsewhere, which has been taught to fail when $elsewhere is not an empty directory. @@ -145,6 +290,194 @@ Fixes since v2.28 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 have 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). + + * "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). + + * "git status" has trouble showing where it came from by interpreting + reflog entries that record certain events, e.g. "checkout @{u}", and + gives a hard/fatal error. Even though it inherently is impossible + to give a correct answer because the reflog entries lose some + information (e.g. "@{u}" does not record what branch the user was + on hence which branch 'the upstream' needs to be computed, and even + if the record were available, the relationship between branches may + have changed), at least hide the error and allow "status" to show its + output. + + * "git status --short" quoted a path with SP in it when tracked, but + not those that are untracked, ignored or unmerged. They are all + shown quoted consistently. + + * "git diff/show" on a change that involves a submodule used to read + the information on commits in the submodule from a wrong repository + and gave a wrong information when the commit-graph is involved. + (merge 85a1ec2c32 mf/submodule-summary-with-correct-repository later to maint). + + * Unlike "git config --local", "git config --worktree" did not fail + early and cleanly when started outside a git repository. + (merge 378fe5fc3d mt/config-fail-nongit-early later to maint). + + * There is a logic to estimate how many objects are in the + repository, which is meant to run once per process invocation, but + it ran every time the estimated value was requested. + (merge 67bb65de5d jk/dont-count-existing-objects-twice later to maint). + + * "git remote set-head" that failed still said something that hints + the operation went through, which was misleading. + (merge 5a07c6c3c2 cs/don-t-pretend-a-failed-remote-set-head-succeeded later to maint). + + * "git fetch --all --ipv4/--ipv6" forgot to pass the protocol options + to instances of the "git fetch" that talk to individual remotes, + which has been corrected. + (merge 4e735c1326 ar/fetch-ipversion-in-all later to maint). + + * The "unshelve" subcommand of "git p4" incorrectly used commit^N + where it meant to say commit~N to name the Nth generation + ancestor, which has been corrected. + (merge 0acbf5997f ld/p4-unshelve-fix later to maint). + + * "git clone" that clones from SHA-1 repository, while + GIT_DEFAULT_HASH set to use SHA-256 already, resulted in an + unusable repository that half-claims to be SHA-256 repository + with SHA-1 objects and refs. This has been corrected. + + * Adjust sample hooks for hash algorithm other than SHA-1. + (merge d8d3d632f4 dl/zero-oid-in-hooks later to maint). + + * "git range-diff" showed incorrect diffstat, which has been + corrected. + + * Earlier we taught "git pull" to warn when the user does not say the + histories need to be merged, rebased or accepts only fast- + forwarding, but the warning triggered for those who have set the + pull.ff configuration variable. + (merge 54200cef86 ah/pull later to maint). + + * Compilation fix around type punning. + (merge 176380fd11 jk/drop-unaligned-loads later to maint). + + * "git blame --ignore-rev/--ignore-revs-file" failed to validate + their input are valid revision, and failed to take into account + that the user may want to give an annotated tag instead of a + commit, which has been corrected. + (merge 610e2b9240 jc/blame-ignore-fix later to maint). + + * "git bisect start X Y", when X and Y are not valid committish + object names, should take X and Y as pathspec, but didn't. + (merge 73c6de06af cc/bisect-start-fix later to maint). + + * The explanation of the "scissors line" has been clarified. + (merge 287416dba6 eg/mailinfo-doc-scissors later to maint). + + * A race that leads to an access to a free'd data was corrected in + the codepath that reads pack files. + (merge bda959c476 mt/delta-base-cache-races later to maint). + + * in_merge_bases_many(), a way to see if a commit is reachable from + any commit in a set of commits, was totally broken when the + commit-graph feature was in use, which has been corrected. + (merge 8791bf1841 ds/in-merge-bases-many-optim-bug later to maint). + + * "git submodule update --quiet" did not squelch underlying "rebase" + and "pull" commands. + (merge 3ad0401e9e td/submodule-update-quiet later to maint). + + * The lazy fetching done internally to make missing objects available + in a partial clone incorrectly made permanent damage to the partial + clone filter in the repository, which has been corrected. + + * "log -c --find-object=X" did not work well to find a merge that + involves a change to an object X from only one parent. + (merge 957876f17d jk/diff-cc-oidfind-fix 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). @@ -160,3 +493,22 @@ Fixes since v2.28 (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). + (merge 27ed6ccc12 jk/worktree-check-clean-leakfix later to maint). + (merge 1302badd16 ea/blame-use-oideq later to maint). + (merge e6d5a11fed al/t3200-back-on-a-branch later to maint). + (merge 324efcf6b6 pw/add-p-leakfix later to maint). + (merge 1c6ffb546b jk/add-i-fixes later to maint). + (merge e40e936551 cd/commit-graph-doc later to maint). + (merge 0512eabd91 jc/sequencer-stopped-sha-simplify later to maint). + (merge d01141de5a so/combine-diff-simplify later to maint). + (merge 3be01e5ab1 sn/fast-import-doc later to maint). diff --git a/Documentation/RelNotes/2.29.1.txt b/Documentation/RelNotes/2.29.1.txt new file mode 100644 index 0000000..295ee21 --- /dev/null +++ b/Documentation/RelNotes/2.29.1.txt @@ -0,0 +1,11 @@ +Git v2.29.1 Release Notes +========================= + +This is to fix the build procedure change in 2.28 where we failed to +install a few programs that should be installed in /usr/bin (namely, +receive-pack, upload-archive and upload-pack) when the non-default +SKIP_DASHED_BUILT_INS installation option is in effect. + +A minor glitch in a non-default installation may usually not deserve +a hotfix, but I know Git for Windows ship binaries built with this +option, so let's make an exception. diff --git a/Documentation/RelNotes/2.29.2.txt b/Documentation/RelNotes/2.29.2.txt new file mode 100644 index 0000000..632b5b5 --- /dev/null +++ b/Documentation/RelNotes/2.29.2.txt @@ -0,0 +1,12 @@ +Git v2.29.2 Release Notes +========================= + +This release is primarily to fix brown-paper-bag breakages in the +2.29.0 release. + +Fixes since v2.29.1 +------------------- + + * In 2.29, "--committer-date-is-author-date" option of "rebase" and + "am" subcommands lost the e-mail address by mistake, which has been + corrected. diff --git a/Documentation/RelNotes/2.30.0.txt b/Documentation/RelNotes/2.30.0.txt new file mode 100644 index 0000000..defa865 --- /dev/null +++ b/Documentation/RelNotes/2.30.0.txt @@ -0,0 +1,201 @@ +Git 2.30 Release Notes +====================== + +Updates since v2.29 +------------------- + +UI, Workflows & Features + + * Userdiff for PHP update. + + * Userdiff for Rust update. + + * Userdiff for CSS update. + + * The command line completion script (in contrib/) learned that "git + stash show" takes the options "git diff" takes. + + * "git worktree list" now shows if each worktree is locked. This + possibly may open us to show other kinds of states in the future. + + * "git maintenance", an extended big brother of "git gc", continues + to evolve. + + * "git push --force-with-lease[=<ref>]" can easily be misused to lose + commits unless the user takes good care of their own "git fetch". + A new option "--force-if-includes" attempts to ensure that what is + being force-pushed was created after examining the commit at the + tip of the remote ref that is about to be force-replaced. + + * "git clone" learned clone.defaultremotename configuration variable + to customize what nickname to use to call the remote the repository + was cloned from. + + * "git checkout" learned to use checkout.guess configuration variable + and enable/disable its "--[no-]guess" option accordingly. + + * "git resurrect" script (in contrib/) learned that the object names + may be longer than 40-hex depending on the hash function in use. + + * "git diff A...B" learned "git diff --merge-base A B", which is a + longer short-hand to say the same thing. + + * A sample 'push-to-checkout' hook, that performs the same as + what the built-in default action does, has been added. + + * "git diff" family of commands learned the "-I<regex>" option to + ignore hunks whose changed lines all match the given pattern. + + * The userdiff pattern learned to identify the function definition in + POSIX shells and bash. + + * "git checkout-index" did not consistently signal an error with its + exit status, but now it does. + + * A commit and tag object may have CR at the end of each and + every line (you can create such an object with hash-object or + using --cleanup=verbatim to decline the default clean-up + action), but it would make it impossible to have a blank line + to separate the title from the body of the message. We are now + more lenient and accept a line with lone CR on it as a blank line, + too. + + * Exit codes from "git remote add" etc. were not usable by scripted + callers, but now they are. + + * Zsh autocompletion (in contrib/) update. + + +Performance, Internal Implementation, Development Support etc. + + * Use "git archive" more to produce the release tarball. + + * GitHub Actions automated test improvement to skip tests on a tree + identical to what has already been tested. + + * Test-coverage for running commit-graph task "git maintenance" has + been extended. + + * Our test scripts can be told to run only individual pieces while + skipping others with the "--run=..." option; they were taught to + take a substring of test title, in addition to numbers, to name the + test pieces to run. + + * Adjust tests so that they won't scream when the default initial + branch name is changed to 'main'. + + * Rewriting "git bisect" in C continues. + + * More preliminary tests have been added to document desired outcome + of various "directory rename" situations. + + * Micro clean-up of a couple of test scripts. + + * "git diff" and other commands that share the same machinery to + compare with working tree files have been taught to take advantage + of the fsmonitor data when available. + + * The code to detect premature EOF in the sideband demultiplexer has + been cleaned up. + + * Test scripts are being prepared to transition of the default branch + name to 'main'. + + + +Fixes since v2.29 +----------------- + + * In 2.29, "--committer-date-is-author-date" option of "rebase" and + "am" subcommands lost the e-mail address by mistake, which has been + corrected. + (merge 5f35edd9d7 jk/committer-date-is-author-date-fix later to maint). + + * "git checkout -p A...B [-- <path>]" did not work, even though the + same command without "-p" correctly used the merge-base between + commits A and B. + (merge 35166b1fb5 dl/checkout-p-merge-base later to maint). + + * The side-band status report can be sent at the same time as the + primary payload multiplexed, but the demultiplexer on the receiving + end incorrectly split a single status report into two, which has + been corrected. + (merge 712b0377db js/avoid-split-sideband-message later to maint). + + * "git fast-import" wasted a lot of memory when many marks were in use. + (merge 3f018ec716 jk/fast-import-marks-alloc-fix later to maint). + + * A test helper "test_cmp A B" was taught to diagnose missing files A + or B as a bug in test, but some tests legitimately wanted to notice + a failure to even create file B as an error, in addition to leaving + the expected result in it, and were misdiagnosed as a bug. This + has been corrected. + (merge 262d5ad5a5 es/test-cmp-typocatcher later to maint). + + * When "git commit-graph" detects the same commit recorded more than + once while it is merging the layers, it used to die. The code now + ignores all but one of them and continues. + (merge 85102ac71b ds/commit-graph-merging-fix later to maint). + + * The meaning of a Signed-off-by trailer can vary from project to + project; this and also what it means to this project has been + clarified in the documentation. + (merge 3abd4a67d9 bk/sob-dco later to maint). + + * "git credential' didn't honor the core.askPass configuration + variable (among other things), which has been corrected. + (merge 567ad2c0f9 tk/credential-config later to maint). + + * Dev support to catch a tentative definition of a variable in our C + code as an error. + (merge 5539183622 jk/no-common later to maint). + + * "git rebase --rebase-merges" did not correctly pass --gpg-sign + command line option to underlying "git merge" when replaying a merge + using non-default merge strategy or when replaying an octopus merge + (because replaying a two-head merge with the default strategy was + done in a separate codepath, the problem did not trigger for most + users), which has been corrected. + (merge 43ad4f2eca sc/sequencer-gpg-octopus later to maint). + + * "git apply -R" did not handle patches that touch the same path + twice correctly, which has been corrected. This is most relevant + in a patch that changes a path from a regular file to a symbolic + link (and vice versa). + (merge b0f266de11 jt/apply-reverse-twice later to maint). + + * A recent oid->hash conversion missed one spot, breaking "git svn". + (merge 03bb366de4 bc/svn-hash-oid-fix later to maint). + + * The documentation on the "--abbrev=<n>" option did not say the + output may be longer than "<n>" hexdigits, which has been + clarified. + (merge cda34e0d0c jc/abbrev-doc later to maint). + + * "git p4" now honors init.defaultBranch configuration. + (merge 1b09d1917f js/p4-default-branch later to maint). + + * Recently the format of an internal state file "rebase -i" uses has + been tightened up for consistency, which would hurt those who start + "rebase -i" with old git and then continue with new git. Loosen + the reader side a bit (which we may want to tighten again in a year + or so). + (merge c779386182 jc/sequencer-stopped-sha-simplify later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge 3e0a5dc9af cc/doc-filter-branch-typofix later to maint). + (merge 32c83afc2c cw/ci-ghwf-check-ws-errors later to maint). + (merge 5eb2ed691b rs/tighten-callers-of-deref-tag later to maint). + (merge 6db29ab213 jk/fast-import-marks-cleanup later to maint). + (merge e5cf6d3df4 nk/dir-c-comment-update later to maint). + (merge 5710dcce74 jk/report-fn-typedef later to maint). + (merge 9a82db1056 en/sequencer-rollback-lock-cleanup later to maint). + (merge 4e1bee9a99 js/t7006-cleanup later to maint). + (merge f5bcde6c58 es/tutorial-mention-asciidoc-early later to maint). + (merge 714d491af0 so/format-patch-doc-on-default-diff-format later to maint). + (merge 0795df4b9b rs/clear-commit-marks-in-repo later to maint). + (merge 9542d56379 sd/prompt-local-variable later to maint). + (merge 06d43fad18 rs/pack-write-hashwrite-simplify later to maint). + (merge b7e20b4373 mc/typofix later to maint). + (merge f6bcd9a8a4 js/test-whitespace-fixes later to maint). + (merge 53b67a801b js/test-file-size later to maint). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 291b61e..d12094b 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -209,7 +209,7 @@ send them as replies to either an additional "cover letter" message (see below), the first patch, or the respective preceding patch. If your log message (including your name on the -Signed-off-by line) is not writable in ASCII, make sure that +`Signed-off-by` trailer) is not writable in ASCII, make sure that you send off a message in the correct encoding. WARNING: Be wary of your MUAs word-wrap @@ -229,7 +229,7 @@ previously sent. The `git format-patch` command follows the best current practice to format the body of an e-mail message. At the beginning of the patch should come your commit message, ending with the -Signed-off-by: lines, and a line that consists of three dashes, +`Signed-off-by` trailers, and a line that consists of three dashes, followed by the diffstat information and the patch itself. If you are forwarding a patch from somebody else, optionally, at the beginning of the e-mail message just before the commit @@ -290,25 +290,24 @@ identify them), to solicit comments and reviews. :git-ml: footnote:[The mailing list: git@vger.kernel.org] After the list reached a consensus that it is a good idea to apply the -patch, re-send it with "To:" set to the maintainer{current-maintainer} and "cc:" the -list{git-ml} for inclusion. +patch, re-send it with "To:" set to the maintainer{current-maintainer} +and "cc:" the list{git-ml} for inclusion. This is especially relevant +when the maintainer did not heavily participate in the discussion and +instead left the review to trusted others. Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and `Tested-by:` lines as necessary to credit people who helped your -patch. +patch, and "cc:" them when sending such a final version for inclusion. [[sign-off]] -=== Certify your work by adding your "Signed-off-by: " line +=== Certify your work by adding your `Signed-off-by` trailer -To improve tracking of who did what, we've borrowed the -"sign-off" procedure from the Linux kernel project on patches -that are being emailed around. Although core Git is a lot -smaller project it is a good discipline to follow it. +To improve tracking of who did what, we ask you to certify that you +wrote the patch or have the right to pass it on under the same license +as ours, by "signing off" your patch. Without sign-off, we cannot +accept your patches. -The sign-off is a simple line at the end of the explanation for -the patch, which certifies that you wrote it or otherwise have -the right to pass it on as an open-source patch. The rules are -pretty simple: if you can certify the below D-C-O: +If you can certify the below D-C-O: [[dco]] .Developer's Certificate of Origin 1.1 @@ -338,23 +337,29 @@ d. I understand and agree that this project and the contribution this project or the open source license(s) involved. ____ -then you just add a line saying +you add a "Signed-off-by" trailer to your commit, that looks like +this: .... Signed-off-by: Random J Developer <random@developer.example.org> .... -This line can be automatically added by Git if you run the git-commit -command with the -s option. +This line can be added by Git if you run the git-commit command with +the -s option. -Notice that you can place your own Signed-off-by: line when +Notice that you can place your own `Signed-off-by` trailer when forwarding somebody else's patch with the above rules for D-C-O. Indeed you are encouraged to do so. Do not forget to place an in-body "From: " line at the beginning to properly attribute the change to its true author (see (2) above). +This procedure originally came from the Linux kernel project, so our +rule is quite similar to theirs, but what exactly it means to sign-off +your patch differs from project to project, so it may be different +from that of the project you are accustomed to. + [[real-name]] -Also notice that a real name is used in the Signed-off-by: line. Please +Also notice that a real name is used in the `Signed-off-by` trailer. Please don't hide your real name. [[commit-trailers]] diff --git a/Documentation/config.txt b/Documentation/config.txt index f93b683..f292c26 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -265,7 +265,7 @@ color:: The basic colors accepted are `normal`, `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan` and `white`. The first color given is the foreground; the second is the background. All the basic colors except -`normal` have a bright variant that can be speficied by prefixing the +`normal` have a bright variant that can be specified by prefixing the color with `bright`, like `brightred`. + Colors may also be given as numbers between 0 and 255; these use ANSI @@ -334,12 +334,16 @@ include::config/checkout.txt[] include::config/clean.txt[] +include::config/clone.txt[] + include::config/color.txt[] include::config/column.txt[] include::config/commit.txt[] +include::config/commitgraph.txt[] + include::config/credential.txt[] include::config/completion.txt[] diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt index bdd37c3..acbd0c0 100644 --- a/Documentation/config/advice.txt +++ b/Documentation/config/advice.txt @@ -10,9 +10,8 @@ advice.*:: that the check is disabled. pushUpdateRejected:: Set this variable to 'false' if you want to disable - 'pushNonFFCurrent', - 'pushNonFFMatching', 'pushAlreadyExists', - 'pushFetchFirst', and 'pushNeedsForce' + 'pushNonFFCurrent', 'pushNonFFMatching', 'pushAlreadyExists', + 'pushFetchFirst', 'pushNeedsForce', and 'pushRefNeedsUpdate' simultaneously. pushNonFFCurrent:: Advice shown when linkgit:git-push[1] fails due to a @@ -41,6 +40,10 @@ advice.*:: we can still suggest that the user push to either 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. statusAheadBehind:: Shown when linkgit:git-status[1] computes the ahead/behind counts for a local ref compared to its remote tracking ref, diff --git a/Documentation/config/checkout.txt b/Documentation/config/checkout.txt index 6b64681..2cddf7b 100644 --- a/Documentation/config/checkout.txt +++ b/Documentation/config/checkout.txt @@ -1,18 +1,23 @@ checkout.defaultRemote:: - When you run 'git checkout <something>' - or 'git switch <something>' and only have one + When you run `git checkout <something>` + or `git switch <something>` and only have one remote, it may implicitly fall back on checking out and - tracking e.g. 'origin/<something>'. This stops working as soon - as you have more than one remote with a '<something>' + tracking e.g. `origin/<something>`. This stops working as soon + as you have more than one remote with a `<something>` reference. This setting allows for setting the name of a preferred remote that should always win when it comes to disambiguation. The typical use-case is to set this to `origin`. + Currently this is used by linkgit:git-switch[1] and -linkgit:git-checkout[1] when 'git checkout <something>' -or 'git switch <something>' -will checkout the '<something>' branch on another remote, -and by linkgit:git-worktree[1] when 'git worktree add' refers to a +linkgit:git-checkout[1] when `git checkout <something>` +or `git switch <something>` +will checkout the `<something>` branch on another remote, +and by linkgit:git-worktree[1] when `git worktree add` refers to a remote branch. This setting might be used for other checkout-like commands or functionality in the future. + +checkout.guess:: + Provides the default value for the `--guess` or `--no-guess` + option in `git checkout` and `git switch`. See + linkgit:git-switch[1] and linkgit:git-checkout[1]. diff --git a/Documentation/config/clone.txt b/Documentation/config/clone.txt new file mode 100644 index 0000000..47de36a --- /dev/null +++ b/Documentation/config/clone.txt @@ -0,0 +1,4 @@ +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 + option to linkgit:git-clone[1]. diff --git a/Documentation/config/commitgraph.txt b/Documentation/config/commitgraph.txt new file mode 100644 index 0000000..4582c39 --- /dev/null +++ b/Documentation/config/commitgraph.txt @@ -0,0 +1,8 @@ +commitGraph.maxNewFilters:: + Specifies the default value for the `--max-new-filters` option of `git + commit-graph write` (c.f., linkgit:git-commit-graph[1]). + +commitGraph.readChangedPaths:: + If true, then git will use the changed-path Bloom filters in the + commit-graph file (if it exists, and they are present). Defaults to + true. See linkgit:git-commit-graph[1] for more information. diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt index 86c91d5..160aaca 100644 --- a/Documentation/config/core.txt +++ b/Documentation/config/core.txt @@ -399,7 +399,7 @@ the largest projects. You probably do not need to adjust this value. Common unit suffixes of 'k', 'm', or 'g' are supported. core.deltaBaseCacheLimit:: - Maximum number of bytes to reserve for caching base objects + Maximum number of bytes per thread to reserve for caching base objects that may be referenced by multiple deltified objects. By storing the entire decompressed base objects in a cache Git is able to avoid unpacking and decompressing frequently used base diff --git a/Documentation/config/feature.txt b/Documentation/config/feature.txt index c0cbf2b..cdecd04 100644 --- a/Documentation/config/feature.txt +++ b/Documentation/config/feature.txt @@ -14,10 +14,6 @@ feature.experimental:: + * `fetch.negotiationAlgorithm=skipping` may improve fetch negotiation times by skipping more commits at a time, reducing the number of round trips. -+ -* `protocol.version=2` speeds up fetches from repositories with many refs by -allowing the client to specify which refs to list before the server lists -them. 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 b203940..6af6f5e 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/fmt-merge-msg.txt b/Documentation/config/fmt-merge-msg.txt index a8e8f74..3fbf40e 100644 --- a/Documentation/config/fmt-merge-msg.txt +++ b/Documentation/config/fmt-merge-msg.txt @@ -13,7 +13,7 @@ merge.suppressDest:: By adding a glob that matches the names of integration branches to this multi-valued configuration variable, the default merge message computed for merges into these - integration branches will omit " into <branch name>" from + integration branches will omit "into <branch name>" from its title. + An element with an empty value can be used to clear the list diff --git a/Documentation/config/format.txt b/Documentation/config/format.txt index 564e809..851bf41 100644 --- a/Documentation/config/format.txt +++ b/Documentation/config/format.txt @@ -79,7 +79,7 @@ format.thread:: format.signOff:: A boolean value which lets you enable the `-s/--signoff` option of - format-patch by default. *Note:* Adding the Signed-off-by: line to a + format-patch by default. *Note:* Adding the `Signed-off-by` trailer to a patch should be a conscious act and means that you certify you have the rights to submit this work under the same open source license. Please see the 'SubmittingPatches' document for further discussion. @@ -96,7 +96,9 @@ format.outputDirectory:: format.useAutoBase:: A boolean value which lets you enable the `--base=auto` option of - format-patch by default. + format-patch by default. Can also be set to "whenAble" to allow + enabling `--base=auto` if a suitable base is available, but to skip + adding base info otherwise without the format dying. format.notes:: Provides the default value for the `--notes` option to diff --git a/Documentation/config/mergetool.txt b/Documentation/config/mergetool.txt index 09ed31d..16a2744 100644 --- a/Documentation/config/mergetool.txt +++ b/Documentation/config/mergetool.txt @@ -30,6 +30,16 @@ mergetool.meld.hasOutput:: to `true` tells Git to unconditionally use the `--output` option, and `false` avoids using `--output`. +mergetool.meld.useAutoMerge:: + When the `--auto-merge` is given, meld will merge all non-conflicting + 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` + is supported and will only use `--auto-merge` when available. A + value of `false` avoids using `--auto-merge` altogether, and is the + default value. + mergetool.keepBackup:: After performing a merge, the original file with conflict markers can be saved as a file with a `.orig` extension. If this variable diff --git a/Documentation/config/protocol.txt b/Documentation/config/protocol.txt index c46e9b3..756591d 100644 --- a/Documentation/config/protocol.txt +++ b/Documentation/config/protocol.txt @@ -48,8 +48,7 @@ protocol.version:: If set, clients will attempt to communicate with a server using the specified protocol version. If the server does not support it, communication falls back to version 0. - If unset, the default is `0`, unless `feature.experimental` - is enabled, in which case the default is `2`. + If unset, the default is `2`. Supported versions: + -- diff --git a/Documentation/config/push.txt b/Documentation/config/push.txt index f5e5b38..21b256e 100644 --- a/Documentation/config/push.txt +++ b/Documentation/config/push.txt @@ -114,3 +114,9 @@ push.recurseSubmodules:: specifying '--recurse-submodules=check|on-demand|no'. If not set, 'no' is used by default, unless 'submodule.recurse' is set (in which case a 'true' value means 'on-demand'). + +push.useForceIfIncludes:: + If set to "true", it is equivalent to specifying + `--force-if-includes` as an option to linkgit:git-push[1] + in the command line. Adding `--no-force-if-includes` at the + time of push overrides this configuration setting. diff --git a/Documentation/config/receive.txt b/Documentation/config/receive.txt index 65f78aa..85d5b5a 100644 --- a/Documentation/config/receive.txt +++ b/Documentation/config/receive.txt @@ -114,6 +114,28 @@ receive.hideRefs:: An attempt to update or delete a hidden ref by `git push` is rejected. +receive.procReceiveRefs:: + This is a multi-valued variable that defines reference prefixes + to match the commands in `receive-pack`. Commands matching the + prefixes will be executed by an external hook "proc-receive", + instead of the internal `execute_commands` function. If this + variable is not defined, the "proc-receive" hook will never be + used, and all commands will be executed by the internal + `execute_commands` function. ++ +For example, if this variable is set to "refs/for", pushing to reference +such as "refs/for/master" will not create or update a reference named +"refs/for/master", but may create or update a pull request directly by +running the hook "proc-receive". ++ +Optional modifiers can be provided in the beginning of the value to filter +commands for specific actions: create (a), modify (m), delete (d). +A `!` can be included in the modifiers to negate the reference prefix entry. +E.g.: ++ + git config --system --add receive.procReceiveRefs ad:refs/heads + git config --system --add receive.procReceiveRefs !:refs/heads + receive.updateServerInfo:: If set to true, git-receive-pack will run git-update-server-info after receiving data from git-push and updating refs. diff --git a/Documentation/config/uploadpack.txt b/Documentation/config/uploadpack.txt index ee7b3ac..b0d7612 100644 --- a/Documentation/config/uploadpack.txt +++ b/Documentation/config/uploadpack.txt @@ -70,7 +70,7 @@ uploadpackfilter.<filter>.allow:: kinds must be allowed. Defaults to `uploadpackfilter.allow`. uploadpackfilter.tree.maxDepth:: - Only allow `--filter=tree=<n>` when `n` is no more than the value of + Only allow `--filter=tree:<n>` when `<n>` is no more than the value of `uploadpackfilter.tree.maxDepth`. If set, this also implies `uploadpackfilter.tree.allow=true`, unless this configuration variable had already been set. Has no effect if unset. diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt index e8ed647..b10ff4c 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 b7af973..2e7a938 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -36,9 +36,9 @@ endif::git-format-patch[] -U<n>:: --unified=<n>:: Generate diffs with <n> lines of context instead of - the usual three. Implies `--patch`. + the usual three. ifndef::git-format-patch[] - Implies `-p`. + Implies `--patch`. endif::git-format-patch[] --output=<file>:: @@ -441,15 +441,20 @@ endif::git-format-patch[] --binary:: In addition to `--full-index`, output a binary diff that - can be applied with `git-apply`. Implies `--patch`. + can be applied with `git-apply`. +ifndef::git-format-patch[] + Implies `--patch`. +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 the shortest prefix that is at least '<n>' + hexdigits long that uniquely refers the object. + 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>]]:: @@ -686,6 +691,11 @@ endif::git-format-patch[] --ignore-blank-lines:: Ignore changes whose lines are all blank. +-I<regex>:: +--ignore-matching-lines=<regex>:: + Ignore changes whose all lines match <regex>. This option may + be specified more than once. + --inter-hunk-context=<lines>:: Show the context between diff hunks, up to the specified number of lines, thereby fusing hunks that are close to each other. diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index b65a758..2bf77b4 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -197,7 +197,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-am.txt b/Documentation/git-am.txt index 38c0852..06bc063 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -33,7 +33,7 @@ OPTIONS -s:: --signoff:: - Add a `Signed-off-by:` line to the commit message, using + Add a `Signed-off-by` trailer to the commit message, using the committer identity of yourself. See the signoff option in linkgit:git-commit[1] for more information. diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt index b9aa390..91d9a86 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-archive.txt b/Documentation/git-archive.txt index cfa1e4e..9f81728 100644 --- a/Documentation/git-archive.txt +++ b/Documentation/git-archive.txt @@ -55,6 +55,12 @@ OPTIONS --output=<file>:: Write the archive to <file> instead of stdout. +--add-file=<file>:: + Add a non-tracked file to the archive. Can be repeated to add + multiple files. The path of the file in the archive is built + by concatenating the value for `--prefix` (if any) and the + basename of <file>. + --worktree-attributes:: Look for attributes in .gitattributes files in the working tree as well (see <<ATTRIBUTES>>). diff --git a/Documentation/git-bisect-lk2009.txt b/Documentation/git-bisect-lk2009.txt index 3ba49e8..f3d9566 100644 --- a/Documentation/git-bisect-lk2009.txt +++ b/Documentation/git-bisect-lk2009.txt @@ -473,7 +473,7 @@ Z-Z ------------- 2) starting from the "good" ends of the graph, associate to each -commit the number of ancestors it has plus one + commit the number of ancestors it has plus one For example with the following graph where H is the "bad" commit and A and D are some parents of some "good" commits: @@ -514,7 +514,7 @@ D---E ------------- 4) the best bisection point is the commit with the highest associated -number + number So in the above example the best bisection point is commit C. @@ -580,8 +580,8 @@ good or a bad commit does not give more or less information). Let's also suppose that we have a cleaned up graph like one after step 1) in the bisection algorithm above. This means that we can measure -the information we get in terms of number of commit we can remove from -the graph.. + the information we get in terms of number of commit we can remove + from the graph.. And let's take a commit X in the graph. @@ -689,18 +689,18 @@ roughly the following steps: 6) sort the commit by decreasing associated value 7) if the first commit has not been skipped, we can return it and stop -here + here 8) otherwise filter out all the skipped commits in the sorted list 9) use a pseudo random number generator (PRNG) to generate a random -number between 0 and 1 + number between 0 and 1 10) multiply this random number with its square root to bias it toward -0 + 0 11) multiply the result by the number of commits in the filtered list -to get an index into this list + to get an index into this list 12) return the commit at the computed index diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index 0e993e4..fbb39fb 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -16,7 +16,7 @@ DESCRIPTION The command takes various subcommands, and different options depending on the subcommand: - git bisect start [--term-{old,good}=<term> --term-{new,bad}=<term>] + 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>...] diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt index 7e81541..34b496d 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -87,7 +87,9 @@ include::blame-options.txt[] --abbrev=<n>:: Instead of using the default 7+1 hexadecimal digits as the - abbreviated object name, use <n>+1 digits. Note that 1 column + abbreviated object name, use <m>+1 digits, where <m> is at + least <n> but ensures the commit object names are unique. + Note that 1 column is used for a caret to mark the boundary commit. diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 03c0824..adaa178 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -9,9 +9,9 @@ SYNOPSIS -------- [verse] 'git branch' [--color[=<when>] | --no-color] [--show-current] - [-v [--abbrev=<length> | --no-abbrev]] + [-v [--abbrev=<n> | --no-abbrev]] [--column[=<options>] | --no-column] [--sort=<key>] - [(--merged | --no-merged) [<commit>]] + [--merged [<commit>]] [--no-merged [<commit>]] [--contains [<commit>]] [--no-contains [<commit>]] [--points-at <object>] [--format=<format>] [(-r | --remotes) | (-a | --all)] @@ -194,8 +194,10 @@ This option is only applicable in non-verbose mode. Be more quiet when creating or deleting a branch, suppressing non-error messages. ---abbrev=<length>:: - Alter the sha1's minimum display length in the output listing. +--abbrev=<n>:: + In the verbose listing that show the commit object name, + show the shortest prefix that is at least '<n>' hexdigits + long that uniquely refers the object. The default value is 7 and can be overridden by the `core.abbrev` config option. @@ -252,13 +254,11 @@ start-point is either a local or remote-tracking branch. --merged [<commit>]:: Only list branches whose tips are reachable from the - specified commit (HEAD if not specified). Implies `--list`, - incompatible with `--no-merged`. + specified commit (HEAD if not specified). Implies `--list`. --no-merged [<commit>]:: Only list branches whose tips are not reachable from the - specified commit (HEAD if not specified). Implies `--list`, - incompatible with `--merged`. + specified commit (HEAD if not specified). Implies `--list`. <branchname>:: The name of the branch to create or delete. @@ -370,6 +370,8 @@ serve four related but different purposes: - `--no-merged` is used to find branches which are candidates for merging into HEAD, since those branches are not fully contained by HEAD. +include::ref-reachability-filters.txt[] + SEE ALSO -------- linkgit:git-check-ref-format[1], diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 5b697ee..b1a6fe4 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -192,12 +192,16 @@ branches from there if `<branch>` is ambiguous but exists on the 'origin' remote. See also `checkout.defaultRemote` in linkgit:git-config[1]. + -Use `--no-guess` to disable this. +`--guess` is the default behavior. Use `--no-guess` to disable it. ++ +The default behavior can be set via the `checkout.guess` configuration +variable. -l:: Create the new branch's reflog; see linkgit:git-branch[1] for details. +-d:: --detach:: Rather than checking out a branch to work on it, check out a commit for inspection and discardable experiments. @@ -350,6 +354,10 @@ leave out at most one of `A` and `B`, in which case it defaults to `HEAD`. <tree-ish>:: Tree to checkout from (when paths are given). If not specified, the index will be used. ++ +As a special case, you may use `"A...B"` as a shortcut for the +merge base of `A` and `B` if there is exactly one merge base. You can +leave out at most one of `A` and `B`, in which case it defaults to `HEAD`. \--:: Do not interpret any more arguments as options. diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index 75feeef..5d75031 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -104,7 +104,7 @@ effect to your index in a row. -s:: --signoff:: - Add Signed-off-by line at the end of the commit message. + Add a `Signed-off-by` trailer at the end of the commit message. See the signoff option in linkgit:git-commit[1] for more information. -S[<keyid>]:: diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 097e6a8..876aedc 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -183,8 +183,9 @@ objects from the source repository into a pack in the cloned repository. -o <name>:: --origin <name>:: - Instead of using the remote name `origin` to keep track - of the upstream repository, use `<name>`. + Instead of using the remote name `origin` to keep track of the upstream + repository, use `<name>`. Overrides `clone.defaultRemoteName` from the + config. -b <name>:: --branch <name>:: diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt index 17405c7..e1f48c9 100644 --- a/Documentation/git-commit-graph.txt +++ b/Documentation/git-commit-graph.txt @@ -39,7 +39,9 @@ COMMANDS -------- 'write':: -Write a commit-graph file based on the commits found in packfiles. +Write a commit-graph file based on the commits found in packfiles. If +the config option `core.commitGraph` is disabled, then this command will +output a warning, then return success without writing a commit-graph file. + With the `--stdin-packs` option, generate the new commit graph by walking objects only in the specified pack-indexes. (Cannot be combined @@ -67,6 +69,13 @@ this option is given, future commit-graph writes will automatically assume that this option was intended. Use `--no-changed-paths` to stop storing this data. + +With the `--max-new-filters=<n>` option, generate at most `n` new Bloom +filters (if `--changed-paths` is specified). If `n` is `-1`, no limit is +enforced. Only commits present in the new layer count against this +limit. To retroactively compute Bloom filters over earlier layers, it is +advised to use `--split=replace`. Overrides the `commitGraph.maxNewFilters` +configuration. ++ With the `--split[=<strategy>]` option, write the commit-graph as a chain of multiple commit-graph files stored in `<dir>/info/commit-graphs`. Commit-graph layers are merged based on the diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index a3baea3..17150fa 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -59,6 +59,7 @@ commit by giving the same set of parameters (options and paths). If you make a commit and then find a mistake immediately after that, you can recover from it with 'git reset'. +:git-commit: 1 OPTIONS ------- @@ -163,14 +164,7 @@ The `-m` option is mutually exclusive with `-c`, `-C`, and `-F`. message, the commit is aborted. This has no effect when a message is given by other means, e.g. with the `-m` or `-F` options. --s:: ---signoff:: - Add Signed-off-by line by the committer at the end of the commit - log message. The meaning of a signoff depends on the project, - but it typically certifies that committer has - the rights to submit this work under the same license and - agrees to a Developer Certificate of Origin - (see http://developercertificate.org/ for more information). +include::signoff-option.txt[] -n:: --no-verify:: diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt index f4bd815..27acb31 100644 --- a/Documentation/git-diff-index.txt +++ b/Documentation/git-diff-index.txt @@ -9,7 +9,7 @@ git-diff-index - Compare a tree to the working tree or index SYNOPSIS -------- [verse] -'git diff-index' [-m] [--cached] [<common diff options>] <tree-ish> [<path>...] +'git diff-index' [-m] [--cached] [--merge-base] [<common diff options>] <tree-ish> [<path>...] DESCRIPTION ----------- @@ -27,7 +27,12 @@ include::diff-options.txt[] The id of a tree object to diff against. --cached:: - do not consider the on-disk file at all + Do not consider the on-disk file at all. + +--merge-base:: + Instead of comparing <tree-ish> directly, use the merge base + between <tree-ish> and HEAD instead. <tree-ish> must be a + commit. -m:: By default, files recorded in the index but not checked diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt index 5c8a2a5..2fc24c5 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git diff-tree' [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty] - [-t] [-r] [-c | --cc] [--combined-all-paths] [--root] + [-t] [-r] [-c | --cc] [--combined-all-paths] [--root] [--merge-base] [<common diff options>] <tree-ish> [<tree-ish>] [<path>...] DESCRIPTION @@ -43,6 +43,11 @@ include::diff-options.txt[] When `--root` is specified the initial commit will be shown as a big creation event. This is equivalent to a diff against the NULL tree. +--merge-base:: + Instead of comparing the <tree-ish>s directly, use the merge + base between the two <tree-ish>s as the "before" side. There + must be two <tree-ish>s given and they must both be commits. + --stdin:: When `--stdin` is specified, the command does not take <tree-ish> arguments from the command line. Instead, it diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 727f24d..7f4c8a8 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -10,8 +10,8 @@ SYNOPSIS -------- [verse] 'git diff' [<options>] [<commit>] [--] [<path>...] -'git diff' [<options>] --cached [<commit>] [--] [<path>...] -'git diff' [<options>] <commit> [<commit>...] <commit> [--] [<path>...] +'git diff' [<options>] --cached [--merge-base] [<commit>] [--] [<path>...] +'git diff' [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...] 'git diff' [<options>] <commit>...<commit> [--] [<path>...] 'git diff' [<options>] <blob> <blob> 'git diff' [<options>] --no-index [--] <path> <path> @@ -40,7 +40,7 @@ files on disk. or when running the command outside a working tree controlled by Git. This form implies `--exit-code`. -'git diff' [<options>] --cached [<commit>] [--] [<path>...]:: +'git diff' [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]:: This form is to view the changes you staged for the next commit relative to the named <commit>. Typically you @@ -49,6 +49,10 @@ files on disk. If HEAD does not exist (e.g. unborn branches) and <commit> is not given, it shows all staged changes. --staged is a synonym of --cached. ++ +If --merge-base is given, instead of using <commit>, use the merge base +of <commit> and HEAD. `git diff --merge-base A` is equivalent to +`git diff $(git merge-base A HEAD)`. 'git diff' [<options>] <commit> [--] [<path>...]:: @@ -58,23 +62,27 @@ files on disk. branch name to compare with the tip of a different branch. -'git diff' [<options>] <commit> <commit> [--] [<path>...]:: +'git diff' [<options>] [--merge-base] <commit> <commit> [--] [<path>...]:: This is to view the changes between two arbitrary <commit>. ++ +If --merge-base is given, use the merge base of the two commits for the +"before" side. `git diff --merge-base A B` is equivalent to +`git diff $(git merge-base A B) B`. 'git diff' [<options>] <commit> <commit>... <commit> [--] [<path>...]:: This form is to view the results of a merge commit. The first listed <commit> must be the merge itself; the remaining two or more commits should be its parents. A convenient way to produce - the desired set of revisions is to use the {caret}@ suffix. + the desired set of revisions is to use the `^@` suffix. For instance, if `master` names a merge commit, `git diff master master^@` gives the same combined diff as `git show master`. 'git diff' [<options>] <commit>..<commit> [--] [<path>...]:: - This is synonymous to the earlier form (without the "..") for + This is synonymous to the earlier form (without the `..`) for viewing the changes between two arbitrary <commit>. If <commit> on one side is omitted, it will have the same effect as using HEAD instead. @@ -83,20 +91,20 @@ files on disk. This form is to view the changes on the branch containing and up to the second <commit>, starting at a common ancestor - of both <commit>. "git diff A\...B" is equivalent to - "git diff $(git merge-base A B) B". You can omit any one + of both <commit>. `git diff A...B` is equivalent to + `git diff $(git merge-base A B) B`. You can omit any one of <commit>, which has the same effect as using HEAD instead. Just in case you are doing something exotic, it should be noted that all of the <commit> in the above description, except -in the last two forms that use ".." notations, can be any -<tree>. +in the `--merge-base` case and in the last two forms that use `..` +notations, can be any <tree>. For a more complete list of ways to spell <commit>, see "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7]. However, "diff" is about comparing two _endpoints_, not ranges, -and the range notations ("<commit>..<commit>" and -"<commit>\...<commit>") do not mean a range as defined in the +and the range notations (`<commit>..<commit>` and +`<commit>...<commit>`) do not mean a range as defined in the "SPECIFYING RANGES" section in linkgit:gitrevisions[7]. 'git diff' [<options>] <blob> <blob>:: @@ -144,9 +152,9 @@ $ git diff HEAD <3> + <1> Changes in the working tree not yet staged for the next commit. <2> Changes between the index and your last commit; what you - would be committing if you run "git commit" without "-a" option. + would be committing if you run `git commit` without `-a` option. <3> Changes in the working tree since your last commit; what you - would be committing if you run "git commit -a" + would be committing if you run `git commit -a` Comparing with arbitrary commits:: + diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index 7d9aad2..39cfa05 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -814,7 +814,7 @@ may have uses for this information 'original-oid' SP <object-identifier> LF .... -where `<object-identifer>` is any string not containing LF. +where `<object-identifier>` is any string not containing LF. `tag` ~~~~~ diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt index 45b6d8e..9067c20 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-filter-branch.txt b/Documentation/git-filter-branch.txt index 40ba4aa..62e482a 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -532,7 +532,7 @@ The https://github.com/newren/git-filter-repo/[git filter-repo] tool is an alternative to git-filter-branch which does not suffer from these performance problems or the safety problems (mentioned below). For those with existing tooling which relies upon git-filter-branch, 'git -repo-filter' also provides +filter-repo' also provides https://github.com/newren/git-filter-repo/blob/master/contrib/filter-repo-demos/filter-lamely[filter-lamely], a drop-in git-filter-branch replacement (with a few caveats). While filter-lamely suffers from all the same safety issues as diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 2ea71c5..2962f85 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -11,7 +11,7 @@ SYNOPSIS 'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl] [(--sort=<key>)...] [--format=<format>] [<pattern>...] [--points-at=<object>] - (--merged[=<object>] | --no-merged[=<object>]) + [--merged[=<object>]] [--no-merged[=<object>]] [--contains[=<object>]] [--no-contains[=<object>]] DESCRIPTION @@ -76,13 +76,11 @@ OPTIONS --merged[=<object>]:: Only list refs whose tips are reachable from the - specified commit (HEAD if not specified), - incompatible with `--no-merged`. + specified commit (HEAD if not specified). --no-merged[=<object>]:: Only list refs whose tips are not reachable from the - specified commit (HEAD if not specified), - incompatible with `--merged`. + specified commit (HEAD if not specified). --contains[=<object>]:: Only list refs which contain the specified commit (HEAD if not @@ -222,6 +220,8 @@ worktreepath:: In addition to the above, for commit and tag objects, the header field names (`tree`, `parent`, `object`, `type`, and `tag`) can be used to specify the value in the header field. +Fields `tree` and `parent` can also be used with modifier `:short` and +`:short=<length>` just like `objectname`. For commit and tag objects, the special `creatordate` and `creator` fields will correspond to the appropriate date or name-email-date tuple @@ -230,7 +230,10 @@ These are intended for working on a mix of annotated and lightweight tags. 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. +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. The message in a commit or a tag object is `contents`, from which `contents:<part>` can be used to extract various parts out of: @@ -242,6 +245,9 @@ contents:subject:: The first paragraph of the message, which typically is a single line, is taken as the "subject" of the commit or the tag message. + Instead of `contents:subject`, field `subject` can also be used to + obtain same results. `:sanitize` can be appended to `subject` for + subject line suitable for filename. contents:body:: The remainder of the commit or the tag message that follows @@ -400,6 +406,11 @@ Note also that multiple copies of an object may be present in the object database; in this case, it is undefined which copy's size or delta base will be reported. +NOTES +----- + +include::ref-reachability-filters.txt[] + SEE ALSO -------- linkgit:git-show-ref[1] diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 0f81d04..bf1bb40 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -119,7 +119,7 @@ include::diff-options.txt[] -s:: --signoff:: - Add `Signed-off-by:` line to the commit message, using + Add a `Signed-off-by` trailer to the commit message, using the committer identity of yourself. See the signoff option in linkgit:git-commit[1] for more information. diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index a7f9bc9..6077ff0 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -209,7 +209,7 @@ providing this option will cause it to die. 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 git-config(1)). + variable core.quotePath (see linkgit:git-config[1]). -o:: --only-matching:: diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt index 65b53fc..63cf498 100644 --- a/Documentation/git-imap-send.txt +++ b/Documentation/git-imap-send.txt @@ -51,17 +51,13 @@ OPTIONS CONFIGURATION ------------- -To use the tool, imap.folder and either imap.tunnel or imap.host must be set +To use the tool, `imap.folder` and either `imap.tunnel` or `imap.host` must be set to appropriate values. -Variables -~~~~~~~~~ - include::config/imap.txt[] -Examples -~~~~~~~~ - +EXAMPLES +-------- Using tunnel mode: .......................... @@ -89,14 +85,18 @@ Using direct mode with SSL: user = bob pass = p4ssw0rd port = 123 - sslverify = false + ; sslVerify = false ......................... -EXAMPLES --------- -To submit patches using GMail's IMAP interface, first, edit your ~/.gitconfig -to specify your account settings: +[NOTE] +You may want to use `sslVerify=false` +while troubleshooting, if you suspect that the reason you are +having trouble connecting is because the certificate you use at +the private server `example.com` you are trying to set up (or +have set up) may not be verified correctly. + +Using Gmail's IMAP interface: --------- [imap] @@ -104,17 +104,21 @@ to specify your account settings: host = imaps://imap.gmail.com user = user@gmail.com port = 993 - sslverify = false --------- -You might need to instead use: folder = "[Google Mail]/Drafts" if you get an error +[NOTE] +You might need to instead use: `folder = "[Google Mail]/Drafts"` if you get an error that the "Folder doesn't exist". +[NOTE] +If your Gmail account is set to another language than English, the name of the "Drafts" +folder will be localized. + Once the commits are ready to be sent, run the following command: $ git format-patch --cover-letter -M --stdout origin/master | git imap-send -Just make sure to disable line wrapping in the email client (GMail's web +Just make sure to disable line wrapping in the email client (Gmail's web interface will wrap lines no matter what, so you need to use a real IMAP client). diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt index ac74d05..af0c262 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 ddfe265..59ecda6 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>:: @@ -68,7 +70,7 @@ repository. + If this is reinitialization, the repository will be moved to the specified path. --b <branch-name:: +-b <branch-name>:: --initial-branch=<branch-name>:: Use the specified name for the initial branch in the newly created repository. diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 3cb2ebb..cbcf526 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -19,7 +19,7 @@ SYNOPSIS [--exclude-standard] [--error-unmatch] [--with-tree=<tree-ish>] [--full-name] [--recurse-submodules] - [--abbrev] [--] [<file>...] + [--abbrev[=<n>]] [--] [<file>...] DESCRIPTION ----------- @@ -153,7 +153,8 @@ a space) at the start of each line: --abbrev[=<n>]:: Instead of showing the full 40-byte hexadecimal object - lines, show only a partial prefix. + lines, show the shortest prefix that is at least '<n>' + hexdigits long that uniquely refers the object. Non default number of digits can be specified with --abbrev=<n>. --debug:: diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt index a751571..db02d6d 100644 --- a/Documentation/git-ls-tree.txt +++ b/Documentation/git-ls-tree.txt @@ -62,7 +62,8 @@ OPTIONS --abbrev[=<n>]:: Instead of showing the full 40-byte hexadecimal object - lines, show only a partial prefix. + lines, show the shortest prefix that is at least '<n>' + hexdigits long that uniquely refers the object. Non default number of digits can be specified with --abbrev=<n>. --full-name:: diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt index 3bbc731..7a6aed0 100644 --- a/Documentation/git-mailinfo.txt +++ b/Documentation/git-mailinfo.txt @@ -72,10 +72,9 @@ conversion, even with this flag. is useful in order to associate commits with mailing list discussions. --scissors:: - Remove everything in body before a scissors line. A line that - mainly consists of scissors (either ">8" or "8<") and perforation - (dash "-") marks is called a scissors line, and is used to request - the reader to cut the message at that line. If such a line + Remove everything in body before a scissors line (e.g. "-- >8 --"). + The line represents scissors and perforation marks, and is used to + request the reader to cut the message at that line. If that line appears in the body of the message before the patch, everything before it (including the scissors line itself) is ignored when this option is used. diff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.txt index 0c66194..eb0caa0 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-p4.txt b/Documentation/git-p4.txt index dab9609..ec233ac 100644 --- a/Documentation/git-p4.txt +++ b/Documentation/git-p4.txt @@ -417,7 +417,7 @@ p4-post-changelist ~~~~~~~~~~~~~~~~~~ The `p4-post-changelist` hook is invoked after the submit has -successfully occured in P4. It takes no parameters and is meant +successfully occurred in P4. It takes no parameters and is meant primarily for notification and cannot affect the outcome of the git p4 submit action. diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 3b80534..ab103c8 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -13,7 +13,7 @@ SYNOPSIS [--repo=<repository>] [-f | --force] [-d | --delete] [--prune] [-v | --verbose] [-u | --set-upstream] [-o <string> | --push-option=<string>] [--[no-]signed|--signed=(true|false|if-asked)] - [--force-with-lease[=<refname>[:<expect>]]] + [--force-with-lease[=<refname>[:<expect>]] [--force-if-includes]] [--no-verify] [<repository> [<refspec>...]] DESCRIPTION @@ -320,6 +320,14 @@ seen and are willing to overwrite, then rewrite history, and finally force push changes to `master` if the remote version is still at `base`, regardless of what your local `remotes/origin/master` has been updated to in the background. ++ +Alternatively, specifying `--force-if-includes` as an ancillary option +along with `--force-with-lease[=<refname>]` (i.e., without saying what +exact commit the ref on the remote side must be pointing at, or which +refs on the remote side are being protected) at the time of "push" will +verify if updates from the remote-tracking refs that may have been +implicitly updated in the background are integrated locally before +allowing a forced update. -f:: --force:: @@ -341,6 +349,22 @@ one branch, use a `+` in front of the refspec to push (e.g `git push origin +master` to force a push to the `master` branch). See the `<refspec>...` section above for details. +--[no-]force-if-includes:: + Force an update only if the tip of the remote-tracking ref + has been integrated locally. ++ +This option enables a check that verifies if the tip of the +remote-tracking ref is reachable from one of the "reflog" entries of +the local branch based in it for a rewrite. The check ensures that any +updates from the remote have been incorporated locally by rejecting the +forced update if that is not the case. ++ +If the option is passed without specifying `--force-with-lease`, or +specified along with `--force-with-lease=<refname>:<expect>`, it is +a "no-op". ++ +Specifying `--no-force-if-includes` disables this behavior. + --repo=<repository>:: This option is equivalent to the <repository> argument. If both are specified, the command-line argument takes precedence. diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 374d248..a0487b5 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,22 +460,43 @@ 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. --signoff:: - Add a Signed-off-by: trailer to all the rebased commits. Note + Add a `Signed-off-by` trailer to all the rebased commits. Note that if `--interactive` is given then only commits marked to be picked, edited or reworded will have the trailer added. + @@ -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-remote.txt b/Documentation/git-remote.txt index 9659abb..31c29c9 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git remote' [-v | --verbose] -'git remote add' [-t <branch>] [-m <master>] [-f] [--[no-]tags] [--mirror=<fetch|push>] <name> <url> +'git remote add' [-t <branch>] [-m <master>] [-f] [--[no-]tags] [--mirror=(fetch|push)] <name> <url> 'git remote rename' <old> <new> 'git remote remove' <name> 'git remote set-head' <name> (-a | --auto | -d | --delete | <branch>) @@ -35,7 +35,7 @@ OPTIONS -v:: --verbose:: Be a little more verbose and show remote url after name. - NOTE: This must be placed between `remote` and `subcommand`. + NOTE: This must be placed between `remote` and subcommand. COMMANDS @@ -46,7 +46,7 @@ subcommands are available to perform operations on the remotes. 'add':: -Adds a remote named <name> for the repository at +Add a remote named <name> for the repository at <url>. The command `git fetch <name>` can then be used to create and update remote-tracking branches <name>/<branch>. + @@ -109,13 +109,13 @@ With `-d` or `--delete`, the symbolic ref `refs/remotes/<name>/HEAD` is deleted. + With `-a` or `--auto`, the remote is queried to determine its `HEAD`, then the symbolic-ref `refs/remotes/<name>/HEAD` is set to the same branch. e.g., if the remote -`HEAD` is pointed at `next`, "`git remote set-head origin -a`" will set +`HEAD` is pointed at `next`, `git remote set-head origin -a` will set the symbolic-ref `refs/remotes/origin/HEAD` to `refs/remotes/origin/next`. This will only work if `refs/remotes/origin/next` already exists; if not it must be fetched first. + -Use `<branch>` to set the symbolic-ref `refs/remotes/<name>/HEAD` explicitly. e.g., "git -remote set-head origin master" will set the symbolic-ref `refs/remotes/origin/HEAD` to +Use `<branch>` to set the symbolic-ref `refs/remotes/<name>/HEAD` explicitly. e.g., `git +remote set-head origin master` will set the symbolic-ref `refs/remotes/origin/HEAD` to `refs/remotes/origin/master`. This will only work if `refs/remotes/origin/master` already exists; if not it must be fetched first. + @@ -127,7 +127,7 @@ This can be used to track a subset of the available remote branches after the initial setup for a remote. + The named branches will be interpreted as if specified with the -`-t` option on the 'git remote add' command line. +`-t` option on the `git remote add` command line. + With `--add`, instead of replacing the list of currently tracked branches, adds to that list. @@ -181,16 +181,16 @@ fetch --prune <name>`, except that no new references will be fetched. See the PRUNING section of linkgit:git-fetch[1] for what it'll prune depending on various configuration. + -With `--dry-run` option, report what branches will be pruned, but do not +With `--dry-run` option, report what branches would be pruned, but do not actually prune them. 'update':: Fetch updates for remotes or remote groups in the repository as defined by -remotes.<group>. If neither group nor remote is specified on the command line, +`remotes.<group>`. If neither group nor remote is specified on the command line, the configuration parameter remotes.default will be used; if remotes.default is not defined, all remotes which do not have the -configuration parameter remote.<name>.skipDefaultUpdate set to true will +configuration parameter `remote.<name>.skipDefaultUpdate` set to true will be updated. (See linkgit:git-config[1]). + With `--prune` option, run pruning against all the remotes that are updated. @@ -203,6 +203,17 @@ The remote configuration is achieved using the `remote.origin.url` and `remote.origin.fetch` configuration variables. (See linkgit:git-config[1]). +EXIT STATUS +----------- + +On success, the exit status is `0`. + +When subcommands such as 'add', 'rename', and 'remove' can't find the +remote in question, the exit status is `2`. When the remote already +exists, the exit status is `3`. + +On any other error, the exit status may be any other non-zero value. + EXAMPLES -------- diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt index 84c6c40..55bde91 100644 --- a/Documentation/git-restore.txt +++ b/Documentation/git-restore.txt @@ -40,6 +40,10 @@ OPTIONS + If not specified, the contents are restored from `HEAD` if `--staged` is given, otherwise from the index. ++ +As a special case, you may use `"A...B"` as a shortcut for the +merge base of `A` and `B` if there is exactly one merge base. You can +leave out at most one of `A` and `B`, in which case it defaults to `HEAD`. -p:: --patch:: diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index 044276e..bb92a4a 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -99,7 +99,7 @@ effect to your index in a row. -s:: --signoff:: - Add Signed-off-by line at the end of the commit message. + Add a `Signed-off-by` trailer at the end of the commit message. See the signoff option in linkgit:git-commit[1] for more information. --strategy=<strategy>:: diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 0a69810..b7bbbea 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -313,7 +313,7 @@ Automating the value of `sendemail.identity`. --[no-]signed-off-by-cc:: - If this is set, add emails found in Signed-off-by: or Cc: lines to the + 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 value; if that is unspecified, default to --signed-off-by-cc. @@ -340,7 +340,7 @@ Automating except for self (use 'self' for that). - 'bodycc' will avoid including anyone mentioned in Cc lines in the patch body (commit message) except for self (use 'self' for that). -- 'sob' will avoid including anyone mentioned in Signed-off-by lines except +- 'sob' will avoid including anyone mentioned in the Signed-off-by trailers except for self (use 'self' for that). - 'misc-by' will avoid including anyone mentioned in Acked-by, Reviewed-by, Tested-by and other "-by" lines in the patch body, diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt index a72ea7f..fd93cd4 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -47,9 +47,38 @@ OPTIONS Each pretty-printed commit will be rewrapped before it is shown. +--group=<type>:: + Group commits based on `<type>`. If no `--group` option is + specified, the default is `author`. `<type>` is one of: ++ +-- + - `author`, commits are grouped by author + - `committer`, commits are grouped by committer (the same as `-c`) + - `trailer:<field>`, the `<field>` is interpreted as a case-insensitive + commit message trailer (see linkgit:git-interpret-trailers[1]). For + example, if your project uses `Reviewed-by` trailers, you might want + to see who has been reviewing with + `git shortlog -ns --group=trailer:reviewed-by`. ++ +Note that commits that do not include the trailer will not be counted. +Likewise, commits with multiple trailers (e.g., multiple signoffs) may +be counted more than once (but only once per unique trailer value in +that commit). ++ +Shortlog will attempt to parse each trailer value as a `name <email>` +identity. If successful, the mailmap is applied and the email is omitted +unless the `--email` option is specified. If the value cannot be parsed +as an identity, it will be taken literally and completely. +-- ++ +If `--group` is specified multiple times, commits are counted under each +value (but again, only once per unique value in that commit). For +example, `git shortlog --group=author --group=trailer:co-authored-by` +counts both authors and co-authors. + -c:: --committer:: - Collect and show committer identities instead of authors. + This is an alias for `--group=committer`. -w[<width>[,<indent1>[,<indent2>]]]:: Linewrap the output by wrapping each line at `width`. The first diff --git a/Documentation/git-show-index.txt b/Documentation/git-show-index.txt index 39b1d8e..e49318a 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-svn.txt b/Documentation/git-svn.txt index 6624a14..67b143c 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -701,7 +701,7 @@ creating the branch or tag. --use-log-author:: When retrieving svn commits into Git (as part of 'fetch', 'rebase', or - 'dcommit' operations), look for the first `From:` or `Signed-off-by:` line + 'dcommit' operations), look for the first `From:` line or `Signed-off-by` trailer in the log message and use that as the author string. + [verse] @@ -710,7 +710,7 @@ config key: svn.useLogAuthor --add-author-from:: When committing to svn from Git (as part of 'set-tree' or 'dcommit' operations), if the existing log message doesn't already have a - `From:` or `Signed-off-by:` line, append a `From:` line based on the + `From:` or `Signed-off-by` trailer, append a `From:` line based on the Git commit's author string. If you use this, then `--use-log-author` will retrieve a valid author string for all commits. + diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt index 3759c3a..5c438cd 100644 --- a/Documentation/git-switch.txt +++ b/Documentation/git-switch.txt @@ -103,6 +103,9 @@ ambiguous but exists on the 'origin' remote. See also `checkout.defaultRemote` in linkgit:git-config[1]. + `--guess` is the default behavior. Use `--no-guess` to disable it. ++ +The default behavior can be set via the `checkout.guess` configuration +variable. -f:: --force:: diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index f6d9791..56656d1 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -15,7 +15,7 @@ SYNOPSIS 'git tag' [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>] [--points-at <object>] [--column[=<options>] | --no-column] [--create-reflog] [--sort=<key>] [--format=<format>] - [--[no-]merged [<commit>]] [<pattern>...] + [--merged <commit>] [--no-merged <commit>] [<pattern>...] 'git tag' -v [--format=<format>] <tagname>... DESCRIPTION @@ -149,11 +149,11 @@ This option is only applicable when listing tags without annotation lines. --merged [<commit>]:: Only list tags whose commits are reachable from the specified - commit (`HEAD` if not specified), incompatible with `--no-merged`. + commit (`HEAD` if not specified). --no-merged [<commit>]:: Only list tags whose commits are not reachable from the specified - commit (`HEAD` if not specified), incompatible with `--merged`. + commit (`HEAD` if not specified). --points-at <object>:: Only list tags of the given object (HEAD if not @@ -377,6 +377,11 @@ $ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1 include::date-formats.txt[] +NOTES +----- + +include::ref-reachability-filters.txt[] + SEE ALSO -------- linkgit:git-check-ref-format[1]. diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index 6ee6ec7..af06128 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -15,6 +15,7 @@ SYNOPSIS 'git worktree move' <worktree> <new-path> 'git worktree prune' [-n] [-v] [--expire <expire>] 'git worktree remove' [-f] <worktree> +'git worktree repair' [<path>...] 'git worktree unlock' <worktree> DESCRIPTION @@ -31,6 +32,18 @@ A repository has one main working tree (if it's not a bare repository) and zero or more linked working trees. When you are done with a linked working tree, remove it with `git worktree remove`. +In its simplest form, `git worktree add <path>` automatically creates a +new branch whose name is the final component of `<path>`, which is +convenient if you plan to work on a new topic. For instance, `git +worktree add ../hotfix` creates new branch `hotfix` and checks it out at +path `../hotfix`. To instead work on an existing branch in a new working +tree, use `git worktree add <path> <branch>`. On the other hand, if you +just plan to make some experimental changes or do testing without +disturbing existing development, it is often convenient to create a +'throwaway' working tree not associated with any branch. For instance, +`git worktree add -d <path>` creates a new working tree with a detached +`HEAD` at the same commit as the current branch. + If a working tree is deleted without using `git worktree remove`, then its associated administrative files, which reside in the repository (see "DETAILS" below), will eventually be removed automatically (see @@ -83,8 +96,9 @@ list:: List details of each working tree. The main working tree is listed first, followed by each of the linked working trees. The output details include -whether the working tree is bare, the revision currently checked out, and the -branch currently checked out (or "detached HEAD" if none). +whether the working tree is bare, the revision currently checked out, the +branch currently checked out (or "detached HEAD" if none), and "locked" if +the worktree is locked. lock:: @@ -97,7 +111,10 @@ with `--reason`. move:: Move a working tree to a new location. Note that the main working tree -or linked working trees containing submodules cannot be moved. +or linked working trees containing submodules cannot be moved with this +command. (The `git worktree repair` command, however, can reestablish +the connection with linked working trees if you move the main working +tree manually.) prune:: @@ -110,6 +127,23 @@ and no modification in tracked files) can be removed. Unclean working trees or ones with submodules can be removed with `--force`. The main working tree cannot be removed. +repair [<path>...]:: + +Repair working tree administrative files, if possible, if they have +become corrupted or outdated due to external factors. ++ +For instance, if the main working tree (or bare repository) is moved, +linked working trees will be unable to locate it. Running `repair` in +the main working tree will reestablish the connection from linked +working trees back to the main working tree. ++ +Similarly, if a linked working tree is moved without using `git worktree +move`, the main working tree (or bare repository) will be unable to +locate it. Running `repair` within the recently-moved working tree will +reestablish the connection. If multiple linked working trees are moved, +running `repair` from any working tree with each tree's new `<path>` as +an argument, will reestablish the connection to all the specified paths. + unlock:: Unlock a working tree, allowing it to be pruned, moved or deleted. @@ -143,6 +177,7 @@ To remove a locked working tree, specify `--force` twice. exists. `-B` overrides this safeguard, resetting `<new-branch>` to `<commit-ish>`. +-d:: --detach:: With `add`, detach `HEAD` in the new working tree. See "DETACHED HEAD" in linkgit:git-checkout[1]. @@ -303,7 +338,8 @@ in the entry's directory. For example, if a linked working tree is moved to `/newpath/test-next` and its `.git` file points to `/path/main/.git/worktrees/test-next`, then update `/path/main/.git/worktrees/test-next/gitdir` to reference `/newpath/test-next` -instead. +instead. Better yet, run `git worktree repair` to reestablish the connection +automatically. To prevent a `$GIT_DIR/worktrees` entry from being pruned (which can be useful in some situations, such as when the diff --git a/Documentation/git.txt b/Documentation/git.txt index 81349a8..c463b93 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' @@ -714,6 +722,10 @@ of clones and fetches. time of each Git command. See `GIT_TRACE` for available trace output options. +`GIT_TRACE_REFS`:: + Enables trace messages for operations on the ref database. + See `GIT_TRACE` for available trace output options. + `GIT_TRACE_SETUP`:: Enables trace messages printing the .git, working tree and current working directory after Git has completed its setup phase. diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 2d0a037..e84e104 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -802,6 +802,9 @@ patterns are available: - `ada` suitable for source code in the Ada language. +- `bash` suitable for source code in the Bourne-Again SHell language. + Covers a superset of POSIX shell function definitions. + - `bibtex` suitable for files with BibTeX coded references. - `cpp` suitable for source code in the C and C++ languages. diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt index 9cd7a59..afdaeab 100644 --- a/Documentation/gitfaq.txt +++ b/Documentation/gitfaq.txt @@ -241,6 +241,59 @@ How do I know if I want to do a fetch or a pull?:: ignore the upstream changes. A pull consists of a fetch followed immediately by either a merge or rebase. See linkgit:git-pull[1]. +Merging and Rebasing +-------------------- + +[[long-running-squash-merge]] +What kinds of problems can occur when merging long-lived branches with squash merges?:: + In general, there are a variety of problems that can occur when using squash + merges to merge two branches multiple times. These can include seeing extra + commits in `git log` output, with a GUI, or when using the `...` notation to + express a range, as well as the possibility of needing to re-resolve conflicts + again and again. ++ +When Git does a normal merge between two branches, it considers exactly three +points: the two branches and a third commit, called the _merge base_, which is +usually the common ancestor of the commits. The result of the merge is the sum +of the changes between the merge base and each head. When you merge two +branches with a regular merge commit, this results in a new commit which will +end up as a merge base when they're merged again, because there is now a new +common ancestor. Git doesn't have to consider changes that occurred before the +merge base, so you don't have to re-resolve any conflicts you resolved before. ++ +When you perform a squash merge, a merge commit isn't created; instead, the +changes from one side are applied as a regular commit to the other side. This +means that the merge base for these branches won't have changed, and so when Git +goes to perform its next merge, it considers all of the changes that it +considered the last time plus the new changes. That means any conflicts may +need to be re-resolved. Similarly, anything using the `...` notation in `git +diff`, `git log`, or a GUI will result in showing all of the changes since the +original merge base. ++ +As a consequence, if you want to merge two long-lived branches repeatedly, it's +best to always use a regular merge commit. + +[[merge-two-revert-one]] +If I make a change on two branches but revert it on one, why does the merge of those branches include the change?:: + By default, when Git does a merge, it uses a strategy called the recursive + strategy, which does a fancy three-way merge. In such a case, when Git + performs the merge, it considers exactly three points: the two heads and a + third point, called the _merge base_, which is usually the common ancestor of + those commits. Git does not consider the history or the individual commits + that have happened on those branches at all. ++ +As a result, if both sides have a change and one side has reverted that change, +the result is to include the change. This is because the code has changed on +one side and there is no net change on the other, and in this scenario, Git +adopts the change. ++ +If this is a problem for you, you can do a rebase instead, rebasing the branch +with the revert onto the other branch. A rebase in this scenario will revert +the change, because a rebase applies each individual commit, including the +revert. Note that rebases rewrite history, so you should avoid rebasing +published branches unless you're sure you're comfortable with that. See the +NOTES section in linkgit:git-rebase[1] for more details. + Hooks ----- @@ -310,6 +363,39 @@ information about how to configure files as text or binary. You can also control this behavior with the `core.whitespace` setting if you don't wish to remove the carriage returns from your line endings. +[[always-modified-files-case]] +Why do I have a file that's always modified?:: + Internally, Git always stores file names as sequences of bytes and doesn't + perform any encoding or case folding. However, Windows and macOS by default + both perform case folding on file names. As a result, it's possible to end up + with multiple files or directories whose names differ only in case. Git can + handle this just fine, but the file system can store only one of these files, + so when Git reads the other file to see its contents, it looks modified. ++ +It's best to remove one of the files such that you only have one file. You can +do this with commands like the following (assuming two files `AFile.txt` and +`afile.txt`) on an otherwise clean working tree: ++ +---- +$ git rm --cached AFile.txt +$ git commit -m 'Remove files conflicting in case' +$ git checkout . +---- ++ +This avoids touching the disk, but removes the additional file. Your project +may prefer to adopt a naming convention, such as all-lowercase names, to avoid +this problem from occurring again; such a convention can be checked using a +`pre-receive` hook or as part of a continuous integration (CI) system. ++ +It is also possible for perpetually modified files to occur on any platform if a +smudge or clean filter is in use on your system but a file was previously +committed without running the smudge or clean filter. To fix this, run the +following on an otherwise clean working tree: ++ +---- +$ git add --renormalize . +---- + [[recommended-storage-settings]] What's the recommended way to store files in Git?:: While Git can store and handle any file of any type, there are some diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index 31b601e..ffccfc7 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -164,7 +164,7 @@ can also be used to refuse the commit after inspecting the message file. The default 'commit-msg' hook, when enabled, detects duplicate -"Signed-off-by" lines, and aborts the commit if one is found. +`Signed-off-by` trailers, and aborts the commit if one is found. post-commit ~~~~~~~~~~~ @@ -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 @@ -333,6 +335,68 @@ The default 'update' hook, when enabled--and with `hooks.allowunannotated` config option unset or set to false--prevents unannotated tags to be pushed. +[[proc-receive]] +proc-receive +~~~~~~~~~~~~ + +This hook is invoked by linkgit:git-receive-pack[1]. If the server has +set the multi-valued config variable `receive.procReceiveRefs`, and the +commands sent to 'receive-pack' have matching reference names, these +commands will be executed by this hook, instead of by the internal +`execute_commands()` function. This hook is responsible for updating +the relevant references and reporting the results back to 'receive-pack'. + +This hook executes once for the receive operation. It takes no +arguments, but uses a pkt-line format protocol to communicate with +'receive-pack' to read commands, push-options and send results. In the +following example for the protocol, the letter 'S' stands for +'receive-pack' and the letter 'H' stands for this hook. + + # Version and features negotiation. + S: PKT-LINE(version=1\0push-options atomic...) + S: flush-pkt + H: PKT-LINE(version=1\0push-options...) + H: flush-pkt + + # Send commands from server to the hook. + S: PKT-LINE(<old-oid> <new-oid> <ref>) + S: ... ... + S: flush-pkt + # Send push-options only if the 'push-options' feature is enabled. + S: PKT-LINE(push-option) + S: ... ... + S: flush-pkt + + # Receive result 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. + H: PKT-LINE(ok <ref>) + H: PKT-LINE(option fall-through) + # OK, but has an alternate reference. The alternate reference name + # and other status can be given in option directives. + H: PKT-LINE(ok <ref>) + H: PKT-LINE(option refname <refname>) + H: PKT-LINE(option old-oid <old-oid>) + H: PKT-LINE(option new-oid <new-oid>) + H: PKT-LINE(option forced-update) + H: ... ... + H: flush-pkt + +Each command for the 'proc-receive' hook may point to a pseudo-reference +and always has a zero-old as its old-oid, while the 'proc-receive' hook +may update an alternate reference and the alternate reference may exist +already with a non-zero old-oid. For this case, this hook will use +"option" directives to report extended attributes for the reference given +by the leading "ok" directive. + +The report of the commands of this hook should have the same order as +the input. The exit status of the 'proc-receive' hook only determines +the success or failure of the group of commands sent to it, unless +atomic push is in use. + [[post-receive]] post-receive ~~~~~~~~~~~~ @@ -591,7 +655,7 @@ p4-post-changelist This hook is invoked by `git-p4 submit`. The `p4-post-changelist` hook is invoked after the submit has -successfully occured in P4. It takes no parameters and is meant +successfully occurred in P4. It takes no parameters and is meant primarily for notification and cannot affect the outcome of the git p4 submit action. diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt index f9f4e65..891c8da 100644 --- a/Documentation/gitsubmodules.txt +++ b/Documentation/gitsubmodules.txt @@ -225,10 +225,10 @@ presence of the .url field. Workflow for a third party library ---------------------------------- - # add a submodule + # Add a submodule git submodule add <url> <path> - # occasionally update the submodule to a new version: + # Occasionally update the submodule to a new version: git -C <path> checkout <new version> git add <path> git commit -m "update submodule to new version" @@ -246,20 +246,23 @@ Workflow for an artificially split repo # regular commands recurse into submodules by default git config --global submodule.recurse true - # Unlike the other commands below clone still needs + # Unlike most other commands below, clone still needs # its own recurse flag: git clone --recurse <URL> <directory> cd <directory> # Get to know the code: git grep foo - git ls-files + git ls-files --recurse-submodules + +[NOTE] +`git ls-files` also requires its own `--recurse-submodules` flag. # Get new code git fetch git pull --rebase - # change worktree + # Change worktree git checkout git reset @@ -267,12 +270,12 @@ Implementation details ---------------------- When cloning or pulling a repository containing submodules the submodules -will not be checked out by default; You can instruct 'clone' to recurse -into submodules. The 'init' and 'update' subcommands of 'git submodule' +will not be checked out by default; you can instruct `clone` to recurse +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 -affects other git commands, see linkgit:git-config[1] for a complete list). +your working tree. Alternatively you can set `submodule.recurse` to have +`checkout` recursing into submodules (note that `submodule.recurse` also +affects other Git commands, see linkgit:git-config[1] for a complete list). SEE ALSO diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index 80d4831..eb0aabd 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -77,16 +77,7 @@ When not possible, refuse to merge and exit with a non-zero status. With --no-log do not list one-line descriptions from the actual commits being merged. ---signoff:: ---no-signoff:: - Add Signed-off-by line by the committer at the end of the commit - log message. The meaning of a signoff depends on the project, - but it typically certifies that committer has - the rights to submit this work under the same license and - agrees to a Developer Certificate of Origin - (see http://developercertificate.org/ for more information). -+ -With --no-signoff do not add a Signed-off-by line. +include::signoff-option.txt[] --stat:: -n:: diff --git a/Documentation/object-format-disclaimer.txt b/Documentation/object-format-disclaimer.txt new file mode 100644 index 0000000..4cb106f --- /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 7a6da6d..27ddaf8 100644 --- a/Documentation/pretty-options.txt +++ b/Documentation/pretty-options.txt @@ -16,17 +16,17 @@ configuration (see linkgit:git-config[1]). --abbrev-commit:: Instead of showing the full 40-byte hexadecimal commit object - name, show only a partial prefix. Non default number of - digits can be specified with "--abbrev=<n>" (which also modifies - diff output, if it is displayed). + name, show a prefix that names the object uniquely. + "--abbrev=<n>" (which also modifies diff output, if it is displayed) + option can be used to specify the minimum length of the prefix. + This should make "--pretty=oneline" a whole lot more readable for 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/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt index 95ea849..95a7390 100644 --- a/Documentation/pull-fetch-param.txt +++ b/Documentation/pull-fetch-param.txt @@ -30,6 +30,22 @@ The colon can be omitted when <dst> is empty. <src> is typically a ref, but it can also be a fully spelled hex object name. + +A <refspec> may contain a `*` in its <src> to indicate a simple pattern +match. Such a refspec functions like a glob that matches any ref with the +same prefix. A pattern <refspec> must have a `*` in both the <src> and +<dst>. It will map refs to the destination by replacing the `*` with the +contents matched from the source. ++ +If a refspec is prefixed by `^`, it will be interpreted as a negative +refspec. Rather than specifying which refs to fetch or which local refs to +update, such a refspec will instead specify refs to exclude. A ref will be +considered to match if it matches at least one positive refspec, and does +not match any negative refspec. Negative refspecs can be useful to restrict +the scope of a pattern refspec so that it will not include specific refs. +Negative refspecs can themselves be pattern refspecs. However, they may only +contain a <src> and do not specify a <dst>. Fully spelled out hex object +names are also not supported. ++ `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`; it requests fetching everything up to the given tag. + diff --git a/Documentation/ref-reachability-filters.txt b/Documentation/ref-reachability-filters.txt new file mode 100644 index 0000000..9bae46d --- /dev/null +++ b/Documentation/ref-reachability-filters.txt @@ -0,0 +1,7 @@ +When combining multiple `--contains` and `--no-contains` filters, only +references that contain at least one of the `--contains` commits and +contain none of the `--no-contains` commits are shown. + +When combining multiple `--merged` and `--no-merged` filters, only +references that are reachable from at least one of the `--merged` +commits and from none of the `--no-merged` commits are shown. diff --git a/Documentation/signoff-option.txt b/Documentation/signoff-option.txt new file mode 100644 index 0000000..12aa233 --- /dev/null +++ b/Documentation/signoff-option.txt @@ -0,0 +1,18 @@ +ifdef::git-commit[] +-s:: +endif::git-commit[] +--signoff:: +--no-signoff:: + Add a `Signed-off-by` trailer by the committer at the end of the commit + log message. The meaning of a signoff depends on the project + to which you're committing. For example, it may certify that + 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 + 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. ++ +The --no-signoff option can be used to countermand an earlier --signoff +option on the command line. diff --git a/Documentation/technical/commit-graph-format.txt b/Documentation/technical/commit-graph-format.txt index 4405410..b3b5888 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" @@ -77,7 +82,7 @@ CHUNK DATA: Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes) * The first H bytes are for the OID of the root tree. * The next 8 bytes are for the positions of the first two parents - of the ith commit. Stores value 0x7000000 if no parent in that + of the ith commit. Stores value 0x70000000 if no parent in that position. If there are more than two parents, the second value has its most-significant bit on and the other bits store an array position into the Extra Edge List chunk. @@ -120,7 +125,7 @@ CHUNK DATA: * The rest of the chunk is the concatenation of all the computed Bloom filters for the commits in lexicographic order. * Note: Commits with no changes or more than 512 changes have Bloom filters - of length zero. + of length one, with either all bits set to zero or one respectively. * The BDAT chunk is present if and only if BIDX is present. Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional] diff --git a/Documentation/technical/commit-graph.txt b/Documentation/technical/commit-graph.txt index 808fa30..f14a765 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/directory-rename-detection.txt b/Documentation/technical/directory-rename-detection.txt index 844629c..49b83ef 100644 --- a/Documentation/technical/directory-rename-detection.txt +++ b/Documentation/technical/directory-rename-detection.txt @@ -18,7 +18,8 @@ It is perhaps easiest to start with an example: More interesting possibilities exist, though, such as: * one side of history renames x -> z, and the other renames some file to - x/e, causing the need for the merge to do a transitive rename. + x/e, causing the need for the merge to do a transitive rename so that + the rename ends up at z/e. * one side of history renames x -> z, but also renames all files within x. For example, x/a -> z/alpha, x/b -> z/bravo, etc. @@ -35,7 +36,7 @@ More interesting possibilities exist, though, such as: directory itself contained inner directories that were renamed to yet other locations). - * combinations of the above; see t/t6043-merge-rename-directories.sh for + * combinations of the above; see t/t6423-merge-rename-directories.sh for various interesting cases. Limitations -- applicability of directory renames @@ -62,19 +63,19 @@ directory rename detection applies: Limitations -- detailed rules and testcases ------------------------------------------- -t/t6043-merge-rename-directories.sh contains extensive tests and commentary +t/t6423-merge-rename-directories.sh contains extensive tests and commentary which generate and explore the rules listed above. It also lists a few additional rules: a) If renames split a directory into two or more others, the directory with the most renames, "wins". - b) Avoid directory-rename-detection for a path, if that path is the - source of a rename on either side of a merge. - - c) Only apply implicit directory renames to directories if the other side + b) Only apply implicit directory renames to directories if the other side of history is the one doing the renaming. + c) Do not perform directory rename detection for directories which had no + new paths added to them. + Limitations -- support in different commands -------------------------------------------- diff --git a/Documentation/technical/hash-function-transition.txt b/Documentation/technical/hash-function-transition.txt index 5b2db3b..6fd20eb 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 51a79e6..96d89ea 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 faa25c5..f9a3644 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 d3a142c..f96b2e6 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/pack-protocol.txt b/Documentation/technical/pack-protocol.txt index a4573d1..e13a2c0 100644 --- a/Documentation/technical/pack-protocol.txt +++ b/Documentation/technical/pack-protocol.txt @@ -503,8 +503,8 @@ The reference discovery phase is done nearly the same way as it is in the fetching protocol. Each reference obj-id and name on the server is sent in packet-line format to the client, followed by a flush-pkt. The only real difference is that the capability listing is different - the only -possible values are 'report-status', 'delete-refs', 'ofs-delta' and -'push-options'. +possible values are 'report-status', 'report-status-v2', 'delete-refs', +'ofs-delta', 'atomic' and 'push-options'. Reference Update Request and Packfile Transfer ---------------------------------------------- @@ -625,7 +625,7 @@ Report Status ------------- After receiving the pack data from the sender, the receiver sends a -report if 'report-status' capability is in effect. +report if 'report-status' or 'report-status-v2' capability is in effect. It is a short listing of what happened in that update. It will first list the status of the packfile unpacking as either 'unpack ok' or 'unpack [error]'. Then it will list the status for each of the references @@ -647,6 +647,41 @@ update was successful, or 'ng [refname] [error]' if the update was not. error-msg = 1*(OCTET) ; where not "ok" ---- +The 'report-status-v2' capability extends the protocol by adding new option +lines in order to support reporting of reference rewritten by the +'proc-receive' hook. The 'proc-receive' hook may handle a command for a +pseudo-reference which may create or update one or more references, and each +reference may have different name, different new-oid, and different old-oid. + +---- + report-status-v2 = unpack-status + 1*(command-status-v2) + flush-pkt + + unpack-status = PKT-LINE("unpack" SP unpack-result) + unpack-result = "ok" / error-msg + + command-status-v2 = command-ok-v2 / command-fail + command-ok-v2 = command-ok + *option-line + + command-ok = PKT-LINE("ok" SP refname) + command-fail = PKT-LINE("ng" SP refname SP error-msg) + + error-msg = 1*(OCTET) ; where not "ok" + + option-line = *1(option-refname) + *1(option-old-oid) + *1(option-new-oid) + *1(option-forced-update) + + option-refname = PKT-LINE("option" SP "refname" SP refname) + option-old-oid = PKT-LINE("option" SP "old-oid" SP obj-id) + option-new-oid = PKT-LINE("option" SP "new-oid" SP obj-id) + option-force = PKT-LINE("option" SP "forced-update") + +---- + Updates can be unsuccessful for a number of reasons. The reference can have changed since the reference discovery phase was originally sent, meaning someone pushed in the meantime. The reference being pushed could be a diff --git a/Documentation/technical/partial-clone.txt b/Documentation/technical/partial-clone.txt index b9e17e7..0780d30 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 36ccd14..ba869a7 100644 --- a/Documentation/technical/protocol-capabilities.txt +++ b/Documentation/technical/protocol-capabilities.txt @@ -22,9 +22,9 @@ was 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. -The 'atomic', 'report-status', 'delete-refs', 'quiet', and 'push-cert' -capabilities are sent and recognized by the receive-pack (push to server) -process. +The 'atomic', 'report-status', 'report-status-v2', 'delete-refs', 'quiet', +and 'push-cert' capabilities are sent and recognized by the receive-pack +(push to server) process. The 'ofs-delta' and 'side-band-64k' capabilities are sent and recognized by both upload-pack and receive-pack protocols. The 'agent' capability @@ -284,6 +284,17 @@ each reference was updated successfully. If any of those were not successful, it will send back an error message. See pack-protocol.txt for example messages. +report-status-v2 +---------------- + +Capability 'report-status-v2' extends capability 'report-status' by +adding new "option" directives in order to support reference rewritten by +the "proc-receive" hook. The "proc-receive" hook may handle a command +for a pseudo-reference which may create or update a reference with +different name, new-oid, and old-oid. While the capability +'report-status' cannot report for such case. See pack-protocol.txt +for details. + delete-refs ----------- @@ -324,15 +335,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 01dedfe..f3738ba 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. |