diff options
Diffstat (limited to 'Documentation')
237 files changed, 3009 insertions, 1071 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 003393ed16..8ed517a5ca 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -1,5 +1,5 @@ -Like other projects, we also have some guidelines to keep to the -code. For Git in general, a few rough rules are: +Like other projects, we also have some guidelines for our code. For +Git in general, a few rough rules are: - Most importantly, we never say "It's in POSIX; we'll happily ignore your needs should your system not conform to it." @@ -24,7 +24,7 @@ code. For Git in general, a few rough rules are: "Once it _is_ in the tree, it's not really worth the patch noise to go and fix it up." - Cf. http://lkml.iu.edu/hypermail/linux/kernel/1001.3/01069.html + Cf. https://lore.kernel.org/all/20100126160632.3bdbe172.akpm@linux-foundation.org/ - Log messages to explain your changes are as important as the changes themselves. Clearly written code and in-code comments @@ -40,7 +40,7 @@ As for more concrete guidelines, just imitate the existing code contributing to). It is always preferable to match the _local_ convention. New code added to Git suite is expected to match the overall style of existing code. Modifications to existing -code is expected to match the style the surrounding code already +code are expected to match the style the surrounding code already uses (even if it doesn't match the overall style of existing code). But if you must have a list of rules, here are some language @@ -188,6 +188,10 @@ For shell scripts specifically (not exhaustive): hopefully nobody starts using "local" before they are reimplemented in C ;-) + - Use octal escape sequences (e.g. "\302\242"), not hexadecimal (e.g. + "\xc2\xa2") in printf format strings, since hexadecimal escape + sequences are not portable. + For C programs: @@ -444,7 +448,7 @@ For C programs: - The first #include in C files, except in platform specific compat/ implementations and sha1dc/, must be either "git-compat-util.h" or one of the approved headers that includes it first for you. (The - approved headers currently include "cache.h", "builtin.h", + approved headers currently include "builtin.h", "t/helper/test-tool.h", "xdiff/xinclude.h", or "reftable/system.h"). You do not have to include more than one of these. @@ -486,7 +490,7 @@ For Perl programs: - Most of the C guidelines above apply. - - We try to support Perl 5.8 and later ("use Perl 5.008"). + - We try to support Perl 5.8.1 and later ("use Perl 5.008001"). - use strict and use warnings are strongly preferred. @@ -514,7 +518,7 @@ For Perl programs: For Python scripts: - - We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/). + - We follow PEP-8 (https://peps.python.org/pep-0008/). - As a minimum, we aim to be compatible with Python 2.7. @@ -687,7 +691,7 @@ Writing Documentation: Do: [-q | --quiet] Don't: [-q|--quiet] - Don't use spacing around "|" tokens when they're used to seperate the + Don't use spacing around "|" tokens when they're used to separate the alternate arguments of an option: Do: --track[=(direct|inherit)] Don't: --track[=(direct | inherit)] diff --git a/Documentation/Makefile b/Documentation/Makefile index b629176d7d..3f2383a12c 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -122,6 +122,7 @@ TECH_DOCS += technical/scalar TECH_DOCS += technical/send-pack-pipeline TECH_DOCS += technical/shallow TECH_DOCS += technical/trivial-merge +TECH_DOCS += technical/unit-tests SP_ARTICLES += $(TECH_DOCS) SP_ARTICLES += technical/api-index diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index 56130e4bec..279f6a3e7c 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -160,10 +160,11 @@ in order to keep the declarations alphabetically sorted: int cmd_psuh(int argc, const char **argv, const char *prefix); ---- -Be sure to `#include "builtin.h"` in your `psuh.c`. +Be sure to `#include "builtin.h"` in your `psuh.c`. You'll also need to +`#include "gettext.h"` to use functions related to printing output text. -Go ahead and add some throwaway printf to that function. This is a decent -starting point as we can now add build rules and register the command. +Go ahead and add some throwaway printf to the `cmd_psuh` function. This is a +decent starting point as we can now add build rules and register the command. NOTE: Your throwaway text, as well as much of the text you will be adding over the course of this tutorial, is user-facing. That means it needs to be @@ -832,7 +833,7 @@ Johannes Schindelin to make life as a Git contributor easier for those used to the GitHub PR workflow. It allows contributors to open pull requests against its mirror of the Git project, and does some magic to turn the PR into a set of emails and send them out for you. It also runs the Git continuous integration -suite for you. It's documented at http://gitgitgadget.github.io. +suite for you. It's documented at https://gitgitgadget.github.io/. [[create-fork]] === Forking `git/git` on GitHub @@ -1256,6 +1257,38 @@ index 88f126184c..38da593a60 100644 [[now-what]] == My Patch Got Emailed - Now What? +Please give reviewers enough time to process your initial patch before +sending an updated version. That is, resist the temptation to send a new +version immediately, because others may have already started reviewing +your initial version. + +While waiting for review comments, you may find mistakes in your initial +patch, or perhaps realize a different and better way to achieve the goal +of the patch. In this case you may communicate your findings to other +reviewers as follows: + + - If the mistakes you found are minor, send a reply to your patch as if + you were a reviewer and mention that you will fix them in an + updated version. + + - On the other hand, if you think you want to change the course so + drastically that reviews on the initial patch would be a waste of + time (for everyone involved), retract the patch immediately with + a reply like "I am working on a much better approach, so please + ignore this patch and wait for the updated version." + +Now, the above is a good practice if you sent your initial patch +prematurely without polish. But a better approach of course is to avoid +sending your patch prematurely in the first place. + +Please be considerate of the time needed by reviewers to examine each +new version of your patch. Rather than seeing the initial version right +now (followed by several "oops, I like this version better than the +previous one" patches over 2 days), reviewers would strongly prefer if a +single polished version came 2 days later instead, and that version with +fewer mistakes were the only one they would need to review. + + [[reviewing]] === Responding to Reviews diff --git a/Documentation/MyFirstObjectWalk.txt b/Documentation/MyFirstObjectWalk.txt index eee513e86f..c68cdb11b9 100644 --- a/Documentation/MyFirstObjectWalk.txt +++ b/Documentation/MyFirstObjectWalk.txt @@ -41,6 +41,7 @@ Open up a new file `builtin/walken.c` and set up the command handler: */ #include "builtin.h" +#include "trace.h" int cmd_walken(int argc, const char **argv, const char *prefix) { @@ -49,12 +50,13 @@ int cmd_walken(int argc, const char **argv, const char *prefix) } ---- -NOTE: `trace_printf()` differs from `printf()` in that it can be turned on or -off at runtime. For the purposes of this tutorial, we will write `walken` as -though it is intended for use as a "plumbing" command: that is, a command which -is used primarily in scripts, rather than interactively by humans (a "porcelain" -command). So we will send our debug output to `trace_printf()` instead. When -running, enable trace output by setting the environment variable `GIT_TRACE`. +NOTE: `trace_printf()`, defined in `trace.h`, differs from `printf()` in +that it can be turned on or off at runtime. For the purposes of this +tutorial, we will write `walken` as though it is intended for use as +a "plumbing" command: that is, a command which is used primarily in +scripts, rather than interactively by humans (a "porcelain" command). +So we will send our debug output to `trace_printf()` instead. +When running, enable trace output by setting the environment variable `GIT_TRACE`. Add usage text and `-h` handling, like all subcommands should consistently do (our test suite will notice and complain if you fail to do so). @@ -124,7 +126,7 @@ parameters provided by the user over the CLI. `nr` represents the number of `rev_cmdline_entry` present in the array. -`alloc` is used by the `ALLOC_GROW` macro. Check `cache.h` - this variable is +`alloc` is used by the `ALLOC_GROW` macro. Check `alloc.h` - this variable is used to track the allocated size of the list. Per entry, we find: @@ -341,6 +343,10 @@ the walk loop below the `prepare_revision_walk()` call within your `walken_commit_walk()`: ---- +#include "pretty.h" + +... + static void walken_commit_walk(struct rev_info *rev) { struct commit *commit; @@ -754,6 +760,10 @@ reachable objects are walked in order to populate the list. First, add the `struct oidset` and related items we will use to iterate it: ---- +#include "oidset.h" + +... + static void walken_object_walk( ... @@ -805,6 +815,10 @@ just walks of commits. First, we'll make our handlers chattier - modify go: ---- +#include "hex.h" + +... + static void walken_show_commit(struct commit *cmt, void *buf) { trace_printf("commit: %s\n", oid_to_hex(&cmt->object.oid)); diff --git a/Documentation/RelNotes/1.6.2.txt b/Documentation/RelNotes/1.6.2.txt index 980adfb315..166d73c60f 100644 --- a/Documentation/RelNotes/1.6.2.txt +++ b/Documentation/RelNotes/1.6.2.txt @@ -10,7 +10,7 @@ To ease the transition plan, the receiving repository of such a push running this release will issue a big warning when the configuration variable is missing. Please refer to: - http://git.or.cz/gitwiki/GitFaq#non-bare + https://archive.kernel.org/oldwiki/git.wiki.kernel.org/index.php/GitFaq.html#non-bare https://lore.kernel.org/git/7vbptlsuyv.fsf@gitster.siamese.dyndns.org/ for more details on the reason why this change is needed and the diff --git a/Documentation/RelNotes/1.6.3.txt b/Documentation/RelNotes/1.6.3.txt index 4bcff945e0..bbf177fc3c 100644 --- a/Documentation/RelNotes/1.6.3.txt +++ b/Documentation/RelNotes/1.6.3.txt @@ -10,7 +10,7 @@ To ease the transition plan, the receiving repository of such a push running this release will issue a big warning when the configuration variable is missing. Please refer to: - http://git.or.cz/gitwiki/GitFaq#non-bare + https://archive.kernel.org/oldwiki/git.wiki.kernel.org/index.php/GitFaq.html#non-bare https://lore.kernel.org/git/7vbptlsuyv.fsf@gitster.siamese.dyndns.org/ for more details on the reason why this change is needed and the diff --git a/Documentation/RelNotes/1.6.4.txt b/Documentation/RelNotes/1.6.4.txt index a2a34b43a7..0fccfb0bf0 100644 --- a/Documentation/RelNotes/1.6.4.txt +++ b/Documentation/RelNotes/1.6.4.txt @@ -10,7 +10,7 @@ To ease the transition plan, the receiving repository of such a push running this release will issue a big warning when the configuration variable is missing. Please refer to: - http://git.or.cz/gitwiki/GitFaq#non-bare + https://archive.kernel.org/oldwiki/git.wiki.kernel.org/index.php/GitFaq.html#non-bare https://lore.kernel.org/git/7vbptlsuyv.fsf@gitster.siamese.dyndns.org/ for more details on the reason why this change is needed and the diff --git a/Documentation/RelNotes/1.6.5.txt b/Documentation/RelNotes/1.6.5.txt index 6c7f7da7eb..79cb1b2b6d 100644 --- a/Documentation/RelNotes/1.6.5.txt +++ b/Documentation/RelNotes/1.6.5.txt @@ -21,7 +21,7 @@ To ease the transition plan, the receiving repository of such a push running this release will issue a big warning when the configuration variable is missing. Please refer to: - http://git.or.cz/gitwiki/GitFaq#non-bare + https://archive.kernel.org/oldwiki/git.wiki.kernel.org/index.php/GitFaq.html#non-bare https://lore.kernel.org/git/7vbptlsuyv.fsf@gitster.siamese.dyndns.org/ for more details on the reason why this change is needed and the diff --git a/Documentation/RelNotes/1.6.6.txt b/Documentation/RelNotes/1.6.6.txt index 3ed1e01433..88b86a827e 100644 --- a/Documentation/RelNotes/1.6.6.txt +++ b/Documentation/RelNotes/1.6.6.txt @@ -63,7 +63,7 @@ users will fare this time. Please refer to: - http://git.or.cz/gitwiki/GitFaq#non-bare + https://archive.kernel.org/oldwiki/git.wiki.kernel.org/index.php/GitFaq.html#non-bare https://lore.kernel.org/git/7vbptlsuyv.fsf@gitster.siamese.dyndns.org/ for more details on the reason why this change is needed and the diff --git a/Documentation/RelNotes/2.42.0.txt b/Documentation/RelNotes/2.42.0.txt new file mode 100644 index 0000000000..0f1897ad5f --- /dev/null +++ b/Documentation/RelNotes/2.42.0.txt @@ -0,0 +1,329 @@ +Git v2.42 Release Notes +======================= + +UI, Workflows & Features + + * "git pack-refs" learns "--include" and "--exclude" to tweak the ref + hierarchy to be packed using pattern matching. + + * 'git worktree add' learned how to create a worktree based on an + orphaned branch with `--orphan`. + + * "git pack-objects" learned to invoke a new hook program that + enumerates extra objects to be used as anchoring points to keep + otherwise unreachable objects in cruft packs. + + * Add more "git var" for toolsmiths to learn various locations Git is + configured with either via the configuration or hard-coded defaults. + + * 'git notes append' was taught '--separator' to specify string to insert + between paragraphs. + + * The "git for-each-ref" family of commands learned placeholders + related to GPG signature verification. + + * "git diff --no-index" learned to read from named pipes as if they + were regular files, to allow "git diff <(process) <(substitution)" + some shells support. + + * Help newbies by suggesting that there are cases where force-pushing + is a valid and sensible thing to update a branch at a remote + repository, rather than reconciling with merge/rebase. + + * "git blame --contents=file" has been taught to work in a bare + repository. + + * "git branch -f X" to repoint the branch X said that X was "checked + out" in another worktree, even when branch X was not and instead + being bisected or rebased. The message was reworded to say the + branch was "in use". + + * Tone down the warning on SHA-256 repositories being an experimental + curiosity. We do not have support for them to interoperate with + traditional SHA-1 repositories, but at this point, we do not plan + to make breaking changes to SHA-256 repositories and there is no + longer need for such a strongly phrased warning. + + +Performance, Internal Implementation, Development Support etc. + + * "git diff-tree" has been taught to take advantage of the + sparse-index feature. + + * Clang's sanitizer implementation seems to work better than GCC's. + (merge d88d727143 jk/ci-use-clang-for-sanitizer-jobs later to maint). + + * The object traversal using reachability bitmap done by + "pack-object" has been tweaked to take advantage of the fact that + using "boundary" commits as representative of all the uninteresting + ones can save quite a lot of object enumeration. + + * discover_git_directory() no longer touches the_repository. + + * "git worktree" learned to work better with sparse index feature. + + * When the external merge driver is killed by a signal, its output + should not be trusted as a resolution with conflicts that is + proposed by the driver, but the code did. + + * The set-up code for the get_revision() API now allows feeding + options like --all and --not in the --stdin mode. + + * Move functions that are not about pure string manipulation out of + strbuf.[ch] + + * "imap-send" codepaths got cleaned up to get rid of unused + parameters. + + * Enumerating refs in the packed-refs file, while excluding refs that + match certain patterns, has been optimized. + + * Mark-up unused parameters in the code so that we can eventually + enable -Wunused-parameter by default. + + * Instead of inventing a custom counter variables for debugging, + use existing trace2 facility in the fsync customization codepath. + + * "git branch --list --format=<format>" and friends are taught + a new "%(describe)" placeholder. + + * Clarify how to choose the starting point for a new topic in + developer guidance document. + + * The implementation of "get_sha1_hex()" that reads a hexadecimal + string that spells a full object name has been extended to cope + with any hash function used in the repository, but the "sha1" in + its name survived. Rename it to get_hash_hex(), a name that is + more consistent within its friends like get_hash_hex_algop(). + + * Command line parser fix, and a small parse-options API update. + + +Fixes since v2.41 +----------------- + + * "git tag" learned to leave the "$GIT_DIR/TAG_EDITMSG" file when the + command failed, so that the user can salvage what they typed. + (merge 08c12ec1d0 kh/keep-tag-editmsg-upon-failure later to maint). + + * The "-s" (silent, squelch) option of the "diff" family of commands + did not interact with other options that specify the output format + well. This has been cleaned up so that it will clear all the + formatting options given before. + (merge 9d484b92ed jc/diff-s-with-other-options later to maint). + + * Update documentation regarding Coccinelle patches. + (merge 3bd0097cfc gc/doc-cocci-updates later to maint). + + * Some atoms that can be used in "--format=<format>" for "git ls-tree" + were not supported by "git ls-files", even though they were relevant + in the context of the latter. + (merge 4d28c4f75f zh/ls-files-format-atoms later to maint). + + * Document more pseudo-refs and teach the command line completion + machinery to complete AUTO_MERGE. + (merge 982ff3a649 pb/complete-and-document-auto-merge-and-friends later to maint). + + * "git submodule" code trusted the data coming from the config (and + the in-tree .gitmodules file) too much without validating, leading + to NULL dereference if the user mucks with a repository (e.g. + submodule.<name>.url is removed). This has been corrected. + (merge fbc806acd1 tb/submodule-null-deref-fix later to maint). + + * The value of config.worktree is per-repository, but has been kept + in a singleton global variable per process. This has been OK as + most Git operations interacted with a single repository at a time, + but not right for operations like recursive "grep" that want to + access multiple repositories from a single process without forking. + + The global variable has been eliminated and made into a member in + the per-repository data structure. + (merge 3867f6d650 vd/worktree-config-is-per-repository later to maint). + + * "git [-c log.follow=true] log [--follow] ':(glob)f**'" used to barf. + (merge 8260bc5902 jk/log-follow-with-non-literal-pathspec later to maint). + + * Introduce a mechanism to disable replace refs globally and per + repository. + (merge 9c7d1b057f ds/disable-replace-refs later to maint). + + * "git cat-file --batch" and friends learned "-Z" that uses NUL + delimiter for both input and output. + (merge f79e18849b ps/cat-file-null-output later to maint). + + * The reimplemented "git add -i" did not honor color.ui configuration. + (merge 6f74648cea ds/add-i-color-configuration-fix later to maint). + + * Compilation fix for platforms without D_TYPE in struct dirent. + (merge 03bf92b9bf as/dtype-compilation-fix later to maint). + + * Suggest to refrain from using hex literals that are non-portable + when writing printf(1) format strings. + (merge f0b68f0546 jt/doc-use-octal-with-printf later to maint). + + * Simplify error message when run-command fails to start a command. + (merge 6d224ac286 rs/run-command-exec-error-on-noent later to maint). + + * Gracefully deal with a stale MIDX file that lists a packfile that + no longer exists. + (merge 06f3867865 tb/open-midx-bitmap-fallback later to maint). + + * Even when diff.ignoreSubmodules tells us to ignore submodule + changes, "git commit" with an index that already records changes to + submodules should include the submodule changes in the resulting + commit, but it did not. + (merge 5768478edc js/defeat-ignore-submodules-config-with-explicit-addition later to maint). + + * When "git commit --trailer=..." invokes the interpret-trailers + machinery, it knows what it feeds to interpret-trailers is a full + log message without any patch, but failed to express that by + passing the "--no-divider" option, which has been corrected. + (merge be3d654343 jk/commit-use-no-divider-with-interpret-trailers later to maint). + + * Avoid breakage of "git pack-objects --cruft" due to inconsistency + between the way the code enumerates packfiles in the repository. + (merge 73320e49ad tb/collect-pack-filenames-fix later to maint). + + * We create .pack and then .idx, we consider only packfiles that have + .idx usable (those with only .pack are not ready yet), so we should + remove .idx before removing .pack for consistency. + (merge 0dd1324a73 ds/remove-idx-before-pack later to maint). + + * Partially revert a sanity check that the rest of the config code + was not ready, to avoid triggering it in a corner case. + (merge a53f43f900 gc/config-partial-submodule-kvi-fix later to maint). + + * "git apply" punts when it is fed too large a patch input; the error + message it gives when it happens has been clarified. + (merge 42612e18d2 pw/apply-too-large later to maint). + + * During a cherry-pick or revert session that works on multiple + commits, "git status" did not give correct information, which has + been corrected. + (merge a096a889f4 jk/cherry-pick-revert-status later to maint). + + * A few places failed to differentiate the case where the index is + truly empty (nothing added) and we haven't yet read from the + on-disk index file, which have been corrected. + (merge 2ee045eea1 js/empty-index-fixes later to maint). + + * "git bugreport" tests did not test what it wanted to test, which + has been corrected. + (merge 1aa92b8500 ma/t0091-fixup later to maint). + + * Code snippets in a tutorial document no longer compiled after + recent header shuffling, which have been corrected. + (merge bbd7c7b7c0 vd/adjust-mfow-doc-to-updated-headers later to maint). + + * "git ls-files '(attr:X)D/'" that triggers the common prefix + optimization codepath failed to read from "D/.gitattributes", + which has been corrected. + (merge f4a8fde057 jc/pathspec-match-with-common-prefix later to maint). + + * "git fsck --no-progress" still spewed noise from the commit-graph + subsystem, which has been corrected. + (merge 9281cd07f0 tb/fsck-no-progress later to maint). + + * Various offset computation in the code that accesses the packfiles + and other data in the object layer has been hardened against + arithmetic overflow, especially on 32-bit systems. + (merge 9a25cad7e0 tb/object-access-overflow-protection later to maint). + + * Names of MinGW header files are spelled in mixed case in some + source files, but the build host can be using case sensitive + filesystem with header files with their name spelled in all + lowercase. + (merge 4a53d0d0bc mh/mingw-case-sensitive-build later to maint). + + * Update message mark-up for i18n in "git bundle". + (merge bbb6acd998 dk/bundle-i18n-more later to maint). + + * "git tag --list --points-at X" showed tags that directly refers to + object X, but did not list a tag that points at such a tag, which + has been corrected. + + * "./configure --with-expat=no" did not work as a way to refuse use + of the expat library on a system with the library installed, which + has been corrected. + (merge fb8f7269c2 ah/autoconf-fixes later to maint). + + * When the user edits "rebase -i" todo file so that it starts with a + "fixup", which would make it invalid, the command truncated the + rest of the file before giving an error and returning the control + back to the user. Stop truncating to make it easier to correct + such a malformed todo file. + (merge 9645a087c2 ah/sequencer-rewrite-todo-fix later to maint). + + * Rewrite the description of giving a custom command to the + submodule.<name>.update configuration variable. + (merge 7cebc5bd78 pv/doc-submodule-update-settings later to maint). + + * Adjust to OpenSSL 3+, which deprecates its SHA-1 functions based on + its traditional API, by using its EVP API instead. + (merge bda9c12073 ew/hash-with-openssl-evp later to maint). + + * Exclude "." from the set of characters to be removed from the + beginning and the end of the human-readable name. + (merge 1c04cb0744 bc/ident-dot-is-no-longer-crud-letter later to maint). + + * "git bisect visualize" stopped running "gitk" on Git for Windows + when the command was reimplemented in C around Git 2.34 timeframe. + This has been corrected. + (merge fff1594fa7 ma/locate-in-path-for-windows later to maint). + + * "git rebase -i" with a series of squash/fixup, when one of the + steps stopped in conflicts and ended up getting skipped, did not + handle the accumulated commit log messages, which has been + corrected. + (merge 6ce7afe163 pw/rebase-skip-commit-message-fix later to maint). + + * Adjust to newer Term::ReadLine to prevent it from breaking + the interactive prompt code in send-email. + (merge c016726c2d jk/send-email-with-new-readline later to maint). + + * Windows updates. + (merge 0050f8e401 ds/maintenance-on-windows-fix later to maint). + + * Correct use of lstat() that assumed a failing call would not + clobber the statbuf. + (merge 72695d8214 st/mv-lstat-fix later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge 51f9d2e563 sa/doc-ls-remote later to maint). + (merge c6d26a9dda jk/format-patch-message-id-unleak later to maint). + (merge f7e063f326 ps/fetch-cleanups later to maint). + (merge e4cf013468 tl/quote-problematic-arg-for-clarity later to maint). + (merge 20025fdfc7 tz/test-ssh-verifytime-fix later to maint). + (merge e48a21df65 tz/test-fix-pthreads-prereq later to maint). + (merge 68b51172e3 mh/commit-reach-get-reachable-plug-leak later to maint). + (merge aeee1408ce kh/use-default-notes-doc later to maint). + (merge 3b8724bce6 jc/test-modernization later to maint). + (merge 447a3b7331 jc/test-modernization-2 later to maint). + (merge d57fa7fc73 la/doc-interpret-trailers later to maint). + (merge 548afb0d9a la/docs-typofixes later to maint). + (merge 3744ffcbcd rs/doc-ls-tree-hex-literal later to maint). + (merge 6c26da8404 mh/credential-erase-improvements later to maint). + (merge 78e56cff69 tz/lib-gpg-prereq-fix later to maint). + (merge 80d32e84b5 rj/leakfixes later to maint). + (merge 0a868031ed pb/complete-diff-options later to maint). + (merge d4f28279ad jc/doc-hash-object-types later to maint). + (merge 1876a5ae15 ks/t4205-test-describe-with-abbrev-fix later to maint). + (merge 6e6a529b57 jk/fsck-indices-in-worktrees later to maint). + (merge 3e81b896f7 rs/packet-length-simplify later to maint). + (merge 4c9cb51fe7 mh/doc-credential-helpers later to maint). + (merge 3437f549dd jr/gitignore-doc-example-markup later to maint). + (merge 947ebd62a0 jc/am-parseopt-fix later to maint). + (merge e12cb98e1e jc/branch-parseopt-fix later to maint). + (merge d6f598e443 jc/gitignore-doc-pattern-markup later to maint). + (merge a2dad4868b jc/transport-parseopt-fix later to maint). + (merge 68cbb20e73 jc/parse-options-show-branch later to maint). + (merge 3821eb6c3d jc/parse-options-reset later to maint). + (merge c48af99a3e bb/trace2-comment-fix later to maint). + (merge c95ae3ff9c rs/describe-parseopt-fix later to maint). + (merge 36f76d2a25 rs/pack-objects-parseopt-fix later to maint). + (merge 30c8c55cbf jc/tree-walk-drop-base-offset later to maint). + (merge d089a06421 rs/bundle-parseopt-cleanup later to maint). + (merge 823839bda1 ew/sha256-gcrypt-leak-fixes later to maint). + (merge a5c01603b3 bc/ignore-clangd-cache later to maint). + (merge 12009a182b js/allow-t4000-to-be-indented-with-spaces later to maint). + (merge b3dcd24b8a jc/send-email-pre-process-fix later to maint). diff --git a/Documentation/RelNotes/2.42.1.txt b/Documentation/RelNotes/2.42.1.txt new file mode 100644 index 0000000000..3d391b7dcd --- /dev/null +++ b/Documentation/RelNotes/2.42.1.txt @@ -0,0 +1,88 @@ +Git 2.42.1 Release Notes +======================== + +There is nothing exciting to see here. Relative to Git 2.42, this +release contains the fixes that have already been merged to the +'master' branch of the development towards Git 2.43 that has been +tagged as Git 2.43.0-rc0. + +Fixes since Git 2.42.0 +---------------------- + + * Tests that are known to pass with LSan are now marked as such. + + * Flaky "git p4" tests, as well as "git svn" tests, are now skipped + in the (rather expensive) sanitizer CI job. + + * Tests with LSan from time to time seem to emit harmless message + that makes our tests unnecessarily flaky; we work it around by + filtering the uninteresting output. + + * GitHub CI workflow has learned to trigger Coverity check. + + * Overly long label names used in the sequencer machinery are now + chopped to fit under filesystem limitation. + + * Scalar updates. + + * Tweak GitHub Actions CI so that pushing the same commit to multiple + branch tips at the same time will not waste building and testing + the same thing twice. + + * The commit-graph verification code that detects mixture of zero and + non-zero generation numbers has been updated. + + * "git diff -w --exit-code" with various options did not work + correctly, which is being addressed. + + * transfer.unpackLimit ought to be used as a fallback, but overrode + fetch.unpackLimit and receive.unpackLimit instead. + + * The use of API between two calls to require_clean_work_tree() from + the sequencer code has been cleaned up for consistency. + + * "git diff --no-such-option" and other corner cases around the exit + status of the "diff" command has been corrected. + + * "git for-each-ref --sort='contents:size'" sorts the refs according + to size numerically, giving a ref that points at a blob twelve-byte + (12) long before showing a blob hundred-byte (100) long. + + * Various fixes to the behavior of "rebase -i" when the command got + interrupted by conflicting changes. + + * References from description of the `--patch` option in various + manual pages have been simplified and improved. + + * "git grep -e A --no-or -e B" is accepted, even though the negation + of "or" did not mean anything, which has been tightened. + + * The completion script (in contrib/) has been taught to treat the + "-t" option to "git checkout" and "git switch" just like the + "--track" option, to complete remote-tracking branches. + + * "git diff --no-index -R <(one) <(two)" did not work correctly, + which has been corrected. + + * Update "git maintenance" timers' implementation based on systemd + timers to work with WSL. + + * "git diff --cached" codepath did not fill the necessary stat + information for a file when fsmonitor knows it is clean and ended + up behaving as if it is not clean, which has been corrected. + + * Clarify how "alias.foo = : git cmd ; aliased-command-string" should + be spelled with necessary whitespaces around punctuation marks to + work. + + * HTTP Header redaction code has been adjusted for a newer version of + cURL library that shows its traces differently from earlier + versions. + + * An error message given by "git send-email" when given a malformed + address did not give correct information, which has been corrected. + + * UBSan options were not propagated through the test framework to git + run via the httpd, unlike ASan options, which has been corrected. + +Also contains various documentation updates, code clean-ups and minor fixups. diff --git a/Documentation/RelNotes/2.43.0.txt b/Documentation/RelNotes/2.43.0.txt new file mode 100644 index 0000000000..e0e5b535bb --- /dev/null +++ b/Documentation/RelNotes/2.43.0.txt @@ -0,0 +1,323 @@ +Git v2.43 Release Notes +======================= + +Backward Compatibility Notes + + * The "--rfc" option of "git format-patch" used to be a valid way to + override an earlier "--subject-prefix=<something>" on the command + line and replace it with "[RFC PATCH]", but from this release, it + merely prefixes the string "RFC " in front of the given subject + prefix. If you are negatively affected by this change, please use + "--subject-prefix=PATCH --rfc" as a replacement. + + * In Git 2.42, "git rev-list --stdin" learned to take non-revisions + (like "--not") from the standard input, but the way such a "--not" was + handled was quite confusing, which has been rethought. The updated + rule is that "--not" given from the command line only affects revs + given from the command line that comes but not revs read from the + standard input, and "--not" read from the standard input affects + revs given from the standard input and not revs given from the + command line. + +UI, Workflows & Features + + * A message written in olden time prevented a branch from getting + checked out, saying it is already checked out elsewhere. But these + days, we treat a branch that is being bisected or rebased just like + a branch that is checked out and protect it from getting modified + with the same codepath. The message has been rephrased to say that + the branch is "in use" to avoid confusion. + + * Hourly and other schedules of "git maintenance" jobs are randomly + distributed now. + + * "git cmd -h" learned to signal which options can be negated by + listing such options like "--[no-]opt". + + * The way authentication related data other than passwords (e.g., + oauth token and password expiration data) are stored in libsecret + keyrings has been rethought. + + * Update the libsecret and wincred credential helpers to correctly + match which credential to erase; they erased the wrong entry in + some cases. + + * Git GUI updates. + + * "git format-patch" learned a new "--description-file" option that + lets cover letter description to be fed; this can be used on + detached HEAD where there is no branch description available, and + also can override the branch description if there is one. + + * Use of the "--max-pack-size" option to allow multiple packfiles to + be created is now supported even when we are sending unreachable + objects to cruft packs. + + * "git format-patch --rfc --subject-prefix=<foo>" used to ignore the + "--subject-prefix" option and used "[RFC PATCH]"; now we will add + "RFC" prefix to whatever subject prefix is specified. + + * "git log --format" has been taught the %(decorate) placeholder for + further customization over what the "--decorate" option offers. + + * The default log message created by "git revert", when reverting a + commit that records a revert, has been tweaked, to encourage people + to describe complex "revert of revert of revert" situations better in + their own words. + + * The command-line completion support (in contrib/) learned to + complete "git commit --trailer=" for possible trailer keys. + + * "git update-index" learned the "--show-index-version" option to + inspect the index format version used by the on-disk index file. + + * "git diff" learned the "diff.statNameWidth" configuration variable, + to give the default width for the name part in the "--stat" output. + + * "git range-diff --notes=foo" compared "log --notes=foo --notes" of + the two ranges, instead of using just the specified notes tree, + which has been corrected to use only the specified notes tree. + + * The command line completion script (in contrib/) can be told to + complete aliases by including ": git <cmd> ;" in the alias to tell + it that the alias should be completed in a similar way to how "git + <cmd>" is completed. The parsing code for the alias has been + loosened to allow ';' without an extra space before it. + + * "git for-each-ref" and friends learned to apply mailmap to + authorname and other fields in a more flexible way than using + separate placeholder letters like %a[eElL] every time we want to + come up with small variants. + + * "git repack" machinery learned to pay attention to the "--filter=" + option. + + * "git repack" learned the "--max-cruft-size" option to prevent cruft + packs from growing without bounds. + + * "git merge-tree" learned to take strategy backend specific options + via the "-X" option, like "git merge" does. + + * "git log" and friends learned the "--dd" option that is a + short-hand for "--diff-merges=first-parent -p". + + * The attribute subsystem learned to honor the "attr.tree" + configuration variable that specifies which tree to read the + .gitattributes files from. + + * "git merge-file" learns a mode to read three variants of the + contents to be merged from blob objects. + + +Performance, Internal Implementation, Development Support etc. + + * "git check-attr" has been taught to work better with sparse-index. + + * It may be tempting to leave the help text NULL for a command line + option that is either hidden or too obvious, but "git subcmd -h" + and "git subcmd --help-all" would have segfaulted if done so. Now + the help text is truly optional. + + * Tests that are known to pass with LSan are now marked as such. + + * Flaky "git p4" tests, as well as "git svn" tests, are now skipped + in the (rather expensive) sanitizer CI job. + + * Tests with LSan from time to time seem to emit harmless messages + that make our tests unnecessarily flaky; we work around it by + filtering the uninteresting output. + + * Unused parameters to functions are marked as such, and/or removed, + in order to bring us closer to "-Wunused-parameter" clean. + + * The code to keep track of existing packs in the repository while + repacking has been refactored. + + * The "streaming" interface used for bulk-checkin codepath has been + narrowed to take only blob objects for now, with no real loss of + functionality. + + * GitHub CI workflow has learned to trigger Coverity check. + + * Test coverage for trailers has been improved. + + * The code to iterate over loose references has been optimized to + reduce the number of lstat() system calls. + + * The codepaths that read "chunk" formatted files have been corrected + to pay attention to the chunk size and notice broken files. + + * Replace macos-12 used at GitHub CI with macos-13. + (merge 682a868f67 js/ci-use-macos-13 later to maint). + + +Fixes since v2.42 +----------------- + + * Overly long label names used in the sequencer machinery are now + chopped to fit under filesystem limitation. + + * Scalar updates. + + * Tweak GitHub Actions CI so that pushing the same commit to multiple + branch tips at the same time will not waste building and testing + the same thing twice. + + * The commit-graph verification code that detects a mixture of zero and + non-zero generation numbers has been updated. + + * "git diff -w --exit-code" with various options did not work + correctly, which has been corrected. + + * The "transfer.unpackLimit" configuration variable ought to be used + as a fallback, but overrode the more specific "fetch.unpackLimit" + and "receive.unpackLimit" configuration variables by mistake, which + has been corrected. + + * The use of API between two calls to require_clean_work_tree() from + the sequencer code has been cleaned up for consistency. + + * "git diff --no-such-option" and other corner cases around the exit + status of the "diff" command have been corrected. + + * "git for-each-ref --sort='contents:size'" sorted the refs according + to size numerically, giving a ref that points at a blob twelve-byte + (12) long before showing a blob hundred-byte (100) long, which has + been corrected. + + * We now limit the depth of the tree objects and maximum length of + pathnames recorded in tree objects. + (merge 4d5693ba05 jk/tree-name-and-depth-limit later to maint). + + * Various fixes to the behavior of "rebase -i", when the command got + interrupted by conflicting changes, have been made. + + * References from a description of the `--patch` option in various + manual pages have been simplified and improved. + + * "git grep -e A --no-or -e B" is accepted, even though the negation + of the "--or" option did not mean anything, which has been tightened. + + * The completion script (in contrib/) has been taught to treat the + "-t" option to "git checkout" and "git switch" just like the + "--track" option, to complete remote-tracking branches. + + * "git diff --no-index -R <(one) <(two)" did not work correctly, + which has been corrected. + + * "git maintenance" timers' implementation has been updated, based on + systemd timers, to work with WSL. + + * "git diff --cached" codepath did not fill the necessary stat + information for a file when fsmonitor knows it is clean and ended + up behaving as if it were not clean, which has been corrected. + + * How "alias.foo = : git cmd ; aliased-command-string" should be + spelled with necessary whitespace around punctuation marks to work + has been more clearly documented (but this will be moot with newer + versions of Git where the parsing rules have been improved). + + * HTTP Header redaction code has been adjusted for a newer version of + cURL library that shows its traces differently from earlier + versions. + + * An error message given by "git send-email", when given a malformed + address, did not show the offending address, which has been corrected. + + * UBSan options were not propagated through the test framework to git + run via the httpd, unlike ASan options, which has been corrected. + + * "checkout --merge -- path" and "update-index --unresolve path" did + not resurrect conflicted state that was resolved to remove path, + but now they do. + (merge 5bdedac3c7 jc/unresolve-removal later to maint). + + * The display width table for unicode characters has been updated for + Unicode 15.1 + (merge 872976c37e bb/unicode-width-table-15 later to maint). + + * Update mailmap entry for Derrick. + (merge 6e5457d8c7 ds/mailmap-entry-update later to maint). + + * In the ".gitmodules" files, submodules are keyed by their names, + and the path to the submodule whose name is $name is specified by + the submodule.$name.path variable. There were a few codepaths that + mixed the name and path up when consulting the submodule database, + which have been corrected. It took long for these bugs to be found + as the name of a submodule initially is the same as its path, and + the problem does not surface until it is moved to a different path, + which apparently happens very rarely. + + * "git diff --merge-base X other args..." insisted that X must be a + commit and errored out when given an annotated tag that peels to a + commit, but we only need it to be a committish. This has been + corrected. + (merge 4adceb5a29 ar/diff-index-merge-base-fix later to maint). + + * "git merge-tree" used to segfault when the "--attr-source" + option is used, which has been corrected. + (merge e95bafc52f jc/merge-ort-attr-index-fix later to maint). + + * Unlike "git log --pretty=%D", "git log --pretty="%(decorate)" did + not auto-initialize the decoration subsystem, which has been + corrected. + + * Feeding "git stash store" with a random commit that was not created + by "git stash create" now errors out. + (merge d9b6634589 jc/fail-stash-to-store-non-stash later to maint). + + * The index file has room only for the lower 32-bit of the file size in + the cached stat information, which means cached stat information + will have 0 in its sd_size member for a file whose size is a multiple + of 4GiB. This is mistaken for a racily clean path. Avoid it by + storing a bogus sd_size value instead for such files. + (merge 5143ac07b1 bc/racy-4gb-files later to maint). + + * "git p4" tried to store symlinks to LFS when told, but has been + fixed not to do so, because it does not make sense. + (merge 10c89a02b0 mm/p4-symlink-with-lfs later to maint). + + * The codepath to handle recipient addresses `git send-email + --compose` learns from the user was completely broken, which has + been corrected. + (merge 3ec6167567 jk/send-email-fix-addresses-from-composed-messages later to maint). + + * "cd sub && git grep -f patterns" tried to read "patterns" file at + the top level of the working tree; it has been corrected to read + "sub/patterns" instead. + + * "git reflog expire --single-worktree" has been broken for the past + 20 months or so, which has been corrected. + + * "git send-email" did not have certain pieces of data computed yet + when it tried to validate the outgoing messages and its recipient + addresses, which has been sorted out. + + * "git bugreport" learned to complain when it received a command line + argument that it will not use. + + * The codepath to traverse the commit-graph learned to notice that a + commit is missing (e.g., corrupt repository lost an object), even + though it knows something about the commit (like its parents) from + what is in commit-graph. + (merge 7a5d604443 ps/do-not-trust-commit-graph-blindly-for-existence later to maint). + + * "git rev-list --missing" did not work for missing commit objects, + which has been corrected. + + * "git rev-list --unpacked --objects" failed to exclude packed + non-commit objects, which has been corrected. + (merge 7b3c8e9f38 tb/rev-list-unpacked-fix later to maint). + + * "To dereference" and "to peel" were sometimes used in in-code + comments and documentation but without description in the glossary. + (merge 893dce2ffb vd/glossary-dereference-peel later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge c2c349a15c xz/commit-title-soft-limit-doc later to maint). + (merge 1bd809938a tb/format-pack-doc-update later to maint). + (merge 8f81532599 an/clang-format-typofix later to maint). + (merge 3ca86adc2d la/strvec-header-fix later to maint). + (merge 6789275d37 jc/test-i18ngrep later to maint). + (merge 9972cd6004 ps/leakfixes later to maint). + (merge 46edab516b tz/send-email-helpfix later to maint). diff --git a/Documentation/RelNotes/2.44.0.txt b/Documentation/RelNotes/2.44.0.txt new file mode 100644 index 0000000000..b44e88fb15 --- /dev/null +++ b/Documentation/RelNotes/2.44.0.txt @@ -0,0 +1,105 @@ +Git v2.44 Release Notes +======================= + +UI, Workflows & Features + + * "git add" and "git stash" learned to support the ":(attr:...)" + magic pathspec. + + * "git rebase --autosquash" is now enabled for non-interactive rebase, + but it is still incompatible with the apply backend. + + * Introduce "git replay", a tool meant on the server side without + working tree to recreate a history. + + * "git merge-file" learned to take the "--diff-algorithm" option to + use algorithm different from the default "myers" diff. + + * Command line completion (in contrib/) learned to complete path + arguments to the "add/set" subcommands of "git sparse-checkout" + better. + + +Performance, Internal Implementation, Development Support etc. + + * Process to add some form of low-level unit tests has started. + + * Add support for GitLab CI. + + * "git for-each-ref --no-sort" still sorted the refs alphabetically + which paid non-trivial cost. It has been redefined to show output + in an unspecified order, to allow certain optimizations to take + advantage of. + + * Simplify API implementation to delete references by eliminating + duplication. + + * Subject approxidate() and show_date() machinery to OSS-Fuzz. + + +Fixes since v2.43 +----------------- + + * The way CI testing used "prove" could lead to running the test + suite twice needlessly, which has been corrected. + (merge e7e03ef995 js/ci-discard-prove-state later to maint). + + * Update ref-related tests. + + * "git format-patch --encode-email-headers" ignored the option when + preparing the cover letter, which has been corrected. + + * Newer versions of Getopt::Long started giving warnings against our + (ab)use of it in "git send-email". Bump the minimum version + requirement for Perl to 5.8.1 (from September 2002) to allow + simplifying our implementation. + (merge 6ff658cc78 tz/send-email-negatable-options later to maint). + + * Earlier we stopped relying on commit-graph that (still) records + information about commits that are lost from the object store, + which has negative performance implications. The default has been + flipped to disable this pessimization. + (merge b1df3b3867 ps/commit-graph-less-paranoid later to maint). + + * Stale URLs have been updated to their current counterparts (or + archive.org) and HTTP links are replaced with working HTTPS links. + (merge 62b4f7b9c6 js/update-urls-in-doc-and-comment later to maint). + + * trace2 streams used to record the URLs that potentially embed + authentication material, which has been corrected. + (merge 16fa3eebc0 jh/trace2-redact-auth later to maint). + + * The sample pre-commit hook that tries to catch introduction of new + paths that use potentially non-portable characters did not notice + an existing path getting renamed to such a problematic path, when + rename detection was enabled. + (merge d9fd71fa2a jp/use-diff-index-in-pre-commit-sample later to maint). + + * The command line parser for the "log" family of commands was too + loose when parsing certain numbers, e.g., silently ignoring the + extra 'q' in "git log -n 1q" without complaining, which has been + tightened up. + (merge 71a1e94821 jc/revision-parse-int later to maint). + + * "git $cmd --end-of-options --rev -- --path" for some $cmd failed + to interpret "--rev" as a rev, and "--path" as a path. This was + fixed for many programs like "reset" and "checkout". + (merge 9385174627 jk/end-of-options later to maint). + + * "git bisect reset" has been taught to clean up state files and refs + even when BISECT_START file is gone. + (merge daaa03e54c jk/bisect-reset-fix later to maint). + + * Some codepaths did not correctly parse configuration variables + specified with valueless "true", which has been corrected. + (merge d49cb162fa jk/implicit-true later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge 50f1abcff6 js/packfile-h-typofix later to maint). + (merge cbf498eb53 jb/reflog-expire-delete-dry-run-options later to maint). + (merge 7854bf4960 rs/i18n-cannot-be-used-together later to maint). + (merge cd3c28c53a rs/column-leakfix later to maint). + (merge 866a1b9026 ps/ref-tests-update-more later to maint). + (merge e4299d26d4 mk/doc-gitfile-more later to maint). + (merge 792b86283b rs/incompatible-options-messages later to maint). + (merge ea8f9494ab jk/config-cleanup later to maint). diff --git a/Documentation/ReviewingGuidelines.txt b/Documentation/ReviewingGuidelines.txt index 0e323d5477..515d470d23 100644 --- a/Documentation/ReviewingGuidelines.txt +++ b/Documentation/ReviewingGuidelines.txt @@ -19,7 +19,7 @@ Principles Selecting patch(es) to review ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you are looking for a patch series in need of review, start by checking -latest "What's cooking in git.git" email +the latest "What's cooking in git.git" email (https://lore.kernel.org/git/xmqqilm1yp3m.fsf@gitster.g/[example]). The "What's cooking" emails & replies can be found using the query `s:"What's cooking"` on the https://lore.kernel.org/git/[`lore.kernel.org` mailing list archive]; @@ -126,7 +126,7 @@ Terminology ----------- nit: :: Denotes a small issue that should be fixed, such as a typographical error - or mis-alignment of conditions in an `if()` statement. + or misalignment of conditions in an `if()` statement. aside: :: optional: :: diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index b218e27357..bce7f97815 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -3,45 +3,101 @@ Submitting Patches == Guidelines -Here are some guidelines for people who want to contribute their code to this -software. There is also a link:MyFirstContribution.html[step-by-step tutorial] +Here are some guidelines for contributing back to this +project. There is also a link:MyFirstContribution.html[step-by-step tutorial] available which covers many of these same guidelines. -[[base-branch]] -=== Decide what to base your work on. - -In general, always base your work on the oldest branch that your -change is relevant to. - -* A bugfix should be based on `maint` in general. If the bug is not - present in `maint`, base it on `master`. For a bug that's not yet - in `master`, find the topic that introduces the regression, and - base your work on the tip of the topic. - -* A new feature should be based on `master` in general. If the new - feature depends on other topics that are in `next`, but not in - `master`, fork a branch from the tip of `master`, merge these topics - to the branch, and work on that branch. You can remind yourself of - how you prepared the base with `git log --first-parent master..`. - -* Corrections and enhancements to a topic not yet in `master` should - be based on the tip of that topic. If the topic has not been merged - to `next`, it's alright to add a note to squash minor corrections - into the series. - -* In the exceptional case that a new feature depends on several topics - not in `master`, start working on `next` or `seen` privately and - send out patches only for discussion. Once your new feature starts - to stabilize, you would have to rebase it (see the "depends on other - topics" above). - -* Some parts of the system have dedicated maintainers with their own - repositories (see the section "Subsystems" below). Changes to - these parts should be based on their trees. - -To find the tip of a topic branch, run `git log --first-parent -master..seen` and look for the merge commit. The second parent of this -commit is the tip of the topic branch. +[[choose-starting-point]] +=== Choose a starting point. + +As a preliminary step, you must first choose a starting point for your +work. Typically this means choosing a branch, although technically +speaking it is actually a particular commit (typically the HEAD, or tip, +of the branch). + +There are several important branches to be aware of. Namely, there are +four integration branches as discussed in linkgit:gitworkflows[7]: + +* maint +* master +* next +* seen + +The branches lower on the list are typically descendants of the ones +that come before it. For example, `maint` is an "older" branch than +`master` because `master` usually has patches (commits) on top of +`maint`. + +There are also "topic" branches, which contain work from other +contributors. Topic branches are created by the Git maintainer (in +their fork) to organize the current set of incoming contributions on +the mailing list, and are itemized in the regular "What's cooking in +git.git" announcements. To find the tip of a topic branch, run `git log +--first-parent master..seen` and look for the merge commit. The second +parent of this commit is the tip of the topic branch. + +There is one guiding principle for choosing the right starting point: in +general, always base your work on the oldest integration branch that +your change is relevant to (see "Merge upwards" in +linkgit:gitworkflows[7]). What this principle means is that for the +vast majority of cases, the starting point for new work should be the +latest HEAD commit of `maint` or `master` based on the following cases: + +* If you are fixing bugs in the released version, use `maint` as the + starting point (which may mean you have to fix things without using + new API features on the cutting edge that recently appeared in + `master` but were not available in the released version). + +* Otherwise (such as if you are adding new features) use `master`. + + +NOTE: In exceptional cases, a bug that was introduced in an old +version may have to be fixed for users of releases that are much older +than the recent releases. `git describe --contains X` may describe +`X` as `v2.30.0-rc2-gXXXXXX` for the commit `X` that introduced the +bug, and the bug may be so high-impact that we may need to issue a new +maintenance release for Git 2.30.x series, when "Git 2.41.0" is the +current release. In such a case, you may want to use the tip of the +maintenance branch for the 2.30.x series, which may be available in the +`maint-2.30` branch in https://github.com/gitster/git[the maintainer's +"broken out" repo]. + +This also means that `next` or `seen` are inappropriate starting points +for your work, if you want your work to have a realistic chance of +graduating to `master`. They are simply not designed to be used as a +base for new work; they are only there to make sure that topics in +flight work well together. This is why both `next` and `seen` are +frequently re-integrated with incoming patches on the mailing list and +force-pushed to replace previous versions of themselves. A topic that is +literally built on top of `next` cannot be merged to `master` without +dragging in all the other topics in `next`, some of which may not be +ready. + +For example, if you are making tree-wide changes, while somebody else is +also making their own tree-wide changes, your work may have severe +overlap with the other person's work. This situation may tempt you to +use `next` as your starting point (because it would have the other +person's work included in it), but doing so would mean you'll not only +depend on the other person's work, but all the other random things from +other contributors that are already integrated into `next`. And as soon +as `next` is updated with a new version, all of your work will need to +be rebased anyway in order for them to be cleanly applied by the +maintainer. + +Under truly exceptional circumstances where you absolutely must depend +on a select few topic branches that are already in `next` but not in +`master`, you may want to create your own custom base-branch by forking +`master` and merging the required topic branches into it. You could then +work on top of this base-branch. But keep in mind that this base-branch +would only be known privately to you. So when you are ready to send +your patches to the list, be sure to communicate how you created it in +your cover letter. This critical piece of information would allow +others to recreate your base-branch on their end in order for them to +try out your work. + +Finally, note that some parts of the system have dedicated maintainers +with their own separate source code repositories (see the section +"Subsystems" below). [[separate-commits]] === Make separate commits for logically separate changes. @@ -210,7 +266,7 @@ date)", like this: noticed that ... .... -The "Copy commit summary" command of gitk can be used to obtain this +The "Copy commit reference" command of gitk can be used to obtain this format (with the subject enclosed in a pair of double-quotes), or this invocation of `git show`: @@ -317,10 +373,13 @@ Please make sure your patch does not add commented out debugging code, or include any extra files which do not relate to what your patch is trying to achieve. Make sure to review your patch after generating it, to ensure accuracy. Before -sending out, please make sure it cleanly applies to the base you -have chosen in the "Decide what to base your work on" section, -and unless it targets the `master` branch (which is the default), -mark your patches as such. +sending out, please make sure it cleanly applies to the starting point you +have chosen in the "Choose a starting point" section. + +NOTE: From the perspective of those reviewing your patch, the `master` +branch is the default expected starting point. So if you have chosen a +different starting point, please communicate this choice in your cover +letter. [[send-patches]] @@ -334,8 +393,8 @@ mailing list{security-ml}, instead of the public mailing list. Learn to use format-patch and send-email if possible. These commands are optimized for the workflow of sending patches, avoiding many ways -your existing e-mail client that is optimized for "multipart/*" mime -type e-mails to corrupt and render your patches unusable. +your existing e-mail client (often optimized for "multipart/*" MIME +type e-mails) might render your patches unusable. People on the Git mailing list need to be able to read and comment on the changes you are submitting. It is important for @@ -456,8 +515,8 @@ repositories. git://git.ozlabs.org/~paulus/gitk - Those who are interested in improve gitk can volunteer to help Paul - in maintaining it cf. <YntxL/fTplFm8lr6@cleo>. + Those who are interested in improving gitk can volunteer to help Paul + maintain it, cf. <YntxL/fTplFm8lr6@cleo>. - `po/` comes from the localization coordinator, Jiang Xin: @@ -497,7 +556,7 @@ help you find out who they are. In any time between the (2)-(3) cycle, the maintainer may pick it up from the list and queue it to `seen`, in order to make it easier for -people play with it without having to pick up and apply the patch to +people to play with it without having to pick up and apply the patch to their trees themselves. [[patch-status]] diff --git a/Documentation/ToolsForGit.txt b/Documentation/ToolsForGit.txt index 5060d0d231..ae7690b45d 100644 --- a/Documentation/ToolsForGit.txt +++ b/Documentation/ToolsForGit.txt @@ -5,7 +5,7 @@ Tools for developing Git [[summary]] == Summary -This document gathers tips, scripts and configuration file to help people +This document gathers tips, scripts, and configuration files to help people working on Git's codebase use their favorite tools while following Git's coding style. @@ -32,7 +32,7 @@ information on using the script. This is adapted from Linux's suggestion in its CodingStyle document: -- To follow rules of the CodingGuideline, it's useful to put the following in +- To follow the rules in CodingGuidelines, it's useful to put the following in GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: ---- ;; note the first part is useful for C editing, too diff --git a/Documentation/config.txt b/Documentation/config.txt index 0e93aef862..e3a74dd1c1 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -11,7 +11,7 @@ file. The file `/etc/gitconfig` can be used to store a system-wide default configuration. The configuration variables are used by both the Git plumbing -and the porcelains. The variables are divided into sections, wherein +and the porcelain commands. The variables are divided into sections, wherein the fully qualified variable name of the variable itself is the last dot-separated segment and the section name is everything before the last dot. The variable names are case-insensitive, allow only alphanumeric @@ -103,7 +103,7 @@ was found. See below for examples. Conditional includes ~~~~~~~~~~~~~~~~~~~~ -You can include a config file from another conditionally by setting a +You can conditionally include a config file from another by setting an `includeIf.<condition>.path` variable to the name of the file to be included. @@ -118,7 +118,7 @@ are: pattern, the include condition is met. + The .git location may be auto-discovered, or come from `$GIT_DIR` -environment variable. If the repository is auto discovered via a .git +environment variable. If the repository is auto-discovered via a .git file (e.g. from submodules, or a linked worktree), the .git location would be the final location where the .git directory is, not where the .git file is. @@ -182,7 +182,7 @@ included, Git breaks the cycle by prohibiting these files from affecting the resolution of these conditions (thus, prohibiting them from declaring remote URLs). + -As for the naming of this keyword, it is for forwards compatibiliy with +As for the naming of this keyword, it is for forwards compatibility with a naming scheme that supports more variable-based include conditions, but currently Git only supports the exact keyword described above. @@ -371,6 +371,8 @@ other popular tools, and describe them in your documentation. include::config/advice.txt[] +include::config/attr.txt[] + include::config/core.txt[] include::config/add.txt[] diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt index c96b5b2e5d..2737381a11 100644 --- a/Documentation/config/advice.txt +++ b/Documentation/config/advice.txt @@ -5,7 +5,7 @@ advice.*:: + -- ambiguousFetchRefspec:: - Advice shown when fetch refspec for multiple remotes map to + Advice shown when a fetch refspec for multiple remotes maps to the same remote-tracking branch namespace and causes branch tracking set-up to fail. fetchShowForcedUpdates:: @@ -63,7 +63,7 @@ advice.*:: the template shown when writing commit messages in linkgit:git-commit[1], and in the help message shown by linkgit:git-switch[1] or - linkgit:git-checkout[1] when switching branch. + linkgit:git-checkout[1] when switching branches. statusUoption:: Advise to consider using the `-u` option to linkgit:git-status[1] when the command takes more than 2 seconds to enumerate untracked @@ -87,7 +87,7 @@ advice.*:: detachedHead:: Advice shown when you used linkgit:git-switch[1] or linkgit:git-checkout[1] - to move to the detach HEAD state, to instruct how to + to move to the detached HEAD state, to instruct how to create a local branch after the fact. suggestDetachingHead:: Advice shown when linkgit:git-switch[1] refuses to detach HEAD @@ -101,7 +101,7 @@ advice.*:: otherwise caused a remote-tracking branch to be checked out. See the `checkout.defaultRemote` configuration variable for how to set a given remote - to used by default in some situations where this + to be used by default in some situations where this advice would be printed. amWorkDir:: Advice that shows the location of the patch file when @@ -138,4 +138,8 @@ advice.*:: checkout. diverging:: Advice shown when a fast-forward is not possible. + worktreeAddOrphan:: + Advice shown when a user tries to create a worktree from an + invalid reference, to instruct how to create a new orphan + branch instead. -- diff --git a/Documentation/config/alias.txt b/Documentation/config/alias.txt index f1ca739d57..01df96fab3 100644 --- a/Documentation/config/alias.txt +++ b/Documentation/config/alias.txt @@ -4,7 +4,7 @@ alias.*:: `git last` is equivalent to `git cat-file commit HEAD`. To avoid confusion and troubles with script usage, aliases that hide existing Git commands are ignored. Arguments are split by - spaces, the usual shell quoting and escaping is supported. + spaces, the usual shell quoting and escaping are supported. A quote pair or a backslash can be used to quote them. + Note that the first word of an alias does not necessarily have to be a diff --git a/Documentation/config/apply.txt b/Documentation/config/apply.txt index 8fb8ef763d..f9908e210a 100644 --- a/Documentation/config/apply.txt +++ b/Documentation/config/apply.txt @@ -2,10 +2,10 @@ apply.ignoreWhitespace:: When set to 'change', tells 'git apply' to ignore changes in whitespace, in the same way as the `--ignore-space-change` option. - When set to one of: no, none, never, false tells 'git apply' to + When set to one of: no, none, never, false, it tells 'git apply' to respect all whitespace differences. See linkgit:git-apply[1]. apply.whitespace:: - Tells 'git apply' how to handle whitespaces, in the same way + Tells 'git apply' how to handle whitespace, in the same way as the `--whitespace` option. See linkgit:git-apply[1]. diff --git a/Documentation/config/attr.txt b/Documentation/config/attr.txt new file mode 100644 index 0000000000..1a482d6af2 --- /dev/null +++ b/Documentation/config/attr.txt @@ -0,0 +1,7 @@ +attr.tree:: + A reference to a tree in the repository from which to read attributes, + instead of the `.gitattributes` file in the working tree. In a bare + repository, this defaults to `HEAD:.gitattributes`. If the value does + not resolve to a valid tree object, an empty tree is used instead. + When the `GIT_ATTR_SOURCE` environment variable or `--attr-source` + command line option are used, this configuration variable has no effect. diff --git a/Documentation/config/branch.txt b/Documentation/config/branch.txt index 445341a906..432b9cd2c0 100644 --- a/Documentation/config/branch.txt +++ b/Documentation/config/branch.txt @@ -36,7 +36,7 @@ branch.sort:: branch.<name>.remote:: When on branch <name>, it tells 'git fetch' and 'git push' - which remote to fetch from/push to. The remote to push to + which remote to fetch from or push to. The remote to push to may be overridden with `remote.pushDefault` (for all branches). The remote to push to, for the current branch, may be further overridden by `branch.<name>.pushRemote`. If no remote is @@ -64,7 +64,7 @@ branch.<name>.merge:: handled like the remote part of a refspec, and must match a ref which is fetched from the remote given by "branch.<name>.remote". - The merge information is used by 'git pull' (which at first calls + The merge information is used by 'git pull' (which first calls 'git fetch') to lookup the default branch for merging. Without this option, 'git pull' defaults to merge the first refspec fetched. Specify multiple values to get an octopus merge. @@ -99,5 +99,5 @@ for details). branch.<name>.description:: Branch description, can be edited with `git branch --edit-description`. Branch description is - automatically added in the format-patch cover letter or + automatically added to the format-patch cover letter or request-pull summary. diff --git a/Documentation/config/checkout.txt b/Documentation/config/checkout.txt index bfbca90f0e..a323022993 100644 --- a/Documentation/config/checkout.txt +++ b/Documentation/config/checkout.txt @@ -30,7 +30,7 @@ checkout.workers:: all commands that perform checkout. E.g. checkout, clone, reset, sparse-checkout, etc. + -Note: parallel checkout usually delivers better performance for repositories +Note: Parallel checkout usually delivers better performance for repositories located on SSDs or over NFS. For repositories on spinning disks and/or machines with a small number of cores, the default sequential checkout often performs better. The size and compression level of a repository might also influence how @@ -39,6 +39,6 @@ well the parallel version performs. checkout.thresholdForParallelism:: When running parallel checkout with a small number of files, the cost of subprocess spawning and inter-process communication might outweigh - the parallelization gains. This setting allows to define the minimum + the parallelization gains. This setting allows you to define the minimum number of files for which parallel checkout should be attempted. The default is 100. diff --git a/Documentation/config/clean.txt b/Documentation/config/clean.txt index a807c925b9..f05b9403b5 100644 --- a/Documentation/config/clean.txt +++ b/Documentation/config/clean.txt @@ -1,3 +1,3 @@ clean.requireForce:: A boolean to make git-clean do nothing unless given -f, - -i or -n. Defaults to true. + -i, or -n. Defaults to true. diff --git a/Documentation/config/clone.txt b/Documentation/config/clone.txt index 26f4fb137a..d037b57f72 100644 --- a/Documentation/config/clone.txt +++ b/Documentation/config/clone.txt @@ -4,8 +4,8 @@ clone.defaultRemoteName:: option to linkgit:git-clone[1]. clone.rejectShallow:: - Reject to clone a repository if it is a shallow one, can be overridden by - passing option `--reject-shallow` in command line. See linkgit:git-clone[1] + Reject cloning a repository if it is a shallow one; this can be overridden by + passing the `--reject-shallow` option on the command line. See linkgit:git-clone[1] clone.filterSubmodules:: If a partial clone filter is provided (see `--filter` in diff --git a/Documentation/config/color.txt b/Documentation/config/color.txt index 1795b2d16b..2f2275ac69 100644 --- a/Documentation/config/color.txt +++ b/Documentation/config/color.txt @@ -106,7 +106,7 @@ color.grep.<slot>:: matching text in context lines `matchSelected`;; matching text in selected lines. Also, used to customize the following - linkgit:git-log[1] subcommands: `--grep`, `--author` and `--committer`. + linkgit:git-log[1] subcommands: `--grep`, `--author`, and `--committer`. `selected`;; non-matching text in selected lines. Also, used to customize the following linkgit:git-log[1] subcommands: `--grep`, `--author` and diff --git a/Documentation/config/column.txt b/Documentation/config/column.txt index 76aa2f29dc..01e4198429 100644 --- a/Documentation/config/column.txt +++ b/Documentation/config/column.txt @@ -43,7 +43,7 @@ column.branch:: See `column.ui` for details. column.clean:: - Specify the layout when list items in `git clean -i`, which always + Specify the layout when listing items in `git clean -i`, which always shows files and directories in columns. See `column.ui` for details. column.status:: @@ -51,5 +51,5 @@ column.status:: See `column.ui` for details. column.tag:: - Specify whether to output tag listing in `git tag` in columns. + Specify whether to output tag listings in `git tag` in columns. See `column.ui` for details. diff --git a/Documentation/config/commit.txt b/Documentation/config/commit.txt index 2c95573930..62f0d92fda 100644 --- a/Documentation/config/commit.txt +++ b/Documentation/config/commit.txt @@ -2,7 +2,7 @@ commit.cleanup:: This setting overrides the default of the `--cleanup` option in `git commit`. See linkgit:git-commit[1] for details. Changing the default can be useful when you always want to keep lines that begin - with comment character `#` in your log message, in which case you + with the comment character `#` in your log message, in which case you would do `git config commit.cleanup whitespace` (note that you will have to remove the help lines that begin with `#` in the commit log template yourself, if you do this). @@ -25,5 +25,5 @@ commit.template:: new commit messages. commit.verbose:: - A boolean or int to specify the level of verbose with `git commit`. + A boolean or int to specify the level of verbosity with `git commit`. See linkgit:git-commit[1]. diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt index dfbdaf00b8..0e8c2832bf 100644 --- a/Documentation/config/core.txt +++ b/Documentation/config/core.txt @@ -736,3 +736,9 @@ core.abbrev:: If set to "no", no abbreviation is made and the object names are shown in their full length. The minimum length is 4. + +core.maxTreeDepth:: + The maximum depth Git is willing to recurse while traversing a + tree (e.g., "a/b/cde/f" has a depth of 4). This is a fail-safe + to allow Git to abort cleanly, and should not generally need to + be adjusted. The default is 4096. diff --git a/Documentation/config/credential.txt b/Documentation/config/credential.txt index 512f31876e..0221c3e620 100644 --- a/Documentation/config/credential.txt +++ b/Documentation/config/credential.txt @@ -21,7 +21,7 @@ credential.username:: credential.<url>.*:: Any of the credential.* options above can be applied selectively to - some credentials. For example "credential.https://example.com.username" + some credentials. For example, "credential.https://example.com.username" would set the default username only for https connections to example.com. See linkgit:gitcredentials[7] for details on how URLs are matched. @@ -31,6 +31,6 @@ credentialCache.ignoreSIGHUP:: credentialStore.lockTimeoutMS:: The length of time, in milliseconds, for git-credential-store to retry - when trying to lock the credentials file. Value 0 means not to retry at + when trying to lock the credentials file. A value of 0 means not to retry at all; -1 means to try indefinitely. Default is 1000 (i.e., retry for 1s). diff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt index 35a7bf86d7..bd5ae0c337 100644 --- a/Documentation/config/diff.txt +++ b/Documentation/config/diff.txt @@ -1,6 +1,6 @@ diff.autoRefreshIndex:: When using 'git diff' to compare with work tree - files, do not consider stat-only change as changed. + files, do not consider stat-only changes as changed. Instead, silently run `git update-index --refresh` to update the cached stat information for paths whose contents in the work tree match the contents in the @@ -52,6 +52,10 @@ directories with less than 10% of the total amount of changed files, and accumulating child directory counts in the parent directories: `files,10,cumulative`. +diff.statNameWidth:: + Limit the width of the filename part in --stat output. If set, applies + to all commands generating --stat output except format-patch. + diff.statGraphWidth:: Limit the width of the graph part in --stat output. If set, applies to all commands generating --stat output except format-patch. diff --git a/Documentation/config/fastimport.txt b/Documentation/config/fastimport.txt index c1166e330d..903677d7ef 100644 --- a/Documentation/config/fastimport.txt +++ b/Documentation/config/fastimport.txt @@ -1,8 +1,8 @@ fastimport.unpackLimit:: If the number of objects imported by linkgit:git-fast-import[1] is below this limit, then the objects will be unpacked into - loose object files. However if the number of imported objects - equals or exceeds this limit then the pack will be stored as a + loose object files. However, if the number of imported objects + equals or exceeds this limit, then the pack will be stored as a pack. Storing the pack from a fast-import can make the import operation complete faster, especially on slow filesystems. If not set, the value of `transfer.unpackLimit` is used instead. diff --git a/Documentation/config/feature.txt b/Documentation/config/feature.txt index 17b4d39f89..bf9546fca4 100644 --- a/Documentation/config/feature.txt +++ b/Documentation/config/feature.txt @@ -14,6 +14,9 @@ feature.experimental:: + * `fetch.negotiationAlgorithm=skipping` may improve fetch negotiation times by skipping more commits at a time, reducing the number of round trips. ++ +* `pack.useBitmapBoundaryTraversal=true` may improve bitmap traversal times by +walking fewer objects. 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 568f0f75b3..aea5b97477 100644 --- a/Documentation/config/fetch.txt +++ b/Documentation/config/fetch.txt @@ -52,8 +52,8 @@ fetch.pruneTags:: fetch.output:: Control how ref update status is printed. Valid values are - `full` and `compact`. Default value is `full`. See section - OUTPUT in linkgit:git-fetch[1] for detail. + `full` and `compact`. Default value is `full`. See the + OUTPUT section in linkgit:git-fetch[1] for details. fetch.negotiationAlgorithm:: Control how information about the commits in the local repository diff --git a/Documentation/config/format.txt b/Documentation/config/format.txt index 539b75c6b4..7410e930e5 100644 --- a/Documentation/config/format.txt +++ b/Documentation/config/format.txt @@ -68,7 +68,7 @@ format.encodeEmailHeaders:: Defaults to true. format.pretty:: - The default pretty format for log/show/whatchanged command, + The default pretty format for log/show/whatchanged command. See linkgit:git-log[1], linkgit:git-show[1], linkgit:git-whatchanged[1]. diff --git a/Documentation/config/fsck.txt b/Documentation/config/fsck.txt index a3c865df56..8e9e508933 100644 --- a/Documentation/config/fsck.txt +++ b/Documentation/config/fsck.txt @@ -11,13 +11,13 @@ to clone or fetch it set `fetch.fsck.<msg-id>`. + The rest of the documentation discusses `fsck.*` for brevity, but the same applies for the corresponding `receive.fsck.*` and -`fetch.<msg-id>.*`. variables. +`fetch.fsck.*`. variables. + -Unlike variables like `color.ui` and `core.editor` the +Unlike variables like `color.ui` and `core.editor`, the `receive.fsck.<msg-id>` and `fetch.fsck.<msg-id>` variables will not fall back on the `fsck.<msg-id>` configuration if they aren't set. To -uniformly configure the same fsck settings in different circumstances -all three of them they must all set to the same values. +uniformly configure the same fsck settings in different circumstances, +all three of them must be set to the same values. + When `fsck.<msg-id>` is set, errors can be switched to warnings and vice versa by configuring the `fsck.<msg-id>` setting where the @@ -36,19 +36,19 @@ Setting an unknown `fsck.<msg-id>` value will cause fsck to die, but doing the same for `receive.fsck.<msg-id>` and `fetch.fsck.<msg-id>` will only cause git to warn. + -See `Fsck Messages` section of linkgit:git-fsck[1] for supported +See the `Fsck Messages` section of linkgit:git-fsck[1] for supported values of `<msg-id>`. fsck.skipList:: The path to a list of object names (i.e. one unabbreviated SHA-1 per line) that are known to be broken in a non-fatal way and should - be ignored. On versions of Git 2.20 and later comments ('#'), empty - lines, and any leading and trailing whitespace is ignored. Everything + be ignored. On versions of Git 2.20 and later, comments ('#'), empty + lines, and any leading and trailing whitespace are ignored. Everything but a SHA-1 per line will error out on older versions. + This feature is useful when an established project should be accepted -despite early commits containing errors that can be safely ignored +despite early commits containing errors that can be safely ignored, such as invalid committer email addresses. Note: corrupt objects cannot be skipped with this setting. + @@ -58,11 +58,11 @@ Like `fsck.<msg-id>` this variable has corresponding Unlike variables like `color.ui` and `core.editor` the `receive.fsck.skipList` and `fetch.fsck.skipList` variables will not fall back on the `fsck.skipList` configuration if they aren't set. To -uniformly configure the same fsck settings in different circumstances -all three of them they must all set to the same values. +uniformly configure the same fsck settings in different circumstances, +all three of them must be set to the same values. + Older versions of Git (before 2.20) documented that the object names -list should be sorted. This was never a requirement, the object names +list should be sorted. This was never a requirement; the object names could appear in any order, but when reading the list we tracked whether the list was sorted for the purposes of an internal binary search implementation, which could save itself some work with an already sorted diff --git a/Documentation/config/fsmonitor--daemon.txt b/Documentation/config/fsmonitor--daemon.txt index c225c6c9e7..671f9b9462 100644 --- a/Documentation/config/fsmonitor--daemon.txt +++ b/Documentation/config/fsmonitor--daemon.txt @@ -1,5 +1,5 @@ fsmonitor.allowRemote:: - By default, the fsmonitor daemon refuses to work against network-mounted + By default, the fsmonitor daemon refuses to work with network-mounted repositories. Setting `fsmonitor.allowRemote` to `true` overrides this behavior. Only respected when `core.fsmonitor` is set to `true`. diff --git a/Documentation/config/gc.txt b/Documentation/config/gc.txt index 7f95c866e1..664a3c2874 100644 --- a/Documentation/config/gc.txt +++ b/Documentation/config/gc.txt @@ -24,7 +24,7 @@ gc.auto:: default value is 6700. + Setting this to 0 disables not only automatic packing based on the -number of loose objects, but any other heuristic `git gc --auto` will +number of loose objects, but also any other heuristic `git gc --auto` will otherwise use to determine if there's work to do, such as `gc.autoPackLimit`. @@ -39,7 +39,7 @@ See the `gc.bigPackThreshold` configuration variable below. When in use, it'll affect how the auto pack limit works. gc.autoDetach:: - Make `git gc --auto` return immediately and run in background + Make `git gc --auto` return immediately and run in the background if the system supports it. Default is true. gc.bigPackThreshold:: @@ -86,6 +86,12 @@ gc.cruftPacks:: linkgit:git-repack[1]) instead of as loose objects. The default is `true`. +gc.maxCruftSize:: + Limit the size of new cruft packs when repacking. When + specified in addition to `--max-cruft-size`, the command line + option takes priority. See the `--max-cruft-size` option of + linkgit:git-repack[1]. + gc.pruneExpire:: When 'git gc' is run, it will call 'prune --expire 2.weeks.ago' (and 'repack --cruft --cruft-expiration 2.weeks.ago' if using @@ -130,6 +136,37 @@ or rebase occurring. Since these changes are not part of the current project most users will want to expire them sooner, which is why the default is more aggressive than `gc.reflogExpire`. +gc.recentObjectsHook:: + When considering whether or not to remove an object (either when + generating a cruft pack or storing unreachable objects as + loose), use the shell to execute the specified command(s). + Interpret their output as object IDs which Git will consider as + "recent", regardless of their age. By treating their mtimes as + "now", any objects (and their descendants) mentioned in the + output will be kept regardless of their true age. ++ +Output must contain exactly one hex object ID per line, and nothing +else. Objects which cannot be found in the repository are ignored. +Multiple hooks are supported, but all must exit successfully, else the +operation (either generating a cruft pack or unpacking unreachable +objects) will be halted. + +gc.repackFilter:: + When repacking, use the specified filter to move certain + objects into a separate packfile. See the + `--filter=<filter-spec>` option of linkgit:git-repack[1]. + +gc.repackFilterTo:: + When repacking and using a filter, see `gc.repackFilter`, the + specified location will be used to create the packfile + containing the filtered out objects. **WARNING:** The + specified location should be accessible, using for example the + Git alternates mechanism, otherwise the repo could be + considered corrupt by Git as it migh not be able to access the + objects in that packfile. See the `--filter-to=<dir>` option + of linkgit:git-repack[1] and the `objects/info/alternates` + section of linkgit:gitrepository-layout[5]. + gc.rerereResolved:: Records of conflicted merge you resolved earlier are kept for this many days when 'git rerere gc' is run. diff --git a/Documentation/config/gpg.txt b/Documentation/config/gpg.txt index 37e2831cd5..5cf32b179d 100644 --- a/Documentation/config/gpg.txt +++ b/Documentation/config/gpg.txt @@ -4,7 +4,7 @@ gpg.program:: same command-line interface as GPG, namely, to verify a detached signature, "`gpg --verify $signature - <$file`" is run, and the program is expected to signal a good signature by exiting with - code 0, and to generate an ASCII-armored detached signature, the + code 0. To generate an ASCII-armored detached signature, the standard input of "`gpg -bsau $key`" is fed with the contents to be signed, and the program is expected to send the result to its standard output. @@ -25,7 +25,7 @@ gpg.<format>.program:: gpg.minTrustLevel:: Specifies a minimum trust level for signature verification. If this option is unset, then signature verification for merge - operations require a key with at least `marginal` trust. Other + operations requires a key with at least `marginal` trust. Other operations that perform signature verification require a key with at least `undefined` trust. Setting this option overrides the required trust-level for all operations. Supported values, @@ -38,7 +38,7 @@ gpg.minTrustLevel:: * `ultimate` gpg.ssh.defaultKeyCommand:: - This command that will be run when user.signingkey is not set and a ssh + This command will be run when user.signingkey is not set and a ssh signature is requested. On successful exit a valid ssh public key prefixed with `key::` is expected in the first line of its output. This allows for a script doing a dynamic lookup of the correct public diff --git a/Documentation/config/gui.txt b/Documentation/config/gui.txt index 0c087fd8c9..171be774d2 100644 --- a/Documentation/config/gui.txt +++ b/Documentation/config/gui.txt @@ -24,7 +24,7 @@ gui.matchTrackingBranch:: not. Default: "false". gui.newBranchTemplate:: - Is used as suggested name when creating new branches using the + Is used as a suggested name when creating new branches using the linkgit:git-gui[1]. gui.pruneDuringFetch:: diff --git a/Documentation/config/http.txt b/Documentation/config/http.txt index 51a70781e5..2d4e0c9b86 100644 --- a/Documentation/config/http.txt +++ b/Documentation/config/http.txt @@ -254,13 +254,13 @@ http.lowSpeedLimit, http.lowSpeedTime:: http.noEPSV:: A boolean which disables using of EPSV ftp command by curl. - This can helpful with some "poor" ftp servers which don't + This can be helpful with some "poor" ftp servers which don't support EPSV mode. Can be overridden by the `GIT_CURL_FTP_NO_EPSV` environment variable. Default is false (curl will use EPSV). http.userAgent:: The HTTP USER_AGENT string presented to an HTTP server. The default - value represents the version of the client Git such as git/1.7.1. + value represents the version of the Git client such as git/1.7.1. This option allows you to override this value to a more common value such as Mozilla/4.0. This may be necessary, for instance, if connecting through a firewall that restricts HTTP connections to a set diff --git a/Documentation/config/i18n.txt b/Documentation/config/i18n.txt index cc25621731..6e72fdb45b 100644 --- a/Documentation/config/i18n.txt +++ b/Documentation/config/i18n.txt @@ -2,7 +2,7 @@ i18n.commitEncoding:: Character encoding the commit messages are stored in; Git itself does not care per se, but this information is necessary e.g. when importing commits from emails or in the gitk graphical history - browser (and possibly at other places in the future or in other + browser (and possibly in other places in the future or in other porcelains). See e.g. linkgit:git-mailinfo[1]. Defaults to 'utf-8'. i18n.logOutputEncoding:: diff --git a/Documentation/config/imap.txt b/Documentation/config/imap.txt index 06166fb5c0..3d28f72643 100644 --- a/Documentation/config/imap.txt +++ b/Documentation/config/imap.txt @@ -4,7 +4,7 @@ imap.folder:: "[Gmail]/Drafts". Required. imap.tunnel:: - Command used to setup a tunnel to the IMAP server through which + Command used to set up a tunnel to the IMAP server through which commands will be piped instead of using a direct network connection to the server. Required when imap.host is not set. @@ -37,7 +37,7 @@ imap.preformattedHTML:: format=fixed email. Default is `false`. imap.authMethod:: - Specify authenticate method for authentication with IMAP server. + Specify the authentication method for authenticating with the IMAP server. If Git was built with the NO_CURL option, or if your curl version is older than 7.34.0, or if you're running git-imap-send with the `--no-curl` option, the only supported method is 'CRAM-MD5'. If this is not set diff --git a/Documentation/config/index.txt b/Documentation/config/index.txt index 23c7985eb4..3eff420360 100644 --- a/Documentation/config/index.txt +++ b/Documentation/config/index.txt @@ -23,7 +23,7 @@ index.threads:: Specifies the number of threads to spawn when loading the index. This is meant to reduce index load time on multiprocessor machines. Specifying 0 or 'true' will cause Git to auto-detect the number of - CPU's and set the number of threads accordingly. Specifying 1 or + CPUs and set the number of threads accordingly. Specifying 1 or 'false' will disable multithreading. Defaults to 'true'. index.version:: diff --git a/Documentation/config/log.txt b/Documentation/config/log.txt index 5f96cf87fb..9003a82191 100644 --- a/Documentation/config/log.txt +++ b/Documentation/config/log.txt @@ -9,7 +9,7 @@ log.date:: `--date` option. See linkgit:git-log[1] for details. + If the format is set to "auto:foo" and the pager is in use, format -"foo" will be the used for the date format. Otherwise "default" will +"foo" will be used for the date format. Otherwise, "default" will be used. log.decorate:: diff --git a/Documentation/config/mailinfo.txt b/Documentation/config/mailinfo.txt index 3854d4ae37..ec3a5d81f7 100644 --- a/Documentation/config/mailinfo.txt +++ b/Documentation/config/mailinfo.txt @@ -1,6 +1,6 @@ mailinfo.scissors:: If true, makes linkgit:git-mailinfo[1] (and therefore linkgit:git-am[1]) act by default as if the --scissors option - was provided on the command-line. When active, this features + was provided on the command-line. When active, this feature removes everything from the message body before a scissors line (i.e. consisting mainly of ">8", "8<" and "-"). diff --git a/Documentation/config/maintenance.txt b/Documentation/config/maintenance.txt index 18f0562131..69a4f05153 100644 --- a/Documentation/config/maintenance.txt +++ b/Documentation/config/maintenance.txt @@ -12,7 +12,7 @@ maintenance.strategy:: then that value is used instead of the one provided by `maintenance.strategy`. The possible strategy strings are: + -* `none`: This default setting implies no task are run at any schedule. +* `none`: This default setting implies no tasks are run at any schedule. * `incremental`: This setting optimizes for performing small maintenance activities that do not delete any data. This does not schedule the `gc` task, but runs the `prefetch` and `commit-graph` tasks hourly, the diff --git a/Documentation/config/man.txt b/Documentation/config/man.txt index a727d987a8..5a0f82cc23 100644 --- a/Documentation/config/man.txt +++ b/Documentation/config/man.txt @@ -5,7 +5,7 @@ man.viewer:: man.<tool>.cmd:: Specify the command to invoke the specified man viewer. The specified command is evaluated in shell with the man page - passed as argument. (See linkgit:git-help[1].) + passed as an argument. (See linkgit:git-help[1].) man.<tool>.path:: Override the path for the given tool that may be used to diff --git a/Documentation/config/merge.txt b/Documentation/config/merge.txt index 99e83dd36e..8851b6cede 100644 --- a/Documentation/config/merge.txt +++ b/Documentation/config/merge.txt @@ -7,7 +7,7 @@ merge.conflictStyle:: marker and the original text before the `=======` marker. The "merge" style tends to produce smaller conflict regions than diff3, both because of the exclusion of the original text, and because - when a subset of lines match on the two sides they are just pulled + when a subset of lines match on the two sides, they are just pulled out of the conflict region. Another alternate style, "zdiff3", is similar to diff3 but removes matching lines on the two sides from the conflict region when those matching lines appear near either diff --git a/Documentation/config/mergetool.txt b/Documentation/config/mergetool.txt index 56a7eeeffb..294f61efd1 100644 --- a/Documentation/config/mergetool.txt +++ b/Documentation/config/mergetool.txt @@ -22,8 +22,8 @@ mergetool.<tool>.trustExitCode:: For a custom merge command, specify whether the exit code of the merge command can be used to determine whether the merge was successful. If this is not set to true then the merge target file - timestamp is checked and the merge assumed to have been successful - if the file has been updated, otherwise the user is prompted to + timestamp is checked, and the merge is assumed to have been successful + if the file has been updated; otherwise, the user is prompted to indicate the success of the merge. mergetool.meld.hasOutput:: @@ -37,7 +37,7 @@ mergetool.meld.hasOutput:: mergetool.meld.useAutoMerge:: When the `--auto-merge` is given, meld will merge all non-conflicting - parts automatically, highlight the conflicting parts and wait for + parts automatically, highlight the conflicting parts, and wait for user decision. Setting `mergetool.meld.useAutoMerge` to `true` tells Git to unconditionally use the `--auto-merge` option with `meld`. Setting this value to `auto` makes git detect whether `--auto-merge` @@ -47,7 +47,7 @@ mergetool.meld.useAutoMerge:: mergetool.vimdiff.layout:: The vimdiff backend uses this variable to control how its split - windows look like. Applies even if you are using Neovim (`nvim`) or + windows appear. Applies even if you are using Neovim (`nvim`) or gVim (`gvim`) as the merge tool. See BACKEND SPECIFIC HINTS section ifndef::git-mergetool[] in linkgit:git-mergetool[1]. @@ -55,7 +55,7 @@ endif::[] for details. mergetool.hideResolved:: - During a merge Git will automatically resolve as many conflicts as + During a merge, Git will automatically resolve as many conflicts as possible and write the 'MERGED' file containing conflict markers around any conflicts that it cannot resolve; 'LOCAL' and 'REMOTE' normally represent the versions of the file from before Git's conflict @@ -74,7 +74,7 @@ mergetool.keepTemporaries:: When invoking a custom merge tool, Git uses a set of temporary files to pass to the tool. If the tool returns an error and this variable is set to `true`, then these temporary files will be - preserved, otherwise they will be removed after the tool has + preserved; otherwise, they will be removed after the tool has exited. Defaults to `false`. mergetool.writeToTemp:: diff --git a/Documentation/config/notes.txt b/Documentation/config/notes.txt index c7c4811734..43db8e808d 100644 --- a/Documentation/config/notes.txt +++ b/Documentation/config/notes.txt @@ -1,7 +1,7 @@ notes.mergeStrategy:: Which merge strategy to choose by default when resolving notes conflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or - `cat_sort_uniq`. Defaults to `manual`. See "NOTES MERGE STRATEGIES" + `cat_sort_uniq`. Defaults to `manual`. See the "NOTES MERGE STRATEGIES" section of linkgit:git-notes[1] for more information on each strategy. + This setting can be overridden by passing the `--strategy` option to diff --git a/Documentation/config/pack.txt b/Documentation/config/pack.txt index d4c7c9d4e4..f50df9dbce 100644 --- a/Documentation/config/pack.txt +++ b/Documentation/config/pack.txt @@ -74,7 +74,7 @@ pack.threads:: warning. This is meant to reduce packing time on multiprocessor machines. The required amount of memory for the delta search window is however multiplied by the number of threads. - Specifying 0 will cause Git to auto-detect the number of CPU's + Specifying 0 will cause Git to auto-detect the number of CPUs and set the number of threads accordingly. pack.indexVersion:: @@ -83,11 +83,11 @@ pack.indexVersion:: the new pack index with capabilities for packs larger than 4 GB as well as proper protection against the repacking of corrupted packs. Version 2 is the default. Note that version 2 is enforced - and this config option ignored whenever the corresponding pack is + and this config option is ignored whenever the corresponding pack is larger than 2 GB. + If you have an old Git that does not understand the version 2 `*.idx` file, -cloning or fetching over a non native protocol (e.g. "http") +cloning or fetching over a non-native protocol (e.g. "http") that will copy both `*.pack` file and corresponding `*.idx` file from the other side may give you a repository that cannot be accessed with your older version of Git. If the `*.pack` file is smaller than 2 GB, however, @@ -102,8 +102,8 @@ pack.packSizeLimit:: in the creation of multiple packfiles. + Note that this option is rarely useful, and may result in a larger total -on-disk size (because Git will not store deltas between packs), as well -as worse runtime performance (object lookup within multiple packs is +on-disk size (because Git will not store deltas between packs) and +worse runtime performance (object lookup within multiple packs is slower than a single pack, and optimizations like reachability bitmaps cannot cope with multiple packs). + @@ -123,6 +123,23 @@ pack.useBitmaps:: true. You should not generally need to turn this off unless you are debugging pack bitmaps. +pack.useBitmapBoundaryTraversal:: + When true, Git will use an experimental algorithm for computing + reachability queries with bitmaps. Instead of building up + complete bitmaps for all of the negated tips and then OR-ing + them together, consider negated tips with existing bitmaps as + additive (i.e. OR-ing them into the result if they exist, + ignoring them otherwise), and build up a bitmap at the boundary + instead. ++ +When using this algorithm, Git may include too many objects as a result +of not opening up trees belonging to certain UNINTERESTING commits. This +inexactness matches the non-bitmap traversal algorithm. ++ +In many cases, this can provide a speed-up over the exact algorithm, +particularly when there is poor bitmap coverage of the negated side of +the query. + pack.useSparse:: When true, git will default to using the '--sparse' option in 'git pack-objects' when the '--revs' option is present. This diff --git a/Documentation/config/push.txt b/Documentation/config/push.txt index 43338b65e8..0acbbea18a 100644 --- a/Documentation/config/push.txt +++ b/Documentation/config/push.txt @@ -35,7 +35,7 @@ push.default:: * `tracking` - This is a deprecated synonym for `upstream`. -* `simple` - pushes the current branch with the same name on the remote. +* `simple` - push the current branch with the same name on the remote. + If you are working on a centralized workflow (pushing to the same repository you pull from, which is typically `origin`), then you need to configure an upstream @@ -67,7 +67,7 @@ new default). -- push.followTags:: - If set to true enable `--follow-tags` option by default. You + If set to true, enable `--follow-tags` option by default. You may override this configuration at time of push by specifying `--no-follow-tags`. diff --git a/Documentation/config/rebase.txt b/Documentation/config/rebase.txt index afaf6dad99..d59576dbb2 100644 --- a/Documentation/config/rebase.txt +++ b/Documentation/config/rebase.txt @@ -9,7 +9,9 @@ rebase.stat:: rebase. False by default. rebase.autoSquash:: - If set to true enable `--autosquash` option by default. + If set to true, enable the `--autosquash` option of + linkgit:git-rebase[1] by default for interactive mode. + This can be overridden with the `--no-autosquash` option. rebase.autoStash:: When set to true, automatically create a temporary stash entry @@ -77,3 +79,9 @@ rebase.rebaseMerges:: equivalent to `--no-rebase-merges`. Passing `--rebase-merges` on the command line, with or without an argument, overrides any `rebase.rebaseMerges` configuration. + +rebase.maxLabelLength:: + When generating label names from commit subjects, truncate the names to + this length. By default, the names are truncated to a little less than + `NAME_MAX` (to allow e.g. `.lock` files to be written for the + corresponding loose refs). diff --git a/Documentation/config/receive.txt b/Documentation/config/receive.txt index 85d5b5a3d2..c77e55b1cd 100644 --- a/Documentation/config/receive.txt +++ b/Documentation/config/receive.txt @@ -14,12 +14,12 @@ receive.autogc:: receive.certNonceSeed:: By setting this variable to a string, `git receive-pack` - will accept a `git push --signed` and verifies it by using + will accept a `git push --signed` and verify it by using a "nonce" protected by HMAC using this string as a secret key. receive.certNonceSlop:: - When a `git push --signed` sent a push certificate with a + When a `git push --signed` sends a push certificate with a "nonce" that was issued by a receive-pack serving the same repository within this many seconds, export the "nonce" found in the certificate to `GIT_PUSH_CERT_NONCE` to the diff --git a/Documentation/config/rerere.txt b/Documentation/config/rerere.txt index 40abdf6a6b..3a78b5ebb1 100644 --- a/Documentation/config/rerere.txt +++ b/Documentation/config/rerere.txt @@ -1,7 +1,7 @@ rerere.autoUpdate:: When set to true, `git-rerere` updates the index with the resulting contents after it cleanly resolves conflicts using - previously recorded resolution. Defaults to false. + previously recorded resolutions. Defaults to false. rerere.enabled:: Activate recording of resolved conflicts, so that identical diff --git a/Documentation/config/safe.txt b/Documentation/config/safe.txt index bde7f31459..577df40223 100644 --- a/Documentation/config/safe.txt +++ b/Documentation/config/safe.txt @@ -14,7 +14,7 @@ repository that contains a bare repository and running a Git command within that directory. + This config setting is only respected in protected configuration (see -<<SCOPES>>). This prevents the untrusted repository from tampering with +<<SCOPES>>). This prevents untrusted repositories from tampering with this value. safe.directory:: @@ -32,7 +32,7 @@ override any such directories specified in the system config), add a `safe.directory` entry with an empty value. + This config setting is only respected in protected configuration (see -<<SCOPES>>). This prevents the untrusted repository from tampering with this +<<SCOPES>>). This prevents untrusted repositories from tampering with this value. + The value of this setting is interpolated, i.e. `~/<path>` expands to a diff --git a/Documentation/config/sendemail.txt b/Documentation/config/sendemail.txt index 92a9ebe98c..7fc770ee9e 100644 --- a/Documentation/config/sendemail.txt +++ b/Documentation/config/sendemail.txt @@ -36,7 +36,7 @@ sendemail.aliasesFile:: sendemail.aliasFileType:: Format of the file(s) specified in sendemail.aliasesFile. Must be - one of 'mutt', 'mailrc', 'pine', 'elm', or 'gnus', or 'sendmail'. + one of 'mutt', 'mailrc', 'pine', 'elm', 'gnus', or 'sendmail'. + What an alias file in each format looks like can be found in the documentation of the email program of the same name. The @@ -91,7 +91,7 @@ sendemail.smtpBatchSize:: See also the `--batch-size` option of linkgit:git-send-email[1]. sendemail.smtpReloginDelay:: - Seconds wait before reconnecting to smtp server. + Seconds to wait before reconnecting to the smtp server. See also the `--relogin-delay` option of linkgit:git-send-email[1]. sendemail.forbidSendmailVariables:: diff --git a/Documentation/config/sequencer.txt b/Documentation/config/sequencer.txt index b48d532a96..e664eef01d 100644 --- a/Documentation/config/sequencer.txt +++ b/Documentation/config/sequencer.txt @@ -2,4 +2,4 @@ sequence.editor:: Text editor used by `git rebase -i` for editing the rebase instruction file. The value is meant to be interpreted by the shell when it is used. It can be overridden by the `GIT_SEQUENCE_EDITOR` environment variable. - When not configured the default commit message editor is used instead. + When not configured, the default commit message editor is used instead. diff --git a/Documentation/config/splitindex.txt b/Documentation/config/splitindex.txt index afdb186df8..cfaa29610b 100644 --- a/Documentation/config/splitindex.txt +++ b/Documentation/config/splitindex.txt @@ -3,10 +3,10 @@ splitIndex.maxPercentChange:: percent of entries the split index can contain compared to the total number of entries in both the split index and the shared index before a new shared index is written. - The value should be between 0 and 100. If the value is 0 then - a new shared index is always written, if it is 100 a new + The value should be between 0 and 100. If the value is 0, then + a new shared index is always written; if it is 100, a new shared index is never written. - By default the value is 20, so a new shared index is written + By default, the value is 20, so a new shared index is written if the number of entries in the split index would be greater than 20 percent of the total number of entries. See linkgit:git-update-index[1]. diff --git a/Documentation/config/stash.txt b/Documentation/config/stash.txt index b9f609ed76..ec1edaeba6 100644 --- a/Documentation/config/stash.txt +++ b/Documentation/config/stash.txt @@ -1,14 +1,14 @@ stash.showIncludeUntracked:: If this is set to true, the `git stash show` command will show the untracked files of a stash entry. Defaults to false. See - description of 'show' command in linkgit:git-stash[1]. + the description of the 'show' command in linkgit:git-stash[1]. stash.showPatch:: If this is set to true, the `git stash show` command without an option will show the stash entry in patch form. Defaults to false. - See description of 'show' command in linkgit:git-stash[1]. + See the description of the 'show' command in linkgit:git-stash[1]. stash.showStat:: If this is set to true, the `git stash show` command without an - option will show diffstat of the stash entry. Defaults to true. - See description of 'show' command in linkgit:git-stash[1]. + option will show a diffstat of the stash entry. Defaults to true. + See the description of the 'show' command in linkgit:git-stash[1]. diff --git a/Documentation/config/status.txt b/Documentation/config/status.txt index 0fc704ab80..2ff8237f8f 100644 --- a/Documentation/config/status.txt +++ b/Documentation/config/status.txt @@ -47,7 +47,7 @@ status.showUntrackedFiles:: contain only untracked files, are shown with the directory name only. Showing untracked files means that Git needs to lstat() all the files in the whole repository, which might be slow on some - systems. So, this variable controls how the commands displays + systems. So, this variable controls how the commands display the untracked files. Possible values are: + -- @@ -62,7 +62,7 @@ of linkgit:git-status[1] and linkgit:git-commit[1]. status.submoduleSummary:: Defaults to false. - If this is set to a non zero number or true (identical to -1 or an + If this is set to a non-zero number or true (identical to -1 or an unlimited number), the submodule summary will be enabled and a summary of commits for modified submodules will be shown (see --summary-limit option of linkgit:git-submodule[1]). Please note diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt index 6490527b45..0672d99117 100644 --- a/Documentation/config/submodule.txt +++ b/Documentation/config/submodule.txt @@ -2,7 +2,7 @@ submodule.<name>.url:: The URL for a submodule. This variable is copied from the .gitmodules file to the git config via 'git submodule init'. The user can change the configured URL before obtaining the submodule via 'git submodule - update'. If neither submodule.<name>.active or submodule.active are + update'. If neither submodule.<name>.active nor submodule.active are set, the presence of this variable is used as a fallback to indicate whether the submodule is of interest to git commands. See linkgit:git-submodule[1] and linkgit:gitmodules[5] for details. @@ -35,7 +35,7 @@ submodule.<name>.ignore:: a submodule as modified. When set to "all", it will never be considered modified (but it will nonetheless show up in the output of status and commit when it has been staged), "dirty" will ignore all changes - to the submodules work tree and + to the submodule's work tree and takes only differences between the HEAD of the submodule and the commit recorded in the superproject into account. "untracked" will additionally let submodules with modified tracked files in their work tree show up. diff --git a/Documentation/config/trace2.txt b/Documentation/config/trace2.txt index fe1642f0d4..3b6bca2b7a 100644 --- a/Documentation/config/trace2.txt +++ b/Documentation/config/trace2.txt @@ -66,6 +66,6 @@ trace2.destinationDebug:: trace2.maxFiles:: Integer. When writing trace files to a target directory, do not - write additional traces if we would exceed this many files. Instead, + write additional traces if doing so would exceed this many files. Instead, write a sentinel file that will block further tracing to this directory. Defaults to 0, which disables this check. diff --git a/Documentation/config/transfer.txt b/Documentation/config/transfer.txt index c3ac767d1e..a9cbdb88a1 100644 --- a/Documentation/config/transfer.txt +++ b/Documentation/config/transfer.txt @@ -7,7 +7,7 @@ transfer.credentialsInUrl:: and any other direct use of the configured URL. + Note that this is currently limited to detecting credentials in -`remote.<name>.url` configuration, it won't detect credentials in +`remote.<name>.url` configuration; it won't detect credentials in `remote.<name>.pushurl` configuration. + You might want to enable this to prevent inadvertent credentials @@ -21,12 +21,12 @@ exposure, e.g. because: system. * The git programs will pass the full URL to one another as arguments on the command-line, meaning the credentials will be exposed to other - users on OS's or systems that allow other users to see the full + unprivileged users on systems that allow them to see the full process list of other users. On linux the "hidepid" setting documented in procfs(5) allows for configuring this behavior. + If such concerns don't apply to you then you probably don't need to be -concerned about credentials exposure due to storing that sensitive +concerned about credentials exposure due to storing sensitive data in git's configuration files. If you do want to use this, set `transfer.credentialsInUrl` to one of these values: + diff --git a/Documentation/config/user.txt b/Documentation/config/user.txt index ec9233b060..2ffc38d164 100644 --- a/Documentation/config/user.txt +++ b/Documentation/config/user.txt @@ -5,14 +5,14 @@ author.email:: committer.name:: committer.email:: The `user.name` and `user.email` variables determine what ends - up in the `author` and `committer` field of commit + up in the `author` and `committer` fields of commit objects. If you need the `author` or `committer` to be different, the - `author.name`, `author.email`, `committer.name` or + `author.name`, `author.email`, `committer.name`, or `committer.email` variables can be set. - Also, all of these can be overridden by the `GIT_AUTHOR_NAME`, + All of these can be overridden by the `GIT_AUTHOR_NAME`, `GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME`, - `GIT_COMMITTER_EMAIL` and `EMAIL` environment variables. + `GIT_COMMITTER_EMAIL`, and `EMAIL` environment variables. + Note that the `name` forms of these variables conventionally refer to some form of a personal name. See linkgit:git-commit[1] and the @@ -40,7 +40,7 @@ user.signingKey:: your private ssh key or the public key when ssh-agent is used. Alternatively it can contain a public key prefixed with `key::` directly (e.g.: "key::ssh-rsa XXXXXX identifier"). The private key - needs to be available via ssh-agent. If not set git will call + needs to be available via ssh-agent. If not set Git will call gpg.ssh.defaultKeyCommand (e.g.: "ssh-add -L") and try to use the first key available. For backward compatibility, a raw key which begins with "ssh-", such as "ssh-rsa XXXXXX identifier", is treated diff --git a/Documentation/config/versionsort.txt b/Documentation/config/versionsort.txt index 6c7cc054fa..0cff090819 100644 --- a/Documentation/config/versionsort.txt +++ b/Documentation/config/versionsort.txt @@ -19,14 +19,14 @@ with those suffixes. E.g. if "-pre" appears before "-rc" in the configuration, then all "1.0-preX" tags will be listed before any "1.0-rcX" tags. The placement of the main release tag relative to tags with various suffixes can be determined by specifying the empty suffix -among those other suffixes. E.g. if the suffixes "-rc", "", "-ck" and +among those other suffixes. E.g. if the suffixes "-rc", "", "-ck", and "-bfs" appear in the configuration in this order, then all "v4.8-rcX" tags are listed first, followed by "v4.8", then "v4.8-ckX" and finally "v4.8-bfsX". + -If more than one suffixes match the same tagname, then that tagname will +If more than one suffix matches the same tagname, then that tagname will be sorted according to the suffix which starts at the earliest position in -the tagname. If more than one different matching suffixes start at +the tagname. If more than one different matching suffix starts at that earliest position, then that tagname will be sorted according to the longest of those suffixes. The sorting order between different suffixes is undefined if they are diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt index 546adf79e5..4b5aa5c2e0 100644 --- a/Documentation/diff-generate-patch.txt +++ b/Documentation/diff-generate-patch.txt @@ -17,7 +17,7 @@ You can customize the creation of patch text via the What the -p option produces is slightly different from the traditional diff format: -1. It is preceded with a "git diff" header that looks like this: +1. It is preceded by a "git diff" header that looks like this: diff --git a/file1 b/file2 + @@ -25,9 +25,9 @@ The `a/` and `b/` filenames are the same unless rename/copy is involved. Especially, even for a creation or a deletion, `/dev/null` is _not_ used in place of the `a/` or `b/` filenames. + -When rename/copy is involved, `file1` and `file2` show the +When a rename/copy is involved, `file1` and `file2` show the name of the source file of the rename/copy and the name of -the file that rename/copy produces, respectively. +the file that the rename/copy produces, respectively. 2. It is followed by one or more extended header lines: @@ -77,7 +77,7 @@ separate lines indicate the old and the new mode. 5. Hunk headers mention the name of the function to which the hunk applies. See "Defining a custom hunk-header" in - linkgit:gitattributes[5] for details of how to tailor to this to + linkgit:gitattributes[5] for details of how to tailor this to specific languages. @@ -89,7 +89,7 @@ produce a 'combined diff' when showing a merge. This is the default format when showing merges with linkgit:git-diff[1] or linkgit:git-show[1]. Note also that you can give suitable `--diff-merges` option to any of these commands to force generation of -diffs in specific format. +diffs in a specific format. A "combined diff" format looks like this: @@ -123,7 +123,7 @@ index fabadb8,cc95eb0..4866510 for_each_ref(get_name); ------------ -1. It is preceded with a "git diff" header, that looks like +1. It is preceded by a "git diff" header, that looks like this (when the `-c` option is used): diff --combined file @@ -142,22 +142,22 @@ or like this (when the `--cc` option is used): + The `mode <mode>,<mode>..<mode>` line appears only if at least one of the <mode> is different from the rest. Extended headers with -information about detected contents movement (renames and -copying detection) are designed to work with diff of two +information about detected content movement (renames and +copying detection) are designed to work with the diff of two <tree-ish> and are not used by combined diff format. -3. It is followed by two-line from-file/to-file header +3. It is followed by a two-line from-file/to-file header: --- a/file +++ b/file + -Similar to two-line header for traditional 'unified' diff +Similar to the two-line header for the traditional 'unified' diff format, `/dev/null` is used to signal created or deleted files. + However, if the --combined-all-paths option is provided, instead of a -two-line from-file/to-file you get a N+1 line from-file/to-file header, -where N is the number of parents in the merge commit +two-line from-file/to-file, you get an N+1 line from-file/to-file header, +where N is the number of parents in the merge commit: --- a/file --- a/file @@ -197,7 +197,7 @@ added, from the point of view of that parent). In the above example output, the function signature was changed from both files (hence two `-` removals from both file1 and file2, plus `++` to mean one line that was added does not appear -in either file1 or file2). Also eight other lines are the same +in either file1 or file2). Also, eight other lines are the same from file1 but do not appear in file2 (hence prefixed with `+`). When shown by `git diff-tree -c`, it compares the parents of a diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 08ab86189a..53ec3c9a34 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -22,84 +22,94 @@ ifndef::git-format-patch[] -p:: -u:: --patch:: - Generate patch (see section titled -ifdef::git-log[] -<<generate_patch_text_with_p, "Generating patch text with -p">>). -endif::git-log[] -ifndef::git-log[] -"Generating patch text with -p"). -endif::git-log[] + Generate patch (see <<generate_patch_text_with_p>>). ifdef::git-diff[] This is the default. endif::git-diff[] -s:: --no-patch:: - Suppress diff output. Useful for commands like `git show` that - show the patch by default, or to cancel the effect of `--patch`. + Suppress all output from the diff machinery. Useful for + commands like `git show` that show the patch by default to + squelch their output, or to cancel the effect of options like + `--patch`, `--stat` earlier on the command line in an alias. + endif::git-format-patch[] ifdef::git-log[] ---diff-merges=(off|none|on|first-parent|1|separate|m|combined|c|dense-combined|cc|remerge|r):: +-m:: + Show diffs for merge commits in the default format. This is + similar to '--diff-merges=on', except `-m` will + produce no output unless `-p` is given as well. + +-c:: + Produce combined diff output for merge commits. + Shortcut for '--diff-merges=combined -p'. + +--cc:: + Produce dense combined diff output for merge commits. + Shortcut for '--diff-merges=dense-combined -p'. + +--dd:: + Produce diff with respect to first parent for both merge and + regular commits. + Shortcut for '--diff-merges=first-parent -p'. + +--remerge-diff:: + Produce remerge-diff output for merge commits. + Shortcut for '--diff-merges=remerge -p'. + --no-diff-merges:: + Synonym for '--diff-merges=off'. + +--diff-merges=<format>:: Specify diff format to be used for merge commits. Default is - {diff-merges-default} unless `--first-parent` is in use, in which case - `first-parent` is the default. + {diff-merges-default} unless `--first-parent` is in use, in + which case `first-parent` is the default. + ---diff-merges=(off|none)::: ---no-diff-merges::: +The following formats are supported: ++ +-- +off, none:: Disable output of diffs for merge commits. Useful to override implied value. + ---diff-merges=on::: ---diff-merges=m::: --m::: - This option makes diff output for merge commits to be shown in - the default format. `-m` will produce the output only if `-p` - is given as well. The default format could be changed using - `log.diffMerges` configuration parameter, which default value +on, m:: + Make diff output for merge commits to be shown in the default + format. The default format can be changed using + `log.diffMerges` configuration variable, whose default value is `separate`. + ---diff-merges=first-parent::: ---diff-merges=1::: - This option makes merge commits show the full diff with - respect to the first parent only. +first-parent, 1:: + Show full diff with respect to first parent. This is the same + format as `--patch` produces for non-merge commits. + ---diff-merges=separate::: - This makes merge commits show the full diff with respect to - each of the parents. Separate log entry and diff is generated - for each parent. +separate:: + Show full diff with respect to each of parents. + Separate log entry and diff is generated for each parent. + ---diff-merges=remerge::: ---diff-merges=r::: ---remerge-diff::: - With this option, two-parent merge commits are remerged to - create a temporary tree object -- potentially containing files - with conflict markers and such. A diff is then shown between - that temporary tree and the actual merge commit. +combined, c:: + Show differences from each of the parents to the merge + result simultaneously instead of showing pairwise diff between + a parent and the result one at a time. Furthermore, it lists + only files which were modified from all parents. ++ +dense-combined, cc:: + Further compress output produced by `--diff-merges=combined` + by omitting uninteresting hunks whose contents in the parents + have only two variants and the merge result picks one of them + without modification. ++ +remerge, r:: + Remerge two-parent merge commits to create a temporary tree + object--potentially containing files with conflict markers + and such. A diff is then shown between that temporary tree + and the actual merge commit. + The output emitted when this option is used is subject to change, and so is its interaction with other options (unless explicitly documented). -+ ---diff-merges=combined::: ---diff-merges=c::: --c::: - With this option, diff output for a merge commit shows the - differences from each of the parents to the merge result - simultaneously instead of showing pairwise diff between a - parent and the result one at a time. Furthermore, it lists - only files which were modified from all parents. `-c` implies - `-p`. -+ ---diff-merges=dense-combined::: ---diff-merges=cc::: ---cc::: - With this option the output produced by - `--diff-merges=combined` is further compressed by omitting - uninteresting hunks whose contents in the parents have only - two variants and the merge result picks one of them without - modification. `--cc` implies `-p`. +-- --combined-all-paths:: This flag causes combined diffs (used for merge commits) to @@ -207,14 +217,15 @@ have to use `--diff-algorithm=default` option. part. Maximum width defaults to terminal width, or 80 columns if not connected to a terminal, and can be overridden by `<width>`. The width of the filename part can be limited by - giving another width `<name-width>` after a comma. The width - of the graph part can be limited by using - `--stat-graph-width=<width>` (affects all commands generating - a stat graph) or by setting `diff.statGraphWidth=<width>` - (does not affect `git format-patch`). - By giving a third parameter `<count>`, you can limit the - output to the first `<count>` lines, followed by `...` if - there are more. + giving another width `<name-width>` after a comma or by setting + `diff.statNameWidth=<width>`. The width of the graph part can be + limited by using `--stat-graph-width=<width>` or by setting + `diff.statGraphWidth=<width>`. Using `--stat` or + `--stat-graph-width` affects all commands generating a stat graph, + while setting `diff.statNameWidth` or `diff.statGraphWidth` + does not affect `git format-patch`. + By giving a third parameter `<count>`, you can limit the output to + the first `<count>` lines, followed by `...` if there are more. + These parameters can also be set individually with `--stat-width=<width>`, `--stat-name-width=<name-width>` and `--stat-count=<count>`. @@ -303,7 +314,7 @@ ifndef::git-format-patch[] -z:: ifdef::git-log[] - Separate the commits with NULs instead of with new newlines. + Separate the commits with NULs instead of newlines. + Also, when `--raw` or `--numstat` has been given, do not munge pathnames and use NULs as output field terminators. @@ -735,7 +746,7 @@ matches "`fooasdfbar`" and "`foo/bar/baz/asdf`" but not "`foobarx`". --rotate-to=<file>:: Discard the files before the named <file> from the output (i.e. 'skip to'), or move them to the end of the output - (i.e. 'rotate to'). These were invented primarily for use + (i.e. 'rotate to'). These options were invented primarily for the use of the `git difftool` command, and may not be very useful otherwise. diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index 41fc7ca3c6..a1d6633a4f 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -43,7 +43,7 @@ the current repository has the same history as the source repository. --update-shallow:: By default when fetching from a shallow repository, `git fetch` refuses refs that require updating - .git/shallow. This option updates .git/shallow and accept such + .git/shallow. This option updates .git/shallow and accepts such refs. --negotiation-tip=<commit|glob>:: @@ -96,7 +96,7 @@ endif::git-pull[] -f:: --force:: - When 'git fetch' is used with `<src>:<dst>` refspec it may + When 'git fetch' is used with `<src>:<dst>` refspec, it may refuse to update the local branch as discussed ifdef::git-pull[] in the `<refspec>` part of the linkgit:git-fetch[1] diff --git a/Documentation/fsck-msgids.txt b/Documentation/fsck-msgids.txt index 12eae8a222..f643585a34 100644 --- a/Documentation/fsck-msgids.txt +++ b/Documentation/fsck-msgids.txt @@ -103,6 +103,13 @@ `hasDotgit`:: (WARN) A tree contains an entry named `.git`. +`largePathname`:: + (WARN) A tree contains an entry with a very long path name. If + the value of `fsck.largePathname` contains a colon, that value + is used as the maximum allowable length (e.g., "warn:10" would + complain about any path component of 11 or more bytes). The + default value is 4096. + `mailmapSymlink`:: (INFO) `.mailmap` is a symlink. @@ -125,7 +132,7 @@ (ERROR) Missing space before date in an author/committer line. `missingSpaceBeforeEmail`:: - (ERROR) Missing space before the email in author/committer line. + (ERROR) Missing space before the email in an author/committer line. `missingTag`:: (ERROR) Unexpected end after `type` line in a tag object. @@ -167,7 +174,7 @@ (FATAL) Missing end-of-line in the object header. `zeroPaddedDate`:: - (ERROR) Found a zero padded date in an author/commiter line. + (ERROR) Found a zero padded date in an author/committer line. `zeroPaddedFilemode`:: (WARN) Found a zero padded filemode in a tree. diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index ed44c1cb31..3d2e670716 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git add' [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [--patch | -p] - [--edit | -e] [--[no-]all | --[no-]ignore-removal | [--update | -u]] [--sparse] + [--edit | -e] [--[no-]all | -A | --[no-]ignore-removal | [--update | -u]] [--sparse] [--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing] [--renormalize] [--chmod=(+|-)x] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...] diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 900be198b1..e080458d6c 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -12,7 +12,7 @@ SYNOPSIS 'git am' [--signoff] [--keep] [--[no-]keep-cr] [--[no-]utf8] [--no-verify] [--[no-]3way] [--interactive] [--committer-date-is-author-date] [--ignore-date] [--ignore-space-change | --ignore-whitespace] - [--whitespace=<option>] [-C<n>] [-p<n>] [--directory=<dir>] + [--whitespace=<action>] [-C<n>] [-p<n>] [--directory=<dir>] [--exclude=<path>] [--include=<path>] [--reject] [-q | --quiet] [--[no-]scissors] [-S[<keyid>]] [--patch-format=<format>] [--quoted-cr=<action>] @@ -22,8 +22,8 @@ SYNOPSIS DESCRIPTION ----------- -Splits mail messages in a mailbox into commit log message, -authorship information and patches, and applies them to the +Splits mail messages in a mailbox into commit log messages, +authorship information, and patches, and applies them to the current branch. You could think of it as a reverse operation of linkgit:git-format-patch[1] run on a branch with a straight history without merges. @@ -69,7 +69,7 @@ OPTIONS --empty=(stop|drop|keep):: By default, or when the option is set to 'stop', the command errors out on an input e-mail message lacking a patch - and stops into the middle of the current am session. When this + and stops in the middle of the current am session. When this option is set to 'drop', skip such an e-mail message instead. When this option is set to 'keep', create an empty commit, recording the contents of the e-mail message as its log. @@ -94,7 +94,7 @@ OPTIONS Pass `-u` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]). The proposed commit log message taken from the e-mail is re-coded into UTF-8 encoding (configuration variable - `i18n.commitEncoding` can be used to specify project's + `i18n.commitEncoding` can be used to specify the project's preferred encoding if it is not UTF-8). + This was optional in prior versions of git, but now it is the @@ -118,7 +118,7 @@ include::rerere-options.txt[] --ignore-space-change:: --ignore-whitespace:: ---whitespace=<option>:: +--whitespace=<action>:: -C<n>:: -p<n>:: --directory=<dir>:: @@ -134,7 +134,7 @@ include::rerere-options.txt[] automatically. This option allows the user to bypass the automatic detection and specify the patch format that the patch(es) should be interpreted as. Valid formats are mbox, mboxrd, - stgit, stgit-series and hg. + stgit, stgit-series, and hg. -i:: --interactive:: @@ -192,7 +192,7 @@ include::rerere-options.txt[] --abort:: Restore the original branch and abort the patching operation. - Revert contents of files involved in the am operation to their + Revert the contents of files involved in the am operation to their pre-am state. --quit:: diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt index 5e16e6db7e..9cce68a38b 100644 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@ -23,8 +23,8 @@ DESCRIPTION Reads the supplied diff output (i.e. "a patch") and applies it to files. When running from a subdirectory in a repository, patched paths outside the directory are ignored. -With the `--index` option the patch is also applied to the index, and -with the `--cached` option the patch is only applied to the index. +With the `--index` option, the patch is also applied to the index, and +with the `--cached` option, the patch is only applied to the index. Without these options, the command applies the patch only to files, and does not require them to be in a Git repository. @@ -52,7 +52,7 @@ OPTIONS --summary:: Instead of applying the patch, output a condensed summary of information obtained from git diff extended - headers, such as creations, renames and mode changes. + headers, such as creations, renames, and mode changes. Turns off "apply". --check:: @@ -140,7 +140,7 @@ linkgit:git-config[1]). applying a diff generated with `--unified=0`. To bypass these checks use `--unidiff-zero`. + -Note, for the reasons stated above usage of context-free patches is +Note, for the reasons stated above, the usage of context-free patches is discouraged. --apply:: @@ -159,9 +159,9 @@ discouraged. --allow-binary-replacement:: --binary:: - Historically we did not allow binary patch applied + Historically we did not allow binary patch application without an explicit permission from the user, and this - flag was the way to do so. Currently we always allow binary + flag was the way to do so. Currently, we always allow binary patch application, so this is a no-op. --exclude=<path-pattern>:: @@ -257,7 +257,7 @@ the `--unsafe-paths` option to override this safety check. This option has no effect when `--index` or `--cached` is in use. --allow-empty:: - Don't return error for patches containing no diff. This includes + Don't return an error for patches containing no diff. This includes empty patches and patches with commit text only. CONFIGURATION diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt index 6bab201d37..98526f2beb 100644 --- a/Documentation/git-archive.txt +++ b/Documentation/git-archive.txt @@ -21,14 +21,14 @@ structure for the named tree, and writes it out to the standard output. If <prefix> is specified it is prepended to the filenames in the archive. -'git archive' behaves differently when given a tree ID versus when -given a commit ID or tag ID. In the first case the current time is -used as the modification time of each file in the archive. In the latter -case the commit time as recorded in the referenced commit object is -used instead. Additionally the commit ID is stored in a global -extended pax header if the tar format is used; it can be extracted -using 'git get-tar-commit-id'. In ZIP files it is stored as a file -comment. +'git archive' behaves differently when given a tree ID as opposed to a +commit ID or tag ID. When a tree ID is provided, the current time is +used as the modification time of each file in the archive. On the +other hand, when a commit ID or tag ID is provided, the commit time as +recorded in the referenced commit object is used instead. +Additionally the commit ID is stored in a global extended pax header +if the tar format is used; it can be extracted using 'git +get-tar-commit-id'. In ZIP files it is stored as a file comment. OPTIONS ------- diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index fbb39fbdf5..aa02e46224 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-{new,bad}=<term> --term-{old,good}=<term>] + git bisect start [--term-(new|bad)=<term-new> --term-(old|good)=<term-old>] [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<paths>...] git bisect (bad|new|<term-new>) [<rev>] git bisect (good|old|<term-old>) [<rev>...] @@ -26,7 +26,7 @@ on the subcommand: git bisect (visualize|view) git bisect replay <logfile> git bisect log - git bisect run <cmd>... + git bisect run <cmd> [<arg>...] git bisect help This command uses a binary search algorithm to find which commit in @@ -204,9 +204,14 @@ as an alternative to `visualize`): $ git bisect visualize ------------ -If the `DISPLAY` environment variable is not set, 'git log' is used -instead. You can also give command-line options such as `-p` and -`--stat`. +Git detects a graphical environment through various environment variables: +`DISPLAY`, which is set in X Window System environments on Unix systems. +`SESSIONNAME`, which is set under Cygwin in interactive desktop sessions. +`MSYSTEM`, which is set under Msys2 and Git for Windows. +`SECURITYSESSIONID`, which may be set on macOS in interactive desktop sessions. + +If none of these environment variables is set, 'git log' is used instead. +You can also give command-line options such as `-p` and `--stat`. ------------ $ git bisect visualize --stat @@ -357,7 +362,7 @@ OPTIONS --no-checkout:: + Do not checkout the new working tree at each iteration of the bisection -process. Instead just update a special reference named `BISECT_HEAD` to make +process. Instead just update the reference named `BISECT_HEAD` to make it point to the commit that should be tested. + This option may be useful when the test you would perform in each step diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt index f69a871a96..5720d04ffe 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -77,7 +77,7 @@ include::blame-options.txt[] -e:: --show-email:: - Show the author email instead of author name (Default: off). + Show the author email instead of the author name (Default: off). This can also be controlled via the `blame.showEmail` config option. @@ -100,7 +100,7 @@ When neither `--porcelain` nor `--incremental` option is specified, `git blame` will output annotation for each line with: - abbreviated object name for the commit the line came from; -- author ident (by default author name and date, unless `-s` or `-e` +- author ident (by default the author name and date, unless `-s` or `-e` is specified); and - line number @@ -128,7 +128,7 @@ at least once for each commit: - the filename in the commit that the line is attributed to. - the first line of the commit log message ("summary"). -The contents of the actual line is output after the above +The contents of the actual line are output after the above header, prefixed by a TAB. This is to allow adding more header elements later. @@ -170,7 +170,7 @@ which limits the annotation to the body of the `hello` subroutine. When you are not interested in changes older than version v2.6.18, or changes older than 3 weeks, you can use revision -range specifiers similar to 'git rev-list': +range specifiers similar to 'git rev-list': git blame v2.6.18.. -- foo git blame --since=3.weeks -- foo diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index d207da9101..4395aa9354 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -324,7 +324,7 @@ superproject's "origin/main", but tracks the submodule's "origin/main". multiple times, in which case the last key becomes the primary key. The keys supported are the same as those in `git for-each-ref`. Sort order defaults to the value configured for the - `branch.sort` variable if exists, or to sorting based on the + `branch.sort` variable if it exists, or to sorting based on the full refname (including `refs/...` prefix). This lists detached HEAD (if present) first, then local branches and finally remote-tracking branches. See linkgit:git-config[1]. diff --git a/Documentation/git-bugreport.txt b/Documentation/git-bugreport.txt index eca726e579..392d9eb6ae 100644 --- a/Documentation/git-bugreport.txt +++ b/Documentation/git-bugreport.txt @@ -13,10 +13,11 @@ SYNOPSIS DESCRIPTION ----------- -Captures information about the user's machine, Git client, and repository state, -as well as a form requesting information about the behavior the user observed, -into a single text file which the user can then share, for example to the Git -mailing list, in order to report an observed bug. +Collects information about the user's machine, Git client, and repository +state, in addition to a form requesting information about the behavior the +user observed, and stores it in a single text file which the user can then +share, for example to the Git mailing list, in order to report an observed +bug. The following information is requested from the user: diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt index 411de2e27d..bd95a6c10a 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -3,8 +3,7 @@ git-cat-file(1) NAME ---- -git-cat-file - Provide content or type and size information for repository objects - +git-cat-file - Provide contents or details of repository objects SYNOPSIS -------- @@ -12,25 +11,24 @@ SYNOPSIS 'git cat-file' <type> <object> 'git cat-file' (-e | -p) <object> 'git cat-file' (-t | -s) [--allow-unknown-type] <object> -'git cat-file' (--batch | --batch-check | --batch-command) [--batch-all-objects] - [--buffer] [--follow-symlinks] [--unordered] - [--textconv | --filters] [-z] 'git cat-file' (--textconv | --filters) [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>] +'git cat-file' (--batch | --batch-check | --batch-command) [--batch-all-objects] + [--buffer] [--follow-symlinks] [--unordered] + [--textconv | --filters] [-Z] DESCRIPTION ----------- -In its first form, the command provides the content or the type of an object in -the repository. The type is required unless `-t` or `-p` is used to find the -object type, or `-s` is used to find the object size, or `--textconv` or -`--filters` is used (which imply type "blob"). - -In the second form, a list of objects (separated by linefeeds) is provided on -stdin, and the SHA-1, type, and size of each object is printed on stdout. The -output format can be overridden using the optional `<format>` argument. If -either `--textconv` or `--filters` was specified, the input is expected to -list the object names followed by the path name, separated by a single -whitespace, so that the appropriate drivers can be determined. +Output the contents or other properties such as size, type or delta +information of one or more objects. + +This command can operate in two modes, depending on whether an option +from the `--batch` family is specified. + +In non-batch mode, the command provides information on an object +named on the command line. + +In batch mode, arguments are read from standard input. OPTIONS ------- @@ -51,8 +49,8 @@ OPTIONS -e:: Exit with zero status if `<object>` exists and is a valid - object. If `<object>` is of an invalid format exit with non-zero and - emits an error on stderr. + object. If `<object>` is of an invalid format, exit with non-zero + status and emit an error on stderr. -p:: Pretty-print the contents of `<object>` based on its type. @@ -243,10 +241,16 @@ respectively print: /etc/passwd -- +-Z:: + Only meaningful with `--batch`, `--batch-check`, or + `--batch-command`; input and output is NUL-delimited instead of + newline-delimited. + -z:: Only meaningful with `--batch`, `--batch-check`, or `--batch-command`; input is NUL-delimited instead of - newline-delimited. + newline-delimited. This option is deprecated in favor of + `-Z` as the output can otherwise be ambiguous. OUTPUT @@ -384,6 +388,11 @@ notdir SP <size> LF is printed when, during symlink resolution, a file is used as a directory name. +Alternatively, when `-Z` is passed, the line feeds in any of the above examples +are replaced with NUL terminators. This ensures that output will be parsable if +the output itself would contain a linefeed and is thus recommended for +scripting purposes. + CAVEATS ------- diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt index 6e4f3aaf34..cb5a6c8f33 100644 --- a/Documentation/git-check-attr.txt +++ b/Documentation/git-check-attr.txt @@ -29,7 +29,7 @@ OPTIONS --stdin:: Read pathnames from the standard input, one per line, - instead of from the command-line. + instead of from the command line. -z:: The output format is modified to be machine-parsable. @@ -38,7 +38,7 @@ OPTIONS --source=<tree-ish>:: Check attributes against the specified tree-ish. It is common to - specify the source tree by naming a commit, branch or tag associated + specify the source tree by naming a commit, branch, or tag associated with it. \--:: @@ -60,7 +60,7 @@ unless `-z` is in effect, in which case NUL is used as delimiter: <path> is the path of a file being queried, <attribute> is an attribute -being queried and <info> can be either: +being queried, and <info> can be either: 'unspecified';; when the attribute is not defined for the path. 'unset';; when the attribute is defined as false. diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt index 2892799e32..3e3b4e3446 100644 --- a/Documentation/git-check-ignore.txt +++ b/Documentation/git-check-ignore.txt @@ -50,7 +50,7 @@ linkgit:gitignore[5]. with a NUL character instead of a linefeed character. -n, --non-matching:: - Show given paths which don't match any pattern. This only + Show given paths which don't match any pattern. This only makes sense when `--verbose` is enabled, otherwise it would not be possible to distinguish between paths which match a pattern and those which don't. diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index ee6a4144fb..2aacfd1808 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -48,7 +48,7 @@ Git imposes the following rules on how references are named: . They cannot begin or end with a slash `/` or contain multiple consecutive slashes (see the `--normalize` option below for an - exception to this rule) + exception to this rule). . They cannot end with a dot `.`. @@ -85,7 +85,7 @@ The rule `git check-ref-format --branch $name` implements may be stricter than what `git check-ref-format refs/heads/$name` says (e.g. a dash may appear at the beginning of a ref component, but it is explicitly forbidden at the beginning of a branch name). -When run with `--branch` option in a repository, the input is first +When run with the `--branch` option in a repository, the input is first expanded for the ``previous checkout syntax'' `@{-n}`. For example, `@{-1}` is a way to refer the last thing that was checked out using "git switch" or "git checkout" operation. diff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt index 01dbd5cbf5..faf8d6ca36 100644 --- a/Documentation/git-checkout-index.txt +++ b/Documentation/git-checkout-index.txt @@ -18,7 +18,7 @@ SYNOPSIS DESCRIPTION ----------- -Will copy all files listed from the index to the working directory +Copies all listed files from the index to the working directory (not overwriting existing files). OPTIONS @@ -53,11 +53,11 @@ OPTIONS --stage=<number>|all:: Instead of checking out unmerged entries, copy out the - files from named stage. <number> must be between 1 and 3. + files from the named stage. <number> must be between 1 and 3. Note: --stage=all automatically implies --temp. --temp:: - Instead of copying the files to the working directory + Instead of copying the files to the working directory, write the content to temporary files. The temporary name associations will be written to stdout. @@ -66,8 +66,8 @@ OPTIONS set. --stdin:: - Instead of taking list of paths from the command line, - read list of paths from the standard input. Paths are + Instead of taking a list of paths from the command line, + read the list of paths from the standard input. Paths are separated by LF (i.e. one path per line) by default. -z:: diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 4af0904f47..55a50b5b23 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -12,8 +12,10 @@ SYNOPSIS 'git checkout' [-q] [-f] [-m] --detach [<branch>] 'git checkout' [-q] [-f] [-m] [--detach] <commit> 'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>] -'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>... -'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul] +'git checkout' [-f] <tree-ish> [--] <pathspec>... +'git checkout' [-f] <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul] +'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>... +'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul] 'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...] DESCRIPTION @@ -41,7 +43,7 @@ $ git checkout -b <branch> --track <remote>/<branch> You could omit `<branch>`, in which case the command degenerates to "check out the current branch", which is a glorified no-op with rather expensive side-effects to show only the tracking information, -if exists, for the current branch. +if it exists, for the current branch. 'git checkout' -b|-B <new-branch> [<start-point>]:: @@ -61,7 +63,9 @@ $ git checkout <branch> ------------ + that is to say, the branch is not reset/created unless "git checkout" is -successful. +successful (e.g., when the branch is in use in another worktree, not +just the current branch stays the same, but the branch is not reset to +the start-point, either). 'git checkout' --detach [<branch>]:: 'git checkout' [--detach] <commit>:: @@ -260,7 +264,8 @@ and mark the resolved paths with `git add` (or `git rm` if the merge should result in deletion of the path). + When checking out paths from the index, this option lets you recreate -the conflicted merge in the specified paths. +the conflicted merge in the specified paths. This option cannot be +used when checking out paths from a tree-ish. + When switching branches with `--merge`, staged changes may be lost. diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt index 160d08b86b..69331e3f05 100644 --- a/Documentation/git-clean.txt +++ b/Documentation/git-clean.txt @@ -103,7 +103,7 @@ filter by pattern:: This shows the files and directories to be deleted and issues an "Input ignore patterns>>" prompt. You can input space-separated patterns to exclude files and directories from deletion. - E.g. "*.c *.h" will excludes files end with ".c" and ".h" from + E.g. "*.c *.h" will exclude files ending with ".c" and ".h" from deletion. When you are satisfied with the filtered result, press ENTER (empty) back to the main menu. @@ -127,7 +127,7 @@ ask each:: quit:: - This lets you quit without do cleaning. + This lets you quit without doing any cleaning. help:: diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 225c6c9f2e..a6cef5d820 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -541,7 +541,7 @@ DISCUSSION ---------- Though not required, it's a good idea to begin the commit message -with a single short (less than 50 character) line summarizing the +with a single short (no more than 50 characters) line summarizing the change, followed by a blank line and then a more thorough description. The text up to the first blank line in a commit message is treated as the commit title, and that title is used throughout Git. diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 7a2bcb2f6c..b1caac887a 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -201,7 +201,7 @@ Valid `<type>`'s include: 1073741824 upon input. - 'bool-or-int': canonicalize according to either 'bool' or 'int', as described above. -- 'path': canonicalize by adding a leading `~` to the value of `$HOME` and +- 'path': canonicalize by expanding a leading `~` to the value of `$HOME` and `~user` to the home directory for the specified user. This specifier has no effect when setting the value (but you can use `git config section.variable ~/` from the command line to let your shell do the expansion.) diff --git a/Documentation/git-count-objects.txt b/Documentation/git-count-objects.txt index cb9b4d2e46..97f9f12610 100644 --- a/Documentation/git-count-objects.txt +++ b/Documentation/git-count-objects.txt @@ -12,7 +12,7 @@ SYNOPSIS DESCRIPTION ----------- -This counts the number of unpacked object files and disk space consumed by +Counts the number of unpacked object files and disk space consumed by them, to help you decide when it is a good time to repack. @@ -20,7 +20,7 @@ OPTIONS ------- -v:: --verbose:: - Report in more detail: + Provide more detailed reports: + count: the number of loose objects + @@ -33,7 +33,7 @@ size-pack: disk space consumed by the packs, in KiB (unless -H is specified) prune-packable: the number of loose objects that are also present in the packs. These objects could be pruned using `git prune-packed`. + -garbage: the number of files in object database that are neither valid loose +garbage: the number of files in the object database that are neither valid loose objects nor valid packs + size-garbage: disk space consumed by garbage files, in KiB (unless -H is diff --git a/Documentation/git-credential-cache.txt b/Documentation/git-credential-cache.txt index f473994a86..487cc557a8 100644 --- a/Documentation/git-credential-cache.txt +++ b/Documentation/git-credential-cache.txt @@ -16,7 +16,7 @@ DESCRIPTION This command caches credentials for use by future Git programs. The stored credentials are kept in memory of the cache-daemon -process (instead of written to a file) and are forgotten after a +process (instead of being written to a file) and are forgotten after a configurable timeout. Credentials are forgotten sooner if the cache-daemon dies, for example if the system restarts. The cache is accessible over a Unix domain socket, restricted to the current diff --git a/Documentation/git-credential-store.txt b/Documentation/git-credential-store.txt index 76b0798856..71864a8726 100644 --- a/Documentation/git-credential-store.txt +++ b/Documentation/git-credential-store.txt @@ -33,7 +33,7 @@ OPTIONS Use `<path>` to lookup and store credentials. The file will have its filesystem permissions set to prevent other users on the system - from reading it, but will not be encrypted or otherwise + from reading it, but it will not be encrypted or otherwise protected. If not specified, credentials will be searched for from `~/.git-credentials` and `$XDG_CONFIG_HOME/git/credentials`, and credentials will be written to `~/.git-credentials` if it exists, or diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt index 0e6d9e85ec..918a0aa42b 100644 --- a/Documentation/git-credential.txt +++ b/Documentation/git-credential.txt @@ -39,7 +39,7 @@ for later use. If the action is `reject`, git-credential will send the description to any configured credential helpers, which may erase any stored -credential matching the description. +credentials matching the description. If the action is `approve` or `reject`, no output should be emitted. @@ -94,7 +94,7 @@ unlocked) before it returned `password=secr3t`. that `git credential` will ask for a new password in its next invocation. In either case, `git credential` should be fed with the credential description obtained from step (2) (which also - contain the ones provided in step (1)). + contains the fields provided in step (1)). [[IOFMT]] INPUT/OUTPUT FORMAT diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt index b3f27671a0..90fdc2551a 100644 --- a/Documentation/git-cvsimport.txt +++ b/Documentation/git-cvsimport.txt @@ -22,7 +22,7 @@ DESCRIPTION deprecated; it does not work with cvsps version 3 and later. If you are performing a one-shot import of a CVS repository consider using http://cvs2svn.tigris.org/cvs2git.html[cvs2git] or -http://www.catb.org/esr/cvs-fast-export/[cvs-fast-export]. +https://gitlab.com/esr/cvs-fast-export[cvs-fast-export]. Imports a CVS repository into Git. It will either create a new repository, or incrementally import into an existing one. @@ -221,7 +221,7 @@ Problems related to tags: If you suspect that any of these issues may apply to the repository you want to import, consider using cvs2git: -* cvs2git (part of cvs2svn), `http://subversion.apache.org/` +* cvs2git (part of cvs2svn), `https://subversion.apache.org/` GIT --- diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt index 53f111bc0a..cf4a5a283e 100644 --- a/Documentation/git-cvsserver.txt +++ b/Documentation/git-cvsserver.txt @@ -118,7 +118,7 @@ for example: myuser:$5$.NqmNH1vwfzGpV8B$znZIcumu1tNLATgV2l6e1/mY8RzhUDHMOaVOeL1cxV3 ------ You can use the 'htpasswd' facility that comes with Apache to make these -files, but only with the -d option (or -B if your system suports it). +files, but only with the -d option (or -B if your system supports it). Preferably use the system specific utility that manages password hash creation in your platform (e.g. mkpasswd in Linux, encrypt in OpenBSD or diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt index 236df516c7..e064f91c9e 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -138,7 +138,7 @@ otherwise `stderr`. --user-path:: --user-path=<path>:: Allow {tilde}user notation to be used in requests. When - specified with no parameter, requests to + specified with no parameter, a request to git://host/{tilde}alice/foo is taken as a request to access 'foo' repository in the home directory of user `alice`. If `--user-path=path` is specified, the same request is diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index c6a79c2a0f..08ff715709 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -140,7 +140,7 @@ at the end. The number of additional commits is the number of commits which would be displayed by "git log v1.0.4..parent". -The hash suffix is "-g" + an unambigous abbreviation for the tip commit +The hash suffix is "-g" + an unambiguous abbreviation for the tip commit of parent (which was `2414721b194453f058079d897d13c4e377f92dc6`). The length of the abbreviation scales as the repository grows, using the approximate number of objects in the repository and a bit of math @@ -203,7 +203,7 @@ BUGS Tree objects as well as tag objects not pointing at commits, cannot be described. When describing blobs, the lightweight tags pointing at blobs are ignored, -but the blob is still described as <committ-ish>:<path> despite the lightweight +but the blob is still described as <commit-ish>:<path> despite the lightweight tag being favorable. GIT diff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt index 591e3801b7..bf78e31431 100644 --- a/Documentation/git-diff-files.txt +++ b/Documentation/git-diff-files.txt @@ -26,7 +26,7 @@ include::diff-options.txt[] -2 --ours:: -3 --theirs:: -0:: - Diff against the "base" version, "our branch" or "their + Diff against the "base" version, "our branch", or "their branch" respectively. With these options, diffs for merged entries are not shown. + @@ -37,12 +37,12 @@ omit diff output for unmerged entries and just show "Unmerged". -c:: --cc:: This compares stage 2 (our branch), stage 3 (their - branch) and the working tree file and outputs a combined + branch), and the working tree file and outputs a combined diff, similar to the way 'diff-tree' shows a merge commit with these flags. -q:: - Remain silent even on nonexistent files + Remain silent even for nonexistent files include::diff-format.txt[] diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt index c30d8f0da8..4de1d4c8f1 100644 --- a/Documentation/git-diff-index.txt +++ b/Documentation/git-diff-index.txt @@ -13,10 +13,10 @@ SYNOPSIS DESCRIPTION ----------- -Compares the content and mode of the blobs found in a tree object +Compare the content and mode of the blobs found in a tree object with the corresponding tracked files in the working tree, or with the corresponding paths in the index. When <path> arguments are present, -compares only paths matching those patterns. Otherwise all tracked +compare only paths matching those patterns. Otherwise all tracked files are compared. OPTIONS diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt index 274d5eaba9..143318c411 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -15,7 +15,7 @@ SYNOPSIS DESCRIPTION ----------- -Compares the content and mode of the blobs found via two tree objects. +Compare the content and mode of blobs found via two tree objects. If there is only one <tree-ish> given, the commit is compared with its parents (see --stdin below). @@ -34,10 +34,10 @@ include::diff-options.txt[] matching one of the provided pathspecs. -r:: - recurse into sub-trees + Recurse into sub-trees. -t:: - show tree entry itself as well as subtrees. Implies -r. + Show tree entry itself as well as subtrees. Implies -r. --root:: When `--root` is specified the initial commit will be shown as a big @@ -78,7 +78,7 @@ commits (but not trees). By default, 'git diff-tree --stdin' shows differences, either in machine-readable form (without `-p`) or in patch form (with `-p`). This output can be suppressed. It is - only useful with `-v` flag. + only useful with the `-v` flag. -v:: This flag causes 'git diff-tree --stdin' to also show @@ -104,10 +104,10 @@ include::pretty-options.txt[] This flag changes the way a merge commit patch is displayed, in a similar way to the `-c` option. It implies the `-c` and `-p` options and further compresses the patch output - by omitting uninteresting hunks whose the contents in the parents + by omitting uninteresting hunks whose contents in the parents have only two variants and the merge result picks one of them without modification. When all hunks are uninteresting, the commit - itself and the commit log message is not shown, just like in any other + itself and the commit log message are not shown, just like in any other "empty diff" case. --combined-all-paths:: diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 52b679256c..c065f023ec 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -102,7 +102,11 @@ If --merge-base is given, use the merge base of the two commits for the Just in case you are doing something exotic, it should be noted that all of the <commit> in the above description, except in the `--merge-base` case and in the last two forms that use `..` -notations, can be any <tree>. +notations, can be any <tree>. A tree of interest is the one pointed to +by the ref named `AUTO_MERGE`, which is written by the 'ort' merge +strategy upon hitting merge conflicts (see linkgit:git-merge[1]). +Comparing the working tree with `AUTO_MERGE` shows changes you've made +so far to resolve textual conflicts (see the examples below). For a more complete list of ways to spell <commit>, see "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7]. @@ -152,6 +156,7 @@ Various ways to check your working tree:: $ git diff <1> $ git diff --cached <2> $ git diff HEAD <3> +$ git diff AUTO_MERGE <4> ------------ + <1> Changes in the working tree not yet staged for the next commit. @@ -159,6 +164,8 @@ $ git diff HEAD <3> 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` +<4> Changes in the working tree you've made to resolve textual + conflicts so far. Comparing with arbitrary commits:: + diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt index ac0ac6fa02..50cb080085 100644 --- a/Documentation/git-difftool.txt +++ b/Documentation/git-difftool.txt @@ -36,7 +36,7 @@ OPTIONS --rotate-to=<file>:: Start showing the diff for the given path, - the paths before it will move to end and output. + the paths before it will move to the end and output. --skip-to=<file>:: Start showing the diff for the given path, skipping all @@ -78,7 +78,7 @@ with custom merge tool commands and has the same value as `$MERGED`. Print a list of diff tools that may be used with `--tool`. --[no-]symlinks:: - 'git difftool''s default behavior is create symlinks to the + 'git difftool''s default behavior is to create symlinks to the working tree when run in `--dir-diff` mode and the right-hand side of the comparison yields the same content as the file in the working tree. diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index 8b5dd6add0..bd7b1e0a2e 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -622,7 +622,7 @@ in octal. Git only supports the following modes: * `100755` or `755`: A normal, but executable, file. * `120000`: A symlink, the content of the file will be the link target. * `160000`: A gitlink, SHA-1 of the object refers to a commit in - another repository. Git links can only be specified by SHA or through + another repository. Git links can only be specified either by SHA or through a commit mark. They are used to implement submodules. * `040000`: A subdirectory. Subdirectories can only be specified by SHA or through a tree mark set with `--import-marks`. @@ -1353,7 +1353,7 @@ the marks back to the source repository, it is easy to verify the accuracy and completeness of the import by comparing each Git commit to the corresponding source revision. -Coming from a system such as Perforce or Subversion this should be +Coming from a system such as Perforce or Subversion, this should be quite simple, as the fast-import mark can also be the Perforce changeset number or the Subversion revision number. diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt index 46747d5f42..b3467664d3 100644 --- a/Documentation/git-fetch-pack.txt +++ b/Documentation/git-fetch-pack.txt @@ -69,7 +69,7 @@ be in a separate packet, and the list must end with a flush packet. --upload-pack=<git-upload-pack>:: Use this to specify the path to 'git-upload-pack' on the - remote side, if is not found on your $PATH. + remote side, if it is not found on your $PATH. Installations of sshd ignores the user's environment setup scripts for login shells (e.g. .bash_profile) and your privately installed git may not be found on the system diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 1e215d4e73..be9543f684 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -14,6 +14,7 @@ SYNOPSIS [--points-at=<object>] [--merged[=<object>]] [--no-merged[=<object>]] [--contains[=<object>]] [--no-contains[=<object>]] + [--exclude=<pattern> ...] DESCRIPTION ----------- @@ -50,17 +51,14 @@ OPTIONS key. --format=<format>:: - A string that interpolates `%(fieldname)` from a ref being shown - and the object it points at. If `fieldname` - is prefixed with an asterisk (`*`) and the ref points - at a tag object, use the value for the field in the object - which the tag object refers to (instead of the field in the tag object). - When unspecified, `<format>` defaults to - `%(objectname) SPC %(objecttype) TAB %(refname)`. - It also interpolates `%%` to `%`, and `%xx` where `xx` - are hex digits interpolates to character with hex code - `xx`; for example `%00` interpolates to `\0` (NUL), - `%09` to `\t` (TAB) and `%0a` to `\n` (LF). + A string that interpolates `%(fieldname)` from a ref being shown and + the object it points at. In addition, the string literal `%%` + renders as `%` and `%xx` - where `xx` are hex digits - renders as + the character with hex code `xx`. For example, `%00` interpolates to + `\0` (NUL), `%09` to `\t` (TAB), and `%0a` to `\n` (LF). ++ +When unspecified, `<format>` defaults to `%(objectname) SPC %(objecttype) +TAB %(refname)`. --color[=<when>]:: Respect any colors specified in the `--format` option. The @@ -102,6 +100,11 @@ OPTIONS Do not print a newline after formatted refs where the format expands to the empty string. +--exclude=<pattern>:: + If one or more patterns are given, only refs which do not match + any excluded pattern(s) are shown. Matching is done using the + same rules as `<pattern>` above. + FIELD NAMES ----------- @@ -221,6 +224,33 @@ symref:: `:lstrip` and `:rstrip` options in the same way as `refname` above. +signature:: + The GPG signature of a commit. + +signature:grade:: + Show "G" for a good (valid) signature, "B" for a bad + signature, "U" for a good signature with unknown validity, "X" + for a good signature that has expired, "Y" for a good + signature made by an expired key, "R" for a good signature + made by a revoked key, "E" if the signature cannot be + checked (e.g. missing key) and "N" for no signature. + +signature:signer:: + The signer of the GPG signature of a commit. + +signature:key:: + The key of the GPG signature of a commit. + +signature:fingerprint:: + The fingerprint of the GPG signature of a commit. + +signature:primarykeyfingerprint:: + The primary key fingerprint of the GPG signature of a commit. + +signature:trustlevel:: + The trust level of the GPG signature of a commit. Possible + outputs are `ultimate`, `fully`, `marginal`, `never` and `undefined`. + worktreepath:: The absolute path to the worktree in which the ref is checked out, if it is checked out in any linked worktree. Empty string @@ -231,6 +261,29 @@ ahead-behind:<committish>:: commits ahead and behind, respectively, when comparing the output ref to the `<committish>` specified in the format. +describe[:options]:: + A human-readable name, like linkgit:git-describe[1]; + empty string for undescribable commits. The `describe` string may + be followed by a colon and one or more comma-separated options. ++ +-- +tags=<bool-value>;; + Instead of only considering annotated tags, consider + lightweight tags as well; see the corresponding option in + linkgit:git-describe[1] for details. +abbrev=<number>;; + Use at least <number> hexadecimal digits; see the corresponding + option in linkgit:git-describe[1] for details. +match=<pattern>;; + Only consider tags matching the given `glob(7)` pattern, + excluding the "refs/tags/" prefix; see the corresponding option + in linkgit:git-describe[1] for details. +exclude=<pattern>;; + Do not consider tags matching the given `glob(7)` pattern, + excluding the "refs/tags/" prefix; see the corresponding option + in linkgit:git-describe[1] for details. +-- + 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. @@ -242,12 +295,20 @@ fields will correspond to the appropriate date or name-email-date tuple from the `committer` or `tagger` fields depending on the object type. These are intended for working on a mix of annotated and lightweight tags. +For tag objects, a `fieldname` prefixed with an asterisk (`*`) expands to +the `fieldname` value of the peeled object, rather than that of the tag +object itself. + Fields that have name-email-date tuple as its value (`author`, `committer`, and `tagger`) can be suffixed with `name`, `email`, and `date` to extract the named component. For email fields (`authoremail`, `committeremail` and `taggeremail`), `:trim` can be appended to get the email without angle brackets, and `:localpart` to get the part before the `@` symbol -out of the trimmed email. +out of the trimmed email. In addition to these, the `:mailmap` option and the +corresponding `:mailmap,trim` and `:mailmap,localpart` can be used (order does +not matter) to get values of the name and email according to the .mailmap file +or according to the file set in the mailmap.file or mailmap.blob configuration +variable (see linkgit:gitmailmap[5]). The raw data in an object is `raw`. diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index b1c13fb39a..414da6b73e 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -55,7 +55,7 @@ A "message" generated by the command consists of three parts: * The "patch", which is the "diff -p --stat" output (see linkgit:git-diff[1]) between the commit and its parent. -The log message and the patch is separated by a line with a +The log message and the patch are separated by a line with a three-dash line. There are two ways to specify which commits to operate on. @@ -215,11 +215,21 @@ is greater than 100 bytes, then the mode will be `message`, otherwise If `<mode>` is `none`, both the cover letter subject and body will be populated with placeholder text. +--description-file=<file>:: + Use the contents of <file> instead of the branch's description + for generating the cover letter. + --subject-prefix=<subject prefix>:: Instead of the standard '[PATCH]' prefix in the subject - line, instead use '[<subject prefix>]'. This - allows for useful naming of a patch series, and can be - combined with the `--numbered` option. + line, instead use '[<subject prefix>]'. This can be used + to name a patch series, and can be combined with the + `--numbered` option. ++ +The configuration variable `format.subjectPrefix` may also be used +to configure a subject prefix to apply to a given repository for +all patches. This is often useful on mailing lists which receive +patches for several repositories and can be used to disambiguate +the patches (with a value of e.g. "PATCH my-project"). --filename-max-length=<n>:: Instead of the standard 64 bytes, chomp the generated output @@ -229,9 +239,9 @@ populated with placeholder text. variable, or 64 if unconfigured. --rfc:: - Alias for `--subject-prefix="RFC PATCH"`. RFC means "Request For - Comments"; use this when sending an experimental patch for - discussion rather than application. + Prepends "RFC" to the subject prefix (producing "RFC PATCH" by + default). RFC means "Request For Comments"; use this when sending + an experimental patch for discussion rather than application. -v <n>:: --reroll-count=<n>:: @@ -245,7 +255,7 @@ populated with placeholder text. or "--reroll-count=4rev2" are allowed), but the downside of using such a reroll-count is that the range-diff/interdiff with the previous version does not state exactly which - version the new interation is compared against. + version the new iteration is compared against. --to=<email>:: Add a `To:` header to the email headers. This is in addition @@ -600,8 +610,8 @@ Approach #3 (external editor) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The following Thunderbird extensions are needed: -AboutConfig from http://aboutconfig.mozdev.org/ and -External Editor from http://globs.org/articles.php?lng=en&pg=8 +AboutConfig from https://mjg.github.io/AboutConfig/ and +External Editor from https://globs.org/articles.php?lng=en&pg=8 1. Prepare the patch as a text file using your method of choice. diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt index b6a0f8a085..5b82e4605c 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -24,7 +24,7 @@ OPTIONS An object to treat as the head of an unreachability trace. + If no objects are given, 'git fsck' defaults to using the -index file, all SHA-1 references in `refs` namespace, and all reflogs +index file, all SHA-1 references in the `refs` namespace, and all reflogs (unless --no-reflogs is given) as heads. --unreachable:: @@ -64,7 +64,7 @@ index file, all SHA-1 references in `refs` namespace, and all reflogs --connectivity-only:: Check only the connectivity of reachable objects, making sure that any objects referenced by a reachable tag, commit, or tree - is present. This speeds up the operation by avoiding reading + are present. This speeds up the operation by avoiding reading blobs entirely (though it does still check that referenced blobs exist). This will detect corruption in commits and trees, but not do any semantic checks (e.g., for format errors). Corruption @@ -79,7 +79,7 @@ care about this output and want to speed it up further. recorded with g+w bit set, which was created by older versions of Git. Existing repositories, including the Linux kernel, Git itself, and sparse repository have old - objects that triggers this check, but it is recommended + objects that trigger this check, but it is recommended to check new projects with this flag. --verbose:: diff --git a/Documentation/git-fsmonitor--daemon.txt b/Documentation/git-fsmonitor--daemon.txt index 8238eadb0e..8585d19f4d 100644 --- a/Documentation/git-fsmonitor--daemon.txt +++ b/Documentation/git-fsmonitor--daemon.txt @@ -70,10 +70,10 @@ the change (as happening against the super repo). However, the client will properly ignore these extra events, so performance may be affected but it will not cause an incorrect result. -By default, the fsmonitor daemon refuses to work against network-mounted +By default, the fsmonitor daemon refuses to work with network-mounted repositories; this may be overridden by setting `fsmonitor.allowRemote` to `true`. Note, however, that the fsmonitor daemon is not guaranteed to work -correctly with all network-mounted repositories and such use is considered +correctly with all network-mounted repositories, so such use is considered experimental. On Mac OS, the inter-process communication (IPC) between various Git @@ -83,10 +83,10 @@ but not on network-mounted filesystems, NTFS, or FAT32. Other filesystems may or may not have the needed support; the fsmonitor daemon is not guaranteed to work with these filesystems and such use is considered experimental. -By default, the socket is created in the `.git` directory, however, if the -`.git` directory is on a network-mounted filesystem, it will be instead be +By default, the socket is created in the `.git` directory. However, if the +`.git` directory is on a network-mounted filesystem, it will instead be created at `$HOME/.git-fsmonitor-*` unless `$HOME` itself is on a -network-mounted filesystem in which case you must set the configuration +network-mounted filesystem, in which case you must set the configuration variable `fsmonitor.socketDir` to the path of a directory on a Mac OS native filesystem in which to create the socket file. diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index 90806fd26a..b5561c458a 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -59,6 +59,13 @@ be performed as well. cruft pack instead of storing them as loose objects. `--cruft` is on by default. +--max-cruft-size=<n>:: + When packing unreachable objects into a cruft pack, limit the + size of new cruft packs to be at most `<n>` bytes. Overrides any + value specified via the `gc.maxCruftSize` configuration. See + the `--max-cruft-size` option of linkgit:git-repack[1] for + more. + --prune=<date>:: Prune loose objects older than date (default is 2 weeks ago, overridable by the config variable `gc.pruneExpire`). diff --git a/Documentation/git-get-tar-commit-id.txt b/Documentation/git-get-tar-commit-id.txt index ac44d85b0b..b537bb45b1 100644 --- a/Documentation/git-get-tar-commit-id.txt +++ b/Documentation/git-get-tar-commit-id.txt @@ -20,7 +20,7 @@ and extract the commit ID stored in it. It reads only the first 1024 bytes of input, thus its runtime is not influenced by the size of the tar archive very much. -If no commit ID is found, 'git get-tar-commit-id' quietly exists with a +If no commit ID is found, 'git get-tar-commit-id' quietly exits with a return code of 1. This can happen if the archive had not been created using 'git archive' or if the first parameter of 'git archive' had been a tree ID instead of a commit ID or tag. diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index dabdbe8471..0d0103c780 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -337,7 +337,7 @@ The `--threads` option (and the grep.threads configuration) will be ignored when When grepping the object store (with `--cached` or giving tree objects), running with multiple threads might perform slower than single threaded if `--textconv` -is given and there're too many text conversions. So if you experience low +is given and there are too many text conversions. So if you experience low performance in this case, it might be desirable to use `--threads=1`. CONFIGURATION diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt index 472b5bb995..ef4719ae41 100644 --- a/Documentation/git-hash-object.txt +++ b/Documentation/git-hash-object.txt @@ -3,7 +3,7 @@ git-hash-object(1) NAME ---- -git-hash-object - Compute object ID and optionally creates a blob from a file +git-hash-object - Compute object ID and optionally create an object from a file SYNOPSIS @@ -25,7 +25,8 @@ OPTIONS ------- -t <type>:: - Specify the type (default: "blob"). + Specify the type of object to be created (default: "blob"). Possible + values are `commit`, `tree`, `blob`, and `tag`. -w:: Actually write the object into the object database. @@ -38,10 +39,10 @@ OPTIONS of from the command-line. --path:: - Hash object as it were located at the given path. The location of - file does not directly influence on the hash value, but path is - used to determine what Git filters should be applied to the object - before it can be placed to the object database, and, as result of + Hash object as if it were located at the given path. The location of + the file does not directly influence the hash value, but the path is + used to determine which Git filters should be applied to the object + before it can be placed in the object database. As a result of applying filters, the actual blob put into the object database may differ from the given file. This option is mainly useful for hashing temporary files located outside of the working directory or files diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index 2b0b5e390d..f0bedc1f96 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -42,13 +42,13 @@ former is internally converted into the latter. To display the linkgit:git[1] man page, use `git help git`. -This page can be displayed with 'git help help' or `git help --help` +This page can be displayed with 'git help help' or `git help --help`. OPTIONS ------- -a:: --all:: - Prints all the available commands on the standard output. + Print all the available commands on the standard output. --no-external-commands:: When used with `--all`, exclude the listing of external "git-*" @@ -59,7 +59,7 @@ OPTIONS aliases. --verbose:: - When used with `--all` print description for all recognized + When used with `--all`, print description for all recognized commands. This is the default. -c:: @@ -69,10 +69,10 @@ OPTIONS -g:: --guides:: - Prints a list of the Git concept guides on the standard output. + Print a list of the Git concept guides on the standard output. --user-interfaces:: - Prints a list of the repository, command and file interfaces + Print a list of the repository, command and file interfaces documentation on the standard output. + In-repository file interfaces such as `.git/info/exclude` are @@ -85,7 +85,7 @@ pseudo-configuration such as the file-based `.git/hooks/*` interface described in linkgit:githooks[5]. --developer-interfaces:: - Print list of file formats, protocols and other developer + Print a list of file formats, protocols and other developer interfaces documentation on the standard output. -i:: @@ -109,7 +109,7 @@ other display programs (see below). format. A web browser will be used for that purpose. + The web browser can be specified using the configuration variable -`help.browser`, or `web.browser` if the former is not set. If none of +`help.browser`, or `web.browser` if the former is not set. If neither of these config variables is set, the 'git web{litdd}browse' helper script (called by 'git help') will pick a suitable default. See linkgit:git-web{litdd}browse[1] for more information about this. @@ -129,8 +129,8 @@ line option: * "info" corresponds to '-i|--info', * "web" or "html" correspond to '-w|--web'. -help.browser, web.browser and browser.<tool>.path -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +help.browser, web.browser, and browser.<tool>.path +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The `help.browser`, `web.browser` and `browser.<tool>.path` will also be checked if the 'web' format is chosen (either by command-line diff --git a/Documentation/git-hook.txt b/Documentation/git-hook.txt index 3407f3c2c0..f6cc72d2ca 100644 --- a/Documentation/git-hook.txt +++ b/Documentation/git-hook.txt @@ -13,7 +13,7 @@ SYNOPSIS DESCRIPTION ----------- -A command interface to running git hooks (see linkgit:githooks[5]), +A command interface for running git hooks (see linkgit:githooks[5]), for use by other scripted git commands. SUBCOMMANDS @@ -32,7 +32,7 @@ OPTIONS ------- --to-stdin:: - For "run"; Specify a file which will be streamed into the + For "run"; specify a file which will be streamed into the hook's stdin. The hook will receive the entire file from beginning to EOF. diff --git a/Documentation/git-http-backend.txt b/Documentation/git-http-backend.txt index 0c5c0dde19..f37ddaded8 100644 --- a/Documentation/git-http-backend.txt +++ b/Documentation/git-http-backend.txt @@ -23,7 +23,7 @@ discussion of `GIT_PROTOCOL` in the ENVIRONMENT section below. It verifies that the directory has the magic file "git-daemon-export-ok", and it will refuse to export any Git directory that hasn't explicitly been marked for export this way (unless the -`GIT_HTTP_EXPORT_ALL` environmental variable is set). +`GIT_HTTP_EXPORT_ALL` environment variable is set). By default, only the `upload-pack` service is enabled, which serves 'git fetch-pack' and 'git ls-remote' clients, which are invoked from @@ -42,12 +42,12 @@ http.getanyfile:: any file within the repository, including objects that are no longer reachable from a branch but are still present. It is enabled by default, but a repository can disable it - by setting this configuration item to `false`. + by setting this configuration value to `false`. http.uploadpack:: This serves 'git fetch-pack' and 'git ls-remote' clients. It is enabled by default, but a repository can disable it - by setting this configuration item to `false`. + by setting this configuration value to `false`. http.receivepack:: This serves 'git send-pack' clients, allowing push. It is @@ -265,12 +265,12 @@ by the invoking web server, including: * QUERY_STRING * REQUEST_METHOD -The `GIT_HTTP_EXPORT_ALL` environmental variable may be passed to +The `GIT_HTTP_EXPORT_ALL` environment variable may be passed to 'git-http-backend' to bypass the check for the "git-daemon-export-ok" file in each repository before allowing export of that repository. The `GIT_HTTP_MAX_REQUEST_BUFFER` environment variable (or the -`http.maxRequestBuffer` config variable) may be set to change the +`http.maxRequestBuffer` config option) may be set to change the largest ref negotiation request that git will handle during a fetch; any fetch requiring a larger buffer will not succeed. This value should not normally need to be changed, but may be helpful if you are fetching from diff --git a/Documentation/git-http-fetch.txt b/Documentation/git-http-fetch.txt index 319062c021..4ec7c68d3b 100644 --- a/Documentation/git-http-fetch.txt +++ b/Documentation/git-http-fetch.txt @@ -31,7 +31,7 @@ commit-id:: Report what is downloaded. -w <filename>:: - Writes the commit-id into the filename under $GIT_DIR/refs/<filename> on + Writes the commit-id into the specified filename under $GIT_DIR/refs/<filename> on the local end after the transfer is complete. --stdin:: diff --git a/Documentation/git-http-push.txt b/Documentation/git-http-push.txt index 7c6a6dd7f6..ce0d808212 100644 --- a/Documentation/git-http-push.txt +++ b/Documentation/git-http-push.txt @@ -13,12 +13,12 @@ SYNOPSIS DESCRIPTION ----------- -Sends missing objects to remote repository, and updates the +Sends missing objects to the remote repository, and updates the remote branch. *NOTE*: This command is temporarily disabled if your libcurl is older than 7.16, as the combination has been reported -not to work and sometimes corrupts repository. +not to work and sometimes corrupts the repository. OPTIONS ------- @@ -44,7 +44,7 @@ OPTIONS -d:: -D:: Remove <ref> from remote repository. The specified branch - cannot be the remote HEAD. If -d is specified the following + cannot be the remote HEAD. If -d is specified, the following other conditions must also be met: - Remote HEAD must resolve to an object that exists locally @@ -83,8 +83,8 @@ and where it is pushed is determined by using the destination side. Without `--force`, the <src> ref is stored at the remote only if <dst> does not exist, or <dst> is a proper subset (i.e. an ancestor) of <src>. This check, known as "fast-forward check", -is performed in order to avoid accidentally overwriting the -remote ref and lose other peoples' commits from there. +is performed to avoid accidentally overwriting the +remote ref and losing other peoples' commits from there. With `--force`, the fast-forward check is disabled for all refs. diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt index f7b1851514..c8a89d7243 100644 --- a/Documentation/git-imap-send.txt +++ b/Documentation/git-imap-send.txt @@ -135,7 +135,7 @@ flames ridiculing you if you don't check this. Thunderbird in particular is known to be problematic. Thunderbird users may wish to visit this web page for more information: - http://kb.mozillazine.org/Plain_text_e-mail_-_Thunderbird#Completely_plain_email + https://kb.mozillazine.org/Plain_text_e-mail_-_Thunderbird#Completely_plain_email SEE ALSO -------- diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt index 4e71c256ec..6486620c3d 100644 --- a/Documentation/git-index-pack.txt +++ b/Documentation/git-index-pack.txt @@ -16,10 +16,10 @@ SYNOPSIS DESCRIPTION ----------- -Reads a packed archive (.pack) from the specified file, and -builds a pack index file (.idx) for it. Optionally writes a +Reads a packed archive (.pack) from the specified file, +builds a pack index file (.idx) for it, and optionally writes a reverse-index (.rev) for the specified pack. The packed -archive together with the pack index can then be placed in +archive, together with the pack index, can then be placed in the objects/pack/ directory of a Git repository. @@ -68,8 +68,8 @@ OPTIONS updated to use objects contained in the pack. --keep=<msg>:: - Like --keep create a .keep file before moving the index into - its final destination, but rather than creating an empty file + Like --keep, create a .keep file before moving the index into + its final destination. However, instead of creating an empty file place '<msg>' followed by an LF into the .keep file. The '<msg>' message can later be searched for within all .keep files to locate any which have outlived their usefulness. diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt index 160dea1372..6f0d2973bf 100644 --- a/Documentation/git-init.txt +++ b/Documentation/git-init.txt @@ -29,7 +29,7 @@ to use instead of `./.git` for the base of the repository. If the object storage directory is specified via the `$GIT_OBJECT_DIRECTORY` environment variable then the sha1 directories -are created underneath - otherwise the default `$GIT_DIR/objects` +are created underneath; otherwise, the default `$GIT_DIR/objects` directory is used. Running 'git init' in an existing repository is safe. It will not @@ -66,10 +66,10 @@ DIRECTORY" section below.) Instead of initializing the repository as a directory to either `$GIT_DIR` or `./.git/`, create a text file there containing the path to the actual -repository. This file acts as filesystem-agnostic Git symbolic link to the +repository. This file acts as a filesystem-agnostic Git symbolic link to the repository. + -If this is reinitialization, the repository will be moved to the specified path. +If this is a reinitialization, the repository will be moved to the specified path. -b <branch-name>:: --initial-branch=<branch-name>:: @@ -99,7 +99,7 @@ specified. 'group' (or 'true'):: -Make the repository group-writable, (and g+sx, since the git group may be not +Make the repository group-writable, (and g+sx, since the git group may not be the primary group of all users). This is used to loosen the permissions of an otherwise safe umask(2) value. Note that the umask still applies to the other permission bits (e.g. if umask is '0022', using 'group' will not remove read @@ -115,7 +115,7 @@ Same as 'group', but make the repository readable by all users. '<perm>' is a 3-digit octal number prefixed with `0` and each file will have mode '<perm>'. '<perm>' will override users' umask(2) value (and not only loosen permissions as 'group' and 'all' -does). '0640' will create a repository which is group-readable, but +do). '0640' will create a repository which is group-readable, but not group-writable or accessible to others. '0660' will create a repo that is readable and writable to the current user and group, but inaccessible to others (directories and executable files get their diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt index 4b97f812be..418265f044 100644 --- a/Documentation/git-interpret-trailers.txt +++ b/Documentation/git-interpret-trailers.txt @@ -9,68 +9,105 @@ SYNOPSIS -------- [verse] 'git interpret-trailers' [--in-place] [--trim-empty] - [(--trailer <token>[(=|:)<value>])...] + [(--trailer (<key>|<keyAlias>)[(=|:)<value>])...] [--parse] [<file>...] DESCRIPTION ----------- -Help parsing or adding 'trailers' lines, that look similar to RFC 822 e-mail +Add or parse 'trailer' lines that look similar to RFC 822 e-mail headers, at the end of the otherwise free-form part of a commit -message. +message. For example, in the following commit message -This command reads some patches or commit messages from either the -<file> arguments or the standard input if no <file> is specified. If -`--parse` is specified, the output consists of the parsed trailers. +------------------------------------------------ +subject + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. + +Signed-off-by: Alice <alice@example.com> +Signed-off-by: Bob <bob@example.com> +------------------------------------------------ + +the last two lines starting with "Signed-off-by" are trailers. + +This command reads commit messages from either the +<file> arguments or the standard input if no <file> is specified. +If `--parse` is specified, the output consists of the parsed trailers +coming from the input, without influencing them with any command line +options or configuration variables. + +Otherwise, this command applies `trailer.*` configuration variables +(which could potentially add new trailers, as well as reposition them), +as well as any command line arguments that can override configuration +variables (such as `--trailer=...` which could also add new trailers), +to each input file. The result is emitted on the standard output. -Otherwise, this command applies the arguments passed using the -`--trailer` option, if any, to the commit message part of each input -file. The result is emitted on the standard output. +This command can also operate on the output of linkgit:git-format-patch[1], +which is more elaborate than a plain commit message. Namely, such output +includes a commit message (as above), a "---" divider line, and a patch part. +For these inputs, the divider and patch parts are not modified by +this command and are emitted as is on the output, unless +`--no-divider` is specified. Some configuration variables control the way the `--trailer` arguments -are applied to each commit message and the way any existing trailer in -the commit message is changed. They also make it possible to +are applied to each input and the way any existing trailer in +the input is changed. They also make it possible to automatically add some trailers. -By default, a '<token>=<value>' or '<token>:<value>' argument given +By default, a '<key>=<value>' or '<key>:<value>' argument given using `--trailer` will be appended after the existing trailers only if -the last trailer has a different (<token>, <value>) pair (or if there -is no existing trailer). The <token> and <value> parts will be trimmed +the last trailer has a different (<key>, <value>) pair (or if there +is no existing trailer). The <key> and <value> parts will be trimmed to remove starting and trailing whitespace, and the resulting trimmed -<token> and <value> will appear in the message like this: +<key> and <value> will appear in the output like this: ------------------------------------------------ -token: value +key: value ------------------------------------------------ -This means that the trimmed <token> and <value> will be separated by +This means that the trimmed <key> and <value> will be separated by `': '` (one colon followed by one space). +For convenience, a <keyAlias> can be configured to make using `--trailer` +shorter to type on the command line. This can be configured using the +'trailer.<keyAlias>.key' configuration variable. The <keyAlias> must be a prefix +of the full <key> string, although case sensitivity does not matter. For +example, if you have + +------------------------------------------------ +trailer.sign.key "Signed-off-by: " +------------------------------------------------ + +in your configuration, you only need to specify `--trailer="sign: foo"` +on the command line instead of `--trailer="Signed-off-by: foo"`. + By default the new trailer will appear at the end of all the existing trailers. If there is no existing trailer, the new trailer will appear -after the commit message part of the output, and, if there is no line -with only spaces at the end of the commit message part, one blank line -will be added before the new trailer. +at the end of the input. A blank line will be added before the new +trailer if there isn't one already. -Existing trailers are extracted from the input message by looking for +Existing trailers are extracted from the input by looking for a group of one or more lines that (i) is all trailers, or (ii) contains at least one Git-generated or user-configured trailer and consists of at least 25% trailers. The group must be preceded by one or more empty (or whitespace-only) lines. -The group must either be at the end of the message or be the last +The group must either be at the end of the input or be the last non-whitespace lines before a line that starts with '---' (followed by a -space or the end of the line). Such three minus signs start the patch -part of the message. See also `--no-divider` below. +space or the end of the line). When reading trailers, there can be no whitespace before or inside the -token, but any number of regular space and tab characters are allowed -between the token and the separator. There can be whitespaces before, -inside or after the value. The value may be split over multiple lines +<key>, but any number of regular space and tab characters are allowed +between the <key> and the separator. There can be whitespaces before, +inside or after the <value>. The <value> may be split over multiple lines with each subsequent line starting with at least one whitespace, like -the "folding" in RFC 822. +the "folding" in RFC 822. Example: -Note that 'trailers' do not follow and are not intended to follow many -rules for RFC 822 headers. For example they do not follow -the encoding rules and probably many other rules. +------------------------------------------------ +key: This is a very long value, with spaces and + newlines in it. +------------------------------------------------ + +Note that trailers do not follow (nor are they intended to follow) many of the +rules for RFC 822 headers. For example they do not follow the encoding rule. OPTIONS ------- @@ -79,38 +116,47 @@ OPTIONS --trim-empty:: If the <value> part of any trailer contains only whitespace, - the whole trailer will be removed from the resulting message. + the whole trailer will be removed from the output. This applies to existing trailers as well as new trailers. ---trailer <token>[(=|:)<value>]:: - Specify a (<token>, <value>) pair that should be applied as a - trailer to the input messages. See the description of this +--trailer <key>[(=|:)<value>]:: + Specify a (<key>, <value>) pair that should be applied as a + trailer to the inputs. See the description of this command. --where <placement>:: --no-where:: Specify where all new trailers will be added. A setting - provided with '--where' overrides all configuration variables + provided with '--where' overrides the `trailer.where` and any + applicable `trailer.<keyAlias>.where` configuration variables and applies to all '--trailer' options until the next occurrence of - '--where' or '--no-where'. Possible values are `after`, `before`, - `end` or `start`. + '--where' or '--no-where'. Upon encountering '--no-where', clear the + effect of any previous use of '--where', such that the relevant configuration + variables are no longer overridden. Possible placements are `after`, + `before`, `end` or `start`. --if-exists <action>:: --no-if-exists:: Specify what action will be performed when there is already at - least one trailer with the same <token> in the message. A setting - provided with '--if-exists' overrides all configuration variables + least one trailer with the same <key> in the input. A setting + provided with '--if-exists' overrides the `trailer.ifExists` and any + applicable `trailer.<keyAlias>.ifExists` configuration variables and applies to all '--trailer' options until the next occurrence of - '--if-exists' or '--no-if-exists'. Possible actions are `addIfDifferent`, + '--if-exists' or '--no-if-exists'. Upon encountering '--no-if-exists, clear the + effect of any previous use of '--if-exists, such that the relevant configuration + variables are no longer overridden. Possible actions are `addIfDifferent`, `addIfDifferentNeighbor`, `add`, `replace` and `doNothing`. --if-missing <action>:: --no-if-missing:: Specify what action will be performed when there is no other - trailer with the same <token> in the message. A setting - provided with '--if-missing' overrides all configuration variables + trailer with the same <key> in the input. A setting + provided with '--if-missing' overrides the `trailer.ifMissing` and any + applicable `trailer.<keyAlias>.ifMissing` configuration variables and applies to all '--trailer' options until the next occurrence of - '--if-missing' or '--no-if-missing'. Possible actions are `doNothing` + '--if-missing' or '--no-if-missing'. Upon encountering '--no-if-missing, + clear the effect of any previous use of '--if-missing, such that the relevant + configuration variables are no longer overridden. Possible actions are `doNothing` or `add`. --only-trailers:: @@ -118,16 +164,19 @@ OPTIONS --only-input:: Output only trailers that exist in the input; do not add any - from the command-line or by following configured `trailer.*` - rules. + from the command-line or by applying `trailer.*` configuration + variables. --unfold:: - Remove any whitespace-continuation in trailers, so that each - trailer appears on a line by itself with its full content. + If a trailer has a value that runs over multiple lines (aka "folded"), + reformat the value into a single line. --parse:: A convenience alias for `--only-trailers --only-input - --unfold`. + --unfold`. This makes it easier to only see the trailers coming from the + input without influencing them with any command line options or + configuration variables, while also making the output machine-friendly with + --unfold. --no-divider:: Do not treat `---` as the end of the commit message. Use this @@ -148,11 +197,11 @@ used when another separator is not specified in the config for this trailer. + For example, if the value for this option is "%=$", then only lines -using the format '<token><sep><value>' with <sep> containing '%', '=' +using the format '<key><sep><value>' with <sep> containing '%', '=' or '$' and then spaces will be considered trailers. And '%' will be the default separator used, so by default trailers will appear like: -'<token>% <value>' (one percent sign and one space will appear between -the token and the value). +'<key>% <value>' (one percent sign and one space will appear between +the key and the value). trailer.where:: This option tells where a new trailer will be added. @@ -166,41 +215,41 @@ If it is `start`, then each new trailer will appear at the start, instead of the end, of the existing trailers. + If it is `after`, then each new trailer will appear just after the -last trailer with the same <token>. +last trailer with the same <key>. + If it is `before`, then each new trailer will appear just before the -first trailer with the same <token>. +first trailer with the same <key>. trailer.ifexists:: This option makes it possible to choose what action will be performed when there is already at least one trailer with the - same <token> in the message. + same <key> in the input. + The valid values for this option are: `addIfDifferentNeighbor` (this is the default), `addIfDifferent`, `add`, `replace` or `doNothing`. + With `addIfDifferentNeighbor`, a new trailer will be added only if no -trailer with the same (<token>, <value>) pair is above or below the line +trailer with the same (<key>, <value>) pair is above or below the line where the new trailer will be added. + With `addIfDifferent`, a new trailer will be added only if no trailer -with the same (<token>, <value>) pair is already in the message. +with the same (<key>, <value>) pair is already in the input. + With `add`, a new trailer will be added, even if some trailers with -the same (<token>, <value>) pair are already in the message. +the same (<key>, <value>) pair are already in the input. + -With `replace`, an existing trailer with the same <token> will be +With `replace`, an existing trailer with the same <key> will be deleted and the new trailer will be added. The deleted trailer will be -the closest one (with the same <token>) to the place where the new one +the closest one (with the same <key>) to the place where the new one will be added. + With `doNothing`, nothing will be done; that is no new trailer will be -added if there is already one with the same <token> in the message. +added if there is already one with the same <key> in the input. trailer.ifmissing:: This option makes it possible to choose what action will be performed when there is not yet any trailer with the same - <token> in the message. + <key> in the input. + The valid values for this option are: `add` (this is the default) and `doNothing`. @@ -209,100 +258,106 @@ With `add`, a new trailer will be added. + With `doNothing`, nothing will be done. -trailer.<token>.key:: - This `key` will be used instead of <token> in the trailer. At - the end of this key, a separator can appear and then some - space characters. By default the only valid separator is ':', - but this can be changed using the `trailer.separators` config - variable. +trailer.<keyAlias>.key:: + Defines a <keyAlias> for the <key>. The <keyAlias> must be a + prefix (case does not matter) of the <key>. For example, in `git + config trailer.ack.key "Acked-by"` the "Acked-by" is the <key> and + the "ack" is the <keyAlias>. This configuration allows the shorter + `--trailer "ack:..."` invocation on the command line using the "ack" + <keyAlias> instead of the longer `--trailer "Acked-by:..."`. ++ +At the end of the <key>, a separator can appear and then some +space characters. By default the only valid separator is ':', +but this can be changed using the `trailer.separators` config +variable. + -If there is a separator, then the key will be used instead of both the -<token> and the default separator when adding the trailer. +If there is a separator in the key, then it overrides the default +separator when adding the trailer. -trailer.<token>.where:: +trailer.<keyAlias>.where:: This option takes the same values as the 'trailer.where' configuration variable and it overrides what is specified by - that option for trailers with the specified <token>. + that option for trailers with the specified <keyAlias>. -trailer.<token>.ifexists:: +trailer.<keyAlias>.ifexists:: This option takes the same values as the 'trailer.ifexists' configuration variable and it overrides what is specified by - that option for trailers with the specified <token>. + that option for trailers with the specified <keyAlias>. -trailer.<token>.ifmissing:: +trailer.<keyAlias>.ifmissing:: This option takes the same values as the 'trailer.ifmissing' configuration variable and it overrides what is specified by - that option for trailers with the specified <token>. + that option for trailers with the specified <keyAlias>. -trailer.<token>.command:: - This option behaves in the same way as 'trailer.<token>.cmd', except +trailer.<keyAlias>.command:: + Deprecated in favor of 'trailer.<keyAlias>.cmd'. + This option behaves in the same way as 'trailer.<keyAlias>.cmd', except that it doesn't pass anything as argument to the specified command. Instead the first occurrence of substring $ARG is replaced by the - value that would be passed as argument. + <value> that would be passed as argument. + -The 'trailer.<token>.command' option has been deprecated in favor of -'trailer.<token>.cmd' due to the fact that $ARG in the user's command is +Note that $ARG in the user's command is only replaced once and that the original way of replacing $ARG is not safe. + -When both 'trailer.<token>.cmd' and 'trailer.<token>.command' are given -for the same <token>, 'trailer.<token>.cmd' is used and -'trailer.<token>.command' is ignored. - -trailer.<token>.cmd:: - This option can be used to specify a shell command that will be called: - once to automatically add a trailer with the specified <token>, and then - each time a '--trailer <token>=<value>' argument to modify the <value> of - the trailer that this option would produce. +When both 'trailer.<keyAlias>.cmd' and 'trailer.<keyAlias>.command' are given +for the same <keyAlias>, 'trailer.<keyAlias>.cmd' is used and +'trailer.<keyAlias>.command' is ignored. + +trailer.<keyAlias>.cmd:: + This option can be used to specify a shell command that will be called + once to automatically add a trailer with the specified <keyAlias>, and then + called each time a '--trailer <keyAlias>=<value>' argument is specified to + modify the <value> of the trailer that this option would produce. + When the specified command is first called to add a trailer -with the specified <token>, the behavior is as if a special -'--trailer <token>=<value>' argument was added at the beginning +with the specified <keyAlias>, the behavior is as if a special +'--trailer <keyAlias>=<value>' argument was added at the beginning of the "git interpret-trailers" command, where <value> is taken to be the standard output of the command with any leading and trailing whitespace trimmed off. + -If some '--trailer <token>=<value>' arguments are also passed +If some '--trailer <keyAlias>=<value>' arguments are also passed on the command line, the command is called again once for each -of these arguments with the same <token>. And the <value> part +of these arguments with the same <keyAlias>. And the <value> part of these arguments, if any, will be passed to the command as its first argument. This way the command can produce a <value> computed -from the <value> passed in the '--trailer <token>=<value>' argument. +from the <value> passed in the '--trailer <keyAlias>=<value>' argument. EXAMPLES -------- * Configure a 'sign' trailer with a 'Signed-off-by' key, and then - add two of these trailers to a message: + add two of these trailers to a commit message file: + ------------ $ git config trailer.sign.key "Signed-off-by" $ cat msg.txt subject -message +body text $ git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>' <msg.txt subject -message +body text Signed-off-by: Alice <alice@example.com> Signed-off-by: Bob <bob@example.com> ------------ -* Use the `--in-place` option to edit a message file in place: +* Use the `--in-place` option to edit a commit message file in place: + ------------ $ cat msg.txt subject -message +body text Signed-off-by: Bob <bob@example.com> $ git interpret-trailers --trailer 'Acked-by: Alice <alice@example.com>' --in-place msg.txt $ cat msg.txt subject -message +body text Signed-off-by: Bob <bob@example.com> Acked-by: Alice <alice@example.com> @@ -325,7 +380,7 @@ $ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Re $ cat msg1.txt subject -message +body text $ git config trailer.sign.key "Signed-off-by: " $ git config trailer.sign.ifmissing add $ git config trailer.sign.ifexists doNothing @@ -333,19 +388,19 @@ $ git config trailer.sign.cmd 'echo "$(git config user.name) <$(git config user. $ git interpret-trailers --trailer sign <msg1.txt subject -message +body text Signed-off-by: Bob <bob@example.com> $ cat msg2.txt subject -message +body text Signed-off-by: Alice <alice@example.com> $ git interpret-trailers --trailer sign <msg2.txt subject -message +body text Signed-off-by: Alice <alice@example.com> ------------ @@ -373,14 +428,14 @@ test -n "$1" && git log --author="$1" --pretty="%an <%ae>" -1 || true $ cat msg.txt subject -message +body text $ git config trailer.help.key "Helped-by: " $ git config trailer.help.ifExists "addIfDifferentNeighbor" $ git config trailer.help.cmd "~/bin/glog-find-author" $ git interpret-trailers --trailer="help:Junio" --trailer="help:Couder" <msg.txt subject -message +body text Helped-by: Junio C Hamano <gitster@pobox.com> Helped-by: Christian Couder <christian.couder@gmail.com> @@ -397,14 +452,14 @@ test -n "$1" && git log --grep "$1" --pretty=reference -1 || true $ cat msg.txt subject -message +body text $ git config trailer.ref.key "Reference-to: " $ git config trailer.ref.ifExists "replace" $ git config trailer.ref.cmd "~/bin/glog-grep" $ git interpret-trailers --trailer="ref:Add copyright notices." <msg.txt subject -message +body text Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07) ------------ @@ -416,7 +471,7 @@ Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07) $ cat msg.txt subject -message +body text see: HEAD~2 $ cat ~/bin/glog-ref @@ -429,7 +484,7 @@ $ git config trailer.see.cmd "glog-ref" $ git interpret-trailers --trailer=see <msg.txt subject -message +body text See-also: fe3187489d69c4 (subject of related commit) ------------ diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 2a66cf8880..579682172f 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -120,11 +120,11 @@ By default, `git log` does not generate any diff output. The options below can be used to show the changes made by each commit. Note that unless one of `--diff-merges` variants (including short -`-m`, `-c`, and `--cc` options) is explicitly given, merge commits +`-m`, `-c`, `--cc`, and `--dd` options) is explicitly given, merge commits will not show a diff, even if a diff format like `--patch` is selected, nor will they match search options like `-S`. The exception is when `--first-parent` is in use, in which case `first-parent` is -the default format. +the default format for merge commits. :git-log: 1 :diff-merges-default: `off` diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 1abdd3c21c..f65a8cd91d 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -25,12 +25,12 @@ SYNOPSIS DESCRIPTION ----------- -This merges the file listing in the index with the actual working +This command merges the file listing in the index with the actual working directory list, and shows different combinations of the two. -One or more of the options below may be used to determine the files +Several flags can be used to determine which files are shown, and each file may be printed multiple times if there are -multiple entries in the index or multiple statuses are applicable for +multiple entries in the index or if multiple statuses are applicable for the relevant file selection options. OPTIONS @@ -62,7 +62,7 @@ OPTIONS matching an exclude pattern. When showing "other" files (i.e. when used with '-o'), show only those matched by an exclude pattern. Standard ignore rules are not automatically - activated, therefore at least one of the `--exclude*` options + activated; therefore, at least one of the `--exclude*` options is required. -s:: @@ -141,7 +141,7 @@ OPTIONS Show status tags together with filenames. Note that for scripting purposes, linkgit:git-status[1] `--porcelain` and linkgit:git-diff-files[1] `--name-status` are almost always - superior alternatives, and users should look at + superior alternatives; users should look at linkgit:git-status[1] `--short` or linkgit:git-diff[1] `--name-status` for more user-friendly alternatives. + @@ -270,8 +270,14 @@ interpolated. The following "fieldname" are understood: objectmode:: The mode of the file which is recorded in the index. +objecttype:: + The object type of the file which is recorded in the index. objectname:: The name of the file which is recorded in the index. +objectsize[:padded]:: + The object size of the file which is recorded in the index + ("-" if the object is a `commit` or `tree`). + It also supports a padded format of size with "%(objectsize:padded)". stage:: The stage of the file which is recorded in the index. eolinfo:index:: diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt index ff3da547dd..1c4f696ab5 100644 --- a/Documentation/git-ls-remote.txt +++ b/Documentation/git-ls-remote.txt @@ -96,27 +96,51 @@ OPTIONS separator (so `bar` matches `refs/heads/bar` but not `refs/heads/foobar`). +OUTPUT +------ + +The output is in the format: + +------------ +<oid> TAB <ref> LF +------------ + +When showing an annotated tag, unless `--refs` is given, two such +lines are shown: one with the refname for the tag itself as `<ref>`, +and another with `<ref>` followed by `^{}`. The `<oid>` on the latter +line shows the name of the object the tag points at. + EXAMPLES -------- +* List all references (including symbolics and pseudorefs), peeling + tags: ++ +---- +$ git ls-remote +27d43aaaf50ef0ae014b88bba294f93658016a2e HEAD +950264636c68591989456e3ba0a5442f93152c1a refs/heads/main +d9ab777d41f92a8c1684c91cfb02053d7dd1046b refs/heads/next +d4ca2e3147b409459955613c152220f4db848ee1 refs/tags/v2.40.0 +73876f4861cd3d187a4682290ab75c9dccadbc56 refs/tags/v2.40.0^{} ---- -$ git ls-remote --tags . -d6602ec5194c87b0fc87103ca4d67251c76f233a refs/tags/v0.99 -f25a265a342aed6041ab0cc484224d9ca54b6f41 refs/tags/v0.99.1 -7ceca275d047c90c0c7d5afb13ab97efdf51bd6e refs/tags/v0.99.3 -c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2 -0918385dbd9656cab0d1d81ba7453d49bbc16250 refs/tags/junio-gpg-pub +* List all references matching given patterns: ++ +---- $ git ls-remote http://www.kernel.org/pub/scm/git/git.git master seen rc 5fe978a5381f1fbad26a80e682ddd2a401966740 refs/heads/master c781a84b5204fb294c9ccc79f8b3baceeb32c061 refs/heads/seen +---- -$ git remote add korg http://www.kernel.org/pub/scm/git/git.git -$ git ls-remote --tags korg v\* -d6602ec5194c87b0fc87103ca4d67251c76f233a refs/tags/v0.99 -f25a265a342aed6041ab0cc484224d9ca54b6f41 refs/tags/v0.99.1 -c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2 -7ceca275d047c90c0c7d5afb13ab97efdf51bd6e refs/tags/v0.99.3 +* List only tags matching a given wildcard pattern: ++ +---- +$ git ls-remote --tags http://www.kernel.org/pub/scm/git/git.git v\* +485a869c64a68cc5795dd99689797c5900f4716d refs/tags/v2.39.2 +cbf04937d5b9fcf0a76c28f69e6294e9e3ecd7e6 refs/tags/v2.39.2^{} +d4ca2e3147b409459955613c152220f4db848ee1 refs/tags/v2.40.0 +73876f4861cd3d187a4682290ab75c9dccadbc56 refs/tags/v2.40.0^{} ---- SEE ALSO diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt index 0240adb8ee..6572095d8d 100644 --- a/Documentation/git-ls-tree.txt +++ b/Documentation/git-ls-tree.txt @@ -86,9 +86,9 @@ OPTIONS --format=<format>:: A string that interpolates `%(fieldname)` from the result being shown. It also interpolates `%%` to `%`, and - `%xx` where `xx` are hex digits interpolates to character - with hex code `xx`; for example `%00` interpolates to - `\0` (NUL), `%09` to `\t` (TAB) and `%0a` to `\n` (LF). + `%xNN` where `NN` are hex digits interpolates to character + with hex code `NN`; for example `%x00` interpolates to + `\0` (NUL), `%x09` to `\t` (TAB) and `%x0a` to `\n` (LF). When specified, `--format` cannot be combined with other format-altering options, including `--long`, `--name-only` and `--object-only`. @@ -145,7 +145,7 @@ FIELD NAMES ----------- Various values from structured fields can be used to interpolate -into the resulting output. For each outputing line, the following +into the resulting output. For each outputting line, the following names can be used: objectmode:: diff --git a/Documentation/git-mailsplit.txt b/Documentation/git-mailsplit.txt index e3b2a88c4b..3f0a6662c8 100644 --- a/Documentation/git-mailsplit.txt +++ b/Documentation/git-mailsplit.txt @@ -34,7 +34,7 @@ OPTIONS -b:: If any file doesn't begin with a From line, assume it is a - single mail message instead of signaling error. + single mail message instead of signaling an error. -d<prec>:: Instead of the default 4 digits with leading zeros, diff --git a/Documentation/git-maintenance.txt b/Documentation/git-maintenance.txt index 805e5a2e3a..51d0f7e94b 100644 --- a/Documentation/git-maintenance.txt +++ b/Documentation/git-maintenance.txt @@ -102,9 +102,9 @@ prefetch:: requested refs within `refs/prefetch/`. Also, tags are not updated. + This is done to avoid disrupting the remote-tracking branches. The end users -expect these refs to stay unmoved unless they initiate a fetch. With prefetch -task, however, the objects necessary to complete a later real fetch would -already be obtained, so the real fetch would go faster. In the ideal case, +expect these refs to stay unmoved unless they initiate a fetch. However, +with the prefetch task, the objects necessary to complete a later real fetch +would already be obtained, making the real fetch faster. In the ideal case, it will just become an update to a bunch of remote-tracking branches without any object transfer. diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt index b01ba3d356..5ab957cfbc 100644 --- a/Documentation/git-merge-base.txt +++ b/Documentation/git-merge-base.txt @@ -18,7 +18,7 @@ SYNOPSIS DESCRIPTION ----------- -'git merge-base' finds best common ancestor(s) between two commits to use +'git merge-base' finds the best common ancestor(s) between two commits to use in a three-way merge. One common ancestor is 'better' than another common ancestor if the latter is an ancestor of the former. A common ancestor that does not have any better common ancestor is a 'best common @@ -28,7 +28,7 @@ merge base for a pair of commits. OPERATION MODES --------------- -As the most common special case, specifying only two commits on the +In the most common special case, specifying only two commits on the command line means computing the merge base between the given two commits. More generally, among the two commits to compute the merge base from, @@ -64,7 +64,7 @@ from linkgit:git-show-branch[1] when used with the `--merge-base` option. the two commits, but also takes into account the reflog of <ref> to see if the history leading to <commit> forked from an earlier incarnation of the branch <ref> (see discussion - on this mode below). + of this mode below). OPTIONS ------- @@ -88,7 +88,7 @@ For example, with this topology: the merge base between 'A' and 'B' is '1'. -Given three commits 'A', 'B' and 'C', `git merge-base A B C` will compute the +Given three commits 'A', 'B', and 'C', `git merge-base A B C` will compute the merge base between 'A' and a hypothetical commit 'M', which is a merge between 'B' and 'C'. For example, with this topology: @@ -130,7 +130,7 @@ When the history involves criss-cross merges, there can be more than one ---2---o---o---B .... -both '1' and '2' are merge-bases of A and B. Neither one is better than +both '1' and '2' are merge bases of A and B. Neither one is better than the other (both are 'best' merge bases). When the `--all` option is not given, it is unspecified which best one is output. @@ -204,7 +204,7 @@ will find B0, and $ git rebase --onto origin/master $fork_point topic -will replay D0, D1 and D on top of B to create a new history of this +will replay D0, D1, and D on top of B to create a new history of this shape: .... diff --git a/Documentation/git-merge-file.txt b/Documentation/git-merge-file.txt index 7e9093fab6..71915a00fa 100644 --- a/Documentation/git-merge-file.txt +++ b/Documentation/git-merge-file.txt @@ -11,19 +11,20 @@ SYNOPSIS [verse] 'git merge-file' [-L <current-name> [-L <base-name> [-L <other-name>]]] [--ours|--theirs|--union] [-p|--stdout] [-q|--quiet] [--marker-size=<n>] - [--[no-]diff3] <current-file> <base-file> <other-file> + [--[no-]diff3] [--object-id] <current> <base> <other> DESCRIPTION ----------- -'git merge-file' incorporates all changes that lead from the `<base-file>` -to `<other-file>` into `<current-file>`. The result ordinarily goes into -`<current-file>`. 'git merge-file' is useful for combining separate changes -to an original. Suppose `<base-file>` is the original, and both -`<current-file>` and `<other-file>` are modifications of `<base-file>`, +Given three files `<current>`, `<base>` and `<other>`, +'git merge-file' incorporates all changes that lead from `<base>` +to `<other>` into `<current>`. The result ordinarily goes into +`<current>`. 'git merge-file' is useful for combining separate changes +to an original. Suppose `<base>` is the original, and both +`<current>` and `<other>` are modifications of `<base>`, then 'git merge-file' combines both changes. -A conflict occurs if both `<current-file>` and `<other-file>` have changes +A conflict occurs if both `<current>` and `<other>` have changes in a common segment of lines. If a conflict is found, 'git merge-file' normally outputs a warning and brackets the conflict with lines containing <<<<<<< and >>>>>>> markers. A typical conflict will look like this: @@ -36,10 +37,14 @@ normally outputs a warning and brackets the conflict with lines containing If there are conflicts, the user should edit the result and delete one of the alternatives. When `--ours`, `--theirs`, or `--union` option is in effect, -however, these conflicts are resolved favouring lines from `<current-file>`, -lines from `<other-file>`, or lines from both respectively. The length of the +however, these conflicts are resolved favouring lines from `<current>`, +lines from `<other>`, or lines from both respectively. The length of the conflict markers can be given with the `--marker-size` option. +If `--object-id` is specified, exactly the same behavior occurs, except that +instead of specifying what to merge as files, it is specified as a list of +object IDs referring to blobs. + The exit value of this program is negative on error, and the number of conflicts otherwise (truncated to 127 if there are more than that many conflicts). If the merge was clean, the exit value is 0. @@ -52,6 +57,14 @@ linkgit:git[1]. OPTIONS ------- +--object-id:: + Specify the contents to merge as blobs in the current repository instead of + files. In this case, the operation must take place within a valid repository. ++ +If the `-p` option is specified, the merged file (including conflicts, if any) +goes to standard output as normal; otherwise, the merged file is written to the +object store and the object ID of its blob is written to standard output. + -L <label>:: This option may be given up to three times, and specifies labels to be used in place of the @@ -62,7 +75,7 @@ OPTIONS -p:: Send results to standard output instead of overwriting - `<current-file>`. + `<current>`. -q:: Quiet; do not warn about conflicts. @@ -79,6 +92,12 @@ OPTIONS Instead of leaving conflicts in the file, resolve conflicts favouring our (or their or both) side of the lines. +--diff-algorithm={patience|minimal|histogram|myers}:: + Use a different diff algorithm while merging. The current default is "myers", + but selecting more recent algorithm such as "histogram" can help + avoid mismerges that occur due to unimportant matching lines + (such as braces from distinct functions). See also + linkgit:git-diff[1] `--diff-algorithm`. EXAMPLES -------- @@ -93,6 +112,11 @@ EXAMPLES merges tmp/a123 and tmp/c345 with the base tmp/b234, but uses labels `a` and `c` instead of `tmp/a123` and `tmp/c345`. +`git merge-file -p --object-id abc1234 def567 890abcd`:: + + combines the changes of the blob abc1234 and 890abcd since def567, + tries to merge them and writes the result to standard output + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-merge-tree.txt b/Documentation/git-merge-tree.txt index ffc4fbf7e8..b50acace3b 100644 --- a/Documentation/git-merge-tree.txt +++ b/Documentation/git-merge-tree.txt @@ -19,12 +19,12 @@ DESCRIPTION This command has a modern `--write-tree` mode and a deprecated `--trivial-merge` mode. With the exception of the <<DEPMERGE,DEPRECATED DESCRIPTION>> section at the end, the rest of -this documentation describes modern `--write-tree` mode. +this documentation describes the modern `--write-tree` mode. Performs a merge, but does not make any new commits and does not read from or write to either the working tree or index. -The performed merge will use the same feature as the "real" +The performed merge will use the same features as the "real" linkgit:git-merge[1], including: * three way content merges of individual files @@ -253,7 +253,7 @@ Do NOT attempt to guess or make the user guess the conflict types from the <<CFI,Conflicted file info>> list. The information there is insufficient to do so. For example: Rename/rename(1to2) conflicts (both sides renamed the same file differently) will result in three different -file having higher order stages (but each only has one higher order +files having higher order stages (but each only has one higher order stage), with no way (short of the <<IM,Informational messages>> section) to determine which three files are related. File/directory conflicts also result in a file with exactly one higher order stage. @@ -263,7 +263,7 @@ a file with exactly one higher order stage. In all cases, the <<IM,Informational messages>> section has the necessary info, though it is not designed to be machine parseable. -Do NOT assume that each paths from <<CFI,Conflicted file info>>, and +Do NOT assume that each path from <<CFI,Conflicted file info>>, and the logical conflicts in the <<IM,Informational messages>> have a one-to-one mapping, nor that there is a one-to-many mapping, nor a many-to-one mapping. Many-to-many mappings exist, meaning that each diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 0aeff572a5..3e9557a44b 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -194,9 +194,13 @@ happens: versions: stage 1 stores the version from the common ancestor, stage 2 from `HEAD`, and stage 3 from `MERGE_HEAD` (you can inspect the stages with `git ls-files -u`). The working - tree files contain the result of the "merge" program; i.e. 3-way + tree files contain the result of the merge operation; i.e. 3-way merge results with familiar conflict markers `<<<` `===` `>>>`. -5. No other changes are made. In particular, the local +5. A ref named `AUTO_MERGE` is written, pointing to a tree + corresponding to the current content of the working tree (including + conflict markers for textual conflicts). Note that this ref is only + written when the 'ort' merge strategy is used (the default). +6. No other changes are made. In particular, the local modifications you had before you started merge will stay the same and the index entries for them stay as they were, i.e. matching `HEAD`. @@ -332,11 +336,12 @@ After seeing a conflict, you can do two things: You can work through the conflict with a number of tools: * Use a mergetool. `git mergetool` to launch a graphical - mergetool which will work you through the merge. + mergetool which will work through the merge with you. * Look at the diffs. `git diff` will show a three-way diff, highlighting changes from both the `HEAD` and `MERGE_HEAD` - versions. + versions. `git diff AUTO_MERGE` will show what changes you've + made so far to resolve textual conflicts. * Look at the diffs from each branch. `git log --merge -p <path>` will show diffs first for the `HEAD` version and then the diff --git a/Documentation/git-mergetool--lib.txt b/Documentation/git-mergetool--lib.txt index 3e8f59ac0e..0726b560d4 100644 --- a/Documentation/git-mergetool--lib.txt +++ b/Documentation/git-mergetool--lib.txt @@ -28,22 +28,22 @@ to define the operation mode for the functions listed below. FUNCTIONS --------- get_merge_tool:: - returns a merge tool. the return code is 1 if we returned a guessed + Returns a merge tool. The return code is 1 if we returned a guessed merge tool, else 0. '$GIT_MERGETOOL_GUI' may be set to 'true' to search for the appropriate guitool. get_merge_tool_cmd:: - returns the custom command for a merge tool. + Returns the custom command for a merge tool. get_merge_tool_path:: - returns the custom path for a merge tool. + Returns the custom path for a merge tool. initialize_merge_tool:: - bring merge tool specific functions into scope so they can be used or + Brings merge tool specific functions into scope so they can be used or overridden. run_merge_tool:: - launches a merge tool given the tool name and a true/false + Launches a merge tool given the tool name and a true/false flag to indicate whether a merge base is present. '$MERGED', '$LOCAL', '$REMOTE', and '$BASE' must be defined for use by the merge tool. diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt index 07535f6576..b9e20c5dcd 100644 --- a/Documentation/git-mergetool.txt +++ b/Documentation/git-mergetool.txt @@ -17,7 +17,7 @@ Use `git mergetool` to run one of several merge utilities to resolve merge conflicts. It is typically run after 'git merge'. If one or more <file> parameters are given, the merge tool program will -be run to resolve differences on each file (skipping those without +be run to resolve differences in each file (skipping those without conflicts). Specifying a directory will include all unresolved files in that path. If no <file> names are specified, 'git mergetool' will run the merge tool program on every file with merge conflicts. @@ -49,7 +49,7 @@ variable `mergetool.<tool>.cmd`. + When 'git mergetool' is invoked with this tool (either through the `-t` or `--tool` option or the `merge.tool` configuration -variable) the configured command line will be invoked with `$BASE` +variable), the configured command line will be invoked with `$BASE` set to the name of a temporary file containing the common base for the merge, if available; `$LOCAL` set to the name of a temporary file containing the contents of the file on the current branch; @@ -81,7 +81,7 @@ success of the resolution after the custom tool has exited. -g:: --gui:: - When 'git-mergetool' is invoked with the `-g` or `--gui` option + When 'git-mergetool' is invoked with the `-g` or `--gui` option, the default merge tool will be read from the configured `merge.guitool` variable instead of `merge.tool`. If `merge.guitool` is not set, we will fallback to the tool @@ -115,7 +115,7 @@ These are safe to remove once a file has been merged and its `git mergetool` session has completed. Setting the `mergetool.keepBackup` configuration variable to `false` -causes `git mergetool` to automatically remove the backup as files +causes `git mergetool` to automatically remove the backup files as files are successfully merged. BACKEND SPECIFIC HINTS diff --git a/Documentation/git-mktag.txt b/Documentation/git-mktag.txt index 466a697519..006d759962 100644 --- a/Documentation/git-mktag.txt +++ b/Documentation/git-mktag.txt @@ -14,7 +14,7 @@ SYNOPSIS DESCRIPTION ----------- -Reads a tag contents on standard input and creates a tag object. The +Reads a tag's contents on standard input and creates a tag object. The output is the new tag's <object> identifier. This command is mostly equivalent to linkgit:git-hash-object[1] @@ -27,13 +27,13 @@ write a tag found in `my-tag`: The difference is that mktag will die before writing the tag if the tag doesn't pass a linkgit:git-fsck[1] check. -The "fsck" check done mktag is stricter than what linkgit:git-fsck[1] +The "fsck" check done by mktag is stricter than what linkgit:git-fsck[1] would run by default in that all `fsck.<msg-id>` messages are promoted from warnings to errors (so e.g. a missing "tagger" line is an error). Extra headers in the object are also an error under mktag, but ignored by linkgit:git-fsck[1]. This extra check can be turned off by setting -the appropriate `fsck.<msg-id>` varible: +the appropriate `fsck.<msg-id>` variable: git -c fsck.extraHeaderEntry=ignore mktag <my-tag-with-headers @@ -56,7 +56,7 @@ has a very simple fixed format: four lines of tagger <tagger> followed by some 'optional' free-form message (some tags created -by older Git may not have `tagger` line). The message, when it +by older Git may not have a `tagger` line). The message, when it exists, is separated by a blank line from the header. The message part may contain a signature that Git itself doesn't care about, but that can be verified with gpg. diff --git a/Documentation/git-mktree.txt b/Documentation/git-mktree.txt index 76b44f4da1..383f09dd33 100644 --- a/Documentation/git-mktree.txt +++ b/Documentation/git-mktree.txt @@ -25,13 +25,13 @@ OPTIONS --missing:: Allow missing objects. The default behaviour (without this option) - is to verify that each tree entry's sha1 identifies an existing + is to verify that each tree entry's hash identifies an existing object. This option has no effect on the treatment of gitlink entries (aka "submodules") which are always allowed to be missing. --batch:: Allow building of more than one tree object before exiting. Each - tree is separated by a single blank line. The final new-line is + tree is separated by a single blank line. The final newline is optional. Note - if the `-z` option is used, lines are terminated with NUL. diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt index fb0220fd18..7f991a3380 100644 --- a/Documentation/git-mv.txt +++ b/Documentation/git-mv.txt @@ -13,7 +13,7 @@ SYNOPSIS DESCRIPTION ----------- -Move or rename a file, directory or symlink. +Move or rename a file, directory, or symlink. git mv [-v] [-f] [-n] [-k] <source> <destination> git mv [-v] [-f] [-n] [-k] <source> ... <destination directory> diff --git a/Documentation/git-name-rev.txt b/Documentation/git-name-rev.txt index 5c56c87025..d4f1c4d594 100644 --- a/Documentation/git-name-rev.txt +++ b/Documentation/git-name-rev.txt @@ -26,7 +26,7 @@ OPTIONS --refs=<pattern>:: Only use refs whose names match a given shell pattern. The pattern - can be one of branch name, tag name or fully qualified ref name. If + can be a branch name, a tag name, or a fully qualified ref name. If given multiple times, use refs whose names match any of the given shell patterns. Use `--no-refs` to clear any previous ref patterns given. diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index efbc10f0f5..f8310e56a8 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -9,10 +9,10 @@ SYNOPSIS -------- [verse] 'git notes' [list [<object>]] -'git notes' add [-f] [--allow-empty] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] +'git notes' add [-f] [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] 'git notes' copy [-f] ( --stdin | <from-object> [<to-object>] ) -'git notes' append [--allow-empty] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] -'git notes' edit [--allow-empty] [<object>] +'git notes' append [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] +'git notes' edit [--allow-empty] [<object>] [--[no-]stripspace] 'git notes' show [<object>] 'git notes' merge [-v | -q] [-s <strategy> ] <notes-ref> 'git notes' merge --commit [-v | -q] @@ -65,7 +65,9 @@ add:: However, if you're using `add` interactively (using an editor to supply the notes contents), then - instead of aborting - the existing notes will be opened in the editor (like the `edit` - subcommand). + subcommand). If you specify multiple `-m` and `-F`, a blank + line will be inserted between the messages. Use the `--separator` + option to insert other delimiters. copy:: Copy the notes for the first object onto the second object (defaults to @@ -85,8 +87,12 @@ corresponding <to-object>. (The optional `<rest>` is ignored so that the command can read the input given to the `post-rewrite` hook.) append:: - Append to the notes of an existing object (defaults to HEAD). - Creates a new notes object if needed. + Append new message(s) given by `-m` or `-F` options to an + existing note, or add them as a new note if one does not + exist, for the object (defaults to HEAD). When appending to + an existing note, a blank line is added before each new + message as an inter-paragraph separator. The separator can + be customized with the `--separator` option. edit:: Edit the notes for a given object (defaults to HEAD). @@ -136,6 +142,7 @@ OPTIONS are concatenated as separate paragraphs. Lines starting with `#` and empty lines other than a single line between paragraphs will be stripped out. + If you wish to keep them verbatim, use `--no-stripspace`. -F <file>:: --file=<file>:: @@ -143,12 +150,16 @@ OPTIONS read the note message from the standard input. Lines starting with `#` and empty lines other than a single line between paragraphs will be stripped out. + If you wish to keep them verbatim, use `--no-stripspace`. -C <object>:: --reuse-message=<object>:: Take the given blob object (for example, another note) as the note message. (Use `git notes copy <object>` instead to - copy notes between objects.) + copy notes between objects.). By default, message will be + copied verbatim, but if you wish to strip out the lines + starting with `#` and empty lines other than a single line + between paragraphs, use with`--stripspace` option. -c <object>:: --reedit-message=<object>:: @@ -159,6 +170,19 @@ OPTIONS Allow an empty note object to be stored. The default behavior is to automatically remove empty notes. +--[no-]separator, --separator=<paragraph-break>:: + Specify a string used as a custom inter-paragraph separator + (a newline is added at the end as needed). If `--no-separator`, no + separators will be added between paragraphs. Defaults to a blank + line. + +--[no-]stripspace:: + Strip leading and trailing whitespace from the note message. + Also strip out empty lines other than a single line between + paragraphs. Lines starting with `#` will be stripped out + in non-editor cases like `-m`, `-F` and `-C`, but not in + editor case like `git notes edit`, `-c`, etc. + --ref <ref>:: Manipulate the notes tree in <ref>. This overrides `GIT_NOTES_REF` and the "core.notesRef" configuration. The ref diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index a9995a932c..e32404c6aa 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -116,9 +116,7 @@ unreachable object whose mtime is newer than the `--cruft-expiration`). + Incompatible with `--unpack-unreachable`, `--keep-unreachable`, `--pack-loose-unreachable`, `--stdin-packs`, as well as any other -options which imply `--revs`. Also incompatible with `--max-pack-size`; -when this option is set, the maximum pack size is not inferred from -`pack.packSizeLimit`. +options which imply `--revs`. --cruft-expiration=<approxidate>:: If specified, objects are eliminated from the cruft pack if they @@ -298,8 +296,8 @@ So does `git bundle` (see linkgit:git-bundle[1]) when it creates a bundle. nevertheless. --filter=<filter-spec>:: - Requires `--stdout`. Omits certain objects (usually blobs) from - the resulting packfile. See linkgit:git-rev-list[1] for valid + Omits certain objects (usually blobs) from the resulting + packfile. See linkgit:git-rev-list[1] for valid `<filter-spec>` forms. --no-filter:: diff --git a/Documentation/git-pack-refs.txt b/Documentation/git-pack-refs.txt index 154081f2de..284956acb3 100644 --- a/Documentation/git-pack-refs.txt +++ b/Documentation/git-pack-refs.txt @@ -8,7 +8,7 @@ git-pack-refs - Pack heads and tags for efficient repository access SYNOPSIS -------- [verse] -'git pack-refs' [--all] [--no-prune] +'git pack-refs' [--all] [--no-prune] [--include <pattern>] [--exclude <pattern>] DESCRIPTION ----------- @@ -51,14 +51,37 @@ The command by default packs all tags and refs that are already packed, and leaves other refs alone. This is because branches are expected to be actively developed and packing their tips does not help performance. -This option causes branch tips to be packed as well. Useful for -a repository with many branches of historical interests. +This option causes all refs to be packed as well, with the exception +of hidden refs, broken refs, and symbolic refs. Useful for a repository +with many branches of historical interests. --no-prune:: The command usually removes loose refs under `$GIT_DIR/refs` hierarchy after packing them. This option tells it not to. +--include <pattern>:: + +Pack refs based on a `glob(7)` pattern. Repetitions of this option +accumulate inclusion patterns. If a ref is both included in `--include` and +`--exclude`, `--exclude` takes precedence. Using `--include` will preclude all +tags from being included by default. Symbolic refs and broken refs will never +be packed. When used with `--all`, it will be a noop. Use `--no-include` to clear +and reset the list of patterns. + +--exclude <pattern>:: + +Do not pack refs matching the given `glob(7)` pattern. Repetitions of this option +accumulate exclusion patterns. Use `--no-exclude` to clear and reset the list of +patterns. If a ref is already packed, including it with `--exclude` will not +unpack it. + +When used with `--all`, pack only loose refs which do not match any of +the provided `--exclude` patterns. + +When used with `--include`, refs provided to `--include`, minus refs that are +provided to `--exclude` will be packed. + BUGS ---- diff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt index 844d6f808a..db742dcfee 100644 --- a/Documentation/git-prune-packed.txt +++ b/Documentation/git-prune-packed.txt @@ -15,7 +15,7 @@ SYNOPSIS DESCRIPTION ----------- This program searches the `$GIT_OBJECT_DIRECTORY` for all objects that currently -exist in a pack file as well as the independent object directories. +exist in a pack file as well as in the independent object directories. All such extra objects are removed. diff --git a/Documentation/git-prune.txt b/Documentation/git-prune.txt index 03552dd86f..9a45571b90 100644 --- a/Documentation/git-prune.txt +++ b/Documentation/git-prune.txt @@ -18,7 +18,7 @@ NOTE: In most cases, users should run 'git gc', which calls 'git prune'. See the section "NOTES", below. This runs 'git fsck --unreachable' using all the refs -available in `refs/`, optionally with additional set of +available in `refs/`, optionally with an additional set of objects specified on the command line, and prunes all unpacked objects unreachable from any of these head objects from the object database. In addition, it diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 297927d866..9b7cfbc5c1 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git push' [--all | --branches | --mirror | --tags] [--follow-tags] [--atomic] [-n | --dry-run] [--receive-pack=<git-receive-pack>] - [--repo=<repository>] [-f | --force] [-d | --delete] [--prune] [-v | --verbose] + [--repo=<repository>] [-f | --force] [-d | --delete] [--prune] [-q | --quiet] [-v | --verbose] [-u | --set-upstream] [-o <string> | --push-option=<string>] [--[no-]signed|--signed=(true|false|if-asked)] [--force-with-lease[=<refname>[:<expect>]] [--force-if-includes]] @@ -37,7 +37,7 @@ the default `<refspec>` by consulting `remote.*.push` configuration, and if it is not found, honors `push.default` configuration to decide what to push (See linkgit:git-config[1] for the meaning of `push.default`). -When neither the command-line nor the configuration specify what to +When neither the command-line nor the configuration specifies what to push, the default behavior is used, which corresponds to the `simple` value for `push.default`: the current branch is pushed to the corresponding upstream branch, but as a safety measure, the push is @@ -48,7 +48,7 @@ local one. OPTIONS[[OPTIONS]] ------------------ <repository>:: - The "remote" repository that is destination of a push + The "remote" repository that is the destination of a push operation. This parameter can be either a URL (see the section <<URLS,GIT URLS>> below) or the name of a remote (see the section <<REMOTES,REMOTES>> below). diff --git a/Documentation/git-quiltimport.txt b/Documentation/git-quiltimport.txt index 70562dc4c0..40e02d92eb 100644 --- a/Documentation/git-quiltimport.txt +++ b/Documentation/git-quiltimport.txt @@ -38,14 +38,14 @@ OPTIONS a patch. At the time of this writing only missing author information is warned about. ---author Author Name <Author Email>:: +--author 'Author Name <Author Email>':: The author name and email address to use when no author information can be found in the patch description. --patches <dir>:: The directory to find the quilt patches. + -The default for the patch directory is patches +The default for the patch directory is 'patches' or the value of the `$QUILT_PATCHES` environment variable. diff --git a/Documentation/git-range-diff.txt b/Documentation/git-range-diff.txt index 0b393715d7..fbdbe0befe 100644 --- a/Documentation/git-range-diff.txt +++ b/Documentation/git-range-diff.txt @@ -70,7 +70,7 @@ to revert to color all lines according to the outer diff markers Defaults to 60. Try a larger value if `git range-diff` erroneously considers a large change a total rewrite (deletion of one commit and addition of another), and a smaller one in the reverse case. - See the ``Algorithm`` section below for an explanation why this is + See the ``Algorithm`` section below for an explanation of why this is needed. --left-only:: @@ -166,7 +166,7 @@ A typical output of `git range-diff` would look like this: In this example, there are 3 old and 3 new commits, where the developer removed the 3rd, added a new one before the first two, and modified the -commit message of the 2nd commit as well its diff. +commit message of the 2nd commit as well as its diff. When the output goes to a terminal, it is color-coded by default, just like regular `git diff`'s output. In addition, the first line (adding a diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index b09707474d..1c48c28996 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -25,15 +25,15 @@ fast-forward (i.e. 2-way) merge, or a 3-way merge, with the `-m` flag. When used with `-m`, the `-u` flag causes it to also update the files in the work tree with the result of the merge. -Trivial merges are done by 'git read-tree' itself. Only conflicting paths -will be in unmerged state when 'git read-tree' returns. +Only trivial merges are done by 'git read-tree' itself. Only conflicting paths +will be in an unmerged state when 'git read-tree' returns. OPTIONS ------- -m:: Perform a merge, not just a read. The command will refuse to run if your index file has unmerged entries, - indicating that you have not finished previous merge you + indicating that you have not finished a previous merge you started. --reset:: diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index e7b39ad244..1dd6555f66 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -289,7 +289,7 @@ See also INCOMPATIBLE OPTIONS below. + See also INCOMPATIBLE OPTIONS below. ---empty={drop,keep,ask}:: +--empty=(drop|keep|ask):: How to handle commits that are not empty to start and are not clean cherry-picks of any upstream commit, but which become empty after rebasing (because they contain a subset of already @@ -589,21 +589,27 @@ See also INCOMPATIBLE OPTIONS below. --autosquash:: --no-autosquash:: - When the commit log message begins with "squash! ..." or "fixup! ..." - or "amend! ...", and there is already a commit in the todo list that - matches the same `...`, automatically modify the todo list of - `rebase -i`, so that the commit marked for squashing comes right after - the commit to be modified, and change the action of the moved commit - from `pick` to `squash` or `fixup` or `fixup -C` respectively. A commit - matches the `...` if the commit subject matches, or if the `...` refers - to the commit's hash. As a fall-back, partial matches of the commit - subject work, too. The recommended way to create fixup/amend/squash - commits is by using the `--fixup`, `--fixup=amend:` or `--fixup=reword:` - and `--squash` options respectively of linkgit:git-commit[1]. + Automatically squash commits with specially formatted messages into + previous commits being rebased. If a commit message starts with + "squash! ", "fixup! " or "amend! ", the remainder of the subject line + is taken as a commit specifier, which matches a previous commit if it + matches the subject line or the hash of that commit. If no commit + matches fully, matches of the specifier with the start of commit + subjects are considered. + -If the `--autosquash` option is enabled by default using the -configuration variable `rebase.autoSquash`, this option can be -used to override and disable this setting. +In the rebase todo list, the actions of squash, fixup and amend commits are +changed from `pick` to `squash`, `fixup` or `fixup -C`, respectively, and they +are moved right after the commit they modify. The `--interactive` option can +be used to review and edit the todo list before proceeding. ++ +The recommended way to create commits with squash markers is by using the +`--squash`, `--fixup`, `--fixup=amend:` or `--fixup=reword:` options of +linkgit:git-commit[1], which take the target commit as an argument and +automatically fill in the subject line of the new commit from that. ++ +Settting configuration variable `rebase.autoSquash` to true enables +auto-squashing by default for interactive rebase. The `--no-autosquash` +option can be used to override that setting. + See also INCOMPATIBLE OPTIONS below. @@ -695,7 +701,7 @@ be dropped automatically with `--no-keep-empty`). Similar to the apply backend, by default the merge backend drops commits that become empty unless `-i`/`--interactive` is specified (in which case it stops and asks the user what to do). The merge backend -also has an `--empty={drop,keep,ask}` option for changing the behavior +also has an `--empty=(drop|keep|ask)` option for changing the behavior of handling commits that become empty. Directory rename detection diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt index 65ff518ccf..20aca92073 100644 --- a/Documentation/git-receive-pack.txt +++ b/Documentation/git-receive-pack.txt @@ -18,10 +18,10 @@ information fed from the remote end. This command is usually not invoked directly by the end user. The UI for the protocol is on the 'git send-pack' side, and the -program pair is meant to be used to push updates to remote +program pair is meant to be used to push updates to a remote repository. For pull operations, see linkgit:git-fetch-pack[1]. -The command allows for creation and fast-forwarding of sha1 refs +The command allows for the creation and fast-forwarding of sha1 refs (heads/tags) on the remote end (strictly speaking, it is the local end 'git-receive-pack' runs, but to the user who is sitting at the send-pack end, it is updating the remote. Confused?) diff --git a/Documentation/git-remote-ext.txt b/Documentation/git-remote-ext.txt index 88ea7e1cc0..b33ee3c9e8 100644 --- a/Documentation/git-remote-ext.txt +++ b/Documentation/git-remote-ext.txt @@ -44,15 +44,15 @@ The following sequences have a special meaning: This argument will not be passed to '<command>'. Instead, it will cause the helper to start by sending git:// service requests to the remote side with the service field set to an appropriate value and - the repository field set to rest of the argument. Default is not to send + the repository field set to the rest of the argument. Default is not to send such a request. + -This is useful if remote side is git:// server accessed over +This is useful if the remote side is git:// server accessed over some tunnel. '%V' (must be first characters in argument):: This argument will not be passed to '<command>'. Instead it sets - the vhost field in the git:// service request (to rest of the argument). + the vhost field in the git:// service request (to the rest of the argument). Default is not to send vhost in such request (if sent). ENVIRONMENT VARIABLES @@ -82,12 +82,12 @@ begins with `ext::`. Examples: "ext::ssh -i /home/foo/.ssh/somekey user@host.example %S 'foo/repo'":: Like host.example:foo/repo, but use /home/foo/.ssh/somekey as - keypair and user as user on remote side. This avoids needing to + keypair and user as the user on the remote side. This avoids the need to edit .ssh/config. "ext::socat -t3600 - ABSTRACT-CONNECT:/git-server %G/somerepo":: Represents repository with path /somerepo accessible over - git protocol at abstract namespace address /git-server. + git protocol at the abstract namespace address /git-server. "ext::git-server-alias foo %G/repo":: Represents a repository with path /repo accessed using the diff --git a/Documentation/git-remote-fd.txt b/Documentation/git-remote-fd.txt index 0451ceb8a2..1dd2648a79 100644 --- a/Documentation/git-remote-fd.txt +++ b/Documentation/git-remote-fd.txt @@ -13,19 +13,19 @@ DESCRIPTION ----------- This helper uses specified file descriptors to connect to a remote Git server. This is not meant for end users but for programs and scripts calling git -fetch, push or archive. +fetch, push, or archive. If only <infd> is given, it is assumed to be a bidirectional socket connected -to remote Git server (git-upload-pack, git-receive-pack or +to a remote Git server (git-upload-pack, git-receive-pack, or git-upload-archive). If both <infd> and <outfd> are given, they are assumed to be pipes connected to a remote Git server (<infd> being the inbound pipe -and <outfd> being the outbound pipe. +and <outfd> being the outbound pipe). It is assumed that any handshaking procedures have already been completed (such as sending service request for git://) before this helper is started. <anything> can be any string. It is ignored. It is meant for providing -information to user in the URL in case that URL is displayed in some +information to the user in the URL in case that URL is displayed in some context. ENVIRONMENT VARIABLES @@ -45,7 +45,7 @@ EXAMPLES `git push fd::7,8 master (as URL)`:: Push master, using file descriptor #7 to read data from git-receive-pack and file descriptor #8 to write data to - same service. + the same service. `git push fd::7,8/bar master`:: Same as above. diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt index 4017157949..c902512a9e 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -74,6 +74,17 @@ to the new separate pack will be written. immediately instead of waiting for the next `git gc` invocation. Only useful with `--cruft -d`. +--max-cruft-size=<n>:: + Repack cruft objects into packs as large as `<n>` bytes before + creating new packs. As long as there are enough cruft packs + smaller than `<n>`, repacking will cause a new cruft pack to + be created containing objects from any combined cruft packs, + along with any new unreachable objects. Cruft packs larger than + `<n>` will not be modified. When the new cruft pack is larger + than `<n>` bytes, it will be split into multiple packs, all of + which are guaranteed to be at most `<n>` bytes in size. Only + useful with `--cruft -d`. + --expire-to=<dir>:: Write a cruft pack containing pruned objects (if any) to the directory `<dir>`. This option is useful for keeping a copy of @@ -143,6 +154,29 @@ depth is 4095. a larger and slower repository; see the discussion in `pack.packSizeLimit`. +--filter=<filter-spec>:: + Remove objects matching the filter specification from the + resulting packfile and put them into a separate packfile. Note + that objects used in the working directory are not filtered + out. So for the split to fully work, it's best to perform it + in a bare repo and to use the `-a` and `-d` options along with + this option. Also `--no-write-bitmap-index` (or the + `repack.writebitmaps` config option set to `false`) should be + used otherwise writing bitmap index will fail, as it supposes + a single packfile containing all the objects. See + linkgit:git-rev-list[1] for valid `<filter-spec>` forms. + +--filter-to=<dir>:: + Write the pack containing filtered out objects to the + directory `<dir>`. Only useful with `--filter`. This can be + used for putting the pack on a separate object directory that + is accessed through the Git alternates mechanism. **WARNING:** + If the packfile containing the filtered out objects is not + accessible, the repo can become corrupt as it might not be + possible to access the objects in that packfile. See the + `objects` and `objects/info/alternates` sections of + linkgit:gitrepository-layout[5]. + -b:: --write-bitmap-index:: Write a reachability bitmap index as part of the repack. This @@ -165,7 +199,7 @@ depth is 4095. Exclude the given pack from repacking. This is the equivalent of having `.keep` file on the pack. `<pack-name>` is the pack file name without leading directory (e.g. `pack-123.pack`). - The option could be specified multiple times to keep multiple + The option can be specified multiple times to keep multiple packs. --unpack-unreachable=<when>:: @@ -186,7 +220,7 @@ depth is 4095. Pass the `--delta-islands` option to `git-pack-objects`, see linkgit:git-pack-objects[1]. --g=<factor>:: +-g<factor>:: --geometric=<factor>:: Arrange resulting pack structure so that each successive pack contains at least `<factor>` times the number of objects as the @@ -203,11 +237,8 @@ uniquely by the set of packs being "rolled-up"; in other words, the packs determined to need to be combined in order to restore a geometric progression. + -When `--unpacked` is specified, loose objects are implicitly included in -this "roll-up", without respect to their reachability. This is subject -to change in the future. This option (implying a drastically different -repack mode) is not guaranteed to work with all other combinations of -option to `git repack`. +Loose objects are implicitly included in this "roll-up", without respect to +their reachability. This is subject to change in the future. + When writing a multi-pack bitmap, `git repack` selects the largest resulting pack as the preferred pack for object selection by the MIDX (see diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt index f271d758c3..4f257126e3 100644 --- a/Documentation/git-replace.txt +++ b/Documentation/git-replace.txt @@ -35,7 +35,7 @@ Replacement references will be used by default by all Git commands except those doing reachability traversal (prune, pack transfer and fsck). -It is possible to disable use of replacement references for any +It is possible to disable the use of replacement references for any command using the `--no-replace-objects` option just after 'git'. For example if commit 'foo' has been replaced by commit 'bar': @@ -111,7 +111,7 @@ OPTIONS FORMATS ------- -The following format are available: +The following formats are available: * 'short': <replaced sha1> diff --git a/Documentation/git-replay.txt b/Documentation/git-replay.txt new file mode 100644 index 0000000000..f6c269c62d --- /dev/null +++ b/Documentation/git-replay.txt @@ -0,0 +1,127 @@ +git-replay(1) +============= + +NAME +---- +git-replay - EXPERIMENTAL: Replay commits on a new base, works with bare repos too + + +SYNOPSIS +-------- +[verse] +(EXPERIMENTAL!) 'git replay' ([--contained] --onto <newbase> | --advance <branch>) <revision-range>... + +DESCRIPTION +----------- + +Takes ranges of commits and replays them onto a new location. Leaves +the working tree and the index untouched, and updates no references. +The output of this command is meant to be used as input to +`git update-ref --stdin`, which would update the relevant branches +(see the OUTPUT section below). + +THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE. + +OPTIONS +------- + +--onto <newbase>:: + Starting point at which to create the new commits. May be any + valid commit, and not just an existing branch name. ++ +When `--onto` is specified, the update-ref command(s) in the output will +update the branch(es) in the revision range to point at the new +commits, similar to the way how `git rebase --update-refs` updates +multiple branches in the affected range. + +--advance <branch>:: + Starting point at which to create the new commits; must be a + branch name. ++ +When `--advance` is specified, the update-ref command(s) in the output +will update the branch passed as an argument to `--advance` to point at +the new commits (in other words, this mimics a cherry-pick operation). + +<revision-range>:: + Range of commits to replay. More than one <revision-range> can + be passed, but in `--advance <branch>` mode, they should have + a single tip, so that it's clear where <branch> should point + to. See "Specifying Ranges" in linkgit:git-rev-parse and the + "Commit Limiting" options below. + +include::rev-list-options.txt[] + +OUTPUT +------ + +When there are no conflicts, the output of this command is usable as +input to `git update-ref --stdin`. It is of the form: + + update refs/heads/branch1 ${NEW_branch1_HASH} ${OLD_branch1_HASH} + update refs/heads/branch2 ${NEW_branch2_HASH} ${OLD_branch2_HASH} + update refs/heads/branch3 ${NEW_branch3_HASH} ${OLD_branch3_HASH} + +where the number of refs updated depends on the arguments passed and +the shape of the history being replayed. When using `--advance`, the +number of refs updated is always one, but for `--onto`, it can be one +or more (rebasing multiple branches simultaneously is supported). + +EXIT STATUS +----------- + +For a successful, non-conflicted replay, the exit status is 0. When +the replay has conflicts, the exit status is 1. If the replay is not +able to complete (or start) due to some kind of error, the exit status +is something other than 0 or 1. + +EXAMPLES +-------- + +To simply rebase `mybranch` onto `target`: + +------------ +$ git replay --onto target origin/main..mybranch +update refs/heads/mybranch ${NEW_mybranch_HASH} ${OLD_mybranch_HASH} +------------ + +To cherry-pick the commits from mybranch onto target: + +------------ +$ git replay --advance target origin/main..mybranch +update refs/heads/target ${NEW_target_HASH} ${OLD_target_HASH} +------------ + +Note that the first two examples replay the exact same commits and on +top of the exact same new base, they only differ in that the first +provides instructions to make mybranch point at the new commits and +the second provides instructions to make target point at them. + +What if you have a stack of branches, one depending upon another, and +you'd really like to rebase the whole set? + +------------ +$ git replay --contained --onto origin/main origin/main..tipbranch +update refs/heads/branch1 ${NEW_branch1_HASH} ${OLD_branch1_HASH} +update refs/heads/branch2 ${NEW_branch2_HASH} ${OLD_branch2_HASH} +update refs/heads/tipbranch ${NEW_tipbranch_HASH} ${OLD_tipbranch_HASH} +------------ + +When calling `git replay`, one does not need to specify a range of +commits to replay using the syntax `A..B`; any range expression will +do: + +------------ +$ git replay --onto origin/main ^base branch1 branch2 branch3 +update refs/heads/branch1 ${NEW_branch1_HASH} ${OLD_branch1_HASH} +update refs/heads/branch2 ${NEW_branch2_HASH} ${OLD_branch2_HASH} +update refs/heads/branch3 ${NEW_branch3_HASH} ${OLD_branch3_HASH} +------------ + +This will simultaneously rebase `branch1`, `branch2`, and `branch3`, +all commits they have since `base`, playing them on top of +`origin/main`. These three branches may have commits on top of `base` +that they have in common, but that does not need to be the case. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-request-pull.txt b/Documentation/git-request-pull.txt index fa5a426709..15dcbb6d91 100644 --- a/Documentation/git-request-pull.txt +++ b/Documentation/git-request-pull.txt @@ -16,7 +16,7 @@ DESCRIPTION Generate a request asking your upstream project to pull changes into their tree. The request, printed to the standard output, begins with the branch description, summarizes -the changes and indicates from where they can be pulled. +the changes, and indicates from where they can be pulled. The upstream project is expected to have the commit named by `<start>` and the output asks it to integrate the changes you made @@ -50,7 +50,7 @@ EXAMPLES -------- Imagine that you built your work on your `master` branch on top of -the `v1.0` release, and want it to be integrated to the project. +the `v1.0` release, and want it to be integrated into the project. First you push that change to your public repository for others to see: diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt index 5964810caa..975825b44a 100644 --- a/Documentation/git-restore.txt +++ b/Documentation/git-restore.txt @@ -78,6 +78,8 @@ all modified paths. --theirs:: When restoring files in the working tree from the index, use stage #2 ('ours') or #3 ('theirs') for unmerged paths. + This option cannot be used when checking out paths from a + tree-ish (i.e. with the `--source` option). + Note that during `git rebase` and `git pull --rebase`, 'ours' and 'theirs' may appear swapped. See the explanation of the same options @@ -87,6 +89,8 @@ in linkgit:git-checkout[1] for details. --merge:: When restoring files on the working tree from the index, recreate the conflicted merge in the unmerged paths. + This option cannot be used when checking out paths from a + tree-ish (i.e. with the `--source` option). --conflict=<style>:: The same as `--merge` option above, but changes the way the @@ -101,7 +105,7 @@ in linkgit:git-checkout[1] for details. specified. Unmerged paths on the working tree are left alone. --ignore-skip-worktree-bits:: - In sparse checkout mode, by default is to only update entries + In sparse checkout mode, the default is to only update entries matched by `<pathspec>` and sparse patterns in $GIT_DIR/info/sparse-checkout. This option ignores the sparse patterns and unconditionally restores any files in @@ -195,7 +199,7 @@ the same as using linkgit:git-reset[1]) $ git restore --staged hello.c ------------ -or you can restore both the index and the working tree (this the same +or you can restore both the index and the working tree (this is the same as using linkgit:git-checkout[1]) ------------ diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index 51029a2271..2e05c4b510 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -17,9 +17,9 @@ DESCRIPTION :git-rev-list: 1 include::rev-list-description.txt[] -'rev-list' is a very essential Git command, since it +'rev-list' is an essential Git command, since it provides the ability to build and traverse commit ancestry graphs. For -this reason, it has a lot of different options that enables it to be +this reason, it has a lot of different options that enable it to be used by commands as different as 'git bisect' and 'git repack'. diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index f26a7591e3..912fab9f5e 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -14,7 +14,7 @@ SYNOPSIS DESCRIPTION ----------- -Many Git porcelainish commands take mixture of flags +Many Git porcelainish commands take a mixture of flags (i.e. parameters that begin with a dash '-') and parameters meant for the underlying 'git rev-list' command they use internally and flags and parameters for the other commands they use @@ -36,7 +36,7 @@ Each of these options must appear first on the command line. --sq-quote:: Use 'git rev-parse' in shell quoting mode (see SQ-QUOTE section below). In contrast to the `--sq` option below, this - mode does only quoting. Nothing else is done to command input. + mode only does quoting. Nothing else is done to command input. Options for --parseopt ~~~~~~~~~~~~~~~~~~~~~~ @@ -156,7 +156,7 @@ for another option. are not refs (i.e. branch or tag names; or more explicitly disambiguating "heads/master" form, when you want to name the "master" branch when there is an - unfortunately named tag "master"), and show them as full + unfortunately named tag "master"), and shows them as full refnames (e.g. "refs/heads/master"). Options for Objects @@ -383,7 +383,7 @@ Each line of options has this format: dash to separate words in a multi-word argument hint. The remainder of the line, after stripping the spaces, is used -as the help associated to the option. +as the help associated with the option. Blank lines are ignored, and lines that don't match this specification are used as option group headers (start the line with a space to create such @@ -398,7 +398,7 @@ some-command [<options>] <args>... some-command does foo and bar! -- -h,help show the help +h,help! show the help foo some nifty option --foo bar= some cool option --bar with an argument @@ -424,10 +424,10 @@ usage: some-command [<options>] <args>... some-command does foo and bar! -h, --help show the help - --foo some nifty option --foo - --bar ... some cool option --bar with an argument - --baz <arg> another cool option --baz with a named argument - --qux[=<path>] qux may take a path argument but has meaning by itself + --[no-]foo some nifty option --foo + --[no-]bar ... some cool option --bar with an argument + --[no-]baz <arg> another cool option --baz with a named argument + --[no-]qux[=<path>] qux may take a path argument but has meaning by itself An option group Header -C[...] option C with an optional argument diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index d2e10d3dce..cbe0208834 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -142,6 +142,16 @@ EXAMPLES changes. The revert only modifies the working tree and the index. +DISCUSSION +---------- + +While git creates a basic commit message automatically, it is +_strongly_ recommended to explain why the original commit is being +reverted. +In addition, repeatedly reverting reverts will result in increasingly +unwieldy subject lines, for example 'Reapply "Reapply "<original subject>""'. +Please consider rewording these to be shorter and more unique. + CONFIGURATION ------------- diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt index 81bc23f3cd..363a26934f 100644 --- a/Documentation/git-rm.txt +++ b/Documentation/git-rm.txt @@ -163,7 +163,7 @@ will be staged (unless --cached or -n are used). A submodule is considered up to date when the HEAD is the same as recorded in the index, no tracked files are modified and no untracked -files that aren't ignored are present in the submodules work tree. +files that aren't ignored are present in the submodule's work tree. Ignored files are deemed expendable and won't stop a submodule's work tree from being removed. diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 492a82323d..30deb7fe2a 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -68,11 +68,12 @@ This option may be specified multiple times. Invoke a text editor (see GIT_EDITOR in linkgit:git-var[1]) to edit an introductory message for the patch series. + -When `--compose` is used, git send-email will use the From, Subject, and -In-Reply-To headers specified in the message. If the body of the message -(what you type after the headers and a blank line) only contains blank -(or Git: prefixed) lines, the summary won't be sent, but From, Subject, -and In-Reply-To headers will be used unless they are removed. +When `--compose` is used, git send-email will use the From, To, Cc, Bcc, +Subject, Reply-To, and In-Reply-To headers specified in the message. If +the body of the message (what you type after the headers and a blank +line) only contains blank (or Git: prefixed) lines, the summary won't be +sent, but the headers mentioned above will be used unless they are +removed. + Missing From or In-Reply-To headers will be prompted for. + @@ -453,7 +454,7 @@ have been specified, in which case default to 'compose'. 998 characters unless a suitable transfer encoding ('auto', 'base64', or 'quoted-printable') is used; this is due to SMTP limits as described by - http://www.ietf.org/rfc/rfc5322.txt. + https://www.ietf.org/rfc/rfc5322.txt. -- + Default is the value of `sendemail.validate`; if this is not set, @@ -468,8 +469,8 @@ Information --dump-aliases:: Instead of the normal operation, dump the shorthand alias names from - the configured alias file(s), one per line in alphabetical order. Note, - this only includes the alias name and not its expanded email addresses. + the configured alias file(s), one per line in alphabetical order. Note + that this only includes the alias name and not its expanded email addresses. See 'sendemail.aliasesfile' for more information about aliases. diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt index 595b002152..b9e73f2e77 100644 --- a/Documentation/git-send-pack.txt +++ b/Documentation/git-send-pack.txt @@ -55,7 +55,7 @@ be in a separate packet, and the list must end with a flush packet. --force:: Usually, the command refuses to update a remote ref that is not an ancestor of the local ref used to overwrite it. - This flag disables the check. What this means is that + This flag disables the check. This means that the remote repository can lose commits; use it with care. @@ -106,7 +106,7 @@ SPECIFYING THE REFS There are three ways to specify which refs to update on the remote end. -With `--all` flag, all refs that exist locally are transferred to +With the `--all` flag, all refs that exist locally are transferred to the remote side. You cannot specify any '<ref>' if you use this flag. @@ -115,9 +115,9 @@ both on the local side and on the remote side are updated. When one or more '<ref>' are specified explicitly (whether on the command line or via `--stdin`), it can be either a -single pattern, or a pair of such pattern separated by a colon +single pattern, or a pair of such patterns separated by a colon ":" (this means that a ref name cannot have a colon in it). A -single pattern '<name>' is just a shorthand for '<name>:<name>'. +single pattern '<name>' is just shorthand for '<name>:<name>'. Each pattern pair consists of the source side (before the colon) and the destination side (after the colon). The ref to be @@ -130,7 +130,7 @@ name. See linkgit:git-rev-parse[1]. - It is an error if <src> does not match exactly one of the local refs. - - It is an error if <dst> matches more than one remote refs. + - It is an error if <dst> matches more than one remote ref. - If <dst> does not match any remote ref, either @@ -143,9 +143,9 @@ name. See linkgit:git-rev-parse[1]. Without `--force`, the <src> ref is stored at the remote only if <dst> does not exist, or <dst> is a proper subset (i.e. an -ancestor) of <src>. This check, known as "fast-forward check", -is performed in order to avoid accidentally overwriting the -remote ref and lose other peoples' commits from there. +ancestor) of <src>. This check, known as the "fast-forward check", +is performed to avoid accidentally overwriting the +remote ref and losing other people's commits from there. With `--force`, the fast-forward check is disabled for all refs. diff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt index 8632612c31..bdaf6e5fc4 100644 --- a/Documentation/git-sh-setup.txt +++ b/Documentation/git-sh-setup.txt @@ -22,7 +22,7 @@ The 'git sh-setup' scriptlet is designed to be sourced (using the normal Git directories and a few helper shell functions. Before sourcing it, your script should set up a few variables; -`USAGE` (and `LONG_USAGE`, if any) is used to define message +`USAGE` (and `LONG_USAGE`, if any) is used to define the message given by `usage()` shell function. `SUBDIRECTORY_OK` can be set if the script can run from a subdirectory of the working tree (some commands do not). diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt index 71f608b1ff..c771c89770 100644 --- a/Documentation/git-show-branch.txt +++ b/Documentation/git-show-branch.txt @@ -50,7 +50,7 @@ OPTIONS --current:: With this option, the command includes the current - branch to the list of revs to be shown when it is not + branch in the list of revs to be shown when it is not given on the command line. --topo-order:: @@ -74,8 +74,7 @@ OPTIONS that is the common ancestor of all the branches. This flag tells the command to go <n> more common commits beyond that. When <n> is negative, display only the - <reference>s given, without showing the commit ancestry - tree. + <ref>s given, without showing the commit ancestry tree. --list:: Synonym to `--more=-1` @@ -88,8 +87,8 @@ OPTIONS the case of three or more commits. --independent:: - Among the <reference>s given, display only the ones that - cannot be reached from any other <reference>. + Among the <ref>s given, display only the ones that cannot be + reached from any other <ref>. --no-name:: Do not show naming strings for each commit. @@ -126,25 +125,26 @@ OPTIONS default to color output. Same as `--color=never`. -Note that --more, --list, --independent and --merge-base options +Note that --more, --list, --independent, and --merge-base options are mutually exclusive. OUTPUT ------ -Given N <references>, the first N lines are the one-line -description from their commit message. The branch head that is -pointed at by $GIT_DIR/HEAD is prefixed with an asterisk `*` -character while other heads are prefixed with a `!` character. -Following these N lines, one-line log for each commit is +Given N <ref>s, the first N lines are the one-line description from +their commit message. The branch head that is pointed at by +$GIT_DIR/HEAD is prefixed with an asterisk `*` character while other +heads are prefixed with a `!` character. + +Following these N lines, a one-line log for each commit is displayed, indented N places. If a commit is on the I-th branch, the I-th indentation character shows a `+` sign; otherwise it shows a space. Merge commits are denoted by a `-` sign. Each commit shows a short name that can be used as an extended SHA-1 to name that commit. -The following example shows three branches, "master", "fixes" +The following example shows three branches, "master", "fixes", and "mhf": ------------------------------------------------ @@ -154,7 +154,7 @@ $ git show-branch master fixes mhf ! [mhf] Allow "+remote:local" refspec to cause --force when fetching. --- + [mhf] Allow "+remote:local" refspec to cause --force when fetching. - + [mhf~1] Use git-octopus when pulling more than one heads. + + [mhf~1] Use git-octopus when pulling more than one head. + [fixes] Introduce "reset type" flag to "git reset" + [mhf~2] "git fetch --force". + [mhf~3] Use .git/remote/origin, not .git/branches/origin. @@ -197,7 +197,7 @@ $ git show-branch --reflog="10,1 hour ago" --list master shows 10 reflog entries going back from the tip as of 1 hour ago. Without `--list`, the output also shows how these tips are -topologically related with each other. +topologically related to each other. CONFIGURATION ------------- diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt index d1d56f68b4..ba75747005 100644 --- a/Documentation/git-show-ref.txt +++ b/Documentation/git-show-ref.txt @@ -8,10 +8,14 @@ git-show-ref - List references in a local repository SYNOPSIS -------- [verse] -'git show-ref' [-q | --quiet] [--verify] [--head] [-d | --dereference] +'git show-ref' [--head] [-d | --dereference] [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags] [--heads] [--] [<pattern>...] +'git show-ref' --verify [-q | --quiet] [-d | --dereference] + [-s | --hash[=<n>]] [--abbrev[=<n>]] + [--] [<ref>...] 'git show-ref' --exclude-existing[=<pattern>] +'git show-ref' --exists <ref> DESCRIPTION ----------- @@ -23,10 +27,14 @@ particular ref exists. By default, shows the tags, heads, and remote refs. -The --exclude-existing form is a filter that does the inverse. It reads +The `--exclude-existing` form is a filter that does the inverse. It reads refs from stdin, one ref per line, and shows those that don't exist in the local repository. +The `--exists` form can be used to check for the existence of a single +references. This form does not verify whether the reference resolves to an +actual object. + Use of this utility is encouraged in favor of directly accessing files under the `.git` directory. @@ -47,14 +55,14 @@ OPTIONS -d:: --dereference:: - Dereference tags into object IDs as well. They will be shown with "{caret}{}" + Dereference tags into object IDs as well. They will be shown with `^{}` appended. -s:: --hash[=<n>]:: - Only show the SHA-1 hash, not the reference name. When combined with - --dereference the dereferenced tag will still be shown after the SHA-1. + Only show the OID, not the reference name. When combined with + `--dereference`, the dereferenced tag will still be shown after the OID. --verify:: @@ -62,6 +70,12 @@ OPTIONS Aside from returning an error code of 1, it will also print an error message if `--quiet` was not specified. +--exists:: + + Check whether the given reference exists. Returns an exit code of 0 if + it does, 2 if it is missing, and 1 in case looking up the reference + failed with an error other than the reference being missing. + --abbrev[=<n>]:: Abbreviate the object name. When using `--hash`, you do @@ -70,15 +84,15 @@ OPTIONS -q:: --quiet:: - Do not print any results to stdout. When combined with `--verify` this - can be used to silently check if a reference exists. + Do not print any results to stdout. Can be used with `--verify` to + silently check if a reference exists. --exclude-existing[=<pattern>]:: - Make 'git show-ref' act as a filter that reads refs from stdin of the - form "`^(?:<anything>\s)?<refname>(?:\^{})?$`" + Make `git show-ref` act as a filter that reads refs from stdin of the + form `^(?:<anything>\s)?<refname>(?:\^{})?$` and performs the following actions on each: - (1) strip "{caret}{}" at the end of line if any; + (1) strip `^{}` at the end of line if any; (2) ignore if pattern is provided and does not head-match refname; (3) warn if refname is not a well-formed refname and skip; (4) ignore if refname is a ref that exists in the local repository; @@ -96,7 +110,13 @@ OPTIONS OUTPUT ------ -The output is in the format: '<SHA-1 ID>' '<space>' '<reference name>'. +The output is in the format: + +------------ +<oid> SP <ref> LF +------------ + +For example, ----------------------------------------------------------------------------- $ git show-ref --head --dereference @@ -110,7 +130,13 @@ $ git show-ref --head --dereference ... ----------------------------------------------------------------------------- -When using --hash (and not --dereference) the output format is: '<SHA-1 ID>' +When using `--hash` (and not `--dereference`), the output is in the format: + +------------ +<oid> LF +------------ + +For example, ----------------------------------------------------------------------------- $ git show-ref --heads --hash @@ -132,7 +158,7 @@ use: ----------------------------------------------------------------------------- This will show "refs/heads/master" but also "refs/remote/other-repo/master", -if such references exists. +if such references exist. When using the `--verify` flag, the command requires an exact path: @@ -142,10 +168,10 @@ When using the `--verify` flag, the command requires an exact path: will only match the exact branch called "master". -If nothing matches, 'git show-ref' will return an error code of 1, +If nothing matches, `git show-ref` will return an error code of 1, and in the case of verification, it will show an error message. -For scripting, you can ask it to be quiet with the "--quiet" flag, which +For scripting, you can ask it to be quiet with the `--quiet` flag, which allows you to do things like ----------------------------------------------------------------------------- @@ -157,11 +183,11 @@ to check whether a particular branch exists or not (notice how we don't actually want to show any results, and we want to use the full refname for it in order to not trigger the problem with ambiguous partial matches). -To show only tags, or only proper branch heads, use "--tags" and/or "--heads" +To show only tags, or only proper branch heads, use `--tags` and/or `--heads` respectively (using both means that it shows tags and heads, but not other random references under the refs/ subdirectory). -To do automatic tag object dereferencing, use the "-d" or "--dereference" +To do automatic tag object dereferencing, use the `-d` or `--dereference` flag, so you can do ----------------------------------------------------------------------------- diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt index 2b1bc7288d..5eb67439af 100644 --- a/Documentation/git-show.txt +++ b/Documentation/git-show.txt @@ -26,7 +26,7 @@ with --name-only). For plain blobs, it shows the plain contents. -The command takes options applicable to the 'git diff-tree' command to +Some options that 'git log' command understands can be used to control how the changes the commit introduces are shown. This manual page describes only the most frequently used options. @@ -61,7 +61,7 @@ EXAMPLES -------- `git show v1.0.0`:: - Shows the tag `v1.0.0`, along with the object the tags + Shows the tag `v1.0.0`, along with the object the tag points at. `git show v1.0.0^{tree}`:: diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt index 53dc17aa77..529a8edd9c 100644 --- a/Documentation/git-sparse-checkout.txt +++ b/Documentation/git-sparse-checkout.txt @@ -286,7 +286,7 @@ patterns in non-cone mode has a number of shortcomings: problem above? Also, if it suggests paths, what if the user has a file or directory that begins with either a '!' or '#' or has a '*', '\', '?', '[', or ']' in its name? And if it suggests paths, will - it complete "/pro" to "/proc" (in the root filesytem) rather than to + it complete "/pro" to "/proc" (in the root filesystem) rather than to "/progress.txt" in the current directory? (Note that users are likely to want to start paths with a leading '/' in non-cone mode, for the same reason that .gitignore files often have one.) diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index f4bb6114d9..06fb7f1d18 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -366,7 +366,7 @@ only the commit ends-up being in the stash and not on the current branch. # ... hack hack hack ... $ git add --patch foo # add unrelated changes to the index $ git stash push --staged # save these changes to the stash -# ... hack hack hack, finish curent changes ... +# ... hack hack hack, finish current changes ... $ git commit -m 'Massive' # commit fully tested changes $ git switch fixup-branch # switch to another branch $ git stash pop # to finish work on the saved changes diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index a051b1e8f3..10fecc51a7 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -245,11 +245,12 @@ U U unmerged, both modified .... Submodules have more state and instead report - M the submodule has a different HEAD than - recorded in the index - m the submodule has modified content - ? the submodule has untracked files -since modified content or untracked files in a submodule cannot be added + +* 'M' = the submodule has a different HEAD than recorded in the index +* 'm' = the submodule has modified content +* '?' = the submodule has untracked files + +This is since modified content or untracked files in a submodule cannot be added via `git add` in the superproject to prepare a commit. 'm' and '?' are applied recursively. For example if a nested submodule diff --git a/Documentation/git-stripspace.txt b/Documentation/git-stripspace.txt index 2438f76da0..a293327581 100644 --- a/Documentation/git-stripspace.txt +++ b/Documentation/git-stripspace.txt @@ -29,7 +29,7 @@ With no arguments, this will: In the case where the input consists entirely of whitespace characters, no output will be produced. -*NOTE*: This is intended for cleaning metadata, prefer the `--whitespace=fix` +*NOTE*: This is intended for cleaning metadata. Prefer the `--whitespace=fix` mode of linkgit:git-apply[1] for correcting whitespace of patches or files in the repository. @@ -37,11 +37,11 @@ OPTIONS ------- -s:: --strip-comments:: - Skip and remove all lines starting with comment character (default '#'). + Skip and remove all lines starting with a comment character (default '#'). -c:: --comment-lines:: - Prepend comment character and blank to each line. Lines will automatically + Prepend the comment character and a blank space to each line. Lines will automatically be terminated with a newline. On empty lines, only the comment character will be prepended. diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 4d3ab6b9f9..695730609a 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -95,7 +95,7 @@ too (and can also report changes to a submodule's work tree). init [--] [<path>...]:: Initialize the submodules recorded in the index (which were added and committed elsewhere) by setting `submodule.$name.url` - in .git/config. It uses the same setting from `.gitmodules` as + in `.git/config`, using the same setting from `.gitmodules` as a template. If the URL is relative, it will be resolved using the default remote. If there is no default remote, the current repository will be assumed to be upstream. @@ -105,9 +105,12 @@ If no path is specified and submodule.active has been configured, submodules configured to be active will be initialized, otherwise all submodules are initialized. + -When present, it will also copy the value of `submodule.$name.update`. -This command does not alter existing information in .git/config. -You can then customize the submodule clone URLs in .git/config +It will also copy the value of `submodule.$name.update`, if present in +the `.gitmodules` file, to `.git/config`, but (1) this command does not +alter existing information in `.git/config`, and (2) `submodule.$name.update` +that is set to a custom command is *not* copied for security reasons. ++ +You can then customize the submodule clone URLs in `.git/config` for your local setup and proceed to `git submodule update`; you can also just use `git submodule update --init` without the explicit 'init' step if you do not intend to customize @@ -143,6 +146,8 @@ the submodules. The "updating" can be done in several ways depending on command line options and the value of `submodule.<name>.update` configuration variable. The command line option takes precedence over the configuration variable. If neither is given, a 'checkout' is performed. +(note: what is in `.gitmodules` file is irrelevant at this point; +see `git submodule init` above for how `.gitmodules` is used). The 'update' procedures supported both from the command line as well as through the `submodule.<name>.update` configuration are: @@ -160,16 +165,18 @@ checked out in the submodule. merge;; the commit recorded in the superproject will be merged into the current branch in the submodule. -The following 'update' procedures are only available via the -`submodule.<name>.update` configuration variable: +The following update procedures have additional limitations: - custom command;; arbitrary shell command that takes a single - argument (the sha1 of the commit recorded in the - superproject) is executed. When `submodule.<name>.update` - is set to '!command', the remainder after the exclamation mark - is the custom command. + custom command;; mechanism for running arbitrary commands with the + commit ID as an argument. Specifically, if the + `submodule.<name>.update` configuration variable is set to + `!custom command`, the object name of the commit recorded in the + superproject for the submodule is appended to the `custom command` + string and executed. Note that this mechanism is not supported in + the `.gitmodules` file or on the command line. - none;; the submodule is not updated. + none;; the submodule is not updated. This update procedure is not + allowed on the command line. If the submodule is not yet initialized, and you just want to use the setting as stored in `.gitmodules`, you can automatically initialize the diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt index c60fc9c138..6137421ede 100644 --- a/Documentation/git-switch.txt +++ b/Documentation/git-switch.txt @@ -59,13 +59,18 @@ out at most one of `A` and `B`, in which case it defaults to `HEAD`. -c <new-branch>:: --create <new-branch>:: Create a new branch named `<new-branch>` starting at - `<start-point>` before switching to the branch. This is a - convenient shortcut for: + `<start-point>` before switching to the branch. This is the + transactional equivalent of + ------------ $ git branch <new-branch> $ git switch <new-branch> ------------ ++ +that is to say, the branch is not reset/created unless "git switch" is +successful (e.g., when the branch is in use in another worktree, not +just the current branch stays the same, but the branch is not reset to +the start-point, either). -C <new-branch>:: --force-create <new-branch>:: diff --git a/Documentation/git-symbolic-ref.txt b/Documentation/git-symbolic-ref.txt index 102c83eb19..761b154bcb 100644 --- a/Documentation/git-symbolic-ref.txt +++ b/Documentation/git-symbolic-ref.txt @@ -27,7 +27,7 @@ symbolic ref. A symbolic ref is a regular file that stores a string that begins with `ref: refs/`. For example, your `.git/HEAD` is -a regular file whose contents is `ref: refs/heads/master`. +a regular file whose content is `ref: refs/heads/master`. OPTIONS ------- diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 7f61c1edb3..d42efb3112 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -381,6 +381,16 @@ $ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1 include::date-formats.txt[] +FILES +----- + +`$GIT_DIR/TAG_EDITMSG`:: + This file contains the message of an in-progress annotated + tag. If `git tag` exits due to an error before creating an + annotated tag then the tag message that has been provided by the + user in an editor session will be available in this file, but + may be overwritten by the next invocation of `git tag`. + NOTES ----- diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index f4bb9c5daf..8c47890a6a 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -49,7 +49,7 @@ OPTIONS --remove:: If a specified file is in the index but is missing then it's removed. - Default behavior is to ignore removed file. + Default behavior is to ignore removed files. --refresh:: Looks at the current index and checks to see if merges or @@ -95,7 +95,7 @@ OPTIONS the index. If you want to change the working tree file, you need to unset the bit to tell Git. This is sometimes helpful when working with a big project on a - filesystem that has very slow lstat(2) system call + filesystem that has a very slow lstat(2) system call (e.g. cifs). + Git will fail (gracefully) in case it needs to modify this file @@ -108,7 +108,7 @@ you will need to handle the situation manually. without regard to the "assume unchanged" setting. --[no-]skip-worktree:: - When one of these flags is specified, the object name recorded + When one of these flags is specified, the object names recorded for the paths are not updated. Instead, these options set and unset the "skip-worktree" bit for the paths. See section "Skip-worktree bit" below for more information. @@ -119,7 +119,7 @@ you will need to handle the situation manually. the `--remove` option was specified. --[no-]fsmonitor-valid:: - When one of these flags is specified, the object name recorded + When one of these flags is specified, the object names recorded for the paths are not updated. Instead, these options set and unset the "fsmonitor valid" bit for the paths. See section "File System Monitor" below for more information. @@ -127,7 +127,7 @@ you will need to handle the situation manually. -g:: --again:: Runs 'git update-index' itself on the paths whose index - entries are different from those from the `HEAD` commit. + entries are different from those of the `HEAD` commit. --unresolve:: Restores the 'unmerged' or 'needs updating' state of a @@ -151,24 +151,30 @@ you will need to handle the situation manually. automatically removed with warning messages. --stdin:: - Instead of taking list of paths from the command line, - read list of paths from the standard input. Paths are + Instead of taking a list of paths from the command line, + read a list of paths from the standard input. Paths are separated by LF (i.e. one path per line) by default. --verbose:: - Report what is being added and removed from index. + Report what is being added and removed from the index. --index-version <n>:: Write the resulting index out in the named on-disk format version. - Supported versions are 2, 3 and 4. The current default version is 2 + Supported versions are 2, 3, and 4. The current default version is 2 or 3, depending on whether extra features are used, such as - `git add -N`. + `git add -N`. With `--verbose`, also report the version the index + file uses before and after this command. + Version 4 performs a simple pathname compression that reduces index size by 30%-50% on large repositories, which results in faster load -time. Version 4 is relatively young (first released in 1.8.0 in -October 2012). Other Git implementations such as JGit and libgit2 -may not support it yet. +time. Git supports it since version 1.8.0, released in October 2012, +and support for it was added to libgit2 in 2016 and to JGit in 2020. +Older versions of this manual page called it "relatively young", but +it should be considered mature technology these days. + +--show-index-version:: + Report the index format version used by the on-disk index file. + See `--index-version` above. -z:: Only meaningful with `--stdin` or `--index-info`; paths are diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index 48b6683071..0561808cca 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -118,7 +118,7 @@ verify:: <oldvalue> is zero or missing, the ref must not exist. option:: - Modify behavior of the next command naming a <ref>. + Modify the behavior of the next command naming a <ref>. The only valid option is `no-deref` to avoid dereferencing a symbolic ref. diff --git a/Documentation/git-update-server-info.txt b/Documentation/git-update-server-info.txt index 17e429dbd0..6bc9b50d89 100644 --- a/Documentation/git-update-server-info.txt +++ b/Documentation/git-update-server-info.txt @@ -23,13 +23,13 @@ OPTIONS ------- -f:: --force:: - update the info files from scratch. + Update the info files from scratch. OUTPUT ------ Currently the command updates the following files. Please see -linkgit:gitrepository-layout[5] for description of +linkgit:gitrepository-layout[5] for a description of what they are for: * objects/info/packs diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt index b656b47567..7ad60bc348 100644 --- a/Documentation/git-upload-pack.txt +++ b/Documentation/git-upload-pack.txt @@ -26,7 +26,7 @@ OPTIONS ------- --[no-]strict:: - Do not try <directory>/.git/ if <directory> is no Git directory. + Do not try <directory>/.git/ if <directory> is not a Git directory. --timeout=<n>:: Interrupt transfer after <n> seconds of inactivity. diff --git a/Documentation/git-var.txt b/Documentation/git-var.txt index f40202b8e3..0680568dfd 100644 --- a/Documentation/git-var.txt +++ b/Documentation/git-var.txt @@ -19,7 +19,7 @@ no value. OPTIONS ------- -l:: - Cause the logical variables to be listed. In addition, all the + Display the logical variables. In addition, all the variables of the Git configuration file .git/config are listed as well. (However, the configuration variables listing functionality is deprecated in favor of `git config -l`.) @@ -71,6 +71,29 @@ endif::git-default-pager[] GIT_DEFAULT_BRANCH:: The name of the first branch created in newly initialized repositories. +GIT_SHELL_PATH:: + The path of the binary providing the POSIX shell for commands which use the shell. + +GIT_ATTR_SYSTEM:: + The path to the system linkgit:gitattributes[5] file, if one is enabled. + +GIT_ATTR_GLOBAL:: + The path to the global (per-user) linkgit:gitattributes[5] file. + +GIT_CONFIG_SYSTEM:: + The path to the system configuration file, if one is enabled. + +GIT_CONFIG_GLOBAL:: + The path to the global (per-user) configuration files, if any. + +Most path values contain only one value. However, some can contain multiple +values, which are separated by newlines, and are listed in order from highest to +lowest priority. Callers should be prepared for any such path value to contain +multiple items. + +Note that paths are printed even if they do not exist, but not if they are +disabled by other environment variables. + SEE ALSO -------- linkgit:git-commit-tree[1] diff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt index b8720dce8a..d7e886918a 100644 --- a/Documentation/git-verify-pack.txt +++ b/Documentation/git-verify-pack.txt @@ -15,7 +15,7 @@ SYNOPSIS DESCRIPTION ----------- Reads given idx file for packed Git archive created with the -'git pack-objects' command and verifies idx file and the +'git pack-objects' command and verifies the idx file and the corresponding pack file. OPTIONS @@ -25,13 +25,13 @@ OPTIONS -v:: --verbose:: - After verifying the pack, show list of objects contained + After verifying the pack, show the list of objects contained in the pack and a histogram of delta chain length. -s:: --stat-only:: Do not verify the pack contents; only show the histogram of delta - chain length. With `--verbose`, list of objects is also shown. + chain length. With `--verbose`, the list of objects is also shown. \--:: Do not interpret any more arguments as options. diff --git a/Documentation/git-whatchanged.txt b/Documentation/git-whatchanged.txt index 8b63ceb00e..8e55e0bb1e 100644 --- a/Documentation/git-whatchanged.txt +++ b/Documentation/git-whatchanged.txt @@ -3,7 +3,7 @@ git-whatchanged(1) NAME ---- -git-whatchanged - Show logs with difference each commit introduces +git-whatchanged - Show logs with differences each commit introduces SYNOPSIS @@ -18,11 +18,11 @@ Shows commit logs and diff output each commit introduces. New users are encouraged to use linkgit:git-log[1] instead. The `whatchanged` command is essentially the same as linkgit:git-log[1] -but defaults to show the raw format diff output and to skip merges. +but defaults to showing the raw format diff output and skipping merges. -The command is kept primarily for historical reasons; fingers of +The command is primarily kept for historical reasons; fingers of many people who learned Git long before `git log` was invented by -reading Linux kernel mailing list are trained to type it. +reading the Linux kernel mailing list are trained to type it. Examples diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index 063d6eeb99..93d76f5d66 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]] - [-b <new-branch>] <path> [<commit-ish>] + [--orphan] [(-b | -B) <new-branch>] <path> [<commit-ish>] 'git worktree list' [-v | --porcelain [-z]] 'git worktree lock' [--reason <string>] <worktree> 'git worktree move' <worktree> <new-path> @@ -95,6 +95,16 @@ exist, a new branch based on `HEAD` is automatically created as if `-b <branch>` was given. If `<branch>` does exist, it will be checked out in the new worktree, if it's not checked out anywhere else, otherwise the command will refuse to create the worktree (unless `--force` is used). ++ +If `<commit-ish>` is omitted, neither `--detach`, or `--orphan` is +used, and there are no valid local branches (or remote branches if +`--guess-remote` is specified) then, as a convenience, the new worktree is +associated with a new orphan branch named `<branch>` (after +`$(basename <path>)` if neither `-b` or `-B` is used) as if `--orphan` was +passed to the command. In the event the repository has a remote and +`--guess-remote` is used, but no remote or local branches exist, then the +command fails with a warning reminding the user to fetch from their remote +first (or override by using `-f/--force`). list:: @@ -222,6 +232,10 @@ This can also be set up as the default behaviour by using the With `prune`, do not remove anything; just report what it would remove. +--orphan:: + With `add`, make the new worktree and index empty, associating + the worktree with a new orphan/unborn branch named `<new-branch>`. + --porcelain:: With `list`, output in an easy-to-parse format for scripts. This format will remain stable across Git versions and regardless of user @@ -272,7 +286,8 @@ rules and how to access refs of one worktree from another. In general, all pseudo refs are per-worktree and all refs starting with `refs/` are shared. Pseudo refs are ones like `HEAD` which are directly under `$GIT_DIR` instead of inside `$GIT_DIR/refs`. There are exceptions, -however: refs inside `refs/bisect` and `refs/worktree` are not shared. +however: refs inside `refs/bisect`, `refs/worktree` and `refs/rewritten` are +not shared. Refs that are per-worktree can still be accessed from another worktree via two special paths, `main-worktree` and `worktrees`. The former gives @@ -349,8 +364,8 @@ linked worktree `git rev-parse --git-path HEAD` returns `/path/other/test-next/.git/HEAD` or `/path/main/.git/HEAD`) while `git rev-parse --git-path refs/heads/master` uses `$GIT_COMMON_DIR` and returns `/path/main/.git/refs/heads/master`, -since refs are shared across all worktrees, except `refs/bisect` and -`refs/worktree`. +since refs are shared across all worktrees, except `refs/bisect`, +`refs/worktree` and `refs/rewritten`. See linkgit:gitrepository-layout[5] for more information. The rule of thumb is do not make any assumption about whether a path belongs to diff --git a/Documentation/git.txt b/Documentation/git.txt index f0cafa2290..bf9e6af695 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -96,9 +96,9 @@ foo.bar= ...`) sets `foo.bar` to the empty string which `git config to avoid ambiguity with `<name>` containing one. + This is useful for cases where you want to pass transitory -configuration options to git, but are doing so on OS's where -other processes might be able to read your cmdline -(e.g. `/proc/self/cmdline`), but not your environ +configuration options to git, but are doing so on operating systems +where other processes might be able to read your command line +(e.g. `/proc/self/cmdline`), but not your environment (e.g. `/proc/self/environ`). That behavior is the default on Linux, but may not be on your system. + @@ -553,8 +553,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 ignored when cloning and the setting of the remote repository - is always used. The default is "sha1". THIS VARIABLE IS - EXPERIMENTAL! See `--object-format` in linkgit:git-init[1]. + is always used. The default is "sha1". + See `--object-format` in linkgit:git-init[1]. Git Commits ~~~~~~~~~~~ @@ -911,6 +911,16 @@ for full details. should not normally need to set this to `0`, but it may be useful when trying to salvage data from a corrupted repository. +`GIT_COMMIT_GRAPH_PARANOIA`:: + When loading a commit object from the commit-graph, Git performs an + existence check on the object in the object database. This is done to + avoid issues with stale commit-graphs that contain references to + already-deleted commits, but comes with a performance penalty. ++ +The default is "false", which disables the aforementioned behavior. +Setting this to "true" enables the existence check so that stale commits +will never be returned from the commit-graph at the cost of performance. + `GIT_ALLOW_PROTOCOL`:: If set to a colon-separated list of protocols, behave as if `protocol.allow` is set to `never`, and each of the listed @@ -1015,10 +1025,11 @@ When first created, objects are stored in individual files, but for efficiency may later be compressed together into "pack files". Named pointers called refs mark interesting points in history. A ref -may contain the SHA-1 name of an object or the name of another ref. Refs -with names beginning `ref/head/` contain the SHA-1 name of the most +may contain the SHA-1 name of an object or the name of another ref (the +latter is called a "symbolic ref"). +Refs with names beginning `refs/head/` contain the SHA-1 name of the most recent commit (or "head") of a branch under development. SHA-1 names of -tags of interest are stored under `ref/tags/`. A special ref named +tags of interest are stored under `refs/tags/`. A symbolic ref named `HEAD` contains the name of the currently checked-out branch. The index file is initialized with a list of all paths and, for each @@ -1061,7 +1072,7 @@ Authors ------- Git was started by Linus Torvalds, and is currently maintained by Junio C Hamano. Numerous contributions have come from the Git mailing list -<git@vger.kernel.org>. http://www.openhub.net/p/git/contributors/summary +<git@vger.kernel.org>. https://openhub.net/p/git/contributors/summary gives you a more complete list of contributors. If you have a clone of git.git itself, the diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 02a3ec83e4..8c1793c148 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -1132,7 +1132,10 @@ size (see below). The merge driver is expected to leave the result of the merge in the file named with `%A` by overwriting it, and exit with zero status if it managed to merge them cleanly, or non-zero if there -were conflicts. +were conflicts. When the driver crashes (e.g. killed by SEGV), +it is expected to exit with non-zero status that are higher than +128, and in such a case, the merge results in a failure (which is +different from producing a conflict). The `merge.*.recursive` variable specifies what other merge driver to use when the merge driver is called for an internal @@ -1148,8 +1151,8 @@ will be stored via placeholder `%P`. ^^^^^^^^^^^^^^^^^^^^^^ This attribute controls the length of conflict markers left in -the work tree file during a conflicted merge. Only setting to -the value to a positive integer has any meaningful effect. +the work tree file during a conflicted merge. Only a positive +integer has a meaningful effect. For example, this line in `.gitattributes` can be used to tell the merge machinery to leave much longer (instead of the usual 7-character-long) diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index 1819a5a185..e5fac94322 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -23,10 +23,10 @@ arguments. Here are the rules: A subcommand may take dashed options (which may take their own arguments, e.g. "--max-parents 2") and arguments. You SHOULD give dashed options first and then arguments. Some commands may - accept dashed options after you have already gave non-option + accept dashed options after you have already given non-option arguments (which may make the command ambiguous), but you should not rely on it (because eventually we may find a way to fix - these ambiguity by enforcing the "options then args" rule). + these ambiguities by enforcing the "options then args" rule). * Revisions come first and then paths. E.g. in `git diff v1.0 v2.0 arch/x86 include/asm-x86`, @@ -37,12 +37,12 @@ arguments. Here are the rules: they can be disambiguated by placing `--` between them. E.g. `git diff -- HEAD` is, "I have a file called HEAD in my work tree. Please show changes between the version I staged in the index - and what I have in the work tree for that file", not "show difference + and what I have in the work tree for that file", not "show the difference between the HEAD commit and the work tree as a whole". You can say `git diff HEAD --` to ask for the latter. * Without disambiguating `--`, Git makes a reasonable guess, but errors - out and asking you to disambiguate when ambiguous. E.g. if you have a + out and asks you to disambiguate when ambiguous. E.g. if you have a file called HEAD in your work tree, `git diff HEAD` is ambiguous, and you have to say either `git diff HEAD --` or `git diff -- HEAD` to disambiguate. diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index c0b95256cc..2122aeb976 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -1089,7 +1089,7 @@ the remote repository URL in the local repository's config file like this: ------------------------------------------------ -$ git config remote.linus.url http://www.kernel.org/pub/scm/git/git.git/ +$ git config remote.linus.url https://git.kernel.org/pub/scm/git/git.git/ ------------------------------------------------ and use the "linus" keyword with 'git pull' instead of the full URL. diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt index 100f045bb1..71dd19731a 100644 --- a/Documentation/gitcredentials.txt +++ b/Documentation/gitcredentials.txt @@ -104,6 +104,17 @@ $ git help credential-foo $ git config --global credential.helper foo ------------------------------------------- +=== Available helpers + +The community maintains a comprehensive list of Git credential helpers at +https://git-scm.com/doc/credential-helpers. + +=== OAuth + +An alternative to inputting passwords or personal access tokens is to use an +OAuth credential helper. Initial authentication opens a browser window to the +host. Subsequent authentication happens in the background. Many popular Git +hosts support OAuth. CREDENTIAL CONTEXTS ------------------- @@ -260,7 +271,7 @@ appended to its command line, which is one of: `erase`:: - Remove a matching credential, if any, from the helper's storage. + Remove matching credentials, if any, from the helper's storage. The details of the credential will be provided on the helper's stdin stream. The exact format is the same as the input/output format of the diff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt index 0d57f86abc..3cda2e07c2 100644 --- a/Documentation/gitdiffcore.txt +++ b/Documentation/gitdiffcore.txt @@ -173,7 +173,7 @@ Note that when rename detection is on but both copy and break detection are off, rename detection adds a preliminary step that first checks if files are moved across directories while keeping their filename the same. If there is a file added to a directory whose -contents is sufficiently similar to a file with the same name that got +contents are sufficiently similar to a file with the same name that got deleted from a different directory, it will mark them as renames and exclude them from the later quadratic step (the one that pairwise compares all unmatched files to find the "best" matches, determined by @@ -213,7 +213,7 @@ from the original, and does not count insertion. If you removed only 10 lines from a 100-line document, even if you added 910 new lines to make a new 1000-line document, you did not do a complete rewrite. diffcore-break breaks such a case in order to -help diffcore-rename to consider such filepairs as candidate of +help diffcore-rename to consider such filepairs as a candidate of rename/copy detection, but if filepairs broken that way were not matched with other filepairs to create rename/copy, then this transformation merges them back into the original @@ -230,13 +230,13 @@ like these: * -B/60 (the same as above, since diffcore-break defaults to 50%). -Note that earlier implementation left a broken pair as a separate -creation and deletion patches. This was an unnecessary hack and +Note that earlier implementation left a broken pair as separate +creation and deletion patches. This was an unnecessary hack, and the latest implementation always merges all the broken pairs back into modifications, but the resulting patch output is formatted differently for easier review in case of such -a complete rewrite by showing the entire contents of old version -prefixed with '-', followed by the entire contents of new +a complete rewrite by showing the entire contents of the old version +prefixed with '-', followed by the entire contents of the new version prefixed with '+'. @@ -263,7 +263,7 @@ textual diff has an added or a deleted line that matches the given regular expression. This means that it will detect in-file (or what rename-detection considers the same file) moves, which is noise. The implementation runs diff twice and greps, and this can be quite -expensive. To speed things up binary files without textconv filters +expensive. To speed things up, binary files without textconv filters will be ignored. When `-S` or `-G` are used without `--pickaxe-all`, only filepairs diff --git a/Documentation/giteveryday.txt b/Documentation/giteveryday.txt index faba2ef088..6cfdd0e07b 100644 --- a/Documentation/giteveryday.txt +++ b/Documentation/giteveryday.txt @@ -14,7 +14,7 @@ DESCRIPTION ----------- Git users can broadly be grouped into four categories for the purposes of -describing here a small set of useful command for everyday Git. +describing here a small set of useful commands for everyday Git. * <<STANDALONE,Individual Developer (Standalone)>> commands are essential for anybody who makes a commit, even for somebody who works alone. @@ -229,7 +229,7 @@ without a formal "merging". Or longhand + git am -3 -k` An alternate participant submission mechanism is using the -`git request-pull` or pull-request mechanisms (e.g as used on +`git request-pull` or pull-request mechanisms (e.g. as used on GitHub (www.github.com) to notify your upstream of your contribution. diff --git a/Documentation/gitformat-bundle.txt b/Documentation/gitformat-bundle.txt index 00e0a20e65..1b75cf71ce 100644 --- a/Documentation/gitformat-bundle.txt +++ b/Documentation/gitformat-bundle.txt @@ -67,7 +67,7 @@ A Git bundle consists of several parts. * "Capabilities", which are only in the v3 format, indicate functionality that the bundle requires to be read properly. -* "Prerequisites" lists the objects that are NOT included in the bundle and the +* "Prerequisites" list the objects that are NOT included in the bundle and the reader of the bundle MUST already have, in order to use the data in the bundle. The objects stored in the bundle may refer to prerequisite objects and anything reachable from them (e.g. a tree object in the bundle can reference @@ -86,10 +86,10 @@ In the bundle format, there can be a comment following a prerequisite obj-id. This is a comment and it has no specific meaning. The writer of the bundle MAY put any string here. The reader of the bundle MUST ignore the comment. -Note on the shallow clone and a Git bundle -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Note on shallow clones and Git bundles +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Note that the prerequisites does not represent a shallow-clone boundary. The +Note that the prerequisites do not represent a shallow-clone boundary. The semantics of the prerequisites and the shallow-clone boundaries are different, and the Git bundle v2 format cannot represent a shallow clone repository. diff --git a/Documentation/gitformat-chunk.txt b/Documentation/gitformat-chunk.txt index 57202ede27..3315df6201 100644 --- a/Documentation/gitformat-chunk.txt +++ b/Documentation/gitformat-chunk.txt @@ -42,7 +42,7 @@ Each row consists of a 4-byte chunk identifier (ID) and an 8-byte offset. Each integer is stored in network-byte order. The chunk identifier `ID[i]` is a label for the data stored within this -fill from `OFFSET[i]` (inclusive) to `OFFSET[i+1]` (exclusive). Thus, the +file from `OFFSET[i]` (inclusive) to `OFFSET[i+1]` (exclusive). Thus, the size of the `i`th chunk is equal to the difference between `OFFSET[i+1]` and `OFFSET[i]`. This requires that the chunk data appears contiguously in the same order as the table of contents. @@ -67,7 +67,7 @@ caller is responsible for opening the `hashfile` and writing header information so the file format is identifiable before the chunk-based format begins. -Then, call `add_chunk()` for each chunk that is intended for write. This +Then, call `add_chunk()` for each chunk that is intended for writing. This populates the `chunkfile` with information about the order and size of each chunk to write. Provide a `chunk_write_fn` function pointer to perform the write of the chunk data upon request. diff --git a/Documentation/gitformat-pack.txt b/Documentation/gitformat-pack.txt index 0c1be2dbe8..9fcb29a9c8 100644 --- a/Documentation/gitformat-pack.txt +++ b/Documentation/gitformat-pack.txt @@ -17,8 +17,8 @@ $GIT_DIR/objects/pack/multi-pack-index DESCRIPTION ----------- -The Git pack format is now Git stores most of its primary repository -data. Over the lietime af a repository loose objects (if any) and +The Git pack format is how Git stores most of its primary repository +data. Over the lifetime of a repository, loose objects (if any) and smaller packs are consolidated into larger pack(s). See linkgit:git-gc[1] and linkgit:git-pack-objects[1]. @@ -48,7 +48,7 @@ Similarly, in SHA-256 repositories, these values are computed using SHA-256. Observation: we cannot have more than 4G versions ;-) and more than 4G objects in a pack. - - The header is followed by number of object entries, each of + - The header is followed by a number of object entries, each of which looks like this: (undeltified representation) @@ -62,7 +62,7 @@ Similarly, in SHA-256 repositories, these values are computed using SHA-256. is an OBJ_OFS_DELTA object compressed delta data - Observation: length of each object is encoded in a variable + Observation: the length of each object is encoded in a variable length format and is not constrained to 32-bit or anything. - The trailer records a pack checksum of all of the above. @@ -117,7 +117,7 @@ the delta data is a sequence of instructions to reconstruct the object from the base object. If the base object is deltified, it must be converted to canonical form first. Each instruction appends more and more data to the target object until it's complete. There are two -supported instructions so far: one for copy a byte range from the +supported instructions so far: one for copying a byte range from the source object and one for inserting new data embedded in the instruction itself. @@ -137,7 +137,7 @@ copy. Offset and size are in little-endian order. All offset and size bytes are optional. This is to reduce the instruction size when encoding small offsets or sizes. The first seven -bits in the first octet determines which of the next seven octets is +bits in the first octet determine which of the next seven octets is present. If bit zero is set, offset1 is present. If bit one is set offset2 is present and so on. @@ -161,9 +161,9 @@ converted to 0x10000. | 0xxxxxxx | data | +----------+============+ -This is the instruction to construct target object without the base +This is the instruction to construct the target object without the base object. The following data is appended to the target object. The first -seven bits of the first octet determines the size of data in +seven bits of the first octet determine the size of data in bytes. The size must be non-zero. ==== Reserved instruction @@ -294,7 +294,7 @@ Pack file entry: <+ - The same trailer as a v1 pack file: - A copy of the pack checksum at the end of + A copy of the pack checksum at the end of the corresponding packfile. Index checksum of all of the above. @@ -390,10 +390,11 @@ CHUNK LOOKUP: CHUNK DATA: Packfile Names (ID: {'P', 'N', 'A', 'M'}) - Stores the packfile names as concatenated, null-terminated strings. - Packfiles must be listed in lexicographic order for fast lookups by - name. This is the only chunk not guaranteed to be a multiple of four - bytes in length, so should be the last chunk for alignment reasons. + Store the names of packfiles as a sequence of NUL-terminated + strings. There is no extra padding between the filenames, + and they are listed in lexicographic order. The chunk itself + is padded at the end with between 0 and 3 NUL bytes to make the + chunk size a multiple of 4 bytes. OID Fanout (ID: {'O', 'I', 'D', 'F'}) The ith entry, F[i], stores the number of OIDs with first @@ -588,51 +589,17 @@ later on. It is linkgit:git-gc[1] that is typically responsible for removing expired unreachable objects. -=== Caution for mixed-version environments - -Repositories that have cruft packs in them will continue to work with any older -version of Git. Note, however, that previous versions of Git which do not -understand the `.mtimes` file will use the cruft pack's mtime as the mtime for -all of the objects in it. In other words, do not expect older (pre-cruft pack) -versions of Git to interpret or even read the contents of the `.mtimes` file. - -Note that having mixed versions of Git GC-ing the same repository can lead to -unreachable objects never being completely pruned. This can happen under the -following circumstances: - - - An older version of Git running GC explodes the contents of an existing - cruft pack loose, using the cruft pack's mtime. - - A newer version running GC collects those loose objects into a cruft pack, - where the .mtime file reflects the loose object's actual mtimes, but the - cruft pack mtime is "now". - -Repeating this process will lead to unreachable objects not getting pruned as a -result of repeatedly resetting the objects' mtimes to the present time. - -If you are GC-ing repositories in a mixed version environment, consider omitting -the `--cruft` option when using linkgit:git-repack[1] and linkgit:git-gc[1], and -setting the `gc.cruftPacks` configuration to "false" until all writers -understand cruft packs. - === Alternatives Notable alternatives to this design include: - - The location of the per-object mtime data, and - - Storing unreachable objects in multiple cruft packs. + - The location of the per-object mtime data. On the location of mtime data, a new auxiliary file tied to the pack was chosen to avoid complicating the `.idx` format. If the `.idx` format were ever to gain support for optional chunks of data, it may make sense to consolidate the `.mtimes` format into the `.idx` itself. -Storing unreachable objects among multiple cruft packs (e.g., creating a new -cruft pack during each repacking operation including only unreachable objects -which aren't already stored in an earlier cruft pack) is significantly more -complicated to construct, and so aren't pursued here. The obvious drawback to -the current implementation is that the entire cruft pack must be re-written from -scratch. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index 86f804720a..883982e7a0 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -80,7 +80,7 @@ If it exits with non-zero status, then the working tree will not be committed after applying the patch. It can be used to inspect the current working tree and refuse to -make a commit if it does not pass certain test. +make a commit if it does not pass certain tests. The default 'pre-applypatch' hook, when enabled, runs the 'pre-commit' hook, if the latter is enabled. @@ -157,7 +157,7 @@ If the exit status is non-zero, `git commit` will abort. The purpose of the hook is to edit the message file in place, and it is not suppressed by the `--no-verify` option. A non-zero exit means a failure of the hook and aborts the commit. It should not -be used as replacement for pre-commit hook. +be used as a replacement for the pre-commit hook. The sample `prepare-commit-msg` hook that comes with Git removes the help message found in the commented portion of the commit template. @@ -345,7 +345,7 @@ for the user. The default 'update' hook, when enabled--and with `hooks.allowunannotated` config option unset or set to false--prevents -unannotated tags to be pushed. +unannotated tags from being pushed. [[proc-receive]] proc-receive @@ -379,12 +379,12 @@ following example for the protocol, the letter 'S' stands for S: ... ... S: flush-pkt - # Receive result from the hook. + # Receive results from the hook. # OK, run this command successfully. H: PKT-LINE(ok <ref>) # NO, I reject it. H: PKT-LINE(ng <ref> <reason>) - # Fall through, let 'receive-pack' to execute it. + # Fall through, let 'receive-pack' execute it. H: PKT-LINE(ok <ref>) H: PKT-LINE(option fall-through) # OK, but has an alternate reference. The alternate reference name diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt index 4c17f2356c..5e0964ef41 100644 --- a/Documentation/gitignore.txt +++ b/Documentation/gitignore.txt @@ -88,7 +88,7 @@ PATTERN FORMAT Put a backslash ("`\`") in front of the first "`!`" for patterns that begin with a literal "`!`", for example, "`\!important!.txt`". - - The slash '/' is used as the directory separator. Separators may + - The slash "`/`" is used as the directory separator. Separators may occur at the beginning, middle or end of the `.gitignore` search pattern. - If there is a separator at the beginning or middle (or both) of the @@ -174,10 +174,10 @@ EXAMPLES is not relevant if there is already a middle slash in the pattern. - - The pattern "foo/*", matches "foo/test.json" - (a regular file), "foo/bar" (a directory), but it does not match - "foo/bar/hello.c" (a regular file), as the asterisk in the - pattern does not match "bar/hello.c" which has a slash in it. + - The pattern `foo/*`, matches `foo/test.json` + (a regular file), `foo/bar` (a directory), but it does not match + `foo/bar/hello.c` (a regular file), as the asterisk in the + pattern does not match `bar/hello.c` which has a slash in it. -------------------------------------------------------------- $ git status diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt index d50e9ed10e..c2213bb77b 100644 --- a/Documentation/gitk.txt +++ b/Documentation/gitk.txt @@ -26,7 +26,7 @@ changes each commit introduces are shown. Finally, it supports some gitk-specific options. gitk generally only understands options with arguments in the -'sticked' form (see linkgit:gitcli[7]) due to limitations in the +'stuck' form (see linkgit:gitcli[7]) due to limitations in the command-line parser. rev-list options and arguments diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt index dcee09b500..d9bec8b187 100644 --- a/Documentation/gitmodules.txt +++ b/Documentation/gitmodules.txt @@ -43,9 +43,9 @@ submodule.<name>.update:: command in the superproject. This is only used by `git submodule init` to initialize the configuration variable of the same name. Allowed values here are 'checkout', 'rebase', - 'merge' or 'none'. See description of 'update' command in - linkgit:git-submodule[1] for their meaning. For security - reasons, the '!command' form is not accepted here. + 'merge' or 'none', but not '!command' (for security reasons). + See the description of the 'update' command in + linkgit:git-submodule[1] for more details. submodule.<name>.branch:: A remote branch name for tracking updates in the upstream submodule. diff --git a/Documentation/gitprotocol-capabilities.txt b/Documentation/gitprotocol-capabilities.txt index 0fb5ea0c1c..d6c6effc21 100644 --- a/Documentation/gitprotocol-capabilities.txt +++ b/Documentation/gitprotocol-capabilities.txt @@ -30,7 +30,7 @@ to be in effect. The client MUST NOT ask for capabilities the server did not say it supports. Server MUST diagnose and abort if capabilities it does not understand -was sent. Server MUST NOT ignore capabilities that client requested +were sent. Server MUST NOT ignore capabilities that client requested and server advertised. As a consequence of these rules, server MUST NOT advertise capabilities it does not understand. @@ -61,8 +61,8 @@ complete cut across the DAG, or the client has said "done". Without multi_ack, a client sends have lines in --date-order until the server has found a common base. That means the client will send have lines that are already known by the server to be common, because -they overlap in time with another branch that the server hasn't found -a common base on yet. +they overlap in time with another branch on which the server hasn't found +a common base yet. For example suppose the client has commits in caps that the server doesn't and the server has commits in lower case that the client @@ -88,7 +88,7 @@ interleaved with S-R-Q. multi_ack_detailed ------------------ -This is an extension of multi_ack that permits client to better +This is an extension of multi_ack that permits the client to better understand the server's in-memory state. See linkgit:gitprotocol-pack[5], section "Packfile Negotiation" for more information. @@ -135,7 +135,7 @@ to disable the feature in a backwards-compatible manner. side-band, side-band-64k ------------------------ -This capability means that server can send, and client understand multiplexed +This capability means that the server can send, and the client can understand, multiplexed progress reports and error info interleaved with the packfile itself. These two options are mutually exclusive. A modern client always @@ -163,14 +163,14 @@ Further, with side-band and its up to 1000-byte messages, it's actually same deal, you have up to 65519 bytes of data and 1 byte for the stream code. -The client MUST send only maximum of one of "side-band" and "side- -band-64k". Server MUST diagnose it as an error if client requests +The client MUST send only one of "side-band" and "side- +band-64k". The server MUST diagnose it as an error if client requests both. ofs-delta --------- -Server can send, and client understand PACKv2 with delta referring to +The server can send, and the client can understand, PACKv2 with delta referring to its base by position in pack rather than by an obj-id. That is, they can send/read OBJ_OFS_DELTA (aka type 6) in a packfile. @@ -252,7 +252,7 @@ the current shallow boundary, instead of the depth from remote refs. no-progress ----------- -The client was started with "git clone -q" or something, and doesn't +The client was started with "git clone -q" or something similar, and doesn't want that side band 2. Basically the client just says "I do not wish to receive stream 2 on sideband, so do not send it to me, and if you did, I will drop it on the floor anyway". However, the sideband @@ -273,7 +273,7 @@ request include-tag only has to do with the client's desires for tag data, whether or not a server had advertised objects in the refs/tags/* namespace. -Servers MUST pack the tags if their referrant is packed and the client +Servers MUST pack the tags if their referent is packed and the client has requested include-tags. Clients MUST be prepared for the case where a server has ignored diff --git a/Documentation/gitprotocol-common.txt b/Documentation/gitprotocol-common.txt index 1486651bd1..cdc9d6e707 100644 --- a/Documentation/gitprotocol-common.txt +++ b/Documentation/gitprotocol-common.txt @@ -13,7 +13,7 @@ SYNOPSIS DESCRIPTION ----------- -This document sets defines things common to various over-the-wire +This document defines things common to various over-the-wire protocols and file formats used in Git. ABNF Notation diff --git a/Documentation/gitprotocol-http.txt b/Documentation/gitprotocol-http.txt index ccc13f0a40..836b3490cc 100644 --- a/Documentation/gitprotocol-http.txt +++ b/Documentation/gitprotocol-http.txt @@ -42,7 +42,7 @@ both the "smart" and "dumb" HTTP protocols used by Git operate by appending additional path components onto the end of the user supplied `$GIT_URL` string. -An example of a dumb client requesting for a loose object: +An example of a dumb client requesting a loose object: $GIT_URL: http://example.com:8080/git/repo.git URL request: http://example.com:8080/git/repo.git/objects/d0/49f6c27a2244e12041955e262a404c7faba355 @@ -379,7 +379,7 @@ C: Place any object seen into set `advertised`. C: Build an empty set, `common`, to hold the objects that are later determined to be on both ends. -C: Build a set, `want`, of the objects from `advertised` the client +C: Build a set, `want`, of the objects from `advertised` that the client wants to fetch, based on what it saw during ref discovery. C: Start a queue, `c_pending`, ordered by commit time (popping newest @@ -423,7 +423,7 @@ 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. +from `c_pending`. Fewer can be supplied if `c_pending` empties. If the client has sent 256 "have" commits and has not yet received one of those back from `s_common`, or the client has @@ -529,8 +529,8 @@ TODO: Document this further. REFERENCES ---------- -http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)] -http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1] +https://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)] +https://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1] SEE ALSO -------- diff --git a/Documentation/gitprotocol-pack.txt b/Documentation/gitprotocol-pack.txt index dd4108b7a3..837b691c89 100644 --- a/Documentation/gitprotocol-pack.txt +++ b/Documentation/gitprotocol-pack.txt @@ -30,7 +30,7 @@ pkt-line Format --------------- The descriptions below build on the pkt-line format described in -linkgit:gitprotocol-common[5]. When the grammar indicate `PKT-LINE(...)`, unless +linkgit:gitprotocol-common[5]. When the grammar indicates `PKT-LINE(...)`, unless otherwise noted the usual pkt-line LF rules apply: the sender SHOULD include a LF, but the receiver MUST NOT complain if it is not present. @@ -137,7 +137,7 @@ an absolute path in the remote filesystem. v ssh user@example.com "git-upload-pack '/project.git'" -In a "user@host:path" format URI, its relative to the user's home +In a "user@host:path" format URI, it's relative to the user's home directory, because the Git client will run: git clone user@example.com:project.git @@ -325,7 +325,7 @@ a positive depth, this step is skipped. If the client has requested a positive depth, the server will compute the set of commits which are no deeper than the desired depth. The set -of commits start at the client's wants. +of commits starts at the client's wants. The server writes 'shallow' lines for each commit whose parents will not be sent as a result. The server writes diff --git a/Documentation/gitprotocol-v2.txt b/Documentation/gitprotocol-v2.txt index acb97ad0c2..8c1e7c61ea 100644 --- a/Documentation/gitprotocol-v2.txt +++ b/Documentation/gitprotocol-v2.txt @@ -29,7 +29,7 @@ protocol. Protocol v2 will improve upon v1 in the following ways: semantics the http remote helper can simply act as a proxy In protocol v2 communication is command oriented. When first contacting a -server a list of capabilities will advertised. Some of these capabilities +server a list of capabilities will be advertised. Some of these capabilities will be commands which a client can request be executed. Once a command has completed, a client can reuse the connection and request that other commands be executed. diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt index 1a2ef4c150..949cd8a31e 100644 --- a/Documentation/gitrepository-layout.txt +++ b/Documentation/gitrepository-layout.txt @@ -23,7 +23,9 @@ A Git repository comes in two different flavours: *Note*: Also you can have a plain text file `.git` at the root of your working tree, containing `gitdir: <path>` to point at the real -directory that has the repository. This mechanism is often used for +directory that has the repository. +This mechanism is called a 'gitfile' and is usually managed via the +`git submodule` and `git worktree` commands. It is often used for a working tree of a submodule checkout, to allow you in the containing superproject to `git checkout` a branch that does not have the submodule. The `checkout` has to remove the entire diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt index 941858a6ec..8400d591da 100644 --- a/Documentation/gitsubmodules.txt +++ b/Documentation/gitsubmodules.txt @@ -78,7 +78,7 @@ Submodule operations can be configured using the following mechanisms * The command line for those commands that support taking submodules as part of their pathspecs. Most commands have a boolean flag - `--recurse-submodules` which specify whether to recurse into submodules. + `--recurse-submodules` which specifies whether to recurse into submodules. Examples are `grep` and `checkout`. Some commands take enums, such as `fetch` and `push`, where you can specify how submodules are affected. @@ -192,7 +192,7 @@ For example: [submodule "baz"] url = https://example.org/baz -In the above config only the submodule 'bar' and 'baz' are active, +In the above config only the submodules 'bar' and 'baz' are active, 'bar' due to (1) and 'baz' due to (3). 'foo' is inactive because (1) takes precedence over (3) @@ -274,7 +274,7 @@ 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 +`checkout` recurse into submodules (note that `submodule.recurse` also affects other Git commands, see linkgit:git-config[1] for a complete list). diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt index c7cadd8aaf..4759408788 100644 --- a/Documentation/gittutorial.txt +++ b/Documentation/gittutorial.txt @@ -137,10 +137,10 @@ which will automatically notice any modified (but not new) files, add them to the index, and commit, all in one step. A note on commit messages: Though not required, it's a good idea to -begin the commit message with a single short (less than 50 character) -line summarizing the change, followed by a blank line and then a more -thorough description. The text up to the first blank line in a commit -message is treated as the commit title, and that title is used +begin the commit message with a single short (no more than 50 +characters) line summarizing the change, followed by a blank line and +then a more thorough description. The text up to the first blank line in +a commit message is treated as the commit title, and that title is used throughout Git. For example, linkgit:git-format-patch[1] turns a commit into email, and it uses the title on the Subject line and the rest of the commit in the body. diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt index 34b1d6e224..59fc1d2741 100644 --- a/Documentation/gitweb.conf.txt +++ b/Documentation/gitweb.conf.txt @@ -53,7 +53,7 @@ following order: `/etc/gitweb-common.conf`), * either per-instance configuration file (defaults to 'gitweb_config.perl' - in the same directory as the installed gitweb), or if it does not exists + in the same directory as the installed gitweb), or if it does not exist then fallback system-wide configuration file (defaults to `/etc/gitweb.conf`). Values obtained in later configuration files override values obtained earlier @@ -242,7 +242,7 @@ $mimetypes_file:: $highlight_bin:: Path to the highlight executable to use (it must be the one from - http://www.andre-simon.de[] due to assumptions about parameters and output). + http://andre-simon.de/zip/download.php[] due to assumptions about parameters and output). By default set to 'highlight'; set it to full path to highlight executable if it is not installed on your web server's PATH. Note that 'highlight' feature must be set for gitweb to actually @@ -820,7 +820,7 @@ filesystem (i.e. "$projectroot/$project"), `%h` to the current hash (\'h' gitweb parameter) and `%b` to the current hash base (\'hb' gitweb parameter); `%%` expands to \'%'. + -For example, at the time this page was written, the http://repo.or.cz[] +For example, at the time this page was written, the https://repo.or.cz[] Git hosting site set it to the following to enable graphical log (using the third party tool *git-browser*): + diff --git a/Documentation/gitweb.txt b/Documentation/gitweb.txt index 7cee9d3689..ddd4a0fc70 100644 --- a/Documentation/gitweb.txt +++ b/Documentation/gitweb.txt @@ -8,7 +8,7 @@ gitweb - Git web interface (web frontend to Git repositories) SYNOPSIS -------- To get started with gitweb, run linkgit:git-instaweb[1] from a Git repository. -This would configure and start your web server, and run web browser pointing to +This will configure and start your web server, and run a web browser pointing to gitweb. @@ -20,15 +20,15 @@ Gitweb provides a web interface to Git repositories. Its features include: * Browsing every revision of the repository. * Viewing the contents of files in the repository at any revision. * Viewing the revision log of branches, history of files and directories, - see what was changed when, by who. + seeing what was changed, when, and by whom. * Viewing the blame/annotation details of any file (if enabled). * Generating RSS and Atom feeds of commits, for any branch. The feeds are auto-discoverable in modern web browsers. -* Viewing everything that was changed in a revision, and step through +* Viewing everything that was changed in a revision, and stepping through revisions one at a time, viewing the history of the repository. -* Finding commits which commit messages matches given search term. +* Finding commits whose commit messages match a given search term. -See http://repo.or.cz/w/git.git/tree/HEAD:/gitweb/[] for gitweb source code, +See https://repo.or.cz/w/git.git/tree/HEAD:/gitweb/[] for gitweb source code, browsed using gitweb itself. @@ -41,9 +41,9 @@ for details. Repositories ~~~~~~~~~~~~ Gitweb can show information from one or more Git repositories. These -repositories have to be all on local filesystem, and have to share common +repositories have to be all on local filesystem, and have to share a common repository root, i.e. be all under a single parent repository (but see also -"Advanced web server setup" section, "Webserver configuration with multiple +the "Advanced web server setup" section, "Webserver configuration with multiple projects' root" subsection). ----------------------------------------------------------------------- @@ -51,7 +51,7 @@ our $projectroot = '/path/to/parent/directory'; ----------------------------------------------------------------------- The default value for `$projectroot` is `/pub/git`. You can change it during -building gitweb via `GITWEB_PROJECTROOT` build configuration variable. +building gitweb via the `GITWEB_PROJECTROOT` build configuration variable. By default all Git repositories under `$projectroot` are visible and available to gitweb. The list of projects is generated by default by scanning the @@ -66,7 +66,7 @@ found at "$projectroot/$repo". Projects list file format ~~~~~~~~~~~~~~~~~~~~~~~~~ -Instead of having gitweb find repositories by scanning filesystem +Instead of having gitweb find repositories by scanning the filesystem starting from $projectroot, you can provide a pre-generated list of visible projects by setting `$projects_list` to point to a plain text file with a list of projects (with some additional info). @@ -503,7 +503,7 @@ repositories, you can configure Apache like this: The above configuration expects your public repositories to live under `/pub/git` and will serve them as `http://git.domain.org/dir-under-pub-git`, -both as clonable Git URL and as browseable gitweb interface. If you then +both as clonable Git URL and as browsable gitweb interface. If you then start your linkgit:git-daemon[1] with `--base-path=/pub/git --export-all` then you can even use the `git://` URL with exactly the same path. diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index 5a537268e2..fbbb3f2de3 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -98,9 +98,8 @@ to point at the new commit. revision. [[def_commit-ish]]commit-ish (also committish):: - A <<def_commit_object,commit object>> or an - <<def_object,object>> that can be recursively dereferenced to - a commit object. + A <<def_commit_object,commit object>> or an <<def_object,object>> that + can be recursively <<def_dereference,dereferenced>> to a commit object. The following are all commit-ishes: a commit object, a <<def_tag_object,tag object>> that points to a commit @@ -125,6 +124,25 @@ to point at the new commit. dangling object has no references to it from any reference or <<def_object,object>> in the <<def_repository,repository>>. +[[def_dereference]]dereference:: + Referring to a <<def_symref,symbolic ref>>: the action of accessing the + <<def_ref,reference>> pointed at by a symbolic ref. Recursive + dereferencing involves repeating the aforementioned process on the + resulting ref until a non-symbolic reference is found. ++ +Referring to a <<def_tag_object,tag object>>: the action of accessing the +<<def_object,object>> a tag points at. Tags are recursively dereferenced by +repeating the operation on the result object until the result has either a +specified <<def_object_type,object type>> (where applicable) or any non-"tag" +object type. A synonym for "recursive dereference" in the context of tags is +"<<def_peel,peel>>". ++ +Referring to a <<def_commit_object,commit object>>: the action of accessing +the commit's tree object. Commits cannot be dereferenced recursively. ++ +Unless otherwise specified, "dereferencing" as it used in the context of Git +commands or protocols is implicitly recursive. + [[def_detached_HEAD]]detached HEAD:: Normally the <<def_HEAD,HEAD>> stores the name of a <<def_branch,branch>>, and commands that operate on the @@ -184,9 +202,11 @@ current branch integrates with) obviously do not work, as there is no [[def_gitfile]]gitfile:: A plain file `.git` at the root of a working tree that points at the directory that is the real repository. + For proper use see linkgit:git-worktree[1] or linkgit:git-submodule[1]. + For syntax see linkgit:gitrepository-layout[5]. [[def_grafts]]grafts:: - Grafts enables two otherwise different lines of development to be joined + Grafts enable two otherwise different lines of development to be joined together by recording fake ancestry information for commits. This way you can make Git pretend the set of <<def_parent,parents>> a <<def_commit,commit>> has is different from what was recorded when the commit was @@ -444,6 +464,10 @@ exclude;; of the logical predecessor(s) in the line of development, i.e. its parents. +[[def_peel]]peel:: + The action of recursively <<def_dereference,dereferencing>> a + <<def_tag_object,tag object>>. + [[def_pickaxe]]pickaxe:: The term <<def_pickaxe,pickaxe>> refers to an option to the diffcore routines that help select changes that add or delete a given text @@ -620,12 +644,11 @@ The most notable example is `HEAD`. copies of) commit objects of the contained submodules. [[def_symref]]symref:: - Symbolic reference: instead of containing the <<def_SHA1,SHA-1>> - id itself, it is of the format 'ref: refs/some/thing' and when - referenced, it recursively dereferences to this reference. - '<<def_HEAD,HEAD>>' is a prime example of a symref. Symbolic - references are manipulated with the linkgit:git-symbolic-ref[1] - command. + Symbolic reference: instead of containing the <<def_SHA1,SHA-1>> id + itself, it is of the format 'ref: refs/some/thing' and when referenced, + it recursively <<def_dereference,dereferences>> to this reference. + '<<def_HEAD,HEAD>>' is a prime example of a symref. Symbolic references + are manipulated with the linkgit:git-symbolic-ref[1] command. [[def_tag]]tag:: A <<def_ref,ref>> under `refs/tags/` namespace that points to an @@ -661,11 +684,11 @@ The most notable example is `HEAD`. <<def_tree,tree>> is equivalent to a <<def_directory,directory>>. [[def_tree-ish]]tree-ish (also treeish):: - A <<def_tree_object,tree object>> or an <<def_object,object>> - that can be recursively dereferenced to a tree object. - Dereferencing a <<def_commit_object,commit object>> yields the - tree object corresponding to the <<def_revision,revision>>'s - top <<def_directory,directory>>. + A <<def_tree_object,tree object>> or an <<def_object,object>> that can + be recursively <<def_dereference,dereferenced>> to a tree object. + Dereferencing a <<def_commit_object,commit object>> yields the tree + object corresponding to the <<def_revision,revision>>'s top + <<def_directory,directory>>. The following are all tree-ishes: a <<def_commit-ish,commit-ish>>, a tree object, diff --git a/Documentation/howto/coordinate-embargoed-releases.txt b/Documentation/howto/coordinate-embargoed-releases.txt index e653775bab..b9cb95e82f 100644 --- a/Documentation/howto/coordinate-embargoed-releases.txt +++ b/Documentation/howto/coordinate-embargoed-releases.txt @@ -145,7 +145,7 @@ Opening a Security Advisory draft The first step is to https://github.com/git/git/security/advisories/new[open an advisory]. Technically, this is not necessary. However, it is the most -convenient way to obtain the CVE number and it give us a private repository +convenient way to obtain the CVE number and it gives us a private repository associated with it that can be used to collaborate on a fix. Notifying the Linux distributions diff --git a/Documentation/howto/keep-canonical-history-correct.txt b/Documentation/howto/keep-canonical-history-correct.txt index 35d48ef714..5f800fd85a 100644 --- a/Documentation/howto/keep-canonical-history-correct.txt +++ b/Documentation/howto/keep-canonical-history-correct.txt @@ -213,4 +213,4 @@ The procedure will result in a history that looks like this: B0--B1---------B2 ------------ -See also http://git-blame.blogspot.com/2013/09/fun-with-first-parent-history.html +See also https://git-blame.blogspot.com/2013/09/fun-with-first-parent-history.html diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt index d07c6d44e5..013014bbef 100644 --- a/Documentation/howto/maintain-git.txt +++ b/Documentation/howto/maintain-git.txt @@ -104,7 +104,7 @@ by doing the following: files in mbox format). - Write his own patches to address issues raised on the list but - nobody has stepped up solving. Send it out just like other + nobody has stepped up to solve. Send it out just like other contributors do, and pick them up just like patches from other contributors (see above). @@ -411,13 +411,13 @@ Preparing a "merge-fix" A merge of two topics may not textually conflict but still have conflict at the semantic level. A classic example is for one topic -to rename an variable and all its uses, while another topic adds a +to rename a variable and all its uses, while another topic adds a new use of the variable under its old name. When these two topics are merged together, the reference to the variable newly added by the latter topic will still use the old name in the result. The Meta/Reintegrate script that is used by redo-jch and redo-seen -scripts implements a crude but usable way to work this issue around. +scripts implements a crude but usable way to work around this issue. When the script merges branch $X, it checks if "refs/merge-fix/$X" exists, and if so, the effect of it is squashed into the result of the mechanical merge. In other words, diff --git a/Documentation/howto/use-git-daemon.txt b/Documentation/howto/use-git-daemon.txt index 7af2e52cf3..2cad9b3ca5 100644 --- a/Documentation/howto/use-git-daemon.txt +++ b/Documentation/howto/use-git-daemon.txt @@ -4,7 +4,7 @@ How to use git-daemon ===================== Git can be run in inetd mode and in stand alone mode. But all you want is -let a coworker pull from you, and therefore need to set up a Git server +to let a coworker pull from you, and therefore need to set up a Git server real quick, right? Note that git-daemon is not really chatty at the moment, especially when diff --git a/Documentation/howto/using-merge-subtree.txt b/Documentation/howto/using-merge-subtree.txt index a499a94ac2..3bd581ac35 100644 --- a/Documentation/howto/using-merge-subtree.txt +++ b/Documentation/howto/using-merge-subtree.txt @@ -11,7 +11,7 @@ Message-ID: <BAYC1-PASMTP12374B54BA370A1E1C6E78AE4E0@CEZ.ICE> How to use the subtree merge strategy ===================================== -There are situations where you want to include contents in your project +There are situations where you want to include content in your project from an independently developed project. You can just pull from the other project as long as there are no conflicting paths. diff --git a/Documentation/i18n.txt b/Documentation/i18n.txt index 6c6baeeeb7..3a866af4a4 100644 --- a/Documentation/i18n.txt +++ b/Documentation/i18n.txt @@ -34,7 +34,7 @@ project find it more convenient to use legacy encodings, Git does not forbid it. However, there are a few things to keep in mind. -. 'git commit' and 'git commit-tree' issues +. 'git commit' and 'git commit-tree' issue a warning if the commit log message given to it does not look like a valid UTF-8 string, unless you explicitly say your project uses a legacy encoding. The way to say this is to @@ -46,7 +46,7 @@ mind. ------------ + Commit objects created with the above setting record the value -of `i18n.commitEncoding` in its `encoding` header. This is to +of `i18n.commitEncoding` in their `encoding` header. This is to help other people who look at them later. Lack of this header implies that the commit log message is encoded in UTF-8. diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index d8f7cd7ca0..3eaefc4e94 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -191,7 +191,7 @@ endif::git-pull[] --autostash:: --no-autostash:: Automatically create a temporary stash entry before the operation - begins, record it in the special ref `MERGE_AUTOSTASH` + begins, record it in the ref `MERGE_AUTOSTASH` and apply it after the operation ends. This means that you can run the operation on a dirty worktree. However, use with care: the final stash application after a successful diff --git a/Documentation/mergetools/vimdiff.txt b/Documentation/mergetools/vimdiff.txt index 2d631e9b1f..d1a4c468e6 100644 --- a/Documentation/mergetools/vimdiff.txt +++ b/Documentation/mergetools/vimdiff.txt @@ -32,10 +32,10 @@ have special meaning: - `+` is used to "open a new tab" - `,` is used to "open a new vertical split" - `/` is used to "open a new horizontal split" - - `@` is used to indicate which is the file containing the final version after + - `@` is used to indicate the file containing the final version after solving the conflicts. If not present, `MERGED` will be used by default. -The precedence of the operators is this one (you can use parentheses to change +The precedence of the operators is as follows (you can use parentheses to change it): `@` > `+` > `/` > `,` @@ -162,7 +162,7 @@ information as the first tab, with a different layout. | REMOTE | | --------------------------------------------- .... -Note how in the third tab definition we need to use parenthesis to make `,` +Note how in the third tab definition we need to use parentheses to make `,` have precedence over `/`. -- diff --git a/Documentation/object-format-disclaimer.txt b/Documentation/object-format-disclaimer.txt index 4cb106f0d1..e561e6668c 100644 --- a/Documentation/object-format-disclaimer.txt +++ b/Documentation/object-format-disclaimer.txt @@ -1,6 +1,9 @@ -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. +Note: At present, there is no interoperability between SHA-256 +repositories and SHA-1 repositories. + +Historically, we warned that SHA-256 repositories may later need +backward incompatible changes when we introduce such interoperability +features. Today, we only expect compatible changes. Furthermore, if such +changes prove to be necessary, it can be expected that SHA-256 repositories +created with today's Git will be usable by future versions of Git +without data loss. diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 3b71334459..d38b4ab566 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -122,7 +122,9 @@ The placeholders are: - Placeholders that expand to a single literal character: '%n':: newline '%%':: a raw '%' -'%x00':: print a byte from a hex code +'%x00':: '%x' followed by two hexadecimal digits is replaced with a + byte with the hexadecimal digits' value (we will call this + "literal formatting code" in the rest of this document). - Placeholders that affect formatting of later placeholders: '%Cred':: switch color to red @@ -222,13 +224,30 @@ The placeholders are: linkgit:git-rev-list[1]) '%d':: ref names, like the --decorate option of linkgit:git-log[1] '%D':: ref names without the " (", ")" wrapping. -'%(describe[:options])':: human-readable name, like - linkgit:git-describe[1]; empty string for - undescribable commits. The `describe` string - may be followed by a colon and zero or more - comma-separated options. Descriptions can be - inconsistent when tags are added or removed at - the same time. +'%(decorate[:<options>])':: +ref names with custom decorations. The `decorate` string may be followed by a +colon and zero or more comma-separated options. Option values may contain +literal formatting codes. These must be used for commas (`%x2C`) and closing +parentheses (`%x29`), due to their role in the option syntax. ++ +** 'prefix=<value>': Shown before the list of ref names. Defaults to "{nbsp}`(`". +** 'suffix=<value>': Shown after the list of ref names. Defaults to "`)`". +** 'separator=<value>': Shown between ref names. Defaults to "`,`{nbsp}". +** 'pointer=<value>': Shown between HEAD and the branch it points to, if any. + Defaults to "{nbsp}`->`{nbsp}". +** 'tag=<value>': Shown before tag names. Defaults to "`tag:`{nbsp}". + ++ +For example, to produce decorations with no wrapping +or tag annotations, and spaces as separators: ++ +`%(decorate:prefix=,suffix=,tag=,separator= )` + +'%(describe[:<options>])':: +human-readable name, like linkgit:git-describe[1]; empty string for +undescribable commits. The `describe` string may be followed by a colon and +zero or more comma-separated options. Descriptions can be inconsistent when +tags are added or removed at the same time. + ** 'tags[=<bool-value>]': Instead of only considering annotated tags, consider lightweight tags as well. @@ -281,13 +300,11 @@ endif::git-rev-list[] '%gE':: reflog identity email (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) '%gs':: reflog subject -'%(trailers[:options])':: display the trailers of the body as - interpreted by - linkgit:git-interpret-trailers[1]. The - `trailers` string may be followed by a colon - and zero or more comma-separated options. - If any option is provided multiple times the - last occurrence wins. +'%(trailers[:<options>])':: +display the trailers of the body as interpreted by +linkgit:git-interpret-trailers[1]. The `trailers` string may be followed by +a colon and zero or more comma-separated options. If any option is provided +multiple times, the last occurrence wins. + ** 'key=<key>': only show trailers with specified <key>. Matching is done case-insensitively and trailing colon is optional. If option is diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt index dc685be363..23888cd612 100644 --- a/Documentation/pretty-options.txt +++ b/Documentation/pretty-options.txt @@ -48,7 +48,7 @@ people using 80-column terminals. --expand-tabs:: --no-expand-tabs:: Perform a tab expansion (replace each tab with enough spaces - to fill to the next display column that is multiple of '<n>') + to fill to the next display column that is a multiple of '<n>') in the log message before showing it in the output. `--expand-tabs` is a short-hand for `--expand-tabs=8`, and `--no-expand-tabs` is a short-hand for `--expand-tabs=0`, @@ -73,7 +73,7 @@ environment overrides). See linkgit:git-config[1] for more details. With an optional '<ref>' argument, use the ref to find the notes to display. The ref can specify the full refname when it begins with `refs/notes/`; when it begins with `notes/`, `refs/` and otherwise -`refs/notes/` is prefixed to form a full name of the ref. +`refs/notes/` is prefixed to form the full name of the ref. + Multiple --notes options can be combined to control which notes are being displayed. Examples: "--notes=foo" will show only notes from @@ -87,6 +87,10 @@ being displayed. Examples: "--notes=foo" will show only notes from "--notes --notes=foo --no-notes --notes=bar" will only show notes from "refs/notes/bar". +--show-notes-by-default:: + Show the default notes unless options for displaying specific + notes are given. + --show-notes[=<ref>]:: --[no-]standard-notes:: These options are deprecated. Use the above --notes/--no-notes diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt index 95a7390b2c..c718f7946f 100644 --- a/Documentation/pull-fetch-param.txt +++ b/Documentation/pull-fetch-param.txt @@ -71,7 +71,7 @@ refspec (or `--force`). Unlike when pushing with linkgit:git-push[1], any updates outside of `refs/{tags,heads}/*` will be accepted without `+` in the refspec (or `--force`), whether that's swapping e.g. a tree object for a blob, or -a commit for another commit that's doesn't have the previous commit as +a commit for another commit that doesn't have the previous commit as an ancestor etc. + Unlike when pushing with linkgit:git-push[1], there is no @@ -80,7 +80,7 @@ configuration which'll amend these rules, and nothing like a + As with pushing with linkgit:git-push[1], all of the rules described above about what's not allowed as an update can be overridden by -adding an the optional leading `+` to a refspec (or using `--force` +adding an optional leading `+` to a refspec (or using the `--force` command line option). The only exception to this is that no amount of forcing will make the `refs/heads/*` namespace accept a non-commit object. @@ -88,7 +88,7 @@ object. [NOTE] When the remote branch you want to fetch is known to be rewound and rebased regularly, it is expected that -its new tip will not be descendant of its previous tip +its new tip will not be a descendant of its previous tip (as stored in your remote-tracking branch the last time you fetched). You would want to use the `+` sign to indicate non-fast-forward updates diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 3000888a90..2bf239ff03 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -56,7 +56,7 @@ endif::git-rev-list[] error to use this option unless `--walk-reflogs` is in use. --grep=<pattern>:: - Limit the commits output to ones with log message that + Limit the commits output to ones with a log message that matches the specified pattern (regular expression). With more than one `--grep=<pattern>`, commits whose message matches any of the given patterns are chosen (but see @@ -72,7 +72,7 @@ endif::git-rev-list[] instead of ones that match at least one. --invert-grep:: - Limit the commits output to ones with log message that do not + Limit the commits output to ones with a log message that do not match the pattern specified with `--grep=<pattern>`. -i:: @@ -151,6 +151,10 @@ endif::git-log[] --not:: Reverses the meaning of the '{caret}' prefix (or lack thereof) for all following revision specifiers, up to the next `--not`. + When used on the command line before --stdin, the revisions passed + through stdin will not be affected by it. Conversely, when passed + via standard input, the revisions passed on the command line will + not be affected by it. --all:: Pretend as if all the refs in `refs/`, along with `HEAD`, are @@ -236,10 +240,13 @@ ifndef::git-rev-list[] endif::git-rev-list[] --stdin:: - In addition to the '<commit>' listed on the command - line, read them from the standard input. If a `--` separator is - seen, stop reading commits and start reading paths to limit the - result. + In addition to getting arguments from the command line, read + them from standard input as well. This accepts commits and + pseudo-options like `--all` and `--glob=`. When a `--` separator + is seen, the following input is treated as paths and used to + limit the result. Flags like `--not` which are read via standard input + are only respected for arguments passed in the same way and will not + influence any subsequent command line arguments. ifdef::git-rev-list[] --quiet:: diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 9aa58052bc..6ea6c7cead 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -30,10 +30,11 @@ characters and to avoid word splitting. explicitly say 'heads/master' to tell Git which one you mean. When ambiguous, a '<refname>' is disambiguated by taking the first match in the following rules: - ++ . If '$GIT_DIR/<refname>' exists, that is what you mean (this is usually - useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD`, `MERGE_HEAD` - and `CHERRY_PICK_HEAD`); + useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD`, `MERGE_HEAD`, + `REBASE_HEAD`, `REVERT_HEAD`, `CHERRY_PICK_HEAD`, `BISECT_HEAD` + and `AUTO_MERGE`); . otherwise, 'refs/<refname>' if it exists; @@ -44,19 +45,38 @@ characters and to avoid word splitting. . otherwise, 'refs/remotes/<refname>' if it exists; . otherwise, 'refs/remotes/<refname>/HEAD' if it exists. + + -`HEAD` names the commit on which you based the changes in the working tree. -`FETCH_HEAD` records the branch which you fetched from a remote repository -with your last `git fetch` invocation. -`ORIG_HEAD` is created by commands that move your `HEAD` in a drastic -way (`git am`, `git merge`, `git rebase`, `git reset`), -to record the position of the `HEAD` before their operation, so that -you can easily change the tip of the branch back to the state before you ran -them. -`MERGE_HEAD` records the commit(s) which you are merging into your branch -when you run `git merge`. -`CHERRY_PICK_HEAD` records the commit which you are cherry-picking -when you run `git cherry-pick`. + `HEAD`::: + names the commit on which you based the changes in the working tree. + `FETCH_HEAD`::: + records the branch which you fetched from a remote repository with + your last `git fetch` invocation. + `ORIG_HEAD`::: + is created by commands that move your `HEAD` in a drastic way (`git + am`, `git merge`, `git rebase`, `git reset`), to record the position + of the `HEAD` before their operation, so that you can easily change + the tip of the branch back to the state before you ran them. + `MERGE_HEAD`::: + records the commit(s) which you are merging into your branch when you + run `git merge`. + `REBASE_HEAD`::: + during a rebase, records the commit at which the operation is + currently stopped, either because of conflicts or an `edit` command in + an interactive rebase. + `REVERT_HEAD`::: + records the commit which you are reverting when you run `git revert`. + `CHERRY_PICK_HEAD`::: + records the commit which you are cherry-picking when you run `git + cherry-pick`. + `BISECT_HEAD`::: + records the current commit to be tested when you run `git bisect + --no-checkout`. + `AUTO_MERGE`::: + records a tree object corresponding to the state the + 'ort' merge strategy wrote to the working tree when a merge operation + resulted in conflicts. + + Note that any of the 'refs/*' cases above may come either from the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file. diff --git a/Documentation/scalar.txt b/Documentation/scalar.txt index f33436c7f6..361f51a647 100644 --- a/Documentation/scalar.txt +++ b/Documentation/scalar.txt @@ -8,7 +8,8 @@ scalar - A tool for managing large Git repositories SYNOPSIS -------- [verse] -scalar clone [--single-branch] [--branch <main-branch>] [--full-clone] <url> [<enlistment>] +scalar clone [--single-branch] [--branch <main-branch>] [--full-clone] + [--[no-]src] <url> [<enlistment>] scalar list scalar register [<enlistment>] scalar unregister [<enlistment>] @@ -80,6 +81,11 @@ remote-tracking branch for the branch this option was used for the initial cloning. If the HEAD at the remote did not point at any branch when `--single-branch` clone was made, no remote-tracking branch is created. +--[no-]src:: + By default, `scalar clone` places the cloned repository within a + `<entlistment>/src` directory. Use `--no-src` to place the cloned + repository directly in the `<enlistment>` directory. + --[no-]full-clone:: A sparse-checkout is initialized by default. This behavior can be turned off via `--full-clone`. diff --git a/Documentation/signoff-option.txt b/Documentation/signoff-option.txt index 12aa2333e4..d98758f3cb 100644 --- a/Documentation/signoff-option.txt +++ b/Documentation/signoff-option.txt @@ -9,7 +9,7 @@ endif::git-commit[] the committer has the rights to submit the work under the project's license or agrees to some contributor representation, such as a Developer Certificate of Origin. - (See http://developercertificate.org for the one used by the + (See https://developercertificate.org for the one used by the Linux kernel and Git projects.) Consult the documentation or leadership of the project to which you're contributing to understand how the signoffs are used in that project. diff --git a/Documentation/technical/api-index-skel.txt b/Documentation/technical/api-index-skel.txt index eda8c195c1..7780a76b08 100644 --- a/Documentation/technical/api-index-skel.txt +++ b/Documentation/technical/api-index-skel.txt @@ -1,7 +1,7 @@ Git API Documents ================= -Git has grown a set of internal API over time. This collection +Git has grown a set of internal APIs over time. This collection documents them. //////////////////////////////////////////////////////////////// diff --git a/Documentation/technical/api-merge.txt b/Documentation/technical/api-merge.txt index 487d4d83ff..c2ba01828c 100644 --- a/Documentation/technical/api-merge.txt +++ b/Documentation/technical/api-merge.txt @@ -28,9 +28,9 @@ and `diff.c` for examples. * `struct ll_merge_options` -Check ll-merge.h for details. +Check merge-ll.h for details. Low-level (single file) merge ----------------------------- -Check ll-merge.h for details. +Check merge-ll.h for details. diff --git a/Documentation/technical/api-simple-ipc.txt b/Documentation/technical/api-simple-ipc.txt index d44ada98e7..c4fb152b23 100644 --- a/Documentation/technical/api-simple-ipc.txt +++ b/Documentation/technical/api-simple-ipc.txt @@ -2,7 +2,7 @@ Simple-IPC API ============== The Simple-IPC API is a collection of `ipc_` prefixed library routines -and a basic communication protocol that allow an IPC-client process to +and a basic communication protocol that allows an IPC-client process to send an application-specific IPC-request message to an IPC-server process and receive an application-specific IPC-response message. @@ -20,12 +20,12 @@ IPC-client. The IPC-client routines within a client application process connect to the IPC-server and send a request message and wait for a response. -When received, the response is returned back the caller. +When received, the response is returned back to the caller. For example, the `fsmonitor--daemon` feature will be built as a server application on top of the IPC-server library routines. It will have threads watching for file system events and a thread pool waiting for -client connections. Clients, such as `git status` will request a list +client connections. Clients, such as `git status`, will request a list of file system events since a point in time and the server will respond with a list of changed files and directories. The formats of the request and response are application-specific; the IPC-client and @@ -37,7 +37,7 @@ Comparison with sub-process model The Simple-IPC mechanism differs from the existing `sub-process.c` model (Documentation/technical/long-running-process-protocol.txt) and -used by applications like Git-LFS. In the LFS-style sub-process model +used by applications like Git-LFS. In the LFS-style sub-process model, the helper is started by the foreground process, communication happens via a pair of file descriptors bound to the stdin/stdout of the sub-process, the sub-process only serves the current foreground @@ -102,4 +102,4 @@ stateless request, receive an application-specific response, and disconnect. It is a one round trip facility for querying the server. The Simple-IPC routines hide the socket, named pipe, and thread pool details and allow the application -layer to focus on the application at hand. +layer to focus on the task at hand. diff --git a/Documentation/technical/bitmap-format.txt b/Documentation/technical/bitmap-format.txt index c2e652b71a..f5d200939b 100644 --- a/Documentation/technical/bitmap-format.txt +++ b/Documentation/technical/bitmap-format.txt @@ -114,7 +114,7 @@ result in an empty bitmap (no bits set). * N entries with compressed bitmaps, one for each indexed commit + -Where `N` is the total amount of entries in this bitmap index. +Where `N` is the total number of entries in this bitmap index. Each entry contains the following: ** {empty} @@ -126,7 +126,7 @@ Each entry contains the following: ** {empty} 1-byte XOR-offset: :: The xor offset used to compress this bitmap. For an entry - in position `x`, a XOR offset of `y` means that the actual + in position `x`, an XOR offset of `y` means that the actual bitmap representing this commit is composed by XORing the bitmap for this entry with the bitmap in entry `x-y` (i.e. the bitmap `y` entries before this one). @@ -239,7 +239,7 @@ bitmaps. For a `.bitmap` containing `nr_entries` reachability bitmaps, the table contains a list of `nr_entries` <commit_pos, offset, xor_row> triplets -(sorted in the ascending order of `commit_pos`). The content of i'th +(sorted in the ascending order of `commit_pos`). The content of the i'th triplet is - * {empty} diff --git a/Documentation/technical/commit-graph.txt b/Documentation/technical/commit-graph.txt index 86fed0de0f..2c26e95e51 100644 --- a/Documentation/technical/commit-graph.txt +++ b/Documentation/technical/commit-graph.txt @@ -136,7 +136,7 @@ Design Details - Commit grafts and replace objects can change the shape of the commit history. The latter can also be enabled/disabled on the fly using - `--no-replace-objects`. This leads to difficultly storing both possible + `--no-replace-objects`. This leads to difficulty storing both possible interpretations of a commit id, especially when computing generation numbers. The commit-graph will not be read or written when replace-objects or grafts are present. diff --git a/Documentation/technical/parallel-checkout.txt b/Documentation/technical/parallel-checkout.txt index 47c9b6183c..b4a144e5f4 100644 --- a/Documentation/technical/parallel-checkout.txt +++ b/Documentation/technical/parallel-checkout.txt @@ -63,7 +63,7 @@ improvements over the sequential code, but there was still too much lock contention. A `perf` profiling indicated that around 20% of the runtime during a local Linux clone (on an SSD) was spent in locking functions. For this reason this approach was rejected in favor of using multiple -child processes, which led to a better performance. +child processes, which led to better performance. Multi-Process Solution ---------------------- @@ -126,7 +126,7 @@ Then, for each assigned item, each worker: * W5: Writes the result to the file descriptor opened at W2. -* W6: Calls `fstat()` or lstat()` on the just-written path, and sends +* W6: Calls `fstat()` or `lstat()` on the just-written path, and sends the result back to the main process, together with the end status of the operation and the item's identification number. @@ -148,7 +148,7 @@ information, the main process handles the results in two steps: - First, it updates the in-memory index with the `lstat()` information sent by the workers. (This must be done first as this information - might me required in the following step.) + might be required in the following step.) - Then it writes the items which collided on disk (i.e. items marked with `PC_ITEM_COLLIDED`). More on this below. @@ -185,7 +185,7 @@ quite straightforward: for each parallel-eligible entry, the main process must remove all files that prevent this entry from being written (before enqueueing it). This includes any non-directory file in the leading path of the entry. Later, when a worker gets assigned the entry, -it looks again for the non-directories files and for an already existing +it looks again for the non-directory files and for an already existing file at the entry's path. If any of these checks finds something, the worker knows that there was a path collision. @@ -232,7 +232,7 @@ conversion and re-encoding, are eligible for parallel checkout. Ineligible entries are checked out by the classic sequential codepath *before* spawning workers. -Note: submodules's files are also eligible for parallel checkout (as +Note: submodules' files are also eligible for parallel checkout (as long as they don't fall into any of the excluding categories mentioned above). But since each submodule is checked out in its own child process, we don't mix the superproject's and the submodules' files in diff --git a/Documentation/technical/partial-clone.txt b/Documentation/technical/partial-clone.txt index 92fcee2bff..cd948b0072 100644 --- a/Documentation/technical/partial-clone.txt +++ b/Documentation/technical/partial-clone.txt @@ -3,7 +3,7 @@ Partial Clone Design Notes The "Partial Clone" feature is a performance optimization for Git that allows Git to function without having a complete copy of the repository. -The goal of this work is to allow Git better handle extremely large +The goal of this work is to allow Git to better handle extremely large repositories. During clone and fetch operations, Git downloads the complete contents @@ -256,7 +256,7 @@ remote in a specific order. - Dynamic object fetching currently uses the existing pack protocol V0 which means that each object is requested via fetch-pack. The server will send a full set of info/refs when the connection is established. - If there are large number of refs, this may incur significant overhead. + If there are a large number of refs, this may incur significant overhead. Future Work @@ -265,7 +265,7 @@ Future Work - Improve the way to specify the order in which promisor remotes are tried. + -For example this could allow to specify explicitly something like: +For example this could allow specifying explicitly something like: "When fetching from this remote, I want to use these promisor remotes in this order, though, when pushing or fetching to that remote, I want to use those promisor remotes in that order." @@ -322,7 +322,7 @@ Footnotes [a] expensive-to-modify list of missing objects: Earlier in the design of partial clone we discussed the need for a single list of missing objects. - This would essentially be a sorted linear list of OIDs that the were + This would essentially be a sorted linear list of OIDs that were omitted by the server during a clone or subsequent fetches. This file would need to be loaded into memory on every object lookup. diff --git a/Documentation/technical/racy-git.txt b/Documentation/technical/racy-git.txt index ceda4bbfda..59bea66c0f 100644 --- a/Documentation/technical/racy-git.txt +++ b/Documentation/technical/racy-git.txt @@ -11,7 +11,7 @@ write out the next tree object to be committed. The state is "virtual" in the sense that it does not necessarily have to, and often does not, match the files in the working tree. -There are cases Git needs to examine the differences between the +There are cases where Git needs to examine the differences between the virtual working tree state in the index and the files in the working tree. The most obvious case is when the user asks `git diff` (or its low level implementation, `git diff-files`) or @@ -165,9 +165,9 @@ Avoiding runtime penalty In order to avoid the above runtime penalty, post 1.4.2 Git used to have a code that made sure the index file -got timestamp newer than the youngest files in the index when -there are many young files with the same timestamp as the -resulting index file would otherwise would have by waiting +got a timestamp newer than the youngest files in the index when +there were many young files with the same timestamp as the +resulting index file otherwise would have by waiting before finishing writing the index file out. I suspected that in practice the situation where many paths in the @@ -190,7 +190,7 @@ In a large project where raciness avoidance cost really matters, however, the initial computation of all object names in the index takes more than one second, and the index file is written out after all that happens. Therefore the timestamp of the -index file will be more than one seconds later than the +index file will be more than one second later than the youngest file in the working tree. This means that in these cases there actually will not be any racily clean entry in the resulting index. diff --git a/Documentation/technical/reftable.txt b/Documentation/technical/reftable.txt index 6a67cc4174..dd0b37c4e3 100644 --- a/Documentation/technical/reftable.txt +++ b/Documentation/technical/reftable.txt @@ -46,7 +46,7 @@ search lookup, and range scans. Storage in the file is organized into variable sized blocks. Prefix compression is used within a single block to reduce disk space. Block -size and alignment is tunable by the writer. +size and alignment are tunable by the writer. Performance ^^^^^^^^^^^ @@ -115,7 +115,7 @@ Varint encoding Varint encoding is identical to the ofs-delta encoding method used within pack files. -Decoder works such as: +Decoder works as follows: .... val = buf[ptr] & 0x7f @@ -175,7 +175,7 @@ log_index* footer .... -in a log-only file the first log block immediately follows the file +In a log-only file, the first log block immediately follows the file header, without padding to block alignment. Block size @@ -247,7 +247,7 @@ uint32( hash_id ) .... The header is identical to `version_number=1`, with the 4-byte hash ID -("sha1" for SHA1 and "s256" for SHA-256) append to the header. +("sha1" for SHA1 and "s256" for SHA-256) appended to the header. For maximum backward compatibility, it is recommended to use version 1 when writing SHA1 reftables. @@ -288,7 +288,7 @@ The 2-byte `restart_count` stores the number of entries in the `restart_count` to binary search between restarts before starting a linear scan. -Exactly `restart_count` 3-byte `restart_offset` values precedes the +Exactly `restart_count` 3-byte `restart_offset` values precede the `restart_count`. Offsets are relative to the start of the block and refer to the first byte of any `ref_record` whose name has not been prefix compressed. Entries in the `restart_offset` list must be sorted, diff --git a/Documentation/technical/remembering-renames.txt b/Documentation/technical/remembering-renames.txt index 1e34d91390..73f41761e2 100644 --- a/Documentation/technical/remembering-renames.txt +++ b/Documentation/technical/remembering-renames.txt @@ -664,7 +664,7 @@ skip-irrelevant-renames optimization means we sometimes don't detect renames for any files within a directory that was renamed, in which case we will not have been able to detect any rename for the directory itself. In such a case, we do not know whether the directory was -renamed; we want to be careful to avoid cacheing some kind of "this +renamed; we want to be careful to avoid caching some kind of "this directory was not renamed" statement. If we did, then a subsequent commit being rebased could add a file to the old directory, and the user would expect it to end up in the correct directory -- something diff --git a/Documentation/technical/repository-version.txt b/Documentation/technical/repository-version.txt index 8ef664b0b9..045a76756f 100644 --- a/Documentation/technical/repository-version.txt +++ b/Documentation/technical/repository-version.txt @@ -96,7 +96,7 @@ The value of this key is the name of the promisor remote. ==== `worktreeConfig` If set, by default "git config" reads from both "config" and -"config.worktree" file from GIT_DIR in that order. In +"config.worktree" files from GIT_DIR in that order. In multiple working directory mode, "config" file is shared while "config.worktree" is per-working directory (i.e., it's in GIT_COMMON_DIR/worktrees/<id>/config.worktree) diff --git a/Documentation/technical/rerere.txt b/Documentation/technical/rerere.txt index be58f1bee3..580f23360a 100644 --- a/Documentation/technical/rerere.txt +++ b/Documentation/technical/rerere.txt @@ -60,7 +60,7 @@ By resolving this conflict, to leave line D, the user declares: what AB and AC wanted to do. As branch AC2 refers to the same commit as AC, the above implies that -this is also compatible what AB and AC2 wanted to do. +this is also compatible with what AB and AC2 wanted to do. By extension, this means that rerere should recognize that the above conflicts are the same. To do this, the labels on the conflict @@ -76,7 +76,7 @@ examples would both result in the following normalized conflict: Sorting hunks ~~~~~~~~~~~~~ -As before, lets imagine that a common ancestor had a file with line A +As before, let's imagine that a common ancestor had a file with line A its early part, and line X in its late part. And then four branches are forked that do these things: @@ -145,7 +145,7 @@ Nested conflicts Nested conflicts are handled very similarly to "simple" conflicts. Similar to simple conflicts, the conflict is first normalized by stripping the labels from conflict markers, stripping the common ancestor -version, and the sorting the conflict hunks, both for the outer and the +version, and sorting the conflict hunks, both for the outer and the inner conflict. This is done recursively, so any number of nested conflicts can be handled. diff --git a/Documentation/technical/unit-tests.txt b/Documentation/technical/unit-tests.txt new file mode 100644 index 0000000000..206037ffb1 --- /dev/null +++ b/Documentation/technical/unit-tests.txt @@ -0,0 +1,240 @@ += Unit Testing + +In our current testing environment, we spend a significant amount of effort +crafting end-to-end tests for error conditions that could easily be captured by +unit tests (or we simply forgo some hard-to-setup and rare error conditions). +Unit tests additionally provide stability to the codebase and can simplify +debugging through isolation. Writing unit tests in pure C, rather than with our +current shell/test-tool helper setup, simplifies test setup, simplifies passing +data around (no shell-isms required), and reduces testing runtime by not +spawning a separate process for every test invocation. + +We believe that a large body of unit tests, living alongside the existing test +suite, will improve code quality for the Git project. + +== Definitions + +For the purposes of this document, we'll use *test framework* to refer to +projects that support writing test cases and running tests within the context +of a single executable. *Test harness* will refer to projects that manage +running multiple executables (each of which may contain multiple test cases) and +aggregating their results. + +In reality, these terms are not strictly defined, and many of the projects +discussed below contain features from both categories. + +For now, we will evaluate projects solely on their framework features. Since we +are relying on having TAP output (see below), we can assume that any framework +can be made to work with a harness that we can choose later. + + +== Summary + +We believe the best way forward is to implement a custom TAP framework for the +Git project. We use a version of the framework originally proposed in +https://lore.kernel.org/git/c902a166-98ce-afba-93f2-ea6027557176@gmail.com/[1]. + +See the <<framework-selection,Framework Selection>> section below for the +rationale behind this decision. + + +== Choosing a test harness + +During upstream discussion, it was occasionally noted that `prove` provides many +convenient features, such as scheduling slower tests first, or re-running +previously failed tests. + +While we already support the use of `prove` as a test harness for the shell +tests, it is not strictly required. The t/Makefile allows running shell tests +directly (though with interleaved output if parallelism is enabled). Git +developers who wish to use `prove` as a more advanced harness can do so by +setting DEFAULT_TEST_TARGET=prove in their config.mak. + +We will follow a similar approach for unit tests: by default the test +executables will be run directly from the t/Makefile, but `prove` can be +configured with DEFAULT_UNIT_TEST_TARGET=prove. + + +[[framework-selection]] +== Framework selection + +There are a variety of features we can use to rank the candidate frameworks, and +those features have different priorities: + +* Critical features: we probably won't consider a framework without these +** Can we legally / easily use the project? +*** <<license,License>> +*** <<vendorable-or-ubiquitous,Vendorable or ubiquitous>> +*** <<maintainable-extensible,Maintainable / extensible>> +*** <<major-platform-support,Major platform support>> +** Does the project support our bare-minimum needs? +*** <<tap-support,TAP support>> +*** <<diagnostic-output,Diagnostic output>> +*** <<runtime-skippable-tests,Runtime-skippable tests>> +* Nice-to-have features: +** <<parallel-execution,Parallel execution>> +** <<mock-support,Mock support>> +** <<signal-error-handling,Signal & error-handling>> +* Tie-breaker stats +** <<project-kloc,Project KLOC>> +** <<adoption,Adoption>> + +[[license]] +=== License + +We must be able to legally use the framework in connection with Git. As Git is +licensed only under GPLv2, we must eliminate any LGPLv3, GPLv3, or Apache 2.0 +projects. + +[[vendorable-or-ubiquitous]] +=== Vendorable or ubiquitous + +We want to avoid forcing Git developers to install new tools just to run unit +tests. Any prospective frameworks and harnesses must either be vendorable +(meaning, we can copy their source directly into Git's repository), or so +ubiquitous that it is reasonable to expect that most developers will have the +tools installed already. + +[[maintainable-extensible]] +=== Maintainable / extensible + +It is unlikely that any pre-existing project perfectly fits our needs, so any +project we select will need to be actively maintained and open to accepting +changes. Alternatively, assuming we are vendoring the source into our repo, it +must be simple enough that Git developers can feel comfortable making changes as +needed to our version. + +In the comparison table below, "True" means that the framework seems to have +active developers, that it is simple enough that Git developers can make changes +to it, and that the project seems open to accepting external contributions (or +that it is vendorable). "Partial" means that at least one of the above +conditions holds. + +[[major-platform-support]] +=== Major platform support + +At a bare minimum, unit-testing must work on Linux, MacOS, and Windows. + +In the comparison table below, "True" means that it works on all three major +platforms with no issues. "Partial" means that there may be annoyances on one or +more platforms, but it is still usable in principle. + +[[tap-support]] +=== TAP support + +The https://testanything.org/[Test Anything Protocol] is a text-based interface +that allows tests to communicate with a test harness. It is already used by +Git's integration test suite. Supporting TAP output is a mandatory feature for +any prospective test framework. + +In the comparison table below, "True" means this is natively supported. +"Partial" means TAP output must be generated by post-processing the native +output. + +Frameworks that do not have at least Partial support will not be evaluated +further. + +[[diagnostic-output]] +=== Diagnostic output + +When a test case fails, the framework must generate enough diagnostic output to +help developers find the appropriate test case in source code in order to debug +the failure. + +[[runtime-skippable-tests]] +=== Runtime-skippable tests + +Test authors may wish to skip certain test cases based on runtime circumstances, +so the framework should support this. + +[[parallel-execution]] +=== Parallel execution + +Ideally, we will build up a significant collection of unit test cases, most +likely split across multiple executables. It will be necessary to run these +tests in parallel to enable fast develop-test-debug cycles. + +In the comparison table below, "True" means that individual test cases within a +single test executable can be run in parallel. We assume that executable-level +parallelism can be handled by the test harness. + +[[mock-support]] +=== Mock support + +Unit test authors may wish to test code that interacts with objects that may be +inconvenient to handle in a test (e.g. interacting with a network service). +Mocking allows test authors to provide a fake implementation of these objects +for more convenient tests. + +[[signal-error-handling]] +=== Signal & error handling + +The test framework should fail gracefully when test cases are themselves buggy +or when they are interrupted by signals during runtime. + +[[project-kloc]] +=== Project KLOC + +The size of the project, in thousands of lines of code as measured by +https://dwheeler.com/sloccount/[sloccount] (rounded up to the next multiple of +1,000). As a tie-breaker, we probably prefer a project with fewer LOC. + +[[adoption]] +=== Adoption + +As a tie-breaker, we prefer a more widely-used project. We use the number of +GitHub / GitLab stars to estimate this. + + +=== Comparison + +:true: [lime-background]#True# +:false: [red-background]#False# +:partial: [yellow-background]#Partial# + +:gpl: [lime-background]#GPL v2# +:isc: [lime-background]#ISC# +:mit: [lime-background]#MIT# +:expat: [lime-background]#Expat# +:lgpl: [lime-background]#LGPL v2.1# + +:custom-impl: https://lore.kernel.org/git/c902a166-98ce-afba-93f2-ea6027557176@gmail.com/[Custom Git impl.] +:greatest: https://github.com/silentbicycle/greatest[Greatest] +:criterion: https://github.com/Snaipe/Criterion[Criterion] +:c-tap: https://github.com/rra/c-tap-harness/[C TAP] +:check: https://libcheck.github.io/check/[Check] + +[format="csv",options="header",width="33%",subs="specialcharacters,attributes,quotes,macros"] +|===== +Framework,"<<license,License>>","<<vendorable-or-ubiquitous,Vendorable or ubiquitous>>","<<maintainable-extensible,Maintainable / extensible>>","<<major-platform-support,Major platform support>>","<<tap-support,TAP support>>","<<diagnostic-output,Diagnostic output>>","<<runtime--skippable-tests,Runtime- skippable tests>>","<<parallel-execution,Parallel execution>>","<<mock-support,Mock support>>","<<signal-error-handling,Signal & error handling>>","<<project-kloc,Project KLOC>>","<<adoption,Adoption>>" +{custom-impl},{gpl},{true},{true},{true},{true},{true},{true},{false},{false},{false},1,0 +{greatest},{isc},{true},{partial},{true},{partial},{true},{true},{false},{false},{false},3,1400 +{criterion},{mit},{false},{partial},{true},{true},{true},{true},{true},{false},{true},19,1800 +{c-tap},{expat},{true},{partial},{partial},{true},{false},{true},{false},{false},{false},4,33 +{check},{lgpl},{false},{partial},{true},{true},{true},{false},{false},{false},{true},17,973 +|===== + +=== Additional framework candidates + +Several suggested frameworks have been eliminated from consideration: + +* Incompatible licenses: +** https://github.com/zorgnax/libtap[libtap] (LGPL v3) +** https://cmocka.org/[cmocka] (Apache 2.0) +* Missing source: https://www.kindahl.net/mytap/doc/index.html[MyTap] +* No TAP support: +** https://nemequ.github.io/munit/[µnit] +** https://github.com/google/cmockery[cmockery] +** https://github.com/lpabon/cmockery2[cmockery2] +** https://github.com/ThrowTheSwitch/Unity[Unity] +** https://github.com/siu/minunit[minunit] +** https://cunit.sourceforge.net/[CUnit] + + +== Milestones + +* Add useful tests of library-like code +* Integrate with + https://lore.kernel.org/git/20230502211454.1673000-1-calvinwan@google.com/[stdlib + work] +* Run alongside regular `make test` target diff --git a/Documentation/urls-remotes.txt b/Documentation/urls-remotes.txt index e410912fe5..bf17012241 100644 --- a/Documentation/urls-remotes.txt +++ b/Documentation/urls-remotes.txt @@ -33,9 +33,9 @@ config file would appear like this: ------------ The `<pushurl>` is used for pushes only. It is optional and defaults -to `<URL>`. Pushing to a remote affects all defined pushurls or to all +to `<URL>`. Pushing to a remote affects all defined pushurls or all defined urls if no pushurls are defined. Fetch, however, will only -fetch from the first defined url if muliple urls are defined. +fetch from the first defined url if multiple urls are defined. Named file in `$GIT_DIR/remotes` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -48,7 +48,7 @@ provide a refspec on the command line. This file should have the following format: ------------ - URL: one of the above URL format + URL: one of the above URL formats Push: <refspec> Pull: <refspec> diff --git a/Documentation/urls.txt b/Documentation/urls.txt index 1c229d7581..4e79c1589e 100644 --- a/Documentation/urls.txt +++ b/Documentation/urls.txt @@ -6,9 +6,9 @@ address of the remote server, and the path to the repository. Depending on the transport protocol, some of this information may be absent. -Git supports ssh, git, http, and https protocols (in addition, ftp, +Git supports ssh, git, http, and https protocols (in addition, ftp and ftps can be used for fetching, but this is inefficient and -deprecated; do not use it). +deprecated; do not use them). The native transport (i.e. git:// URL) does no authentication and should be used with caution on unsecured networks. diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index dc9c6a663a..5d32ff2384 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1122,7 +1122,7 @@ choosing "Stage Hunk For Commit"). === Creating good commit messages Though not required, it's a good idea to begin the commit message -with a single short (less than 50 character) line summarizing the +with a single short (no more than 50 characters) line summarizing the change, followed by a blank line and then a more thorough description. The text up to the first blank line in a commit message is treated as the commit title, and that title is used @@ -1343,6 +1343,33 @@ $ git diff -3 file.txt # diff against stage 3 $ git diff --theirs file.txt # same as the above. ------------------------------------------------- +When using the 'ort' merge strategy (the default), before updating the working +tree with the result of the merge, Git writes a ref named AUTO_MERGE +reflecting the state of the tree it is about to write. Conflicted paths with +textual conflicts that could not be automatically merged are written to this +tree with conflict markers, just as in the working tree. AUTO_MERGE can thus be +used with linkgit:git-diff[1] to show the changes you've made so far to resolve +conflicts. Using the same example as above, after resolving the conflict we +get: + +------------------------------------------------- +$ git diff AUTO_MERGE +diff --git a/file.txt b/file.txt +index cd10406..8bf5ae7 100644 +--- a/file.txt ++++ b/file.txt +@@ -1,5 +1 @@ +-<<<<<<< HEAD:file.txt +-Hello world +-======= +-Goodbye +->>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt ++Goodbye world +------------------------------------------------- + +Notice that the diff shows we deleted the conflict markers and both versions of +the content line, and wrote "Goodbye world" instead. + The linkgit:git-log[1] and linkgit:gitk[1] commands also provide special help for merges: @@ -4102,13 +4129,11 @@ Note that terminology has changed since that revision. For example, the README in that revision uses the word "changeset" to describe what we now call a <<def_commit_object,commit>>. -Also, we do not call it "cache" any more, but rather "index"; however, the -file is still called `cache.h`. Remark: Not much reason to change it now, -especially since there is no good single name for it anyway, because it is -basically _the_ header file which is included by _all_ of Git's C sources. +Also, we do not call it "cache" any more, but rather "index"; however, +the file is still called `read-cache.h`. If you grasp the ideas in that initial commit, you should check out a -more recent version and skim `cache.h`, `object.h` and `commit.h`. +more recent version and skim `read-cache-ll.h`, `object.h` and `commit.h`. In the early days, Git (in the tradition of UNIX) was a bunch of programs which were extremely simple, and which you used in scripts, piping the @@ -4119,11 +4144,11 @@ many of these parts have become builtins, and some of the core has been and to avoid code duplication. By now, you know what the index is (and find the corresponding data -structures in `cache.h`), and that there are just a couple of object types -(blobs, trees, commits and tags) which inherit their common structure from -`struct object`, which is their first member (and thus, you can cast e.g. -`(struct object *)commit` to achieve the _same_ as `&commit->object`, i.e. -get at the object name and flags). +structures in `read-cache-ll.h`), and that there are just a couple of +object types (blobs, trees, commits and tags) which inherit their +common structure from `struct object`, which is their first member +(and thus, you can cast e.g. `(struct object *)commit` to achieve the +_same_ as `&commit->object`, i.e. get at the object name and flags). Now is a good point to take a break to let this information sink in. |