diff options
Diffstat (limited to 'Documentation')
101 files changed, 2096 insertions, 687 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 711cb9171e..1a7bc4591c 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -26,6 +26,13 @@ code. For Git in general, a few rough rules are: go and fix it up." Cf. http://lkml.iu.edu/hypermail/linux/kernel/1001.3/01069.html + - Log messages to explain your changes are as important as the + changes themselves. Clearly written code and in-code comments + explain how the code works and what is assumed from the surrounding + context. The log messages explain what the changes wanted to + achieve and why the changes were necessary (more on this in the + accompanying SubmittingPatches document). + Make your code readable and sensible, and don't try to be clever. As for more concrete guidelines, just imitate the existing code @@ -210,6 +217,9 @@ For C programs: . since mid 2017 with 512f41cf, we have been using designated initializers for array (e.g. "int array[10] = { [5] = 2 }"). + . since early 2021 with 765dc168882, we have been using variadic + macros, mostly for printf-like trace and debug macros. + These used to be forbidden, but we have not heard any breakage report, and they are assumed to be safe. @@ -499,6 +509,33 @@ For Python scripts: - Where required libraries do not restrict us to Python 2, we try to also be compatible with Python 3.1 and later. + +Program Output + + We make a distinction between a Git command's primary output and + output which is merely chatty feedback (for instance, status + messages, running transcript, or progress display), as well as error + messages. Roughly speaking, a Git command's primary output is that + which one might want to capture to a file or send down a pipe; its + chatty output should not interfere with these use-cases. + + As such, primary output should be sent to the standard output stream + (stdout), and chatty output should be sent to the standard error + stream (stderr). Examples of commands which produce primary output + include `git log`, `git show`, and `git branch --list` which generate + output on the stdout stream. + + Not all Git commands have primary output; this is often true of + commands whose main function is to perform an action. Some action + commands are silent, whereas others are chatty. An example of a + chatty action commands is `git clone` with its "Cloning into + '<path>'..." and "Checking connectivity..." status messages which it + sends to the stderr stream. + + Error messages from Git commands should always be sent to the stderr + stream. + + Error Messages - Do not end error messages with a full stop. diff --git a/Documentation/Makefile b/Documentation/Makefile index ed656db2ae..1eb9192dae 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -1,3 +1,6 @@ +# Import tree-wide shared Makefile behavior and libraries +include ../shared.mak + # Guard against environment variables MAN1_TXT = MAN5_TXT = @@ -215,38 +218,6 @@ DEFAULT_EDITOR_SQ = $(subst ','\'',$(DEFAULT_EDITOR)) ASCIIDOC_EXTRA += -a 'git-default-editor=$(DEFAULT_EDITOR_SQ)' endif -QUIET_SUBDIR0 = +$(MAKE) -C # space to separate -C and subdir -QUIET_SUBDIR1 = - -ifneq ($(findstring $(MAKEFLAGS),w),w) -PRINT_DIR = --no-print-directory -else # "make -w" -NO_SUBDIR = : -endif - -ifneq ($(findstring $(MAKEFLAGS),s),s) -ifndef V - QUIET = @ - QUIET_ASCIIDOC = @echo ' ' ASCIIDOC $@; - QUIET_XMLTO = @echo ' ' XMLTO $@; - QUIET_DB2TEXI = @echo ' ' DB2TEXI $@; - QUIET_MAKEINFO = @echo ' ' MAKEINFO $@; - QUIET_DBLATEX = @echo ' ' DBLATEX $@; - QUIET_XSLTPROC = @echo ' ' XSLTPROC $@; - QUIET_GEN = @echo ' ' GEN $@; - QUIET_STDERR = 2> /dev/null - QUIET_SUBDIR0 = +@subdir= - QUIET_SUBDIR1 = ;$(NO_SUBDIR) echo ' ' SUBDIR $$subdir; \ - $(MAKE) $(PRINT_DIR) -C $$subdir - - QUIET_LINT_GITLINK = @echo ' ' LINT GITLINK $<; - QUIET_LINT_MANSEC = @echo ' ' LINT MAN SEC $<; - QUIET_LINT_MANEND = @echo ' ' LINT MAN END $<; - - export V -endif -endif - all: html man html: $(DOC_HTML) @@ -463,25 +434,11 @@ quick-install-html: require-htmlrepo print-man1: @for i in $(MAN1_TXT); do echo $$i; done -## Lint: Common -.build: - $(QUIET)mkdir $@ -.build/lint-docs: | .build - $(QUIET)mkdir $@ - ## Lint: gitlink -.build/lint-docs/gitlink: | .build/lint-docs - $(QUIET)mkdir $@ -.build/lint-docs/gitlink/howto: | .build/lint-docs/gitlink - $(QUIET)mkdir $@ -.build/lint-docs/gitlink/config: | .build/lint-docs/gitlink - $(QUIET)mkdir $@ LINT_DOCS_GITLINK = $(patsubst %.txt,.build/lint-docs/gitlink/%.ok,$(HOWTO_TXT) $(DOC_DEP_TXT)) -$(LINT_DOCS_GITLINK): | .build/lint-docs/gitlink -$(LINT_DOCS_GITLINK): | .build/lint-docs/gitlink/howto -$(LINT_DOCS_GITLINK): | .build/lint-docs/gitlink/config $(LINT_DOCS_GITLINK): lint-gitlink.perl $(LINT_DOCS_GITLINK): .build/lint-docs/gitlink/%.ok: %.txt + $(call mkdir_p_parent_template) $(QUIET_LINT_GITLINK)$(PERL_PATH) lint-gitlink.perl \ $< \ $(HOWTO_TXT) $(DOC_DEP_TXT) \ @@ -492,23 +449,18 @@ $(LINT_DOCS_GITLINK): .build/lint-docs/gitlink/%.ok: %.txt lint-docs-gitlink: $(LINT_DOCS_GITLINK) ## Lint: man-end-blurb -.build/lint-docs/man-end-blurb: | .build/lint-docs - $(QUIET)mkdir $@ LINT_DOCS_MAN_END_BLURB = $(patsubst %.txt,.build/lint-docs/man-end-blurb/%.ok,$(MAN_TXT)) -$(LINT_DOCS_MAN_END_BLURB): | .build/lint-docs/man-end-blurb $(LINT_DOCS_MAN_END_BLURB): lint-man-end-blurb.perl $(LINT_DOCS_MAN_END_BLURB): .build/lint-docs/man-end-blurb/%.ok: %.txt + $(call mkdir_p_parent_template) $(QUIET_LINT_MANEND)$(PERL_PATH) lint-man-end-blurb.perl $< >$@ .PHONY: lint-docs-man-end-blurb -lint-docs-man-end-blurb: $(LINT_DOCS_MAN_END_BLURB) ## Lint: man-section-order -.build/lint-docs/man-section-order: | .build/lint-docs - $(QUIET)mkdir $@ LINT_DOCS_MAN_SECTION_ORDER = $(patsubst %.txt,.build/lint-docs/man-section-order/%.ok,$(MAN_TXT)) -$(LINT_DOCS_MAN_SECTION_ORDER): | .build/lint-docs/man-section-order $(LINT_DOCS_MAN_SECTION_ORDER): lint-man-section-order.perl $(LINT_DOCS_MAN_SECTION_ORDER): .build/lint-docs/man-section-order/%.ok: %.txt + $(call mkdir_p_parent_template) $(QUIET_LINT_MANSEC)$(PERL_PATH) lint-man-section-order.perl $< >$@ .PHONY: lint-docs-man-section-order lint-docs-man-section-order: $(LINT_DOCS_MAN_SECTION_ORDER) @@ -524,7 +476,4 @@ doc-l10n install-l10n:: $(MAKE) -C po $@ endif -# Delete the target file on error -.DELETE_ON_ERROR: - .PHONY: FORCE diff --git a/Documentation/MyFirstObjectWalk.txt b/Documentation/MyFirstObjectWalk.txt index 45eb84d8b4..8d9e85566e 100644 --- a/Documentation/MyFirstObjectWalk.txt +++ b/Documentation/MyFirstObjectWalk.txt @@ -58,14 +58,19 @@ 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). +We'll need to include the `parse-options.h` header. ---- +#include "parse-options.h" + +... + int cmd_walken(int argc, const char **argv, const char *prefix) { const char * const walken_usage[] = { N_("git walken"), NULL, - } + }; struct option options[] = { OPT_END() }; @@ -195,9 +200,14 @@ Similarly to the default values, we don't have anything to do here yet ourselves; however, we should call `git_default_config()` if we aren't calling any other existing config callbacks. -Add a new function to `builtin/walken.c`: +Add a new function to `builtin/walken.c`. +We'll also need to include the `config.h` header: ---- +#include "config.h" + +... + static int git_walken_config(const char *var, const char *value, void *cb) { /* @@ -229,8 +239,14 @@ typically done by calling `repo_init_revisions()` with the repository you intend to target, as well as the `prefix` argument of `cmd_walken` and your `rev_info` struct. -Add the `struct rev_info` and the `repo_init_revisions()` call: +Add the `struct rev_info` and the `repo_init_revisions()` call. +We'll also need to include the `revision.h` header: + ---- +#include "revision.h" + +... + int cmd_walken(int argc, const char **argv, const char *prefix) { /* This can go wherever you like in your declarations.*/ @@ -506,24 +522,25 @@ function shows that the all-object walk is being performed by `traverse_commit_list()` or `traverse_commit_list_filtered()`. Those two functions reside in `list-objects.c`; examining the source shows that, despite the name, these functions traverse all kinds of objects. Let's have a look at -the arguments to `traverse_commit_list_filtered()`, which are a superset of the -arguments to the unfiltered version. +the arguments to `traverse_commit_list()`. -- `struct list_objects_filter_options *filter_options`: This is a struct which - stores a filter-spec as outlined in `Documentation/rev-list-options.txt`. -- `struct rev_info *revs`: This is the `rev_info` used for the walk. +- `struct rev_info *revs`: This is the `rev_info` used for the walk. If + its `filter` member is not `NULL`, then `filter` contains information for + how to filter the object list. - `show_commit_fn show_commit`: A callback which will be used to handle each individual commit object. - `show_object_fn show_object`: A callback which will be used to handle each non-commit object (so each blob, tree, or tag). - `void *show_data`: A context buffer which is passed in turn to `show_commit` and `show_object`. + +In addition, `traverse_commit_list_filtered()` has an additional paramter: + - `struct oidset *omitted`: A linked-list of object IDs which the provided filter caused to be omitted. -It looks like this `traverse_commit_list_filtered()` uses callbacks we provide -instead of needing us to call it repeatedly ourselves. Cool! Let's add the -callbacks first. +It looks like these methods use callbacks we provide instead of needing us +to call it repeatedly ourselves. Cool! Let's add the callbacks first. For the sake of this tutorial, we'll simply keep track of how many of each kind of object we find. At file scope in `builtin/walken.c` add the following @@ -624,9 +641,14 @@ static void walken_object_walk(struct rev_info *rev) ---- Let's start by calling just the unfiltered walk and reporting our counts. -Complete your implementation of `walken_object_walk()`: +Complete your implementation of `walken_object_walk()`. +We'll also need to include the `list-objects.h` header. ---- +#include "list-objects.h" + +... + traverse_commit_list(rev, walken_show_commit, walken_show_object, NULL); printf("commits %d\nblobs %d\ntags %d\ntrees %d\n", commit_count, @@ -691,20 +713,9 @@ help understand. In our case, that means we omit trees and blobs not directly referenced by `HEAD` or `HEAD`'s history, because we begin the walk with only `HEAD` in the `pending` list.) -First, we'll need to `#include "list-objects-filter-options.h"` and set up the -`struct list_objects_filter_options` at the top of the function. - ----- -static void walken_object_walk(struct rev_info *rev) -{ - struct list_objects_filter_options filter_options = {}; - - ... ----- - For now, we are not going to track the omitted objects, so we'll replace those parameters with `NULL`. For the sake of simplicity, we'll add a simple -build-time branch to use our filter or not. Replace the line calling +build-time branch to use our filter or not. Preface the line calling `traverse_commit_list()` with the following, which will remind us which kind of walk we've just performed: @@ -712,19 +723,17 @@ walk we've just performed: if (0) { /* Unfiltered: */ trace_printf(_("Unfiltered object walk.\n")); - traverse_commit_list(rev, walken_show_commit, - walken_show_object, NULL); } else { trace_printf( _("Filtered object walk with filterspec 'tree:1'.\n")); - parse_list_objects_filter(&filter_options, "tree:1"); - - traverse_commit_list_filtered(&filter_options, rev, - walken_show_commit, walken_show_object, NULL, NULL); + CALLOC_ARRAY(rev->filter, 1); + parse_list_objects_filter(rev->filter, "tree:1"); } + traverse_commit_list(rev, walken_show_commit, + walken_show_object, NULL); ---- -`struct list_objects_filter_options` is usually built directly from a command +The `rev->filter` member is usually built directly from a command line argument, so the module provides an easy way to build one from a string. Even though we aren't taking user input right now, we can still build one with a hardcoded string using `parse_list_objects_filter()`. @@ -763,7 +772,7 @@ object: ---- ... - traverse_commit_list_filtered(&filter_options, rev, + traverse_commit_list_filtered(rev, walken_show_commit, walken_show_object, NULL, &omitted); ... diff --git a/Documentation/RelNotes/2.35.0.txt b/Documentation/RelNotes/2.35.0.txt index 120fac5b21..d69b50d180 100644 --- a/Documentation/RelNotes/2.35.0.txt +++ b/Documentation/RelNotes/2.35.0.txt @@ -9,6 +9,19 @@ Backward compatibility warts * "_" is now treated as any other URL-valid characters in an URL when matching the per-URL configuration variable names. + * The color palette used by "git grep" has been updated to match that + of GNU grep. + + +Note to those who build from the source + + * You may need to define NO_UNCOMPRESS2 Makefile macro if you build + with zlib older than 1.2.9. + + * If your compiler cannot grok C99, the build will fail. See the + instruction at the beginning of git-compat-util.h if this happens + to you. + UI, Workflows & Features @@ -18,6 +31,76 @@ UI, Workflows & Features * "git stash" learned the "--staged" option to stash away what has been added to the index (and nothing else). + * "git var GIT_DEFAULT_BRANCH" is a way to see what name is used for + the newly created branch if "git init" is run. + + * Various operating modes of "git reset" have been made to work + better with the sparse index. + + * "git submodule deinit" for a submodule whose .git metadata + directory is embedded in its working tree refused to work, until + the submodule gets converted to use the "absorbed" form where the + metadata directory is stored in superproject, and a gitfile at the + top-level of the working tree of the submodule points at it. The + command is taught to convert such submodules to the absorbed form + as needed. + + * The completion script (in contrib/) learns that the "--date" + option of commands from the "git log" family takes "human" and + "auto" as valid values. + + * "Zealous diff3" style of merge conflict presentation has been added. + + * The "git log --format=%(describe)" placeholder has been extended to + allow passing selected command-line options to the underlying "git + describe" command. + + * "default" and "reset" have been added to our color palette. + + * The cryptographic signing using ssh keys can specify literal keys + for keytypes whose name do not begin with the "ssh-" prefix by + using the "key::" prefix mechanism (e.g. "key::ecdsa-sha2-nistp256"). + + * "git fetch" without the "--update-head-ok" option ought to protect + a checked out branch from getting updated, to prevent the working + tree that checks it out to go out of sync. The code was written + before the use of "git worktree" got widespread, and only checked + the branch that was checked out in the current worktree, which has + been updated. + + * "git name-rev" has been tweaked to give output that is shorter and + easier to understand. + + * "git apply" has been taught to ignore a message without a patch + with the "--allow-empty" option. It also learned to honor the + "--quiet" option given from the command line. + + * The "init" and "set" subcommands in "git sparse-checkout" have been + unified for a better user experience and performance. + + * Many git commands that deal with working tree files try to remove a + directory that becomes empty (i.e. "git switch" from a branch that + has the directory to another branch that does not would attempt + remove all files in the directory and the directory itself). This + drops users into an unfamiliar situation if the command was run in + a subdirectory that becomes subject to removal due to the command. + The commands have been taught to keep an empty directory if it is + the directory they were started in to avoid surprising users. + + * "git am" learns "--empty=(stop|drop|keep)" option to tweak what is + done to a piece of e-mail without a patch in it. + + * The default merge message prepared by "git merge" records the name + of the current branch; the name can be overridden with a new option + to allow users to pretend a merge is made on a different branch. + + * The way "git p4" shows file sizes in its output has been updated to + use human-readable units. + + * "git -c branch.autosetupmerge=inherit branch new old" makes "new" + to have the same upstream as the "old" branch, instead of marking + "old" itself as its upstream. + Performance, Internal Implementation, Development Support etc. @@ -27,9 +110,94 @@ Performance, Internal Implementation, Development Support etc. * Teach and encourage first-time contributors to this project to state the base commit when they submit their topic. - * The command line complation for "git send-email" options have been + * The command line completion for "git send-email" options have been tweaked to make it easier to keep it in sync with the command itself. + * Ensure that the sparseness of the in-core index matches the + index.sparse configuration specified by the repository immediately + after the on-disk index file is read. + + * Code clean-up to eventually allow information on remotes defined + for an arbitrary repository to be read. + + * Build optimization. + + * Tighten code for testing pack-bitmap. + + * Weather balloon to break people with compilers that do not support + C99. + + * The "reftable" backend for the refs API, without integrating into + the refs subsystem, has been added. + + * More tests are marked as leak-free. + + * The test framework learns to list unsatisfied test prerequisites, + and optionally error out when prerequisites that are expected to be + satisfied are not. + + * The default setting for trace2 event nesting was too low to cause + test failures, which is worked around by bumping it up in the test + framework. + + * Drop support for TravisCI and update test workflows at GitHub. + + * Many tests that used to need GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME + mechanism to force "git" to use 'master' as the default name for + the initial branch no longer need it; the use of the mechanism from + them have been removed. + + * Allow running our tests while disabling fsync. + + * Document the parameters given to the reflog entry iterator callback + functions. + (merge e6e94f34b2 jc/reflog-iterator-callback-doc later to maint). + + * The test helper for refs subsystem learned to write bogus and/or + nonexistent object name to refs to simulate error situations we + want to test Git in. + + * "diff --histogram" optimization. + + * Weather balloon to find compilers that do not grok variable + declaration in the for() loop. + + * diff and blame commands have been taught to work better with sparse + index. + + * The chainlint test script linter in the test suite has been updated. + + * The DEVELOPER=yes build uses -std=gnu99 now. + + * "git format-patch" uses a single rev_info instance and then exits. + Mark the structure with UNLEAK() macro to squelch leak sanitizer. + + * New interface into the tmp-objdir API to help in-core use of the + quarantine feature. + + * Broken &&-chains in the test scripts have been corrected. + + * The RCS keyword substitution in "git p4" used to be done assuming + that the contents are UTF-8 text, which can trigger decoding + errors. We now treat the contents as a bytestring for robustness + and correctness. + + * The conditions to choose different definitions of the FLEX_ARRAY + macro for vendor compilers has been simplified to make it easier to + maintain. + + * Correctness and performance update to "diff --color-moved" feature. + + * "git upload-pack" (the other side of "git fetch") used a 8kB buffer + but most of its payload came on 64kB "packets". The buffer size + has been enlarged so that such a packet fits. + + * "git fetch" and "git pull" are now declared sparse-index clean. + Also "git ls-files" learns the "--sparse" option to help debugging. + + * Similar message templates have been consolidated so that + translators need to work on fewer number of messages. + Fixes since v2.34 ----------------- @@ -63,3 +231,182 @@ Fixes since v2.34 * The clean/smudge conversion code path has been prepared to better work on platforms where ulong is narrower than size_t. (merge 596b5e77c9 mc/clean-smudge-with-llp64 later to maint). + + * Redact the path part of packfile URI that appears in the trace output. + (merge 0ba558ffb1 if/redact-packfile-uri later to maint). + + * CI has been taught to catch some Unicode directional formatting + sequence that can be used in certain mischief. + (merge 0e7696c64d js/ci-no-directional-formatting later to maint). + + * The "--date=format:<strftime>" gained a workaround for the lack of + system support for a non-local timezone to handle "%s" placeholder. + (merge 9b591b9403 jk/strbuf-addftime-seconds-since-epoch later to maint). + + * The "merge" subcommand of "git jump" (in contrib/) silently ignored + pathspec and other parameters. + (merge 67ba13e5a4 jk/jump-merge-with-pathspec later to maint). + + * The code to decode the length of packed object size has been + corrected. + (merge 34de5b8eac jt/pack-header-lshift-overflow later to maint). + + * The advice message given by "git pull" when the user hasn't made a + choice between merge and rebase still said that the merge is the + default, which no longer is the case. This has been corrected. + (merge 71076d0edd ah/advice-pull-has-no-preference-between-rebase-and-merge later to maint). + + * "git fetch", when received a bad packfile, can fail with SIGPIPE. + This wasn't wrong per-se, but we now detect the situation and fail + in a more predictable way. + (merge 2a4aed42ec jk/fetch-pack-avoid-sigpipe-to-index-pack later to maint). + + * The function to cull a child process and determine the exit status + had two separate code paths for normal callers and callers in a + signal handler, and the latter did not yield correct value when the + child has caught a signal. The handling of the exit status has + been unified for these two code paths. An existing test with + flakiness has also been corrected. + (merge 5263e22cba jk/t7006-sigpipe-tests-fix later to maint). + + * When a non-existent program is given as the pager, we tried to + reuse an uninitialized child_process structure and crashed, which + has been fixed. + (merge f917f57f40 em/missing-pager later to maint). + + * The single-key-input mode in "git add -p" had some code to handle + keys that generate a sequence of input via ReadKey(), which did not + handle end-of-file correctly, which has been fixed. + (merge fc8a8126df cb/add-p-single-key-fix later to maint). + + * "git rebase -x" added an unnecessary 'exec' instructions before + 'noop', which has been corrected. + (merge cc9dcdee61 en/rebase-x-fix later to maint). + + * When the "git push" command is killed while the receiving end is + trying to report what happened to the ref update proposals, the + latter used to die, due to SIGPIPE. The code now ignores SIGPIPE + to increase our chances to run the post-receive hook after it + happens. + (merge d34182b9e3 rj/receive-pack-avoid-sigpipe-during-status-reporting later to maint). + + * "git worktree add" showed "Preparing worktree" message to the + standard output stream, but when it failed, the message from die() + went to the standard error stream. Depending on the order the + stdio streams are flushed at the program end, this resulted in + confusing output. It has been corrected by sending all the chatty + messages to the standard error stream. + (merge b50252484f es/worktree-chatty-to-stderr later to maint). + + * Coding guideline document has been updated to clarify what goes to + standard error in our system. + (merge e258eb4800 es/doc-stdout-vs-stderr later to maint). + + * The sparse-index/sparse-checkout feature had a bug in its use of + the matching code to determine which path is in or outside the + sparse checkout patterns. + (merge 8c5de0d265 ds/sparse-deep-pattern-checkout-fix later to maint). + + * "git rebase -x" by mistake started exporting the GIT_DIR and + GIT_WORK_TREE environment variables when the command was rewritten + in C, which has been corrected. + (merge 434e0636db en/rebase-x-wo-git-dir-env later to maint). + + * When "git log" implicitly enabled the "decoration" processing + without being explicitly asked with "--decorate" option, it failed + to read and honor the settings given by the "--decorate-refs" + option. + + * "git fetch --set-upstream" did not check if there is a current + branch, leading to a segfault when it is run on a detached HEAD, + which has been corrected. + (merge 17baeaf82d ab/fetch-set-upstream-while-detached later to maint). + + * Among some code paths that ask an yes/no question, only one place + gave a prompt that looked different from the others, which has been + updated to match what the others create. + (merge 0fc8ed154c km/help-prompt-fix later to maint). + + * "git log --invert-grep --author=<name>" used to exclude commits + written by the given author, but now "--invert-grep" only affects + the matches made by the "--grep=<pattern>" option. + (merge 794c000267 rs/log-invert-grep-with-headers later to maint). + + * "git grep --perl-regexp" failed to match UTF-8 characters with + wildcard when the pattern consists only of ASCII letters, which has + been corrected. + (merge 32e3e8bc55 rs/pcre2-utf later to maint). + + * Certain sparse-checkout patterns that are valid in non-cone mode + led to segfault in cone mode, which has been corrected. + + * Use of certain "git rev-list" options with "git fast-export" + created nonsense results (the worst two of which being "--reverse" + and "--invert-grep --grep=<foo>"). The use of "--first-parent" is + made to behave a bit more sensible than before. + (merge 726a228dfb ws/fast-export-with-revision-options later to maint). + + * Perf tests were run with end-user's shell, but it has been + corrected to use the shell specified by $TEST_SHELL_PATH. + (merge 9ccab75608 ja/perf-use-specified-shell later to maint). + + * Fix dependency rules to generate hook-list.h header file. + (merge d3fd1a6667 ab/makefile-hook-list-dependency-fix later to maint). + + * "git stash" by default triggers its "push" action, but its + implementation also made "git stash -h" to show short help only for + "git stash push", which has been corrected. + (merge ca7990cea5 ab/do-not-limit-stash-help-to-push later to maint). + + * "git apply --3way" bypasses the attempt to do a three-way + application in more cases to address the regression caused by the + recent change to use direct application as a fallback. + (merge 34d607032c jz/apply-3-corner-cases later to maint). + + * Fix performance-releated bug in "git subtree" (in contrib/). + (merge 3ce8888fb4 jl/subtree-check-parents-argument-passing-fix later to maint). + + * Extend the guidance to choose the base commit to build your work + on, and hint/nudge contributors to read others' changes. + (merge fdfae830f8 jc/doc-submitting-patches-choice-of-base later to maint). + + * A corner case bug in the ort merge strategy has been corrected. + (merge d30126c20d en/merge-ort-renorm-with-rename-delete-conflict-fix later to maint). + + * "git stash apply" forgot to attempt restoring untracked files when + it failed to restore changes to tracked ones. + (merge 71cade5a0b en/stash-df-fix later to maint). + + * Calling dynamically loaded functions on Windows has been corrected. + (merge 4a9b204920 ma/windows-dynload-fix later to maint). + + * Some lockfile code called free() in signal-death code path, which + has been corrected. + (merge 58d4d7f1c5 ps/lockfile-cleanup-fix later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge 74db416c9c cw/protocol-v2-doc-fix later to maint). + (merge f9b2b6684d ja/doc-cleanup later to maint). + (merge 7d1b866778 jc/fix-first-object-walk later to maint). + (merge 538ac74604 js/trace2-avoid-recursive-errors later to maint). + (merge 152923b132 jk/t5319-midx-corruption-test-deflake later to maint). + (merge 9081a421a6 ab/checkout-branch-info-leakfix later to maint). + (merge 42c456ff81 rs/mergesort later to maint). + (merge ad506e6780 tl/midx-docfix later to maint). + (merge bf5b83fd8a hk/ci-checkwhitespace-commentfix later to maint). + (merge 49f1eb3b34 jk/refs-g11-workaround later to maint). + (merge 7d3fc7df70 jt/midx-doc-fix later to maint). + (merge 7b089120d9 hn/create-reflog-simplify later to maint). + (merge 9e12400da8 cb/mingw-gmtime-r later to maint). + (merge 0bf0de6cc7 tb/pack-revindex-on-disk-cleanup later to maint). + (merge 2c68f577fc ew/cbtree-remove-unused-and-broken-cb-unlink later to maint). + (merge eafd6e7e55 ab/die-with-bug later to maint). + (merge 91028f7659 jc/grep-patterntype-default-doc later to maint). + (merge 47ca93d071 ds/repack-fixlets later to maint). + (merge e6a9bc0c60 rs/t4202-invert-grep-test-fix later to maint). + (merge deb5407a42 gh/gpg-doc-markup-fix later to maint). + (merge 999bba3e0b rs/daemon-plug-leak later to maint). + (merge 786eb1ba39 js/l10n-mention-ngettext-early-in-readme later to maint). + (merge 2f12b31b74 ab/makefile-msgfmt-wo-stats later to maint). + (merge 0517f591ca fs/gpg-unknown-key-test-fix later to maint). + (merge 97d6fb5a1f ma/header-dup-cleanup later to maint). diff --git a/Documentation/RelNotes/2.35.1.txt b/Documentation/RelNotes/2.35.1.txt new file mode 100644 index 0000000000..726ba250ef --- /dev/null +++ b/Documentation/RelNotes/2.35.1.txt @@ -0,0 +1,6 @@ +Git v2.35.1 Release Notes +========================= + +Git 2.35 shipped with a regression that broke use of "rebase" and +"stash" in a secondary worktree. This maintenance release ought to +fix it. diff --git a/Documentation/RelNotes/2.36.0.txt b/Documentation/RelNotes/2.36.0.txt new file mode 100644 index 0000000000..ffabec17b5 --- /dev/null +++ b/Documentation/RelNotes/2.36.0.txt @@ -0,0 +1,398 @@ +Git 2.36 Release Notes +====================== + +Updates since Git 2.35 +---------------------- + +Backward compatibility warts + + * "git name-rev --stdin" has been deprecated and issues a warning + when used; use "git name-rev --annotate-stdin" instead. + + * "git clone --filter=... --recurse-submodules" only makes the + top-level a partial clone, while submodules are fully cloned. This + behaviour is changed to pass the same filter down to the submodules. + + +Note to those who build from the source + + * Since Git 2.31, our source assumed that the compiler you use to + build Git supports variadic macros, with an easy-to-use escape + hatch to allow compilation without variadic macros with an request + to report that you had to use the escape hatch to the list. + Because we haven't heard from anybody who actually needed to use + the escape hatch, it has been removed, making support of variadic + macros a hard requirement. + + +UI, Workflows & Features + + * Assorted updates to "git cat-file", especially "-h". + + * The command line completion (in contrib/) learns to complete + arguments to give to "git sparse-checkout" command. + + * "git log --remerge-diff" shows the difference from mechanical merge + result and the result that is actually recorded in a merge commit. + + * "git log" and friends learned an option --exclude-first-parent-only + to propagate UNINTERESTING bit down only along the first-parent + chain, just like --first-parent option shows commits that lack the + UNINTERESTING bit only along the first-parent chain. + + * The command line completion script (in contrib/) learned to + complete all Git subcommands, including the ones that are normally + hidden, when GIT_COMPLETION_SHOW_ALL_COMMANDS is used. + + * "git branch" learned the "--recurse-submodules" option. + + * A not-so-common mistake is to write a script to feed "git bisect + run" without making it executable, in which case all tests will + exit with 126 or 127 error codes, even on revisions that are marked + as good. Try to recognize this situation and stop iteration early. + + * When "index-pack" dies due to incoming data exceeding the maximum + allowed input size, include the value of the limit in the error + message. + + * The error message given by "git switch HEAD~4" has been clarified + to suggest the "--detach" option that is required. + + * In sparse-checkouts, files mis-marked as missing from the working tree + could lead to later problems. Such files were hard to discover, and + harder to correct. Automatically detecting and correcting the marking + of such files has been added to avoid these problems. + + * "git cat-file" learns "--batch-command" mode, which is a more + flexible interface than the existing "--batch" or "--batch-check" + modes, to allow different kinds of inquiries made. + + * The level of verbose output from the ort backend during inner merge + has been aligned to that of the recursive backend. + + * "git remote rename A B", depending on the number of remote-tracking + refs involved, takes long time renaming them. The command has been + taught to show progress bar while making the user wait. + + * Bundle file format gets extended to allow a partial bundle, + filtered by similar criteria you would give when making a + partial/lazy clone. + + * A new built-in userdiff driver for kotlin has been added. + + * "git repack" learned a new configuration to disable triggering of + age-old "update-server-info" command, which is rarely useful these + days. + + * "git stash" does not allow subcommands it internally runs as its + implementation detail, except for "git reset", to emit messages; + now "git reset" part has also been squelched. + + +Performance, Internal Implementation, Development Support etc. + + * "git apply" (ab)used the util pointer of the string-list to keep + track of how each symbolic link needs to be handled, which has been + simplified by using strset. + + * Fix a hand-rolled alloca() imitation that may have violated + alignment requirement of data being sorted in compatibility + implementation of qsort_s() and stable qsort(). + + * Use the parse-options API in "git reflog" command. + + * The conditional inclusion mechanism of configuration files using + "[includeIf <condition>]" learns to base its decision on the + URL of the remote repository the repository interacts with. + (merge 399b198489 jt/conditional-config-on-remote-url later to maint). + + * "git name-rev --stdin" does not behave like usual "--stdin" at + all. Start the process of renaming it to "--annotate-stdin". + (merge a2585719b3 jc/name-rev-stdin later to maint). + + * "git update-index", "git checkout-index", and "git clean" are + taught to work better with the sparse checkout feature. + + * Use an internal call to reset_head() helper function instead of + spawning "git checkout" in "rebase", and update code paths that are + involved in the change. + + * Messages "ort" merge backend prepares while dealing with conflicted + paths were unnecessarily confusing since it did not differentiate + inner merges and outer merges. + + * Small modernization of the rerere-train script (in contrib/). + + * Use designated initializers we started using in mid 2017 in more + parts of the codebase that are relatively quiescent. + + * Improve failure case behaviour of xdiff library when memory + allocation fails. + + * General clean-up in reftable implementation, including + clarification of the API documentation, tightening the code to + honor documented length limit, etc. + + * Remove the escape hatch we added when we introduced the weather + balloon to use variadic macros unconditionally, to make it official + that we now have a hard dependency on the feature. + + * Makefile refactoring with a bit of suffixes rule stripping to + optimize the runtime overhead. + + * "git stash drop" is reimplemented as an internal call to + reflog_delete() function, instead of invoking "git reflog delete" + via run_command() API. + + * Count string_list items in size_t, not "unsigned int". + + * The single-key interactive operation used by "git add -p" has been + made more robust. + + * Remove unneeded <meta http-equiv=content-type...> from gitweb + output. + + * "git name-rev" learned to use the generation numbers when setting + the lower bound of searching commits used to explain the revision, + when available, instead of committer time. + + * Replace core.fsyncObjectFiles with two new configuration variables, + core.fsync and core.fsyncMethod. + + * Updates to refs traditionally weren't fsync'ed, but we can + configure using core.fsync variable to do so. + + +Fixes since v2.35 +----------------- + + * "rebase" and "stash" in secondary worktrees are broken in + Git 2.35.0, which has been corrected. + + * "git pull --rebase" ignored the rebase.autostash configuration + variable when the remote history is a descendant of our history, + which has been corrected. + (merge 3013d98d7a pb/pull-rebase-autostash-fix later to maint). + + * "git update-index --refresh" has been taught to deal better with + racy timestamps (just like "git status" already does). + (merge 2ede073fd2 ms/update-index-racy later to maint). + + * Avoid tests that are run under GIT_TRACE2 set from failing + unnecessarily. + (merge 944d808e42 js/test-unset-trace2-parents later to maint). + + * The merge-ort misbehaved when merge.renameLimit configuration is + set too low and failed to find all renames. + (merge 9ae39fef7f en/merge-ort-restart-optim-fix later to maint). + + * We explain that revs come first before the pathspec among command + line arguments, but did not spell out that dashed options come + before other args, which has been corrected. + (merge c11f95010c tl/doc-cli-options-first later to maint). + + * "git add -p" rewritten in C regressed hunk splitting in some cases, + which has been corrected. + (merge 7008ddc645 pw/add-p-hunk-split-fix later to maint). + + * "git fetch --negotiate-only" is an internal command used by "git + push" to figure out which part of our history is missing from the + other side. It should never recurse into submodules even when + fetch.recursesubmodules configuration variable is set, nor it + should trigger "gc". The code has been tightened up to ensure it + only does common ancestry discovery and nothing else. + (merge de4eaae63a gc/fetch-negotiate-only-early-return later to maint). + + * The code path that verifies signatures made with ssh were made to + work better on a system with CRLF line endings. + (merge caeef01ea7 fs/ssh-signing-crlf later to maint). + + * "git sparse-checkout init" failed to write into $GIT_DIR/info + directory when the repository was created without one, which has + been corrected to auto-create it. + (merge 7f44842ac1 jt/sparse-checkout-leading-dir-fix later to maint). + + * Cloning from a repository that does not yet have any branches or + tags but has other refs resulted in a "remote transport reported + error", which has been corrected. + (merge dccea605b6 jt/clone-not-quite-empty later to maint). + + * Mark in various places in the code that the sparse index and the + split index features are mutually incompatible. + (merge 451b66c533 js/sparse-vs-split-index later to maint). + + * Update the logic to compute alignment requirement for our mem-pool. + (merge e38bcc66d8 jc/mem-pool-alignment later to maint). + + * Pick a better random number generator and use it when we prepare + temporary filenames. + (merge 47efda967c bc/csprng-mktemps later to maint). + + * Update the contributor-facing documents on proposed log messages. + (merge cdba0295b0 jc/doc-log-messages later to maint). + + * When "git fetch --prune" failed to prune the refs it wanted to + prune, the command issued error messages but exited with exit + status 0, which has been corrected. + (merge c9e04d905e tg/fetch-prune-exit-code-fix later to maint). + + * Problems identified by Coverity in the reftable code have been + corrected. + (merge 01033de49f hn/reftable-coverity-fixes later to maint). + + * A bug that made multi-pack bitmap and the object order out-of-sync, + making the .midx data corrupt, has been fixed. + (merge f8b60cf99b tb/midx-bitmap-corruption-fix later to maint). + + * The build procedure has been taught to notice older version of zlib + and enable our replacement uncompress2() automatically. + (merge 07564773c2 ab/auto-detect-zlib-compress2 later to maint). + + * Interaction between fetch.negotiationAlgorithm and + feature.experimental configuration variables has been corrected. + (merge 714edc620c en/fetch-negotiation-default-fix later to maint). + + * "git diff --diff-filter=aR" is now parsed correctly. + (merge 75408ca949 js/diff-filter-negation-fix later to maint). + + * When "git subtree" wants to create a merge, it used "git merge" and + let it be affected by end-user's "merge.ff" configuration, which + has been corrected. + (merge 9158a3564a tk/subtree-merge-not-ff-only later to maint). + + * Unlike "git apply", "git patch-id" did not handle patches with + hunks that has only 1 line in either preimage or postimage, which + has been corrected. + (merge 757e75c81e jz/patch-id-hunk-header-parsing-fix later to maint). + + * "receive-pack" checks if it will do any ref updates (various + conditions could reject a push) before received objects are taken + out of the temporary directory used for quarantine purposes, so + that a push that is known-to-fail will not leave crufts that a + future "gc" needs to clean up. + (merge 5407764069 cb/clear-quarantine-early-on-all-ref-update-errors later to maint). + + * Because a deletion of ref would need to remove it from both the + loose ref store and the packed ref store, a delete-ref operation + that logically removes one ref may end up invoking ref-transaction + hook twice, which has been corrected. + (merge 2ed1b64ebd ps/avoid-unnecessary-hook-invocation-with-packed-refs later to maint). + + * When there is no object to write .bitmap file for, "git + multi-pack-index" triggered an error, instead of just skipping, + which has been corrected. + (merge eb57277ba3 tb/midx-no-bitmap-for-no-objects later to maint). + + * "git cmd -h" outside a repository should error out cleanly for many + commands, but instead it hit a BUG(), which has been corrected. + (merge 87ad07d735 js/short-help-outside-repo-fix later to maint). + + * "working tree" and "per-worktree ref" were in glossary, but + "worktree" itself wasn't, which has been corrected. + (merge 2df5387ed0 jc/glossary-worktree later to maint). + + * L10n support for a few error messages. + (merge 3d3c23b3a7 bs/forbid-i18n-of-protocol-token-in-fetch-pack later to maint). + + * Test modernization. + (merge d4fe066e4b sy/t0001-use-path-is-helper later to maint). + + * "git log --graph --graph" used to leak a graph structure, and there + was no way to countermand "--graph" that appear earlier on the + command line. A "--no-graph" option has been added and resource + leakage has been plugged. + + * Error output given in response to an ambiguous object name has been + improved. + (merge 3a73c1dfaf ab/ambiguous-object-name later to maint). + + * "git sparse-checkout" wants to work with per-worktree configuration, + but did not work well in a worktree attached to a bare repository. + (merge 3ce1138272 ds/sparse-checkout-requires-per-worktree-config later to maint). + + * Setting core.untrackedCache to true failed to add the untracked + cache extension to the index. + + * Workaround we have for versions of PCRE2 before their version 10.36 + were in effect only for their versions newer than 10.36 by mistake, + which has been corrected. + (merge 97169fc361 rs/pcre-invalid-utf8-fix-fix later to maint). + + * Document Taylor as a new member of Git PLC at SFC. Welcome. + (merge e8d56ca863 tb/coc-plc-update later to maint). + + * "git checkout -b branch/with/multi/level/name && git stash" only + recorded the last level component of the branch name, which has + been corrected. + + * "git fetch" can make two separate fetches, but ref updates coming + from them were in two separate ref transactions under "--atomic", + which has been corrected. + + * Check the return value from parse_tree_indirect() to turn segfaults + into calls to die(). + (merge 8d2eaf649a gc/parse-tree-indirect-errors later to maint). + + * Newer version of GPGSM changed its output in a backward + incompatible way to break our code that parses its output. It also + added more processes our tests need to kill when cleaning up. + Adjustments have been made to accommodate these changes. + (merge b0b70d54c4 fs/gpgsm-update later to maint). + + * The untracked cache newly computed weren't written back to the + on-disk index file when there is no other change to the index, + which has been corrected. + + * "git config -h" did not describe the "--type" option correctly. + (merge 5445124fad mf/fix-type-in-config-h later to maint). + + * The way generation number v2 in the commit-graph files are + (not) handled has been corrected. + (merge 6dbf4b8172 ds/commit-graph-gen-v2-fixes later to maint). + + * The method to trigger malloc check used in our tests no longer work + with newer versions of glibc. + (merge baedc59543 ep/test-malloc-check-with-glibc-2.34 later to maint). + + * When "git fetch --recurse-submodules" grabbed submodule commits + that would be needed to recursively check out newly fetched commits + in the superproject, it only paid attention to submodules that are + in the current checkout of the superproject. We now do so for all + submodules that have been run "git submodule init" on. + + * "git rebase $base $non_branch_commit", when $base is an ancestor or + the $non_branch_commit, modified the current branch, which has been + corrected. + + * When "shallow" information is updated, we forgot to update the + in-core equivalent, which has been corrected. + + * Other code cleanup, docfix, build fix, etc. + (merge cfc5cf428b jc/find-header later to maint). + (merge 40e7cfdd46 jh/p4-fix-use-of-process-error-exception later to maint). + (merge 727e6ea350 jh/p4-spawning-external-commands-cleanup later to maint). + (merge 0a6adc26e2 rs/grep-expr-cleanup later to maint). + (merge 4ed7dfa713 po/readme-mention-contributor-hints later to maint). + (merge 6046f7a91c en/plug-leaks-in-merge later to maint). + (merge 8c591dbfce bc/clarify-eol-attr later to maint). + (merge 518e15db74 rs/parse-options-lithelp-help later to maint). + (merge cbac0076ef gh/doc-typos later to maint). + (merge ce14de03db ab/no-errno-from-resolve-ref-unsafe later to maint). + (merge 2826ffad8c rc/negotiate-only-typofix later to maint). + (merge 0f03f04c5c en/sparse-checkout-leakfix later to maint). + (merge 74f3390dde sy/diff-usage-typofix later to maint). + (merge 45d0212a71 ll/doc-mktree-typofix later to maint). + (merge e9b272e4c1 js/no-more-legacy-stash later to maint). + (merge 6798b08e84 ab/do-not-hide-failures-in-git-dot-pm later to maint). + (merge 9325285df4 po/doc-check-ignore-markup-fix later to maint). + (merge cd26cd6c7c sy/modernize-t-lib-read-tree-m-3way later to maint). + (merge d17294a05e ab/hash-object-leakfix later to maint). + (merge b8403129d3 jd/t0015-modernize later to maint). + (merge 332acc248d ds/mailmap later to maint). + (merge 04bf052eef ab/grep-patterntype later to maint). + (merge 6ee36364eb ab/diff-free-more later to maint). + (merge 63a36017fe nj/read-tree-doc-reffix later to maint). + (merge eed36fce38 sm/no-git-in-upstream-of-pipe-in-tests later to maint). + (merge c614beb933 ep/t6423-modernize later to maint). + (merge 57be9c6dee ab/reflog-prep-fix later to maint). + (merge 5327d8982a js/in-place-reverse-in-sequencer later to maint). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 11e03056f2..a6121d1d42 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -19,8 +19,10 @@ change is relevant to. 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 a topic that is in `seen`, but not in `master`, - base your work on the tip of that topic. + 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 @@ -28,10 +30,10 @@ change is relevant to. 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 for discussion. Before the final merge, you may have to - wait until some of the dependent topics graduate to `master`, and - rebase your work. + 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 @@ -71,8 +73,13 @@ Make sure that you have tests for the bug you are fixing. See [[tests]] When adding a new feature, make sure that you have new tests to show the feature triggers the new behavior when it should, and to show the -feature does not trigger when it shouldn't. After any code change, make -sure that the entire test suite passes. +feature does not trigger when it shouldn't. After any code change, +make sure that the entire test suite passes. When fixing a bug, make +sure you have new tests that break if somebody else breaks what you +fixed by accident to avoid regression. Also, try merging your work to +'next' and 'seen' and make sure the tests still pass; topics by others +that are still in flight may have unexpected interactions with what +you are trying to do in your topic. Pushing to a fork of https://github.com/git/git will use their CI integration to test your changes on Linux, Mac and Windows. See the @@ -103,6 +110,35 @@ run `git diff --check` on your changes before you commit. [[describe-changes]] === Describe your changes well. +The log message that explains your changes is just as important as the +changes themselves. Your code may be clearly written with in-code +comment to sufficiently explain how it works with the surrounding +code, but those who need to fix or enhance your code in the future +will need to know _why_ your code does what it does, for a few +reasons: + +. Your code may be doing something differently from what you wanted it + to do. Writing down what you actually wanted to achieve will help + them fix your code and make it do what it should have been doing + (also, you often discover your own bugs yourself, while writing the + log message to summarize the thought behind it). + +. Your code may be doing things that were only necessary for your + immediate needs (e.g. "do X to directories" without implementing or + even designing what is to be done on files). Writing down why you + excluded what the code does not do will help guide future developers. + Writing down "we do X to directories, because directories have + characteristic Y" would help them infer "oh, files also have the same + characteristic Y, so perhaps doing X to them would also make sense?". + Saying "we don't do the same X to files, because ..." will help them + decide if the reasoning is sound (in which case they do not waste + time extending your code to cover files), or reason differently (in + which case, they can explain why they extend your code to cover + files, too). + +The goal of your log message is to convey the _why_ behind your +change to help future developers. + The first line of the commit message should be a short description (50 characters is the soft limit, see DISCUSSION in linkgit:git-commit[1]), and should skip the full stop. It is also conventional in most cases to @@ -135,6 +171,13 @@ The body should provide a meaningful commit message, which: . alternate solutions considered but discarded, if any. +[[present-tense]] +The problem statement that describes the status quo is written in the +present tense. Write "The code does X when it is given input Y", +instead of "The code used to do Y when given input X". You do not +have to say "Currently"---the status quo in the problem statement is +about the code _without_ your change, by project convention. + [[imperative-mood]] Describe your changes in imperative mood, e.g. "make xyzzy do frotz" instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy @@ -144,8 +187,21 @@ without external resources. Instead of giving a URL to a mailing list archive, summarize the relevant points of the discussion. [[commit-reference]] -If you want to reference a previous commit in the history of a stable -branch, use the format "abbreviated hash (subject, date)", like this: + +There are a few reasons why you may want to refer to another commit in +the "more stable" part of the history (i.e. on branches like `maint`, +`master`, and `next`): + +. A commit that introduced the root cause of a bug you are fixing. + +. A commit that introduced a feature that you are enhancing. + +. A commit that conflicts with your work when you made a trial merge + of your work into `next` and `seen` for testing. + +When you reference a commit on a more stable branch (like `master`, +`maint` and `next`), use the format "abbreviated hash (subject, +date)", like this: .... Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30) @@ -259,9 +315,11 @@ 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 `master` -branch head. If you are preparing a work based on "next" branch, -that is fine, but please mark it as such. +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. + [[send-patches]] === Sending your patches. @@ -365,7 +423,10 @@ Security mailing list{security-ml-ref}. Send your patch with "To:" set to the mailing list, with "cc:" listing people who are involved in the area you are touching (the `git contacts` command in `contrib/contacts/` can help to -identify them), to solicit comments and reviews. +identify them), to solicit comments and reviews. Also, when you made +trial merges of your topic to `next` and `seen`, you may have noticed +work by others conflicting with your changes. There is a good possibility +that these people may know the area you are touching well. :current-maintainer: footnote:[The current maintainer: gitster@pobox.com] :git-ml: footnote:[The mailing list: git@vger.kernel.org] diff --git a/Documentation/config.txt b/Documentation/config.txt index 1167e88e34..43f5e6fd6d 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -159,6 +159,33 @@ all branches that begin with `foo/`. This is useful if your branches are organized hierarchically and you would like to apply a configuration to all the branches in that hierarchy. +`hasconfig:remote.*.url:`:: + The data that follows this keyword is taken to + be a pattern with standard globbing wildcards and two + additional ones, `**/` and `/**`, that can match multiple + components. The first time this keyword is seen, the rest of + the config files will be scanned for remote URLs (without + applying any values). If there exists at least one remote URL + that matches this pattern, the include condition is met. ++ +Files included by this option (directly or indirectly) are not allowed +to contain remote URLs. ++ +Note that unlike other includeIf conditions, resolving this condition +relies on information that is not yet known at the point of reading the +condition. A typical use case is this option being present as a +system-level or global-level config, and the remote URL being in a +local-level config; hence the need to scan ahead when resolving this +condition. In order to avoid the chicken-and-egg problem in which +potentially-included files can affect whether such files are potentially +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 +a naming scheme that supports more variable-based include conditions, +but currently Git only supports the exact keyword described above. + A few more notes on matching via `gitdir` and `gitdir/i`: * Symlinks in `$GIT_DIR` are not resolved before matching. @@ -226,6 +253,14 @@ Example ; currently checked out [includeIf "onbranch:foo-branch"] path = foo.inc + +; include only if a remote with the given URL exists (note +; that such a URL may be provided later in a file or in a +; file read after this file is read, as seen in this example) +[includeIf "hasconfig:remote.*.url:https://example.com/**"] + path = foo.inc +[remote "origin"] + url = https://example.com/git ---- Values @@ -262,11 +297,19 @@ color:: colors (at most two, one for foreground and one for background) and attributes (as many as you want), separated by spaces. + -The basic colors accepted are `normal`, `black`, `red`, `green`, `yellow`, -`blue`, `magenta`, `cyan` and `white`. The first color given is the -foreground; the second is the background. All the basic colors except -`normal` have a bright variant that can be specified by prefixing the -color with `bright`, like `brightred`. +The basic colors accepted are `normal`, `black`, `red`, `green`, +`yellow`, `blue`, `magenta`, `cyan`, `white` and `default`. The first +color given is the foreground; the second is the background. All the +basic colors except `normal` and `default` have a bright variant that can +be specified by prefixing the color with `bright`, like `brightred`. ++ +The color `normal` makes no change to the color. It is the same as an +empty string, but can be used as the foreground color when specifying a +background color alone (for example, "normal red"). ++ +The color `default` explicitly resets the color to the terminal default, +for example to specify a cleared background. Although it varies between +terminals, this is usually not the same as setting to "white black". + Colors may also be given as numbers between 0 and 255; these use ANSI 256-color mode (but note that not all terminals may support this). If @@ -280,6 +323,11 @@ The position of any attributes with respect to the colors be turned off by prefixing them with `no` or `no-` (e.g., `noreverse`, `no-ul`, etc). + +The pseudo-attribute `reset` resets all colors and attributes before +applying the specified coloring. For example, `reset green` will result +in a green foreground and default background without any active +attributes. ++ An empty color string produces no color effect at all. This can be used to avoid coloring specific elements without disabling color entirely. + @@ -447,14 +495,14 @@ include::config/repack.txt[] include::config/rerere.txt[] -include::config/reset.txt[] - include::config/sendemail.txt[] include::config/sequencer.txt[] include::config/showbranch.txt[] +include::config/sparse.txt[] + include::config/splitindex.txt[] include::config/ssh.txt[] diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt index adee26fbbb..83c2a95661 100644 --- a/Documentation/config/advice.txt +++ b/Documentation/config/advice.txt @@ -67,10 +67,10 @@ advice.*:: commitBeforeMerge:: Advice shown when linkgit:git-merge[1] refuses to merge to avoid overwriting local changes. - resetQuiet:: - Advice to consider using the `--quiet` option to linkgit:git-reset[1] - when the command takes more than 2 seconds to enumerate unstaged - changes after reset. + resetNoRefresh:: + Advice to consider using the `--no-refresh` option to + linkgit:git-reset[1] when the command takes more than 2 seconds + to refresh the index after reset. resolveConflict:: Advice shown by various commands when conflicts prevent the operation from being performed. @@ -85,6 +85,9 @@ advice.*:: linkgit:git-switch[1] or linkgit:git-checkout[1] to move to the detach HEAD state, to instruct how to create a local branch after the fact. + suggestDetachingHead:: + Advice shown when linkgit:git-switch[1] refuses to detach HEAD + without the explicit `--detach` option. checkoutAmbiguousRemoteBranchName:: Advice shown when the argument to linkgit:git-checkout[1] and linkgit:git-switch[1] diff --git a/Documentation/config/clone.txt b/Documentation/config/clone.txt index 7bcfbd18a5..26f4fb137a 100644 --- a/Documentation/config/clone.txt +++ b/Documentation/config/clone.txt @@ -6,3 +6,8 @@ clone.defaultRemoteName:: clone.rejectShallow:: Reject to clone a repository if it is a shallow one, can be overridden by passing option `--reject-shallow` in command line. See linkgit:git-clone[1] + +clone.filterSubmodules:: + If a partial clone filter is provided (see `--filter` in + linkgit:git-rev-list[1]) and `--recurse-submodules` is used, also apply + the filter to submodules. diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt index c04f62a54a..9da3e5d88f 100644 --- a/Documentation/config/core.txt +++ b/Documentation/config/core.txt @@ -547,13 +547,64 @@ core.whitespace:: is relevant for `indent-with-non-tab` and when Git fixes `tab-in-indent` errors. The default tab width is 8. Allowed values are 1 to 63. +core.fsync:: + A comma-separated list of components of the repository that + should be hardened via the core.fsyncMethod when created or + modified. You can disable hardening of any component by + prefixing it with a '-'. Items that are not hardened may be + lost in the event of an unclean system shutdown. Unless you + have special requirements, it is recommended that you leave + this option empty or pick one of `committed`, `added`, + or `all`. ++ +When this configuration is encountered, the set of components starts with +the platform default value, disabled components are removed, and additional +components are added. `none` resets the state so that the platform default +is ignored. ++ +The empty string resets the fsync configuration to the platform +default. The default on most platforms is equivalent to +`core.fsync=committed,-loose-object`, which has good performance, +but risks losing recent work in the event of an unclean system shutdown. ++ +* `none` clears the set of fsynced components. +* `loose-object` hardens objects added to the repo in loose-object form. +* `pack` hardens objects added to the repo in packfile form. +* `pack-metadata` hardens packfile bitmaps and indexes. +* `commit-graph` hardens the commit graph file. +* `index` hardens the index when it is modified. +* `objects` is an aggregate option that is equivalent to + `loose-object,pack`. +* `reference` hardens references modified in the repo. +* `derived-metadata` is an aggregate option that is equivalent to + `pack-metadata,commit-graph`. +* `committed` is an aggregate option that is currently equivalent to + `objects`. This mode sacrifices some performance to ensure that work + that is committed to the repository with `git commit` or similar commands + is hardened. +* `added` is an aggregate option that is currently equivalent to + `committed,index`. This mode sacrifices additional performance to + ensure that the results of commands like `git add` and similar operations + are hardened. +* `all` is an aggregate option that syncs all individual components above. + +core.fsyncMethod:: + A value indicating the strategy Git will use to harden repository data + using fsync and related primitives. ++ +* `fsync` uses the fsync() system call or platform equivalents. +* `writeout-only` issues pagecache writeback requests, but depending on the + filesystem and storage hardware, data added to the repository may not be + durable in the event of a system crash. This is the default mode on macOS. + core.fsyncObjectFiles:: This boolean will enable 'fsync()' when writing object files. + This setting is deprecated. Use core.fsync instead. + -This is a total waste of time and effort on a filesystem that orders -data writes properly, but can be useful for filesystems that do not use -journalling (traditional UNIX filesystems) or that only journal metadata -and not file contents (OS X's HFS+, or Linux ext3 with "data=writeback"). +This setting affects data added to the Git repository in loose-object +form. When set to true, Git will issue an fsync or similar system call +to flush caches so that loose-objects remain consistent in the face +of a unclean system shutdown. core.preloadIndex:: Enable parallel index preload for operations like 'git diff' diff --git a/Documentation/config/extensions.txt b/Documentation/config/extensions.txt index 4e23d73cdc..bccaec7a96 100644 --- a/Documentation/config/extensions.txt +++ b/Documentation/config/extensions.txt @@ -6,3 +6,34 @@ extensions.objectFormat:: Note that this setting should only be set by linkgit:git-init[1] or linkgit:git-clone[1]. Trying to change it after initialization will not work and will produce hard-to-diagnose issues. + +extensions.worktreeConfig:: + If enabled, then worktrees will load config settings from the + `$GIT_DIR/config.worktree` file in addition to the + `$GIT_COMMON_DIR/config` file. Note that `$GIT_COMMON_DIR` and + `$GIT_DIR` are the same for the main working tree, while other + working trees have `$GIT_DIR` equal to + `$GIT_COMMON_DIR/worktrees/<id>/`. The settings in the + `config.worktree` file will override settings from any other + config files. ++ +When enabling `extensions.worktreeConfig`, you must be careful to move +certain values from the common config file to the main working tree's +`config.worktree` file, if present: ++ +* `core.worktree` must be moved from `$GIT_COMMON_DIR/config` to + `$GIT_COMMON_DIR/config.worktree`. +* If `core.bare` is true, then it must be moved from `$GIT_COMMON_DIR/config` + to `$GIT_COMMON_DIR/config.worktree`. ++ +It may also be beneficial to adjust the locations of `core.sparseCheckout` +and `core.sparseCheckoutCone` depending on your desire for customizable +sparse-checkout settings for each worktree. By default, the `git +sparse-checkout` builtin enables `extensions.worktreeConfig`, assigns +these config values on a per-worktree basis, and uses the +`$GIT_DIR/info/sparse-checkout` file to specify the sparsity for each +worktree independently. See linkgit:git-sparse-checkout[1] for more +details. ++ +For historical reasons, `extensions.worktreeConfig` is respected +regardless of the `core.repositoryFormatVersion` setting. diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt index 63748c02b7..cd65d236b4 100644 --- a/Documentation/config/fetch.txt +++ b/Documentation/config/fetch.txt @@ -56,18 +56,19 @@ fetch.output:: OUTPUT in linkgit:git-fetch[1] for detail. fetch.negotiationAlgorithm:: - Control how information about the commits in the local repository is - sent when negotiating the contents of the packfile to be sent by the - server. Set to "skipping" to use an algorithm that skips commits in an - effort to converge faster, but may result in a larger-than-necessary - packfile; or set to "noop" to not send any information at all, which - will almost certainly result in a larger-than-necessary packfile, but - will skip the negotiation step. - The default is "default" which instructs Git to use the default algorithm - that never skips commits (unless the server has acknowledged it or one - of its descendants). If `feature.experimental` is enabled, then this - setting defaults to "skipping". - Unknown values will cause 'git fetch' to error out. + Control how information about the commits in the local repository + is sent when negotiating the contents of the packfile to be sent by + the server. Set to "consecutive" to use an algorithm that walks + over consecutive commits checking each one. Set to "skipping" to + use an algorithm that skips commits in an effort to converge + faster, but may result in a larger-than-necessary packfile; or set + to "noop" to not send any information at all, which will almost + certainly result in a larger-than-necessary packfile, but will skip + the negotiation step. Set to "default" to override settings made + previously and use the default behaviour. The default is normally + "consecutive", but if `feature.experimental` is true, then the + default is "skipping". Unknown values will cause 'git fetch' to + error out. + See also the `--negotiate-only` and `--negotiation-tip` options to linkgit:git-fetch[1]. diff --git a/Documentation/config/gpg.txt b/Documentation/config/gpg.txt index 4f30c7dbdd..86892ada77 100644 --- a/Documentation/config/gpg.txt +++ b/Documentation/config/gpg.txt @@ -34,17 +34,17 @@ gpg.minTrustLevel:: * `fully` * `ultimate` -gpg.ssh.defaultKeyCommand: +gpg.ssh.defaultKeyCommand:: This command that will be run when user.signingkey is not set and a ssh signature is requested. On successful exit a valid ssh public key is - expected in the first line of its output. To automatically use the first + expected in the first line of its output. To automatically use the first available key from your ssh-agent set this to "ssh-add -L". gpg.ssh.allowedSignersFile:: A file containing ssh public keys which you are willing to trust. The file consists of one or more lines of principals followed by an ssh public key. - e.g.: user1@example.com,user2@example.com ssh-rsa AAAAX1... + e.g.: `user1@example.com,user2@example.com ssh-rsa AAAAX1...` See ssh-keygen(1) "ALLOWED SIGNERS" for details. The principal is only used to identify the key and is available when verifying a signature. @@ -64,6 +64,11 @@ A repository that only allows signed commits can store the file in the repository itself using a path relative to the top-level of the working tree. This way only committers with an already valid key can add or change keys in the keyring. + +Since OpensSSH 8.8 this file allows specifying a key lifetime using valid-after & +valid-before options. Git will mark signatures as valid if the signing key was +valid at the time of the signature's creation. This allows users to change a +signing key without invalidating all previously made signatures. ++ Using a SSH CA key with the cert-authority option (see ssh-keygen(1) "CERTIFICATES") is also valid. diff --git a/Documentation/config/grep.txt b/Documentation/config/grep.txt index 44abe45a7c..182edd813a 100644 --- a/Documentation/config/grep.txt +++ b/Documentation/config/grep.txt @@ -8,7 +8,8 @@ grep.patternType:: Set the default matching behavior. Using a value of 'basic', 'extended', 'fixed', or 'perl' will enable the `--basic-regexp`, `--extended-regexp`, `--fixed-strings`, or `--perl-regexp` option accordingly, while the - value 'default' will return to the default matching behavior. + value 'default' will use the `grep.extendedRegexp` option to choose + between 'basic' and 'extended'. grep.extendedRegexp:: If set to true, enable `--extended-regexp` option by default. This diff --git a/Documentation/config/merge.txt b/Documentation/config/merge.txt index e27cc63944..99e83dd36e 100644 --- a/Documentation/config/merge.txt +++ b/Documentation/config/merge.txt @@ -4,7 +4,14 @@ merge.conflictStyle:: shows a `<<<<<<<` conflict marker, changes made by one side, a `=======` marker, changes made by the other side, and then a `>>>>>>>` marker. An alternate style, "diff3", adds a `|||||||` - marker and the original text before the `=======` marker. + 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 + 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 + the beginning or end of a conflict region. merge.defaultToUpstream:: If merge is called without any commit argument, merge the upstream diff --git a/Documentation/config/repack.txt b/Documentation/config/repack.txt index 9c413e177e..41ac6953c8 100644 --- a/Documentation/config/repack.txt +++ b/Documentation/config/repack.txt @@ -25,3 +25,8 @@ repack.writeBitmaps:: space and extra time spent on the initial repack. This has no effect if multiple packfiles are created. Defaults to true on bare repos, false otherwise. + +repack.updateServerInfo:: + If set to false, linkgit:git-repack[1] will not run + linkgit:git-update-server-info[1]. Defaults to true. Can be overridden + when true by the `-n` option of linkgit:git-repack[1]. diff --git a/Documentation/config/reset.txt b/Documentation/config/reset.txt deleted file mode 100644 index 63b7c45aac..0000000000 --- a/Documentation/config/reset.txt +++ /dev/null @@ -1,2 +0,0 @@ -reset.quiet:: - When set to true, 'git reset' will default to the '--quiet' option. diff --git a/Documentation/config/sparse.txt b/Documentation/config/sparse.txt new file mode 100644 index 0000000000..aff49a8d3a --- /dev/null +++ b/Documentation/config/sparse.txt @@ -0,0 +1,27 @@ +sparse.expectFilesOutsideOfPatterns:: + Typically with sparse checkouts, files not matching any + sparsity patterns are marked with a SKIP_WORKTREE bit in the + index and are missing from the working tree. Accordingly, Git + will ordinarily check whether files with the SKIP_WORKTREE bit + are in fact present in the working tree contrary to + expectations. If Git finds any, it marks those paths as + present by clearing the relevant SKIP_WORKTREE bits. This + option can be used to tell Git that such + present-despite-skipped files are expected and to stop + checking for them. ++ +The default is `false`, which allows Git to automatically recover +from the list of files in the index and working tree falling out of +sync. ++ +Set this to `true` if you are in a setup where some external factor +relieves Git of the responsibility for maintaining the consistency +between the presence of working tree files and sparsity patterns. For +example, if you have a Git-aware virtual file system that has a robust +mechanism for keeping the working tree and the sparsity patterns up to +date based on access patterns. ++ +Regardless of this setting, Git does not check for +present-despite-skipped files unless sparse checkout is enabled, so +this config option has no effect unless `core.sparseCheckout` is +`true`. diff --git a/Documentation/config/stash.txt b/Documentation/config/stash.txt index 9ed775281f..b9f609ed76 100644 --- a/Documentation/config/stash.txt +++ b/Documentation/config/stash.txt @@ -1,10 +1,3 @@ -stash.useBuiltin:: - Unused configuration variable. Used in Git versions 2.22 to - 2.26 as an escape hatch to enable the legacy shellscript - implementation of stash. Now the built-in rewrite of it in C - is always used. Setting this will emit a warning, to alert any - remaining users that setting this now does nothing. - 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 diff --git a/Documentation/config/user.txt b/Documentation/config/user.txt index ad78dce9ec..ec9233b060 100644 --- a/Documentation/config/user.txt +++ b/Documentation/config/user.txt @@ -36,10 +36,13 @@ user.signingKey:: commit, you can override the default selection with this variable. This option is passed unchanged to gpg's --local-user parameter, so you may specify a key using any method that gpg supports. - If gpg.format is set to "ssh" this can contain the literal ssh public - key (e.g.: "ssh-rsa XXXXXX identifier") or a file which contains it and - corresponds to the private key used for signing. The private key - needs to be available via ssh-agent. Alternatively it can be set to - a file containing a private key directly. If not set git will call - gpg.ssh.defaultKeyCommand (e.g.: "ssh-add -L") and try to use the first - key available. + If gpg.format is set to `ssh` this can contain the path to either + 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 + 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 + as "key::ssh-rsa XXXXXX identifier", but this form is deprecated; + use the `key::` form instead. diff --git a/Documentation/date-formats.txt b/Documentation/date-formats.txt index 99c455f51c..67645cae64 100644 --- a/Documentation/date-formats.txt +++ b/Documentation/date-formats.txt @@ -5,9 +5,9 @@ The `GIT_AUTHOR_DATE` and `GIT_COMMITTER_DATE` environment variables support the following date formats: Git internal format:: - It is `<unix timestamp> <time zone offset>`, where `<unix - timestamp>` is the number of seconds since the UNIX epoch. - `<time zone offset>` is a positive or negative offset from UTC. + It is `<unix-timestamp> <time-zone-offset>`, where + `<unix-timestamp>` is the number of seconds since the UNIX epoch. + `<time-zone-offset>` is a positive or negative offset from UTC. For example CET (which is 1 hour ahead of UTC) is `+0100`. RFC 2822:: diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index c89d530d3d..3674ac48e9 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -34,7 +34,7 @@ endif::git-diff[] endif::git-format-patch[] ifdef::git-log[] ---diff-merges=(off|none|on|first-parent|1|separate|m|combined|c|dense-combined|cc):: +--diff-merges=(off|none|on|first-parent|1|separate|m|combined|c|dense-combined|cc|remerge|r):: --no-diff-merges:: Specify diff format to be used for merge commits. Default is {diff-merges-default} unless `--first-parent` is in use, in which case @@ -64,6 +64,18 @@ ifdef::git-log[] each of the 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. ++ +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::: @@ -616,11 +628,8 @@ ifndef::git-format-patch[] Also, these upper-case letters can be downcased to exclude. E.g. `--diff-filter=ad` excludes added and deleted paths. + -Note that not all diffs can feature all types. For instance, diffs -from the index to the working tree can never have Added entries -(because the set of paths included in the diff is limited by what is in -the index). Similarly, copied and renamed entries cannot appear if -detection for those types is disabled. +Note that not all diffs can feature all types. For instance, copied and +renamed entries cannot appear if detection for those types is disabled. -S<string>:: Look for differences that change the number of occurrences of diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index e967ff1874..6cdd9d43c5 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -71,6 +71,7 @@ configuration variables documented in linkgit:git-config[1], and the ancestors of the provided `--negotiation-tip=*` arguments, which we have in common with the server. + +This is incompatible with `--recurse-submodules=[yes|on-demand]`. Internally this is used to implement the `push.negotiate` option, see linkgit:git-config[1]. @@ -185,15 +186,23 @@ endif::git-pull[] ifndef::git-pull[] --recurse-submodules[=yes|on-demand|no]:: This option controls if and under what conditions new commits of - populated submodules should be fetched too. It can be used as a - boolean option to completely disable recursion when set to 'no' or to - unconditionally recurse into all populated submodules when set to - 'yes', which is the default when this option is used without any - value. Use 'on-demand' to only recurse into a populated submodule - when the superproject retrieves a commit that updates the submodule's - reference to a commit that isn't already in the local submodule - clone. By default, 'on-demand' is used, unless - `fetch.recurseSubmodules` is set (see linkgit:git-config[1]). + submodules should be fetched too. When recursing through submodules, + `git fetch` always attempts to fetch "changed" submodules, that is, a + submodule that has commits that are referenced by a newly fetched + superproject commit but are missing in the local submodule clone. A + changed submodule can be fetched as long as it is present locally e.g. + in `$GIT_DIR/modules/` (see linkgit:gitsubmodules[7]); if the upstream + adds a new submodule, that submodule cannot be fetched until it is + cloned e.g. by `git submodule update`. ++ +When set to 'on-demand', only changed submodules are fetched. When set +to 'yes', all populated submodules are fetched and submodules that are +both unpopulated and changed are fetched. When set to 'no', submodules +are never fetched. ++ +When unspecified, this uses the value of `fetch.recurseSubmodules` if it +is set (see linkgit:git-config[1]), defaulting to 'on-demand' if unset. +When this option is used without any value, it defaults to 'yes'. endif::git-pull[] -j:: diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 0a4a984dfd..09107fb106 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -16,8 +16,9 @@ SYNOPSIS [--exclude=<path>] [--include=<path>] [--reject] [-q | --quiet] [--[no-]scissors] [-S[<keyid>]] [--patch-format=<format>] [--quoted-cr=<action>] + [--empty=(stop|drop|keep)] [(<mbox> | <Maildir>)...] -'git am' (--continue | --skip | --abort | --quit | --show-current-patch[=(diff|raw)]) +'git am' (--continue | --skip | --abort | --quit | --show-current-patch[=(diff|raw)] | --allow-empty) DESCRIPTION ----------- @@ -63,6 +64,14 @@ OPTIONS --quoted-cr=<action>:: This flag will be passed down to 'git mailinfo' (see linkgit:git-mailinfo[1]). +--empty=(stop|drop|keep):: + By default, or when the option is set to 'stop', the command + errors out on an input e-mail message lacking a patch + and stops into the middle of the current am session. When this + option is set to 'drop', skip such an e-mail message instead. + When this option is set to 'keep', create an empty commit, + recording the contents of the e-mail message as its log. + -m:: --message-id:: Pass the `-m` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]), @@ -191,6 +200,11 @@ default. You can use `--no-utf8` to override this. the e-mail message; if `diff`, show the diff portion only. Defaults to `raw`. +--allow-empty:: + After a patch failure on an input e-mail message lacking a patch, + create an empty commit with the contents of the e-mail message + as its log message. + DISCUSSION ---------- diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt index aa1ae56a25..b6d77f4206 100644 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@ -16,7 +16,7 @@ SYNOPSIS [--ignore-space-change | --ignore-whitespace] [--whitespace=(nowarn|warn|fix|error|error-all)] [--exclude=<path>] [--include=<path>] [--directory=<root>] - [--verbose] [--unsafe-paths] [<patch>...] + [--verbose | --quiet] [--unsafe-paths] [--allow-empty] [<patch>...] DESCRIPTION ----------- @@ -228,6 +228,11 @@ behavior: current patch being applied will be printed. This option will cause additional information to be reported. +-q:: +--quiet:: + Suppress stderr output. Messages about patch status and progress + will not be printed. + --recount:: Do not trust the line counts in the hunk headers, but infer them by inspecting the patch (e.g. after editing the patch without @@ -251,6 +256,10 @@ When `git apply` is used as a "better GNU patch", the user can pass 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 + empty patches and patches with commit text only. + CONFIGURATION ------------- diff --git a/Documentation/git-archimport.txt b/Documentation/git-archimport.txt index a595a0ffee..847777fd17 100644 --- a/Documentation/git-archimport.txt +++ b/Documentation/git-archimport.txt @@ -9,14 +9,14 @@ git-archimport - Import a GNU Arch repository into Git SYNOPSIS -------- [verse] -'git archimport' [-h] [-v] [-o] [-a] [-f] [-T] [-D depth] [-t tempdir] - <archive/branch>[:<git-branch>] ... +'git archimport' [-h] [-v] [-o] [-a] [-f] [-T] [-D <depth>] [-t <tempdir>] + <archive>/<branch>[:<git-branch>]... DESCRIPTION ----------- Imports a project from one or more GNU Arch repositories. It will follow branches -and repositories within the namespaces defined by the <archive/branch> +and repositories within the namespaces defined by the <archive>/<branch> parameters supplied. If it cannot find the remote branch a merge comes from it will just import it as a regular commit. If it can find it, it will mark it as a merge whenever possible (see discussion below). @@ -27,7 +27,7 @@ import new branches within the provided roots. It expects to be dealing with one project only. If it sees branches that have different roots, it will refuse to run. In that case, -edit your <archive/branch> parameters to define clearly the scope of the +edit your <archive>/<branch> parameters to define clearly the scope of the import. 'git archimport' uses `tla` extensively in the background to access the @@ -42,7 +42,7 @@ incremental imports. While 'git archimport' will try to create sensible branch names for the archives that it imports, it is also possible to specify Git branch names -manually. To do so, write a Git branch name after each <archive/branch> +manually. To do so, write a Git branch name after each <archive>/<branch> parameter, separated by a colon. This way, you can shorten the Arch branch names and convert Arch jargon to Git jargon, for example mapping a "PROJECT{litdd}devo{litdd}VERSION" branch to "master". @@ -104,8 +104,8 @@ OPTIONS Override the default tempdir. -<archive/branch>:: - Archive/branch identifier in a format that `tla log` understands. +<archive>/<branch>:: + <archive>/<branch> identifier in a format that `tla log` understands. GIT diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index 72ab813905..7685b57045 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -75,8 +75,11 @@ verify <file>:: cleanly to the current repository. This includes checks on the bundle format itself as well as checking that the prerequisite commits exist and are fully linked in the current repository. - 'git bundle' prints a list of missing commits, if any, and exits - with a non-zero status. + Then, 'git bundle' prints a list of missing commits, if any. + Finally, information about additional capabilities, such as "object + filter", is printed. See "Capabilities" in link:technical/bundle-format.html + for more information. The exit code is zero for success, but will + be nonzero if the bundle file is invalid. list-heads <file>:: Lists the references defined in the bundle. If followed by a diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt index 27b27e2b30..70c5b4f12d 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -9,8 +9,14 @@ git-cat-file - Provide content or type and size information for repository objec SYNOPSIS -------- [verse] -'git cat-file' (-t [--allow-unknown-type]| -s [--allow-unknown-type]| -e | -p | <type> | --textconv | --filters ) [--path=<path>] <object> -'git cat-file' (--batch[=<format>] | --batch-check[=<format>]) [ --textconv | --filters ] [--follow-symlinks] +'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-all-objects] + [--buffer] [--follow-symlinks] [--unordered] + [--textconv | --filters] +'git cat-file' (--textconv | --filters) + [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>] DESCRIPTION ----------- @@ -90,6 +96,33 @@ OPTIONS need to specify the path, separated by whitespace. See the section `BATCH OUTPUT` below for details. +--batch-command:: +--batch-command=<format>:: + Enter a command mode that reads commands and arguments from stdin. May + only be combined with `--buffer`, `--textconv` or `--filters`. In the + case of `--textconv` or `--filters`, the input lines also need to specify + the path, separated by whitespace. See the section `BATCH OUTPUT` below + for details. ++ +`--batch-command` recognizes the following commands: ++ +-- +contents <object>:: + Print object contents for object reference `<object>`. This corresponds to + the output of `--batch`. + +info <object>:: + Print object info for object reference `<object>`. This corresponds to the + output of `--batch-check`. + +flush:: + Used with `--buffer` to execute all preceding commands that were issued + since the beginning or since the last flush was issued. When `--buffer` + is used, no output will come until a `flush` is issued. When `--buffer` + is not used, commands are flushed each time without issuing `flush`. +-- ++ + --batch-all-objects:: Instead of reading a list of objects on stdin, perform the requested batch operation on all objects in the repository and @@ -104,7 +137,7 @@ OPTIONS that a process can interactively read and write from `cat-file`. With this option, the output uses normal stdio buffering; this is much more efficient when invoking - `--batch-check` on a large number of objects. + `--batch-check` or `--batch-command` on a large number of objects. --unordered:: When `--batch-all-objects` is in use, visit objects in an @@ -196,6 +229,13 @@ from stdin, one per line, and print information about them. By default, the whole line is considered as an object, as if it were fed to linkgit:git-rev-parse[1]. +When `--batch-command` is given, `cat-file` will read commands from stdin, +one per line, and print information based on the command given. With +`--batch-command`, the `info` command followed by an object will print +information about the object the same way `--batch-check` would, and the +`contents` command followed by an object prints contents in the same way +`--batch` would. + You can specify the information shown for each object by using a custom `<format>`. The `<format>` is copied literally to stdout for each object, with placeholders of the form `%(atom)` expanded, followed by a @@ -231,9 +271,9 @@ newline. The available atoms are: If no format is specified, the default format is `%(objectname) %(objecttype) %(objectsize)`. -If `--batch` is specified, the object information is followed by the -object contents (consisting of `%(objectsize)` bytes), followed by a -newline. +If `--batch` is specified, or if `--batch-command` is used with the `contents` +command, the object information is followed by the object contents (consisting +of `%(objectsize)` bytes), followed by a newline. For example, `--batch` without a custom format would produce: diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt index 0c3924a63d..2892799e32 100644 --- a/Documentation/git-check-ignore.txt +++ b/Documentation/git-check-ignore.txt @@ -33,7 +33,7 @@ OPTIONS Instead of printing the paths that are excluded, for each path that matches an exclude pattern, print the exclude pattern together with the path. (Matching an exclude pattern usually - means the path is excluded, but if the pattern begins with '!' + means the path is excluded, but if the pattern begins with "`!`" then it is a negated pattern and matching it means the path is NOT excluded.) + @@ -77,7 +77,7 @@ If `--verbose` is specified, the output is a series of lines of the form: <pathname> is the path of a file being queried, <pattern> is the matching pattern, <source> is the pattern's source file, and <linenum> is the line number of the pattern within that source. If the pattern -contained a `!` prefix or `/` suffix, it will be preserved in the +contained a "`!`" prefix or "`/`" suffix, it will be preserved in the output. <source> will be an absolute path when referring to the file configured by `core.excludesFile`, or relative to the repository root when referring to `.git/info/exclude` or a per-directory exclude file. diff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt index 4d33e7be0f..01dbd5cbf5 100644 --- a/Documentation/git-checkout-index.txt +++ b/Documentation/git-checkout-index.txt @@ -12,6 +12,7 @@ SYNOPSIS 'git checkout-index' [-u] [-q] [-a] [-f] [-n] [--prefix=<string>] [--stage=<number>|all] [--temp] + [--ignore-skip-worktree-bits] [-z] [--stdin] [--] [<file>...] @@ -37,8 +38,9 @@ OPTIONS -a:: --all:: - checks out all files in the index. Cannot be used - together with explicit filenames. + checks out all files in the index except for those with the + skip-worktree bit set (see `--ignore-skip-worktree-bits`). + Cannot be used together with explicit filenames. -n:: --no-create:: @@ -59,6 +61,10 @@ OPTIONS write the content to temporary files. The temporary name associations will be written to stdout. +--ignore-skip-worktree-bits:: + Check out all files, including those with the skip-worktree bit + set. + --stdin:: Instead of taking list of paths from the command line, read list of paths from the standard input. Paths are diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 4353f1031b..9f37e22e13 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -11,7 +11,7 @@ SYNOPSIS 'git checkout' [-q] [-f] [-m] [<branch>] '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' [-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' (-p|--patch) [<tree-ish>] [--] [<pathspec>...] @@ -43,7 +43,7 @@ You could omit `<branch>`, in which case the command degenerates to rather expensive side-effects to show only the tracking information, if exists, for the current branch. -'git checkout' -b|-B <new_branch> [<start point>]:: +'git checkout' -b|-B <new-branch> [<start-point>]:: Specifying `-b` causes a new branch to be created as if linkgit:git-branch[1] were called and then checked out. In @@ -52,11 +52,11 @@ if exists, for the current branch. `--track` without `-b` implies branch creation; see the description of `--track` below. + -If `-B` is given, `<new_branch>` is created if it doesn't exist; otherwise, it +If `-B` is given, `<new-branch>` is created if it doesn't exist; otherwise, it is reset. This is the transactional equivalent of + ------------ -$ git branch -f <branch> [<start point>] +$ git branch -f <branch> [<start-point>] $ git checkout <branch> ------------ + @@ -145,13 +145,13 @@ as `ours` (i.e. "our shared canonical history"), while what you did on your side branch as `theirs` (i.e. "one contributor's work on top of it"). --b <new_branch>:: - Create a new branch named `<new_branch>` and start it at - `<start_point>`; see linkgit:git-branch[1] for details. +-b <new-branch>:: + Create a new branch named `<new-branch>` and start it at + `<start-point>`; see linkgit:git-branch[1] for details. --B <new_branch>:: - Creates the branch `<new_branch>` and start it at `<start_point>`; - if it already exists, then reset it to `<start_point>`. This is +-B <new-branch>:: + Creates the branch `<new-branch>` and start it at `<start-point>`; + if it already exists, then reset it to `<start-point>`. This is equivalent to running "git branch" with "-f"; see linkgit:git-branch[1] for details. @@ -210,16 +210,16 @@ variable. `<commit>` is not a branch name. See the "DETACHED HEAD" section below for details. ---orphan <new_branch>:: - Create a new 'orphan' branch, named `<new_branch>`, started from - `<start_point>` and switch to it. The first commit made on this +--orphan <new-branch>:: + Create a new 'orphan' branch, named `<new-branch>`, started from + `<start-point>` and switch to it. The first commit made on this new branch will have no parents and it will be the root of a new history totally disconnected from all the other branches and commits. + The index and the working tree are adjusted as if you had previously run -`git checkout <start_point>`. This allows you to start a new history -that records a set of paths similar to `<start_point>` by easily running +`git checkout <start-point>`. This allows you to start a new history +that records a set of paths similar to `<start-point>` by easily running `git commit -a` to make the root commit. + This can be useful when you want to publish the tree from a commit @@ -229,7 +229,7 @@ whose full history contains proprietary or otherwise encumbered bits of code. + If you want to start a disconnected history that records a set of paths -that is totally different from the one of `<start_point>`, then you should +that is totally different from the one of `<start-point>`, then you should clear the index and the working tree right after creating the orphan branch by running `git rm -rf .` from the top level of the working tree. Afterwards you will be ready to prepare your new files, repopulating the @@ -266,8 +266,7 @@ When switching branches with `--merge`, staged changes may be lost. The same as `--merge` option above, but changes the way the conflicting hunks are presented, overriding the `merge.conflictStyle` configuration variable. Possible values are - "merge" (default) and "diff3" (in addition to what is shown by - "merge" style, shows the original contents). + "merge" (default), "diff3", and "zdiff3". -p:: --patch:: @@ -341,10 +340,10 @@ As a special case, you may use `A...B` as a shortcut for the merge base of `A` and `B` if there is exactly one merge base. You can leave out at most one of `A` and `B`, in which case it defaults to `HEAD`. -<new_branch>:: +<new-branch>:: Name for the new branch. -<start_point>:: +<start-point>:: The name of a commit at which to start the new branch; see linkgit:git-branch[1] for details. Defaults to `HEAD`. + diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index 5d750314b2..78dcc9171f 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -8,7 +8,7 @@ git-cherry-pick - Apply the changes introduced by some existing commits SYNOPSIS -------- [verse] -'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] [--ff] +'git cherry-pick' [--edit] [-n] [-m <parent-number>] [-s] [-x] [--ff] [-S[<keyid>]] <commit>... 'git cherry-pick' (--continue | --skip | --abort | --quit) @@ -81,8 +81,8 @@ OPTIONS described above, and `-r` was to disable it. Now the default is not to do `-x` so this option is a no-op. --m parent-number:: ---mainline parent-number:: +-m <parent-number>:: +--mainline <parent-number>:: Usually you cannot cherry-pick a merge because you do not know which side of the merge should be considered the mainline. This option specifies the parent number (starting from 1) of diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 3fe3810f1c..632bd1348e 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -9,14 +9,14 @@ git-clone - Clone a repository into a new directory SYNOPSIS -------- [verse] -'git clone' [--template=<template_directory>] +'git clone' [--template=<template-directory>] [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror] [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>] - [--dissociate] [--separate-git-dir <git dir>] + [--dissociate] [--separate-git-dir <git-dir>] [--depth <depth>] [--[no-]single-branch] [--no-tags] [--recurse-submodules[=<pathspec>]] [--[no-]shallow-submodules] [--[no-]remote-submodules] [--jobs <n>] [--sparse] [--[no-]reject-shallow] - [--filter=<filter>] [--] <repository> + [--filter=<filter> [--also-filter-submodules]] [--] <repository> [<directory>] DESCRIPTION @@ -167,10 +167,10 @@ objects from the source repository into a pack in the cloned repository. configuration variables are created. --sparse:: - Initialize the sparse-checkout file so the working - directory starts with only the files in the root - of the repository. The sparse-checkout file can be - modified to grow the working directory as needed. + Employ a sparse-checkout, with only files in the toplevel + directory initially being present. The + linkgit:git-sparse-checkout[1] command can be used to grow the + working directory as needed. --filter=<filter-spec>:: Use the partial clone feature and request that the server sends @@ -182,6 +182,11 @@ objects from the source repository into a pack in the cloned repository. at least `<size>`. For more details on filter specifications, see the `--filter` option in linkgit:git-rev-list[1]. +--also-filter-submodules:: + Also apply the partial clone filter to any submodules in the repository. + Requires `--filter` and `--recurse-submodules`. This can be turned on by + default by setting the `clone.filterSubmodules` config option. + --mirror:: Set up a mirror of the source repository. This implies `--bare`. Compared to `--bare`, `--mirror` not only maps local branches of the @@ -211,7 +216,7 @@ objects from the source repository into a pack in the cloned repository. via ssh, this specifies a non-default path for the command run on the other end. ---template=<template_directory>:: +--template=<template-directory>:: Specify the directory from which templates will be used; (See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].) @@ -294,7 +299,7 @@ or `--mirror` is given) superproject's recorded SHA-1. Equivalent to passing `--remote` to `git submodule update`. ---separate-git-dir=<git dir>:: +--separate-git-dir=<git-dir>:: Instead of placing the cloned repository where it is supposed to be, place the cloned repository at the specified directory, then make a filesystem-agnostic Git symbolic link to there. diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 992225f612..bdcfd94b64 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -9,20 +9,20 @@ git-config - Get and set repository or global options SYNOPSIS -------- [verse] -'git config' [<file-option>] [--type=<type>] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] name [value [value-pattern]] -'git config' [<file-option>] [--type=<type>] --add name value -'git config' [<file-option>] [--type=<type>] [--fixed-value] --replace-all name value [value-pattern] -'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get name [value-pattern] -'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all name [value-pattern] -'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp name_regex [value-pattern] -'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch name URL -'git config' [<file-option>] [--fixed-value] --unset name [value-pattern] -'git config' [<file-option>] [--fixed-value] --unset-all name [value-pattern] -'git config' [<file-option>] --rename-section old_name new_name -'git config' [<file-option>] --remove-section name +'git config' [<file-option>] [--type=<type>] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] <name> [<value> [<value-pattern>]] +'git config' [<file-option>] [--type=<type>] --add <name> <value> +'git config' [<file-option>] [--type=<type>] [--fixed-value] --replace-all <name> <value> [<value-pattern>] +'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get <name> [<value-pattern>] +'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all <name> [<value-pattern>] +'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp <name-regex> [<value-pattern>] +'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch <name> <URL> +'git config' [<file-option>] [--fixed-value] --unset <name> [<value-pattern>] +'git config' [<file-option>] [--fixed-value] --unset-all <name> [<value-pattern>] +'git config' [<file-option>] --rename-section <old-name> <new-name> +'git config' [<file-option>] --remove-section <name> 'git config' [<file-option>] [--show-origin] [--show-scope] [-z|--null] [--name-only] -l | --list -'git config' [<file-option>] --get-color name [default] -'git config' [<file-option>] --get-colorbool name [stdout-is-tty] +'git config' [<file-option>] --get-color <name> [<default>] +'git config' [<file-option>] --get-colorbool <name> [<stdout-is-tty>] 'git config' [<file-option>] -e | --edit DESCRIPTION @@ -102,9 +102,9 @@ OPTIONS in which section and variable names are lowercased, but subsection names are not. ---get-urlmatch name URL:: +--get-urlmatch <name> <URL>:: When given a two-part name section.key, the value for - section.<url>.key whose <url> part matches the best to the + section.<URL>.key whose <URL> part matches the best to the given URL is returned (if no such key exists, the value for section.key is used as a fallback). When given just the section as name, do so for all the keys in the section and @@ -141,12 +141,16 @@ from all available files. See also <<FILES>>. --worktree:: - Similar to `--local` except that `.git/config.worktree` is + Similar to `--local` except that `$GIT_DIR/config.worktree` is read from or written to if `extensions.worktreeConfig` is - present. If not it's the same as `--local`. - --f config-file:: ---file config-file:: + enabled. If not it's the same as `--local`. Note that `$GIT_DIR` + is equal to `$GIT_COMMON_DIR` for the main working tree, but is of + the form `$GIT_DIR/worktrees/<id>/` for other working trees. See + linkgit:git-worktree[1] to learn how to enable + `extensions.worktreeConfig`. + +-f <config-file>:: +--file <config-file>:: For writing options: write to the specified file rather than the repository `.git/config`. + @@ -155,7 +159,7 @@ available files. + See also <<FILES>>. ---blob blob:: +--blob <blob>:: Similar to `--file` but use the given blob instead of a file. E.g. you can use 'master:.gitmodules' to read values from the file '.gitmodules' in the master branch. See "SPECIFYING REVISIONS" @@ -246,18 +250,18 @@ Valid `<type>`'s include: all queried config options with the scope of that value (local, global, system, command). ---get-colorbool name [stdout-is-tty]:: +--get-colorbool <name> [<stdout-is-tty>]:: - Find the color setting for `name` (e.g. `color.diff`) and output - "true" or "false". `stdout-is-tty` should be either "true" or + Find the color setting for `<name>` (e.g. `color.diff`) and output + "true" or "false". `<stdout-is-tty>` should be either "true" or "false", and is taken into account when configuration says - "auto". If `stdout-is-tty` is missing, then checks the standard + "auto". If `<stdout-is-tty>` is missing, then checks the standard output of the command itself, and exits with status 0 if color is to be used, or exits with status 1 otherwise. When the color setting for `name` is undefined, the command uses `color.ui` as fallback. ---get-color name [default]:: +--get-color <name> [<default>]:: Find the color configured for `name` (e.g. `color.diff.new`) and output it as the ANSI color escape sequence to the standard diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt index 206e3c5f40..f18673017f 100644 --- a/Documentation/git-credential.txt +++ b/Documentation/git-credential.txt @@ -8,7 +8,7 @@ git-credential - Retrieve and store user credentials SYNOPSIS -------- ------------------ -git credential <fill|approve|reject> +'git credential' (fill|approve|reject) ------------------ DESCRIPTION diff --git a/Documentation/git-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.txt index 00154b6c85..41c8a8a05c 100644 --- a/Documentation/git-cvsexportcommit.txt +++ b/Documentation/git-cvsexportcommit.txt @@ -9,8 +9,8 @@ git-cvsexportcommit - Export a single commit to a CVS checkout SYNOPSIS -------- [verse] -'git cvsexportcommit' [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d cvsroot] - [-w cvsworkdir] [-W] [-f] [-m msgprefix] [PARENTCOMMIT] COMMITID +'git cvsexportcommit' [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d <cvsroot>] + [-w <cvs-workdir>] [-W] [-f] [-m <msgprefix>] [<parent-commit>] <commit-id> DESCRIPTION diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt index de1ebed67d..b3f27671a0 100644 --- a/Documentation/git-cvsimport.txt +++ b/Documentation/git-cvsimport.txt @@ -11,9 +11,9 @@ SYNOPSIS [verse] 'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <CVSROOT>] [-A <author-conv-file>] [-p <options-for-cvsps>] [-P <file>] - [-C <git_repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>] - [-a] [-m] [-M <regex>] [-S <regex>] [-L <commitlimit>] - [-r <remote>] [-R] [<CVS_module>] + [-C <git-repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>] + [-a] [-m] [-M <regex>] [-S <regex>] [-L <commit-limit>] + [-r <remote>] [-R] [<CVS-module>] DESCRIPTION @@ -59,7 +59,7 @@ OPTIONS from `CVS/Root`. If no such file exists, it checks for the `CVSROOT` environment variable. -<CVS_module>:: +<CVS-module>:: The CVS module you want to import. Relative to <CVSROOT>. If not given, 'git cvsimport' tries to read it from `CVS/Repository`. diff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt index 906774f0f7..bf1febb9ae 100644 --- a/Documentation/git-diff-files.txt +++ b/Documentation/git-diff-files.txt @@ -9,7 +9,7 @@ git-diff-files - Compares files in the working tree and the index SYNOPSIS -------- [verse] -'git diff-files' [-q] [-0|-1|-2|-3|-c|--cc] [<common diff options>] [<path>...] +'git diff-files' [-q] [-0|-1|-2|-3|-c|--cc] [<common-diff-options>] [<path>...] DESCRIPTION ----------- diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt index 27acb31cbf..679cae27d9 100644 --- a/Documentation/git-diff-index.txt +++ b/Documentation/git-diff-index.txt @@ -9,7 +9,7 @@ git-diff-index - Compare a tree to the working tree or index SYNOPSIS -------- [verse] -'git diff-index' [-m] [--cached] [--merge-base] [<common diff options>] <tree-ish> [<path>...] +'git diff-index' [-m] [--cached] [--merge-base] [<common-diff-options>] <tree-ish> [<path>...] DESCRIPTION ----------- diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt index 2fc24c542f..274d5eaba9 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -11,7 +11,7 @@ SYNOPSIS [verse] 'git diff-tree' [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty] [-t] [-r] [-c | --cc] [--combined-all-paths] [--root] [--merge-base] - [<common diff options>] <tree-ish> [<tree-ish>] [<path>...] + [<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...] DESCRIPTION ----------- diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt index 550c16ca61..e9d364669a 100644 --- a/Documentation/git-fetch.txt +++ b/Documentation/git-fetch.txt @@ -287,12 +287,10 @@ include::transfer-data-leaks.txt[] BUGS ---- -Using --recurse-submodules can only fetch new commits in already checked -out submodules right now. When e.g. upstream added a new submodule in the -just fetched commits of the superproject the submodule itself cannot be -fetched, making it impossible to check out that submodule later without -having to do a fetch again. This is expected to be fixed in a future Git -version. +Using --recurse-submodules can only fetch new commits in submodules that are +present locally e.g. in `$GIT_DIR/modules/`. If the upstream adds a new +submodule, that submodule cannot be fetched until it is cloned e.g. by `git +submodule update`. This is expected to be fixed in a future Git version. SEE ALSO -------- diff --git a/Documentation/git-fmt-merge-msg.txt b/Documentation/git-fmt-merge-msg.txt index 6793d8fc05..6f28812f38 100644 --- a/Documentation/git-fmt-merge-msg.txt +++ b/Documentation/git-fmt-merge-msg.txt @@ -9,7 +9,7 @@ git-fmt-merge-msg - Produce a merge commit message SYNOPSIS -------- [verse] -'git fmt-merge-msg' [-m <message>] [--log[=<n>] | --no-log] +'git fmt-merge-msg' [-m <message>] [--into-name <branch>] [--log[=<n>] | --no-log] 'git fmt-merge-msg' [-m <message>] [--log[=<n>] | --no-log] -F <file> DESCRIPTION @@ -44,6 +44,10 @@ OPTIONS Use <message> instead of the branch names for the first line of the log message. For use with `--log`. +--into-name <branch>:: + Prepare the merge message as if merging to the branch `<branch>`, + instead of the name of the real branch to which the merge is made. + -F <file>:: --file <file>:: Take the list of merged objects from <file> instead of diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 113eabc107..be797d7a28 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -18,7 +18,7 @@ SYNOPSIS [-n | --numbered | -N | --no-numbered] [--start-number <n>] [--numbered-files] [--in-reply-to=<message id>] [--suffix=.<sfx>] - [--ignore-if-in-upstream] + [--ignore-if-in-upstream] [--always] [--cover-from-description=<mode>] [--rfc] [--subject-prefix=<subject prefix>] [(--reroll-count|-v) <n>] @@ -192,6 +192,10 @@ will want to ensure that threading is disabled for `git send-email`. patches being generated, and any patch that matches is ignored. +--always:: + Include patches for commits that do not introduce any change, + which are omitted by default. + --cover-from-description=<mode>:: Controls which parts of the cover letter will be automatically populated using the branch's description. diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt index bd596619c0..5088783dcc 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -12,7 +12,7 @@ SYNOPSIS 'git fsck' [--tags] [--root] [--unreachable] [--cache] [--no-reflogs] [--[no-]full] [--strict] [--verbose] [--lost-found] [--[no-]dangling] [--[no-]progress] [--connectivity-only] - [--[no-]name-objects] [<object>*] + [--[no-]name-objects] [<object>...] DESCRIPTION ----------- diff --git a/Documentation/git-gui.txt b/Documentation/git-gui.txt index c9d7e96214..e8f3ccb433 100644 --- a/Documentation/git-gui.txt +++ b/Documentation/git-gui.txt @@ -8,7 +8,7 @@ git-gui - A portable graphical interface to Git SYNOPSIS -------- [verse] -'git gui' [<command>] [arguments] +'git gui' [<command>] [<arguments>] DESCRIPTION ----------- diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index 96d5f598b4..239c68db45 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -8,15 +8,15 @@ git-help - Display help information about Git SYNOPSIS -------- [verse] -'git help' [-a|--all [--[no-]verbose]] - [[-i|--info] [-m|--man] [-w|--web]] [COMMAND|GUIDE] +'git help' [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases] +'git help' [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>] 'git help' [-g|--guides] 'git help' [-c|--config] DESCRIPTION ----------- -With no options and no COMMAND or GUIDE given, the synopsis of the 'git' +With no options and no '<command>' or '<guide>' given, the synopsis of the 'git' command and a list of the most commonly used Git commands are printed on the standard output. @@ -33,7 +33,7 @@ variables. If an alias is given, git shows the definition of the alias on standard output. To get the manual page for the aliased command, use -`git COMMAND --help`. +`git <command> --help`. Note that `git --help ...` is identical to `git help ...` because the former is internally converted into the latter. @@ -46,8 +46,15 @@ OPTIONS ------- -a:: --all:: - Prints all the available commands on the standard output. This - option overrides any given command or guide name. + Prints all the available commands on the standard output. + +--no-external-commands:: + When used with `--all`, exclude the listing of external "git-*" + commands found in the `$PATH`. + +--no-aliases:: + When used with `--all`, exclude the listing of configured + aliases. --verbose:: When used with `--all` print description for all recognized diff --git a/Documentation/git-hook.txt b/Documentation/git-hook.txt new file mode 100644 index 0000000000..77c3a8ad90 --- /dev/null +++ b/Documentation/git-hook.txt @@ -0,0 +1,45 @@ +git-hook(1) +=========== + +NAME +---- +git-hook - Run git hooks + +SYNOPSIS +-------- +[verse] +'git hook' run [--ignore-missing] <hook-name> [-- <hook-args>] + +DESCRIPTION +----------- + +A command interface to running git hooks (see linkgit:githooks[5]), +for use by other scripted git commands. + +SUBCOMMANDS +----------- + +run:: + Run the `<hook-name>` hook. See linkgit:githooks[5] for + supported hook names. ++ + +Any positional arguments to the hook should be passed after a +mandatory `--` (or `--end-of-options`, see linkgit:gitcli[7]). See +linkgit:githooks[5] for arguments hooks might expect (if any). + +OPTIONS +------- + +--ignore-missing:: + Ignore any missing hook by quietly returning zero. Used for + tools that want to do a blind one-shot run of a hook that may + or may not be present. + +SEE ALSO +-------- +linkgit:githooks[5] + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-http-fetch.txt b/Documentation/git-http-fetch.txt index 9fa17b60e4..319062c021 100644 --- a/Documentation/git-http-fetch.txt +++ b/Documentation/git-http-fetch.txt @@ -9,7 +9,7 @@ git-http-fetch - Download from a remote Git repository via HTTP SYNOPSIS -------- [verse] -'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [--stdin | --packfile=<hash> | <commit>] <url> +'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w <filename>] [--recover] [--stdin | --packfile=<hash> | <commit>] <URL> DESCRIPTION ----------- diff --git a/Documentation/git-http-push.txt b/Documentation/git-http-push.txt index ea03a4eeb0..7c6a6dd7f6 100644 --- a/Documentation/git-http-push.txt +++ b/Documentation/git-http-push.txt @@ -9,7 +9,7 @@ git-http-push - Push objects over HTTP/DAV to another repository SYNOPSIS -------- [verse] -'git http-push' [--all] [--dry-run] [--force] [--verbose] <url> <ref> [<ref>...] +'git http-push' [--all] [--dry-run] [--force] [--verbose] <URL> <ref> [<ref>...] DESCRIPTION ----------- @@ -63,16 +63,15 @@ 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>'. -Each pattern pair consists of the source side (before the colon) -and the destination side (after the colon). The ref to be -pushed is determined by finding a match that matches the source -side, and where it is pushed is determined by using the -destination side. +Each pattern pair '<src>:<dst>' consists of the source side (before +the colon) and the destination side (after the colon). The ref to be +pushed is determined by finding a match that matches the source side, +and where it is pushed is determined by using the destination side. - - It is an error if <src> does not match exactly one of the + - It is an error if '<src>' does not match exactly one of the local refs. - - If <dst> does not match any remote ref, either + - If '<dst>' does not match any remote ref, either * it has to start with "refs/"; <dst> is used as the destination literally in this case. diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt index 1f1e359225..4e71c256ec 100644 --- a/Documentation/git-index-pack.txt +++ b/Documentation/git-index-pack.txt @@ -122,6 +122,14 @@ This option cannot be used with --stdin. + include::object-format-disclaimer.txt[] +--promisor[=<message>]:: + Before committing the pack-index, create a .promisor file for this + pack. Particularly helpful when writing a promisor pack with --fix-thin + since the name of the pack is not final until the pack has been fully + written. If a `<message>` is provided, then that content will be + written to the .promisor file for future reference. See + link:technical/partial-clone.html[partial clone] for more information. + NOTES ----- diff --git a/Documentation/git-init-db.txt b/Documentation/git-init-db.txt index 648a6cd78a..18bf1a3c8c 100644 --- a/Documentation/git-init-db.txt +++ b/Documentation/git-init-db.txt @@ -9,7 +9,7 @@ git-init-db - Creates an empty Git repository SYNOPSIS -------- [verse] -'git init-db' [-q | --quiet] [--bare] [--template=<template_directory>] [--separate-git-dir <git dir>] [--shared[=<permissions>]] +'git init-db' [-q | --quiet] [--bare] [--template=<template-directory>] [--separate-git-dir <git-dir>] [--shared[=<permissions>]] DESCRIPTION diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt index b611d80697..ad921fe782 100644 --- a/Documentation/git-init.txt +++ b/Documentation/git-init.txt @@ -9,10 +9,10 @@ git-init - Create an empty Git repository or reinitialize an existing one SYNOPSIS -------- [verse] -'git init' [-q | --quiet] [--bare] [--template=<template_directory>] - [--separate-git-dir <git dir>] [--object-format=<format>] +'git init' [-q | --quiet] [--bare] [--template=<template-directory>] + [--separate-git-dir <git-dir>] [--object-format=<format>] [-b <branch-name> | --initial-branch=<branch-name>] - [--shared[=<permissions>]] [directory] + [--shared[=<permissions>]] [<directory>] DESCRIPTION @@ -57,12 +57,12 @@ values are 'sha1' and (if enabled) 'sha256'. 'sha1' is the default. + include::object-format-disclaimer.txt[] ---template=<template_directory>:: +--template=<template-directory>:: Specify the directory from which templates will be used. (See the "TEMPLATE DIRECTORY" section below.) ---separate-git-dir=<git dir>:: +--separate-git-dir=<git-dir>:: Instead of initializing the repository as a directory to either `$GIT_DIR` or `./.git/`, create a text file there containing the path to the actual @@ -79,7 +79,7 @@ repository. If not specified, fall back to the default name (currently `master`, but this is subject to change in the future; the name can be customized via the `init.defaultBranch` configuration variable). ---shared[=(false|true|umask|group|all|world|everybody|0xxx)]:: +--shared[=(false|true|umask|group|all|world|everybody|<perm>)]:: Specify that the Git repository is to be shared amongst several users. This allows users belonging to the same group to push into that @@ -110,13 +110,16 @@ the repository permissions. Same as 'group', but make the repository readable by all users. -'0xxx':: +'<perm>':: -'0xxx' is an octal number and each file will have mode '0xxx'. '0xxx' will -override users' umask(2) value (and not only loosen permissions as 'group' and -'all' does). '0640' will create a repository which is group-readable, but not -group-writable or accessible to others. '0660' will create a repo that is -readable and writable to the current user and group, but inaccessible to others. +'<perm>' is a 3-digit octal number prefixed with `0` and each file +will have mode '<perm>'. '<perm>' will override users' umask(2) +value (and not only loosen permissions as 'group' and 'all' +does). '0640' will create a repository which is group-readable, but +not group-writable or accessible to others. '0660' will create a repo +that is readable and writable to the current user and group, but +inaccessible to others (directories and executable files get their +`x` bit from the `r` bit for corresponding classes of users). -- By default, the configuration flag `receive.denyNonFastForwards` is enabled diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 0498e7bacb..20e87cecf4 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -9,7 +9,7 @@ git-log - Show commit logs SYNOPSIS -------- [verse] -'git log' [<options>] [<revision range>] [[--] <path>...] +'git log' [<options>] [<revision-range>] [[--] <path>...] DESCRIPTION ----------- @@ -81,13 +81,13 @@ produced by `--stat`, etc. include::line-range-options.txt[] -<revision range>:: +<revision-range>:: Show only commits in the specified revision range. When no - <revision range> is specified, it defaults to `HEAD` (i.e. the + <revision-range> is specified, it defaults to `HEAD` (i.e. the whole history leading to the current commit). `origin..HEAD` specifies all the commits reachable from the current commit (i.e. `HEAD`), but not from `origin`. For a complete list of - ways to spell <revision range>, see the 'Specifying Ranges' + ways to spell <revision-range>, see the 'Specifying Ranges' section of linkgit:gitrevisions[7]. [--] <path>...:: diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 6d11ab506b..0dabf3f0dd 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -10,9 +10,9 @@ SYNOPSIS -------- [verse] 'git ls-files' [-z] [-t] [-v] [-f] - (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])* - (-[c|d|o|i|s|u|k|m])* - [--eol] + [-c|--cached] [-d|--deleted] [-o|--others] [-i|--|ignored] + [-s|--stage] [-u|--unmerged] [-k|--|killed] [-m|--modified] + [--directory [--no-empty-directory]] [--eol] [--deduplicate] [-x <pattern>|--exclude=<pattern>] [-X <file>|--exclude-from=<file>] @@ -156,7 +156,7 @@ a space) at the start of each line: --recurse-submodules:: Recursively calls ls-files on each active submodule in the repository. - Currently there is only support for the --cached mode. + Currently there is only support for the --cached and --stage modes. --abbrev[=<n>]:: Instead of showing the full 40-byte hexadecimal object @@ -187,6 +187,11 @@ Both the <eolinfo> in the index ("i/<eolinfo>") and in the working tree ("w/<eolinfo>") are shown for regular files, followed by the ("attr/<eolattr>"). +--sparse:: + If the index is sparse, show the sparse directories without expanding + to the contained files. Sparse directories will be shown with a + trailing slash, such as "x/" for a sparse directory "x". + \--:: Do not interpret any more arguments as options. diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt index db02d6d79a..43aebb9938 100644 --- a/Documentation/git-ls-tree.txt +++ b/Documentation/git-ls-tree.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git ls-tree' [-d] [-r] [-t] [-l] [-z] - [--name-only] [--name-status] [--full-name] [--full-tree] [--abbrev[=<n>]] + [--name-only] [--name-status] [--object-only] [--full-name] [--full-tree] [--abbrev[=<n>]] [--format=<format>] <tree-ish> [<path>...] DESCRIPTION @@ -59,6 +59,15 @@ OPTIONS --name-only:: --name-status:: List only filenames (instead of the "long" output), one per line. + Cannot be combined with `--object-only`. + +--object-only:: + List only names of the objects, one per line. Cannot be combined + with `--name-only` or `--name-status`. + This is equivalent to specifying `--format='%(objectname)'`, but + for both this option and that exact format the command takes a + hand-optimized codepath instead of going through the generic + formatting mechanism. --abbrev[=<n>]:: Instead of showing the full 40-byte hexadecimal object @@ -74,6 +83,16 @@ OPTIONS Do not limit the listing to the current working directory. Implies --full-name. +--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). + When specified, `--format` cannot be combined with other + format-altering options, including `--long`, `--name-only` + and `--object-only`. + [<path>...]:: When paths are given, show them (note that this isn't really raw pathnames, but rather a list of patterns to match). Otherwise @@ -82,16 +101,29 @@ OPTIONS Output Format ------------- - <mode> SP <type> SP <object> TAB <file> + +The output format of `ls-tree` is determined by either the `--format` +option, or other format-altering options such as `--name-only` etc. +(see `--format` above). + +The use of certain `--format` directives is equivalent to using those +options, but invoking the full formatting machinery can be slower than +using an appropriate formatting option. + +In cases where the `--format` would exactly map to an existing option +`ls-tree` will use the appropriate faster path. Thus the default format +is equivalent to: + + %(objectmode) %(objecttype) %(objectname)%x09%(path) This output format is compatible with what `--index-info --stdin` of 'git update-index' expects. When the `-l` option is used, format changes to - <mode> SP <type> SP <object> SP <object size> TAB <file> + %(objectmode) %(objecttype) %(objectname) %(objectsize:padded)%x09%(path) -Object size identified by <object> is given in bytes, and right-justified +Object size identified by <objectname> is given in bytes, and right-justified with minimum width of 7 characters. Object size is given only for blobs (file) entries; for other entries `-` character is used in place of size. @@ -100,6 +132,34 @@ quoted as explained for the configuration variable `core.quotePath` (see linkgit:git-config[1]). Using `-z` the filename is output verbatim and the line is terminated by a NUL byte. +Customized format: + +It is possible to print in a custom format by using the `--format` option, +which is able to interpolate different fields using a `%(fieldname)` notation. +For example, if you only care about the "objectname" and "path" fields, you +can execute with a specific "--format" like + + git ls-tree --format='%(objectname) %(path)' <tree-ish> + +FIELD NAMES +----------- + +Various values from structured fields can be used to interpolate +into the resulting output. For each outputing line, the following +names can be used: + +objectmode:: + The mode of the object. +objecttype:: + The type of the object (`blob` or `tree`). +objectname:: + The name of the object. +objectsize[:padded]:: + The size of the object ("-" if it's a tree). + It also supports a padded format of size with "%(size:padded)". +path:: + The pathname of the object. + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-maintenance.txt b/Documentation/git-maintenance.txt index e2cfb68ab5..e56bad28c6 100644 --- a/Documentation/git-maintenance.txt +++ b/Documentation/git-maintenance.txt @@ -10,6 +10,8 @@ SYNOPSIS -------- [verse] 'git maintenance' run [<options>] +'git maintenance' start [--scheduler=<scheduler>] +'git maintenance' (stop|register|unregister) DESCRIPTION @@ -29,6 +31,24 @@ Git repository. SUBCOMMANDS ----------- +run:: + Run one or more maintenance tasks. If one or more `--task` options + are specified, then those tasks are run in that order. Otherwise, + the tasks are determined by which `maintenance.<task>.enabled` + config options are true. By default, only `maintenance.gc.enabled` + is true. + +start:: + Start running maintenance on the current repository. This performs + the same config updates as the `register` subcommand, then updates + the background scheduler to run `git maintenance run --scheduled` + on an hourly basis. + +stop:: + Halt the background maintenance schedule. The current repository + is not removed from the list of maintained repositories, in case + the background maintenance is restarted later. + register:: Initialize Git config values so any scheduled maintenance will start running on this repository. This adds the repository to the @@ -55,24 +75,6 @@ task: setting `maintenance.auto = false` in the current repository. This config setting will remain after a `git maintenance unregister` command. -run:: - Run one or more maintenance tasks. If one or more `--task` options - are specified, then those tasks are run in that order. Otherwise, - the tasks are determined by which `maintenance.<task>.enabled` - config options are true. By default, only `maintenance.gc.enabled` - is true. - -start:: - Start running maintenance on the current repository. This performs - the same config updates as the `register` subcommand, then updates - the background scheduler to run `git maintenance run --scheduled` - on an hourly basis. - -stop:: - Halt the background maintenance schedule. The current repository - is not removed from the list of maintained repositories, in case - the background maintenance is restarted later. - unregister:: Remove the current repository from background maintenance. This only removes the repository from the configured list. It does not diff --git a/Documentation/git-merge-file.txt b/Documentation/git-merge-file.txt index f856032613..7e9093fab6 100644 --- a/Documentation/git-merge-file.txt +++ b/Documentation/git-merge-file.txt @@ -70,6 +70,9 @@ OPTIONS --diff3:: Show conflicts in "diff3" style. +--zdiff3:: + Show conflicts in "zdiff3" style. + --ours:: --theirs:: --union:: diff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt index 2ab84a91e5..eea56b3154 100644 --- a/Documentation/git-merge-index.txt +++ b/Documentation/git-merge-index.txt @@ -9,7 +9,7 @@ git-merge-index - Run a merge for files needing merging SYNOPSIS -------- [verse] -'git merge-index' [-o] [-q] <merge-program> (-a | [--] <file>*) +'git merge-index' [-o] [-q] <merge-program> (-a | ( [--] <file>...) ) DESCRIPTION ----------- diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index e4f3352eb5..3125473cc1 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -12,7 +12,8 @@ SYNOPSIS 'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit] [--no-verify] [-s <strategy>] [-X <strategy-option>] [-S[<keyid>]] [--[no-]allow-unrelated-histories] - [--[no-]rerere-autoupdate] [-m <msg>] [-F <file>] [<commit>...] + [--[no-]rerere-autoupdate] [-m <msg>] [-F <file>] + [--into-name <branch>] [<commit>...] 'git merge' (--continue | --abort | --quit) DESCRIPTION @@ -76,6 +77,11 @@ The 'git fmt-merge-msg' command can be used to give a good default for automated 'git merge' invocations. The automated message can include the branch description. +--into-name <branch>:: + Prepare the default merge message as if merging to the branch + `<branch>`, instead of the name of the real branch to which + the merge is made. + -F <file>:: --file=<file>:: Read the commit message to be used for the merge commit (in @@ -240,7 +246,8 @@ from the RCS suite to present such a conflicted hunk, like this: ------------ Here are lines that are either unchanged from the common -ancestor, or cleanly resolved because only one side changed. +ancestor, or cleanly resolved because only one side changed, +or cleanly resolved because both sides changed the same way. <<<<<<< yours:sample.txt Conflict resolution is hard; let's go shopping. @@ -261,16 +268,37 @@ side wants to say it is hard and you'd prefer to go shopping, while the other side wants to claim it is easy. An alternative style can be used by setting the "merge.conflictStyle" -configuration variable to "diff3". In "diff3" style, the above conflict -may look like this: +configuration variable to either "diff3" or "zdiff3". In "diff3" +style, the above conflict may look like this: + +------------ +Here are lines that are either unchanged from the common +ancestor, or cleanly resolved because only one side changed, +<<<<<<< yours:sample.txt +or cleanly resolved because both sides changed the same way. +Conflict resolution is hard; +let's go shopping. +||||||| base:sample.txt +or cleanly resolved because both sides changed identically. +Conflict resolution is hard. +======= +or cleanly resolved because both sides changed the same way. +Git makes conflict resolution easy. +>>>>>>> theirs:sample.txt +And here is another line that is cleanly resolved or unmodified. +------------ + +while in "zdiff3" style, it may look like this: ------------ Here are lines that are either unchanged from the common -ancestor, or cleanly resolved because only one side changed. +ancestor, or cleanly resolved because only one side changed, +or cleanly resolved because both sides changed the same way. <<<<<<< yours:sample.txt Conflict resolution is hard; let's go shopping. -||||||| +||||||| base:sample.txt +or cleanly resolved because both sides changed identically. Conflict resolution is hard. ======= Git makes conflict resolution easy. diff --git a/Documentation/git-mktree.txt b/Documentation/git-mktree.txt index 27fe2b32e1..76b44f4da1 100644 --- a/Documentation/git-mktree.txt +++ b/Documentation/git-mktree.txt @@ -31,7 +31,7 @@ OPTIONS --batch:: Allow building of more than one tree object before exiting. Each - tree is separated by as single blank line. The final new-line is + tree is separated by a single blank line. The final new-line is optional. Note - if the `-z` option is used, lines are terminated with NUL. diff --git a/Documentation/git-name-rev.txt b/Documentation/git-name-rev.txt index 5cb0eb0855..ec8a27ce8b 100644 --- a/Documentation/git-name-rev.txt +++ b/Documentation/git-name-rev.txt @@ -42,11 +42,37 @@ OPTIONS --all:: List all commits reachable from all refs ---stdin:: +--annotate-stdin:: Transform stdin by substituting all the 40-character SHA-1 hexes (say $hex) with "$hex ($rev_name)". When used with --name-only, substitute with "$rev_name", omitting $hex - altogether. Intended for the scripter's use. + altogether. ++ +For example: ++ +----------- +$ cat sample.txt + +An abbreviated revision 2ae0a9cb82 will not be substituted. +The full name after substitution is 2ae0a9cb8298185a94e5998086f380a355dd8907, +while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad + +$ git name-rev --annotate-stdin <sample.txt + +An abbreviated revision 2ae0a9cb82 will not be substituted. +The full name after substitution is 2ae0a9cb8298185a94e5998086f380a355dd8907 (master), +while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad + +$ git name-rev --name-only --annotate-stdin <sample.txt + +An abbreviated revision 2ae0a9cb82 will not be substituted. +The full name after substitution is master, +while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad +----------- + +--stdin:: + This option is deprecated in favor of 'git name-rev --annotate-stdin'. + They are functionally equivalent. --name-only:: Instead of printing both the SHA-1 and the name, print only diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt index 38e5257b2a..e21fcd8f71 100644 --- a/Documentation/git-p4.txt +++ b/Documentation/git-p4.txt @@ -9,10 +9,10 @@ git-p4 - Import from and submit to Perforce repositories SYNOPSIS -------- [verse] -'git p4 clone' [<sync options>] [<clone options>] <p4 depot path>... -'git p4 sync' [<sync options>] [<p4 depot path>...] +'git p4 clone' [<sync-options>] [<clone-options>] <p4-depot-path>... +'git p4 sync' [<sync-options>] [<p4-depot-path>...] 'git p4 rebase' -'git p4 submit' [<submit options>] [<master branch name>] +'git p4 submit' [<submit-options>] [<master-branch-name>] DESCRIPTION @@ -361,7 +361,7 @@ These options can be used to modify 'git p4 submit' behavior. p4/master. See the "Sync options" section above for more information. ---commit <sha1>|<sha1..sha1>:: +--commit (<sha1>|<sha1>..<sha1>):: Submit only the specified commit or range of commits, instead of the full list of changes that are in the current Git branch. diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index dbfd1f9017..f8344e1e5b 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -13,8 +13,8 @@ SYNOPSIS [--no-reuse-delta] [--delta-base-offset] [--non-empty] [--local] [--incremental] [--window=<n>] [--depth=<n>] [--revs [--unpacked | --all]] [--keep-pack=<pack-name>] - [--stdout [--filter=<filter-spec>] | base-name] - [--shallow] [--keep-true-parents] [--[no-]sparse] < object-list + [--stdout [--filter=<filter-spec>] | <base-name>] + [--shallow] [--keep-true-parents] [--[no-]sparse] < <object-list> DESCRIPTION diff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt index f2869da572..ee7034b5e5 100644 --- a/Documentation/git-pack-redundant.txt +++ b/Documentation/git-pack-redundant.txt @@ -9,7 +9,7 @@ git-pack-redundant - Find redundant pack files SYNOPSIS -------- [verse] -'git pack-redundant' [ --verbose ] [ --alt-odb ] < --all | .pack filename ... > +'git pack-redundant' [ --verbose ] [ --alt-odb ] ( --all | <pack-filename>... ) DESCRIPTION ----------- diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 8c3aceb832..a5356a230b 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -375,9 +375,14 @@ have finished your work-in-progress), attempt the merge again. SPARSE CHECKOUT --------------- +Note: The `update-index` and `read-tree` primitives for supporting the +skip-worktree bit predated the introduction of +linkgit:git-sparse-checkout[1]. Users are encouraged to use +`sparse-checkout` in preference to these low-level primitives. + "Sparse checkout" allows populating the working directory sparsely. -It uses the skip-worktree bit (see linkgit:git-update-index[1]) to tell -Git whether a file in the working directory is worth looking at. +It uses the skip-worktree bit (see linkgit:git-update-index[1]) to +tell Git whether a file in the working directory is worth looking at. 'git read-tree' and other merge-based commands ('git merge', 'git checkout'...) can help maintaining the skip-worktree bitmap and working @@ -385,7 +390,8 @@ directory update. `$GIT_DIR/info/sparse-checkout` is used to define the skip-worktree reference bitmap. When 'git read-tree' needs to update the working directory, it resets the skip-worktree bit in the index based on this file, which uses the same syntax as .gitignore files. -If an entry matches a pattern in this file, skip-worktree will not be +If an entry matches a pattern in this file, or the entry corresponds to +a file present in the working tree, then skip-worktree will not be set on that entry. Otherwise, skip-worktree will be set. Then it compares the new skip-worktree value with the previous one. If @@ -420,8 +426,8 @@ support. SEE ALSO -------- -linkgit:git-write-tree[1]; linkgit:git-ls-files[1]; -linkgit:gitignore[5]; linkgit:git-sparse-checkout[1]; +linkgit:git-write-tree[1], linkgit:git-ls-files[1], +linkgit:gitignore[5], linkgit:git-sparse-checkout[1] GIT --- diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index a1af21fcef..9da4647061 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -714,9 +714,9 @@ information about the rebased commits and their parents (and instead generates new fake commits based off limited information in the generated patches), those commits cannot be identified; instead it has to fall back to a commit summary. Also, when merge.conflictStyle is -set to diff3, the apply backend will use "constructed merge base" to -label the content from the merge base, and thus provide no information -about the merge base commit whatsoever. +set to diff3 or zdiff3, the apply backend will use "constructed merge +base" to label the content from the merge base, and thus provide no +information about the merge base commit whatsoever. The merge backend works with the full commits on both sides of history and thus has no such limitations. diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt index ff487ff77d..5ced7ad4f8 100644 --- a/Documentation/git-reflog.txt +++ b/Documentation/git-reflog.txt @@ -17,12 +17,12 @@ The command takes various subcommands, and different options depending on the subcommand: [verse] -'git reflog' ['show'] [log-options] [<ref>] +'git reflog' ['show'] [<log-options>] [<ref>] 'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>] [--rewrite] [--updateref] [--stale-fix] [--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...] 'git reflog delete' [--rewrite] [--updateref] - [--dry-run | -n] [--verbose] ref@\{specifier\}... + [--dry-run | -n] [--verbose] <ref>@\{<specifier>\}... 'git reflog exists' <ref> Reference logs, or "reflogs", record when the tips of branches and diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index 31c29c9b31..cde9614e36 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -10,15 +10,15 @@ SYNOPSIS -------- [verse] 'git remote' [-v | --verbose] -'git remote add' [-t <branch>] [-m <master>] [-f] [--[no-]tags] [--mirror=(fetch|push)] <name> <url> -'git remote rename' <old> <new> +'git remote add' [-t <branch>] [-m <master>] [-f] [--[no-]tags] [--mirror=(fetch|push)] <name> <URL> +'git remote rename' [--[no-]progress] <old> <new> 'git remote remove' <name> 'git remote set-head' <name> (-a | --auto | -d | --delete | <branch>) 'git remote set-branches' [--add] <name> <branch>... 'git remote get-url' [--push] [--all] <name> 'git remote set-url' [--push] <name> <newurl> [<oldurl>] 'git remote set-url --add' [--push] <name> <newurl> -'git remote set-url --delete' [--push] <name> <url> +'git remote set-url --delete' [--push] <name> <URL> 'git remote' [-v | --verbose] 'show' [-n] <name>... 'git remote prune' [-n | --dry-run] <name>... 'git remote' [-v | --verbose] 'update' [-p | --prune] [(<group> | <remote>)...] @@ -47,7 +47,7 @@ subcommands are available to perform operations on the remotes. 'add':: Add a remote named <name> for the repository at -<url>. The command `git fetch <name>` can then be used to create and +<URL>. The command `git fetch <name>` can then be used to create and update remote-tracking branches <name>/<branch>. + With `-f` option, `git fetch <name>` is run immediately after @@ -152,7 +152,7 @@ With `--push`, push URLs are manipulated instead of fetch URLs. With `--add`, instead of changing existing URLs, new URL is added. + With `--delete`, instead of changing existing URLs, all URLs matching -regex <url> are deleted for remote <name>. Trying to delete all +regex <URL> are deleted for remote <name>. Trying to delete all non-push URLs is an error. + Note that the push URL and the fetch URL, even though they can diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt index 7183fb498f..ee30edc178 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -76,8 +76,9 @@ to the new separate pack will be written. linkgit:git-pack-objects[1]. -q:: - Pass the `-q` option to 'git pack-objects'. See - linkgit:git-pack-objects[1]. +--quiet:: + Show no progress over the standard error stream and pass the `-q` + option to 'git pack-objects'. See linkgit:git-pack-objects[1]. -n:: Do not update the server information with diff --git a/Documentation/git-request-pull.txt b/Documentation/git-request-pull.txt index 4d4392d0f8..fa5a426709 100644 --- a/Documentation/git-request-pull.txt +++ b/Documentation/git-request-pull.txt @@ -8,7 +8,7 @@ git-request-pull - Generates a summary of pending changes SYNOPSIS -------- [verse] -'git request-pull' [-p] <start> <url> [<end>] +'git request-pull' [-p] <start> <URL> [<end>] DESCRIPTION ----------- @@ -21,7 +21,7 @@ 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 since that commit, up to the commit named by `<end>`, by visiting -the repository named by `<url>`. +the repository named by `<URL>`. OPTIONS @@ -33,14 +33,14 @@ OPTIONS Commit to start at. This names a commit that is already in the upstream history. -<url>:: +<URL>:: The repository URL to be pulled from. <end>:: Commit to end at (defaults to HEAD). This names the commit at the tip of the history you are asking to be pulled. + -When the repository named by `<url>` has the commit at a tip of a +When the repository named by `<URL>` has the commit at a tip of a ref that is different from the ref you have locally, you can use the `<local>:<remote>` syntax, to have its local name, a colon `:`, and its remote name. diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 6f7685f53d..01cb4c9b9c 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -105,10 +105,11 @@ OPTIONS -q:: --quiet:: ---no-quiet:: - Be quiet, only report errors. The default behavior is set by the - `reset.quiet` config option. `--quiet` and `--no-quiet` will - override the default behavior. + Be quiet, only report errors. + +--refresh:: +--no-refresh:: + Refresh the index after a mixed reset. Enabled by default. --pathspec-from-file=<file>:: Pathspec is passed in `<file>` instead of commandline args. If diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt index 55bde91ef9..5964810caa 100644 --- a/Documentation/git-restore.txt +++ b/Documentation/git-restore.txt @@ -92,8 +92,7 @@ in linkgit:git-checkout[1] for details. The same as `--merge` option above, but changes the way the conflicting hunks are presented, overriding the `merge.conflictStyle` configuration variable. Possible values - are "merge" (default) and "diff3" (in addition to what is - shown by "merge" style, shows the original contents). + are "merge" (default), "diff3", and "zdiff3". --ignore-unmerged:: When restoring files on the working tree from the index, do diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt index c9c7f3065c..f64e77047b 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -8,7 +8,7 @@ git-shortlog - Summarize 'git log' output SYNOPSIS -------- [verse] -'git shortlog' [<options>] [<revision range>] [[--] <path>...] +'git shortlog' [<options>] [<revision-range>] [[--] <path>...] git log --pretty=short | 'git shortlog' [<options>] DESCRIPTION @@ -89,13 +89,13 @@ counts both authors and co-authors. If width is `0` (zero) then indent the lines of the output without wrapping them. -<revision range>:: +<revision-range>:: Show only commits in the specified revision range. When no - <revision range> is specified, it defaults to `HEAD` (i.e. the + <revision-range> is specified, it defaults to `HEAD` (i.e. the whole history leading to the current commit). `origin..HEAD` specifies all the commits reachable from the current commit (i.e. `HEAD`), but not from `origin`. For a complete list of - ways to spell <revision range>, see the "Specifying Ranges" + ways to spell <revision-range>, see the "Specifying Ranges" section of linkgit:gitrevisions[7]. [--] <path>...:: diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt index 42056ee9ff..88e55f432f 100644 --- a/Documentation/git-sparse-checkout.txt +++ b/Documentation/git-sparse-checkout.txt @@ -3,22 +3,32 @@ git-sparse-checkout(1) NAME ---- -git-sparse-checkout - Initialize and modify the sparse-checkout -configuration, which reduces the checkout to a set of paths -given by a list of patterns. +git-sparse-checkout - Reduce your working tree to a subset of tracked files SYNOPSIS -------- [verse] -'git sparse-checkout <subcommand> [options]' +'git sparse-checkout <subcommand> [<options>]' DESCRIPTION ----------- -Initialize and modify the sparse-checkout configuration, which reduces -the checkout to a set of paths given by a list of patterns. +This command is used to create sparse checkouts, which means that it +changes the working tree from having all tracked files present, to only +have a subset of them. It can also switch which subset of files are +present, or undo and go back to having all tracked files present in the +working copy. + +The subset of files is chosen by providing a list of directories in +cone mode (which is recommended), or by providing a list of patterns +in non-cone mode. + +When in a sparse-checkout, other Git commands behave a bit differently. +For example, switching branches will not update paths outside the +sparse-checkout directories/patterns, and `git commit -a` will not record +paths outside the sparse-checkout directories/patterns as deleted. THIS COMMAND IS EXPERIMENTAL. ITS BEHAVIOR, AND THE BEHAVIOR OF OTHER COMMANDS IN THE PRESENCE OF SPARSE-CHECKOUTS, WILL LIKELY CHANGE IN @@ -28,30 +38,52 @@ THE FUTURE. COMMANDS -------- 'list':: - Describe the patterns in the sparse-checkout file. + Describe the directories or patterns in the sparse-checkout file. -'init':: - Enable the `core.sparseCheckout` setting. If the - sparse-checkout file does not exist, then populate it with - patterns that match every file in the root directory and - no other directories, then will remove all directories tracked - by Git. Add patterns to the sparse-checkout file to - repopulate the working directory. +'set':: + Enable the necessary sparse-checkout config settings + (`core.sparseCheckout`, `core.sparseCheckoutCone`, and + `index.sparse`) if they are not already set to the desired values, + and write a set of patterns to the sparse-checkout file from the + list of arguments following the 'set' subcommand. Update the + working directory to match the new patterns. + -To avoid interfering with other worktrees, it first enables the -`extensions.worktreeConfig` setting and makes sure to set the -`core.sparseCheckout` setting in the worktree-specific config file. +To ensure that adjusting the sparse-checkout settings within a worktree +does not alter the sparse-checkout settings in other worktrees, the 'set' +subcommand will upgrade your repository config to use worktree-specific +config if not already present. The sparsity defined by the arguments to +the 'set' subcommand are stored in the worktree-specific sparse-checkout +file. See linkgit:git-worktree[1] and the documentation of +`extensions.worktreeConfig` in linkgit:git-config[1] for more details. + -When `--cone` is provided, the `core.sparseCheckoutCone` setting is -also set, allowing for better performance with a limited set of -patterns (see 'CONE PATTERN SET' below). +When the `--stdin` option is provided, the directories or patterns are +read from standard in as a newline-delimited list instead of from the +arguments. + -Use the `--[no-]sparse-index` option to toggle the use of the sparse -index format. This reduces the size of the index to be more closely -aligned with your sparse-checkout definition. This can have significant -performance advantages for commands such as `git status` or `git add`. -This feature is still experimental. Some commands might be slower with -a sparse index until they are properly integrated with the feature. +When `--cone` is passed or `core.sparseCheckoutCone` is enabled, the +input list is considered a list of directories. This allows for +better performance with a limited set of patterns (see 'CONE PATTERN +SET' below). The input format matches the output of `git ls-tree +--name-only`. This includes interpreting pathnames that begin with a +double quote (") as C-style quoted strings. Note that the set command +will write patterns to the sparse-checkout file to include all files +contained in those directories (recursively) as well as files that are +siblings of ancestor directories. This may become the default in the +future; --no-cone can be passed to request non-cone mode. ++ +When `--no-cone` is passed or `core.sparseCheckoutCone` is not enabled, +the input list is considered a list of patterns. This mode is harder +to use and less performant, and is thus not recommended. See the +"Sparse Checkout" section of linkgit:git-read-tree[1] and the "Pattern +Set" sections below for more details. ++ +Use the `--[no-]sparse-index` option to use a sparse index (the +default is to not use it). A sparse index reduces the size of the +index to be more closely aligned with your sparse-checkout +definition. This can have significant performance advantages for +commands such as `git status` or `git add`. This feature is still +experimental. Some commands might be slower with a sparse index until +they are properly integrated with the feature. + **WARNING:** Using a sparse index requires modifying the index in a way that is not completely understood by external tools. If you have trouble @@ -60,29 +92,11 @@ to rewrite your index to not be sparse. Older versions of Git will not understand the sparse directory entries index extension and may fail to interact with your repository until it is disabled. -'set':: - Write a set of patterns to the sparse-checkout file, as given as - a list of arguments following the 'set' subcommand. Update the - working directory to match the new patterns. Enable the - core.sparseCheckout config setting if it is not already enabled. -+ -When the `--stdin` option is provided, the patterns are read from -standard in as a newline-delimited list instead of from the arguments. -+ -When `core.sparseCheckoutCone` is enabled, the input list is considered a -list of directories instead of sparse-checkout patterns. The command writes -patterns to the sparse-checkout file to include all files contained in those -directories (recursively) as well as files that are siblings of ancestor -directories. The input format matches the output of `git ls-tree --name-only`. -This includes interpreting pathnames that begin with a double quote (") as -C-style quoted strings. - 'add':: - Update the sparse-checkout file to include additional patterns. - By default, these patterns are read from the command-line arguments, - but they can be read from stdin using the `--stdin` option. When - `core.sparseCheckoutCone` is enabled, the given patterns are interpreted - as directory names as in the 'set' subcommand. + Update the sparse-checkout file to include additional directories + (in cone mode) or patterns (in non-cone mode). By default, these + directories or patterns are read from the command-line arguments, + but they can be read from stdin using the `--stdin` option. 'reapply':: Reapply the sparsity pattern rules to paths in the working tree. @@ -93,23 +107,47 @@ C-style quoted strings. cases, it can make sense to run `git sparse-checkout reapply` later after cleaning up affected paths (e.g. resolving conflicts, undoing or committing changes, etc.). ++ +The `reapply` command can also take `--[no-]cone` and `--[no-]sparse-index` +flags, with the same meaning as the flags from the `set` command, in order +to change which sparsity mode you are using without needing to also respecify +all sparsity paths. 'disable':: Disable the `core.sparseCheckout` config setting, and restore the - working directory to include all files. Leaves the sparse-checkout - file intact so a later 'git sparse-checkout init' command may - return the working directory to the same state. + working directory to include all files. + +'init':: + Deprecated command that behaves like `set` with no specified paths. + May be removed in the future. ++ +Historically, `set` did not handle all the necessary config settings, +which meant that both `init` and `set` had to be called. Invoking +both meant the `init` step would first remove nearly all tracked files +(and in cone mode, ignored files too), then the `set` step would add +many of the tracked files (but not ignored files) back. In addition +to the lost files, the performance and UI of this combination was +poor. ++ +Also, historically, `init` would not actually initialize the +sparse-checkout file if it already existed. This meant it was +possible to return to a sparse-checkout without remembering which +paths to pass to a subsequent 'set' or 'add' command. However, +`--cone` and `--sparse-index` options would not be remembered across +the disable command, so the easy restore of calling a plain `init` +decreased in utility. SPARSE CHECKOUT --------------- -"Sparse checkout" allows populating the working directory sparsely. -It uses the skip-worktree bit (see linkgit:git-update-index[1]) to tell -Git whether a file in the working directory is worth looking at. If -the skip-worktree bit is set, then the file is ignored in the working -directory. Git will not populate the contents of those files, which -makes a sparse checkout helpful when working in a repository with many -files, but only a few are important to the current user. +"Sparse checkout" allows populating the working directory sparsely. It +uses the skip-worktree bit (see linkgit:git-update-index[1]) to tell Git +whether a file in the working directory is worth looking at. If the +skip-worktree bit is set, and the file is not present in the working tree, +then its absence is ignored. Git will avoid populating the contents of +those files, which makes a sparse checkout helpful when working in a +repository with many files, but only a few are important to the current +user. The `$GIT_DIR/info/sparse-checkout` file is used to define the skip-worktree reference bitmap. When Git updates the working @@ -117,10 +155,8 @@ directory, it updates the skip-worktree bits in the index based on this file. The files matching the patterns in the file will appear in the working directory, and the rest will not. -To enable the sparse-checkout feature, run `git sparse-checkout init` to -initialize a simple sparse-checkout file and enable the `core.sparseCheckout` -config setting. Then, run `git sparse-checkout set` to modify the patterns in -the sparse-checkout file. +To enable the sparse-checkout feature, run `git sparse-checkout set` to +set the patterns you want to use. To repopulate the working directory with all files, use the `git sparse-checkout disable` command. diff --git a/Documentation/git-stage.txt b/Documentation/git-stage.txt index 25bcda936d..2f6aaa75b9 100644 --- a/Documentation/git-stage.txt +++ b/Documentation/git-stage.txt @@ -9,7 +9,7 @@ git-stage - Add file contents to the staging area SYNOPSIS -------- [verse] -'git stage' args... +'git stage' <arg>... DESCRIPTION diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 7e5f995f77..4d3ab6b9f9 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -133,7 +133,7 @@ If you really want to remove a submodule from the repository and commit that use linkgit:git-rm[1] instead. See linkgit:gitsubmodules[7] for removal options. -update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--depth <depth>] [--recursive] [--jobs <n>] [--[no-]single-branch] [--] [<path>...]:: +update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--depth <depth>] [--recursive] [--jobs <n>] [--[no-]single-branch] [--filter <filter spec>] [--] [<path>...]:: + -- Update the registered submodules to match what the superproject @@ -177,6 +177,10 @@ submodule with the `--init` option. If `--recursive` is specified, this command will recurse into the registered submodules, and update any nested submodules within. + +If `--filter <filter spec>` is specified, the given partial clone filter will be +applied to the submodule. See linkgit:git-rev-list[1] for details on filter +specifications. -- set-branch (-b|--branch) <branch> [--] <path>:: set-branch (-d|--default) [--] <path>:: diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 222b556d7a..4e92308e85 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -575,7 +575,7 @@ OPTIONS ------- --shared[=(false|true|umask|group|all|world|everybody)]:: ---template=<template_directory>:: +--template=<template-directory>:: Only used with the 'init' command. These are passed directly to 'git init'. diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt index 96dc036ea5..bbcbdceb45 100644 --- a/Documentation/git-switch.txt +++ b/Documentation/git-switch.txt @@ -137,8 +137,7 @@ should result in deletion of the path). The same as `--merge` option above, but changes the way the conflicting hunks are presented, overriding the `merge.conflictStyle` configuration variable. Possible values are - "merge" (default) and "diff3" (in addition to what is shown by - "merge" style, shows the original contents). + "merge" (default), "diff3", and "zdiff3". -q:: --quiet:: diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index 2853f168d9..568dbfe76b 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -351,6 +351,10 @@ unchanged". Note that "assume unchanged" bit is *not* set if the index (use `git update-index --really-refresh` if you want to mark them as "assume unchanged"). +Sometimes users confuse the assume-unchanged bit with the +skip-worktree bit. See the final paragraph in the "Skip-worktree bit" +section below for an explanation of the differences. + EXAMPLES -------- @@ -392,22 +396,47 @@ M foo.c SKIP-WORKTREE BIT ----------------- -Skip-worktree bit can be defined in one (long) sentence: When reading -an entry, if it is marked as skip-worktree, then Git pretends its -working directory version is up to date and read the index version -instead. - -To elaborate, "reading" means checking for file existence, reading -file attributes or file content. The working directory version may be -present or absent. If present, its content may match against the index -version or not. Writing is not affected by this bit, content safety -is still first priority. Note that Git _can_ update working directory -file, that is marked skip-worktree, if it is safe to do so (i.e. -working directory version matches index version) +Skip-worktree bit can be defined in one (long) sentence: Tell git to +avoid writing the file to the working directory when reasonably +possible, and treat the file as unchanged when it is not +present in the working directory. + +Note that not all git commands will pay attention to this bit, and +some only partially support it. + +The update-index flags and the read-tree capabilities relating to the +skip-worktree bit predated the introduction of the +linkgit:git-sparse-checkout[1] command, which provides a much easier +way to configure and handle the skip-worktree bits. If you want to +reduce your working tree to only deal with a subset of the files in +the repository, we strongly encourage the use of +linkgit:git-sparse-checkout[1] in preference to the low-level +update-index and read-tree primitives. + +The primary purpose of the skip-worktree bit is to enable sparse +checkouts, i.e. to have working directories with only a subset of +paths present. When the skip-worktree bit is set, Git commands (such +as `switch`, `pull`, `merge`) will avoid writing these files. +However, these commands will sometimes write these files anyway in +important cases such as conflicts during a merge or rebase. Git +commands will also avoid treating the lack of such files as an +intentional deletion; for example `git add -u` will not not stage a +deletion for these files and `git commit -a` will not make a commit +deleting them either. Although this bit looks similar to assume-unchanged bit, its goal is -different from assume-unchanged bit's. Skip-worktree also takes -precedence over assume-unchanged bit when both are set. +different. The assume-unchanged bit is for leaving the file in the +working tree but having Git omit checking it for changes and presuming +that the file has not been changed (though if it can determine without +stat'ing the file that it has changed, it is free to record the +changes). skip-worktree tells Git to ignore the absence of the file, +avoid updating it when possible with commands that normally update +much of the working directory (e.g. `checkout`, `switch`, `pull`, +etc.), and not have its absence be recorded in commits. Note that in +sparse checkouts (setup by `git sparse-checkout` or by configuring +core.sparseCheckout to true), if a file is marked as skip-worktree in +the index but is found in the working tree, Git will clear the +skip-worktree bit for that file. SPLIT INDEX ----------- diff --git a/Documentation/git-var.txt b/Documentation/git-var.txt index 6072f936ab..387cc1b914 100644 --- a/Documentation/git-var.txt +++ b/Documentation/git-var.txt @@ -59,6 +59,9 @@ ifdef::git-default-pager[] The build you are using chose '{git-default-pager}' as the default. endif::git-default-pager[] +GIT_DEFAULT_BRANCH:: + The name of the first branch created in newly initialized repositories. + SEE ALSO -------- linkgit:git-commit-tree[1] diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt index 8d162b56c5..f2f996cbe1 100644 --- a/Documentation/git-web--browse.txt +++ b/Documentation/git-web--browse.txt @@ -8,7 +8,7 @@ git-web--browse - Git helper script to launch a web browser SYNOPSIS -------- [verse] -'git web{litdd}browse' [<options>] <url|file>... +'git web{litdd}browse' [<options>] (<URL>|<file>)... DESCRIPTION ----------- diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index 8a7cbdd19c..453e155022 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>] -'git worktree list' [--porcelain] +'git worktree list' [-v | --porcelain] 'git worktree lock' [--reason <string>] <worktree> 'git worktree move' <worktree> <new-path> 'git worktree prune' [-n] [-v] [--expire <expire>] @@ -25,45 +25,49 @@ Manage multiple working trees attached to the same repository. A git repository can support multiple working trees, allowing you to check out more than one branch at a time. With `git worktree add` a new working -tree is associated with the repository. This new working tree is called a -"linked working tree" as opposed to the "main working tree" prepared by -linkgit:git-init[1] or linkgit:git-clone[1]. -A repository has one main working tree (if it's not a -bare repository) and zero or more linked working trees. When you are done -with a linked working tree, remove it with `git worktree remove`. +tree is associated with the repository, along with additional metadata +that differentiates that working tree from others in the same repository. +The working tree, along with this metadata, is called a "worktree". + +This new worktree is called a "linked worktree" as opposed to the "main +worktree" prepared by linkgit:git-init[1] or linkgit:git-clone[1]. +A repository has one main worktree (if it's not a bare repository) and +zero or more linked worktrees. When you are done with a linked worktree, +remove it with `git worktree remove`. In its simplest form, `git worktree add <path>` automatically creates a new branch whose name is the final component of `<path>`, which is convenient if you plan to work on a new topic. For instance, `git worktree add ../hotfix` creates new branch `hotfix` and checks it out at -path `../hotfix`. To instead work on an existing branch in a new working -tree, use `git worktree add <path> <branch>`. On the other hand, if you -just plan to make some experimental changes or do testing without -disturbing existing development, it is often convenient to create a -'throwaway' working tree not associated with any branch. For instance, -`git worktree add -d <path>` creates a new working tree with a detached -`HEAD` at the same commit as the current branch. +path `../hotfix`. To instead work on an existing branch in a new worktree, +use `git worktree add <path> <branch>`. On the other hand, if you just +plan to make some experimental changes or do testing without disturbing +existing development, it is often convenient to create a 'throwaway' +worktree not associated with any branch. For instance, +`git worktree add -d <path>` creates a new worktree with a detached `HEAD` +at the same commit as the current branch. If a working tree is deleted without using `git worktree remove`, then its associated administrative files, which reside in the repository (see "DETAILS" below), will eventually be removed automatically (see `gc.worktreePruneExpire` in linkgit:git-config[1]), or you can run -`git worktree prune` in the main or any linked working tree to -clean up any stale administrative files. +`git worktree prune` in the main or any linked worktree to clean up any +stale administrative files. -If a linked working tree is stored on a portable device or network share -which is not always mounted, you can prevent its administrative files from -being pruned by issuing the `git worktree lock` command, optionally -specifying `--reason` to explain why the working tree is locked. +If the working tree for a linked worktree is stored on a portable device +or network share which is not always mounted, you can prevent its +administrative files from being pruned by issuing the `git worktree lock` +command, optionally specifying `--reason` to explain why the worktree is +locked. COMMANDS -------- add <path> [<commit-ish>]:: -Create `<path>` and checkout `<commit-ish>` into it. The new working directory -is linked to the current repository, sharing everything except working -directory specific files such as `HEAD`, `index`, etc. As a convenience, -`<commit-ish>` may be a bare "`-`", which is synonymous with `@{-1}`. +Create a worktree at `<path>` and checkout `<commit-ish>` into it. The new worktree +is linked to the current repository, sharing everything except per-worktree +files such as `HEAD`, `index`, etc. As a convenience, `<commit-ish>` may +be a bare "`-`", which is synonymous with `@{-1}`. + If `<commit-ish>` is a branch name (call it `<branch>`) and is not found, and neither `-b` nor `-B` nor `--detach` are used, but there does @@ -84,100 +88,97 @@ branches from there if `<branch>` is ambiguous but exists on the linkgit:git-config[1]. + If `<commit-ish>` is omitted and neither `-b` nor `-B` nor `--detach` used, -then, as a convenience, the new working tree is associated with a branch -(call it `<branch>`) named after `$(basename <path>)`. If `<branch>` -doesn't 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 working tree, if it's not checked out anywhere -else, otherwise the command will refuse to create the working tree (unless -`--force` is used). +then, as a convenience, the new worktree is associated with a branch (call +it `<branch>`) named after `$(basename <path>)`. If `<branch>` doesn't +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). list:: -List details of each working tree. The main working tree is listed first, -followed by each of the linked working trees. The output details include -whether the working tree is bare, the revision currently checked out, the +List details of each worktree. The main worktree is listed first, +followed by each of the linked worktrees. The output details include +whether the worktree is bare, the revision currently checked out, the branch currently checked out (or "detached HEAD" if none), "locked" if -the worktree is locked, "prunable" if the worktree can be pruned by `prune` -command. +the worktree is locked, "prunable" if the worktree can be pruned by the +`prune` command. lock:: -If a working tree is on a portable device or network share which -is not always mounted, lock it to prevent its administrative -files from being pruned automatically. This also prevents it from -being moved or deleted. Optionally, specify a reason for the lock -with `--reason`. +If a worktree is on a portable device or network share which is not always +mounted, lock it to prevent its administrative files from being pruned +automatically. This also prevents it from being moved or deleted. +Optionally, specify a reason for the lock with `--reason`. move:: -Move a working tree to a new location. Note that the main working tree -or linked working trees containing submodules cannot be moved with this -command. (The `git worktree repair` command, however, can reestablish -the connection with linked working trees if you move the main working -tree manually.) +Move a worktree to a new location. Note that the main worktree or linked +worktrees containing submodules cannot be moved with this command. (The +`git worktree repair` command, however, can reestablish the connection +with linked worktrees if you move the main worktree manually.) prune:: -Prune working tree information in `$GIT_DIR/worktrees`. +Prune worktree information in `$GIT_DIR/worktrees`. remove:: -Remove a working tree. Only clean working trees (no untracked files -and no modification in tracked files) can be removed. Unclean working -trees or ones with submodules can be removed with `--force`. The main -working tree cannot be removed. +Remove a worktree. Only clean worktrees (no untracked files and no +modification in tracked files) can be removed. Unclean worktrees or ones +with submodules can be removed with `--force`. The main worktree cannot be +removed. repair [<path>...]:: -Repair working tree administrative files, if possible, if they have -become corrupted or outdated due to external factors. +Repair worktree administrative files, if possible, if they have become +corrupted or outdated due to external factors. + -For instance, if the main working tree (or bare repository) is moved, -linked working trees will be unable to locate it. Running `repair` in -the main working tree will reestablish the connection from linked -working trees back to the main working tree. +For instance, if the main worktree (or bare repository) is moved, linked +worktrees will be unable to locate it. Running `repair` in the main +worktree will reestablish the connection from linked worktrees back to the +main worktree. + -Similarly, if a linked working tree is moved without using `git worktree -move`, the main working tree (or bare repository) will be unable to -locate it. Running `repair` within the recently-moved working tree will -reestablish the connection. If multiple linked working trees are moved, -running `repair` from any working tree with each tree's new `<path>` as -an argument, will reestablish the connection to all the specified paths. +Similarly, if the working tree for a linked worktree is moved without +using `git worktree move`, the main worktree (or bare repository) will be +unable to locate it. Running `repair` within the recently-moved worktree +will reestablish the connection. If multiple linked worktrees are moved, +running `repair` from any worktree with each tree's new `<path>` as an +argument, will reestablish the connection to all the specified paths. + -If both the main working tree and linked working trees have been moved -manually, then running `repair` in the main working tree and specifying the -new `<path>` of each linked working tree will reestablish all connections -in both directions. +If both the main worktree and linked worktrees have been moved manually, +then running `repair` in the main worktree and specifying the new `<path>` +of each linked worktree will reestablish all connections in both +directions. unlock:: -Unlock a working tree, allowing it to be pruned, moved or deleted. +Unlock a worktree, allowing it to be pruned, moved or deleted. OPTIONS ------- -f:: --force:: - By default, `add` refuses to create a new working tree when + By default, `add` refuses to create a new worktree when `<commit-ish>` is a branch name and is already checked out by - another working tree, or if `<path>` is already assigned to some - working tree but is missing (for instance, if `<path>` was deleted + another worktree, or if `<path>` is already assigned to some + worktree but is missing (for instance, if `<path>` was deleted manually). This option overrides these safeguards. To add a missing but - locked working tree path, specify `--force` twice. + locked worktree path, specify `--force` twice. + -`move` refuses to move a locked working tree unless `--force` is specified -twice. If the destination is already assigned to some other working tree but is +`move` refuses to move a locked worktree unless `--force` is specified +twice. If the destination is already assigned to some other worktree but is missing (for instance, if `<new-path>` was deleted manually), then `--force` allows the move to proceed; use `--force` twice if the destination is locked. + -`remove` refuses to remove an unclean working tree unless `--force` is used. -To remove a locked working tree, specify `--force` twice. +`remove` refuses to remove an unclean worktree unless `--force` is used. +To remove a locked worktree, specify `--force` twice. -b <new-branch>:: -B <new-branch>:: With `add`, create a new branch named `<new-branch>` starting at - `<commit-ish>`, and check out `<new-branch>` into the new working tree. + `<commit-ish>`, and check out `<new-branch>` into the new worktree. If `<commit-ish>` is omitted, it defaults to `HEAD`. By default, `-b` refuses to create a new branch if it already exists. `-B` overrides this safeguard, resetting `<new-branch>` to @@ -185,7 +186,7 @@ To remove a locked working tree, specify `--force` twice. -d:: --detach:: - With `add`, detach `HEAD` in the new working tree. See "DETACHED HEAD" + With `add`, detach `HEAD` in the new worktree. See "DETACHED HEAD" in linkgit:git-checkout[1]. --[no-]checkout:: @@ -211,7 +212,7 @@ This can also be set up as the default behaviour by using the `--track` in linkgit:git-branch[1] for details. --lock:: - Keep the working tree locked after creation. This is the + Keep the worktree locked after creation. This is the equivalent of `git worktree lock` after `git worktree add`, but without a race condition. @@ -236,43 +237,42 @@ This can also be set up as the default behaviour by using the With `list`, output additional information about worktrees (see below). --expire <time>:: - With `prune`, only expire unused working trees older than `<time>`. + With `prune`, only expire unused worktrees older than `<time>`. + -With `list`, annotate missing working trees as prunable if they are -older than `<time>`. +With `list`, annotate missing worktrees as prunable if they are older than +`<time>`. --reason <string>:: - With `lock` or with `add --lock`, an explanation why the working tree is locked. + With `lock` or with `add --lock`, an explanation why the worktree + is locked. <worktree>:: - Working trees can be identified by path, either relative or - absolute. + Worktrees can be identified by path, either relative or absolute. + -If the last path components in the working tree's path is unique among -working trees, it can be used to identify a working tree. For example if -you only have two working trees, at `/abc/def/ghi` and `/abc/def/ggg`, -then `ghi` or `def/ghi` is enough to point to the former working tree. +If the last path components in the worktree's path is unique among +worktrees, it can be used to identify a worktree. For example if you only +have two worktrees, at `/abc/def/ghi` and `/abc/def/ggg`, then `ghi` or +`def/ghi` is enough to point to the former worktree. REFS ---- -In multiple working trees, some refs may be shared between all working -trees and some refs are local. One example is `HEAD` which is different for each -working tree. This section is about the sharing rules and how to access -refs of one working tree from another. - -In general, all pseudo refs are per working tree 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. - -Refs that are per working tree can still be accessed from another -working tree via two special paths, `main-worktree` and `worktrees`. The -former gives access to per-working tree refs of the main working tree, -while the latter to all linked working trees. +When using multiple worktrees, some refs are shared between all worktrees, +but others are specific to an individual worktree. One example is `HEAD`, +which is different for each worktree. This section is about the sharing +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. + +Refs that are per-worktree can still be accessed from another worktree via +two special paths, `main-worktree` and `worktrees`. The former gives +access to per-worktree refs of the main worktree, while the latter to all +linked worktrees. For example, `main-worktree/HEAD` or `main-worktree/refs/bisect/good` -resolve to the same value as the main working tree's `HEAD` and +resolve to the same value as the main worktree's `HEAD` and `refs/bisect/good` respectively. Similarly, `worktrees/foo/HEAD` or `worktrees/bar/refs/bisect/bad` are the same as `$GIT_COMMON_DIR/worktrees/foo/HEAD` and @@ -284,13 +284,13 @@ which will handle refs correctly. CONFIGURATION FILE ------------------ -By default, the repository `config` file is shared across all working -trees. If the config variables `core.bare` or `core.worktree` are -already present in the config file, they will be applied to the main -working trees only. +By default, the repository `config` file is shared across all worktrees. +If the config variables `core.bare` or `core.worktree` are present in the +common config file and `extensions.worktreeConfig` is disabled, then they +will be applied to the main worktree only. -In order to have configuration specific to working trees, you can turn -on the `worktreeConfig` extension, e.g.: +In order to have worktree-specific configuration, you can turn on the +`worktreeConfig` extension, e.g.: ------------ $ git config extensions.worktreeConfig true @@ -303,40 +303,45 @@ versions will refuse to access repositories with this extension. Note that in this file, the exception for `core.bare` and `core.worktree` is gone. If they exist in `$GIT_DIR/config`, you must move -them to the `config.worktree` of the main working tree. You may also -take this opportunity to review and move other configuration that you -do not want to share to all working trees: +them to the `config.worktree` of the main worktree. You may also take this +opportunity to review and move other configuration that you do not want to +share to all worktrees: + + - `core.worktree` should never be shared. + + - `core.bare` should not be shared if the value is `core.bare=true`. - - `core.worktree` and `core.bare` should never be shared + - `core.sparseCheckout` should not be shared, unless you are sure you + always use sparse checkout for all worktrees. - - `core.sparseCheckout` is recommended per working tree, unless you - are sure you always use sparse checkout for all working trees. +See the documentation of `extensions.worktreeConfig` in +linkgit:git-config[1] for more details. DETAILS ------- -Each linked working tree has a private sub-directory in the repository's +Each linked worktree has a private sub-directory in the repository's `$GIT_DIR/worktrees` directory. The private sub-directory's name is usually -the base name of the linked working tree's path, possibly appended with a +the base name of the linked worktree's path, possibly appended with a number to make it unique. For example, when `$GIT_DIR=/path/main/.git` the command `git worktree add /path/other/test-next next` creates the linked -working tree in `/path/other/test-next` and also creates a +worktree in `/path/other/test-next` and also creates a `$GIT_DIR/worktrees/test-next` directory (or `$GIT_DIR/worktrees/test-next1` if `test-next` is already taken). -Within a linked working tree, `$GIT_DIR` is set to point to this private +Within a linked worktree, `$GIT_DIR` is set to point to this private directory (e.g. `/path/main/.git/worktrees/test-next` in the example) and -`$GIT_COMMON_DIR` is set to point back to the main working tree's `$GIT_DIR` +`$GIT_COMMON_DIR` is set to point back to the main worktree's `$GIT_DIR` (e.g. `/path/main/.git`). These settings are made in a `.git` file located at -the top directory of the linked working tree. +the top directory of the linked worktree. Path resolution via `git rev-parse --git-path` uses either `$GIT_DIR` or `$GIT_COMMON_DIR` depending on the path. For example, in the -linked working tree `git rev-parse --git-path HEAD` returns +linked worktree `git rev-parse --git-path HEAD` returns `/path/main/.git/worktrees/test-next/HEAD` (not `/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 working trees, except `refs/bisect` and +since refs are shared across all worktrees, except `refs/bisect` and `refs/worktree`. See linkgit:gitrepository-layout[5] for more information. The rule of @@ -344,8 +349,8 @@ thumb is do not make any assumption about whether a path belongs to `$GIT_DIR` or `$GIT_COMMON_DIR` when you need to directly access something inside `$GIT_DIR`. Use `git rev-parse --git-path` to get the final path. -If you manually move a linked working tree, you need to update the `gitdir` file -in the entry's directory. For example, if a linked working tree is moved +If you manually move a linked worktree, you need to update the `gitdir` file +in the entry's directory. For example, if a linked worktree is moved to `/newpath/test-next` and its `.git` file points to `/path/main/.git/worktrees/test-next`, then update `/path/main/.git/worktrees/test-next/gitdir` to reference `/newpath/test-next` @@ -354,10 +359,10 @@ automatically. To prevent a `$GIT_DIR/worktrees` entry from being pruned (which can be useful in some situations, such as when the -entry's working tree is stored on a portable device), use the +entry's worktree is stored on a portable device), use the `git worktree lock` command, which adds a file named `locked` to the entry's directory. The file contains the reason in -plain text. For example, if a linked working tree's `.git` file points +plain text. For example, if a linked worktree's `.git` file points to `/path/main/.git/worktrees/test-next` then a file named `/path/main/.git/worktrees/test-next/locked` will prevent the `test-next` entry from being pruned. See @@ -378,11 +383,11 @@ $ git worktree list /path/to/other-linked-worktree 1234abc (detached HEAD) ------------ -The command also shows annotations for each working tree, according to its state. +The command also shows annotations for each worktree, according to its state. These annotations are: - * `locked`, if the working tree is locked. - * `prunable`, if the working tree can be pruned via `git worktree prune`. + * `locked`, if the worktree is locked. + * `prunable`, if the worktree can be pruned via `git worktree prune`. ------------ $ git worktree list @@ -400,14 +405,14 @@ $ git worktree list --verbose /path/to/linked-worktree abcd1234 [master] /path/to/locked-worktree-no-reason abcd5678 (detached HEAD) locked /path/to/locked-worktree-with-reason 1234abcd (brancha) - locked: working tree path is mounted on a portable device + locked: worktree path is mounted on a portable device /path/to/prunable-worktree 5678abc1 (detached HEAD) prunable: gitdir file points to non-existent location ------------ Note that the annotation is moved to the next line if the additional information is available, otherwise it stays on the same line as the -working tree itself. +worktree itself. Porcelain Format ~~~~~~~~~~~~~~~~ @@ -416,7 +421,7 @@ label and value separated by a single space. Boolean attributes (like `bare` and `detached`) are listed as a label only, and are present only if the value is true. Some attributes (like `locked`) can be listed as a label only or with a value depending upon whether a reason is available. The first -attribute of a working tree is always `worktree`, an empty line indicates the +attribute of a worktree is always `worktree`, an empty line indicates the end of the record. For example: ------------ @@ -468,7 +473,7 @@ demands that you fix something immediately. You might typically use linkgit:git-stash[1] to store your changes away temporarily, however, your working tree is in such a state of disarray (with new, moved, and removed files, and other bits and pieces strewn around) that you don't want to risk -disturbing any of it. Instead, you create a temporary linked working tree to +disturbing any of it. Instead, you create a temporary linked worktree to make the emergency fix, remove it when done, and then resume your earlier refactoring session. diff --git a/Documentation/git.txt b/Documentation/git.txt index 281c5f8cae..13f83a2a3a 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -832,8 +832,9 @@ for full details. `GIT_TRACE_REDACT`:: By default, when tracing is activated, Git redacts the values of - cookies, the "Authorization:" header, and the "Proxy-Authorization:" - header. Set this variable to `0` to prevent this redaction. + cookies, the "Authorization:" header, the "Proxy-Authorization:" + header and packfile URIs. Set this variable to `0` to prevent this + redaction. `GIT_LITERAL_PATHSPECS`:: Setting this variable to `1` will cause Git to treat all diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 83fd4e19a4..4b36d51beb 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -160,11 +160,13 @@ unspecified. ^^^^^ This attribute sets a specific line-ending style to be used in the -working directory. It enables end-of-line conversion without any -content checks, effectively setting the `text` attribute. Note that -setting this attribute on paths which are in the index with CRLF line -endings may make the paths to be considered dirty. Adding the path to -the index again will normalize the line endings in the index. +working directory. This attribute has effect only if the `text` +attribute is set or unspecified, or if it is set to `auto`, the file is +detected as text, and it is stored with LF endings in the index. Note +that setting this attribute on paths which are in the index with CRLF +line endings may make the paths to be considered dirty unless +`text=auto` is set. Adding the path to the index again will normalize +the line endings in the index. Set to string value "crlf":: @@ -827,6 +829,8 @@ patterns are available: - `java` suitable for source code in the Java language. +- `kotlin` suitable for source code in the Kotlin language. + - `markdown` suitable for Markdown documents. - `matlab` suitable for source code in the MATLAB and Octave languages. diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index 92e4ba6a2f..1819a5a185 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -19,6 +19,15 @@ Many commands take revisions (most often "commits", but sometimes "tree-ish", depending on the context and command) and paths as their arguments. Here are the rules: + * Options come first and then args. + 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 + 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). + * Revisions come first and then paths. E.g. in `git diff v1.0 v2.0 arch/x86 include/asm-x86`, `v1.0` and `v2.0` are revisions and `arch/x86` and `include/asm-x86` @@ -72,24 +81,24 @@ you will. Here are the rules regarding the "flags" that you should follow when you are scripting Git: - * it's preferred to use the non-dashed form of Git commands, which means that + * It's preferred to use the non-dashed form of Git commands, which means that you should prefer `git foo` to `git-foo`. - * splitting short options to separate words (prefer `git foo -a -b` + * Splitting short options to separate words (prefer `git foo -a -b` to `git foo -ab`, the latter may not even work). - * when a command-line option takes an argument, use the 'stuck' form. In + * When a command-line option takes an argument, use the 'stuck' form. In other words, write `git foo -oArg` instead of `git foo -o Arg` for short options, and `git foo --long-opt=Arg` instead of `git foo --long-opt Arg` for long options. An option that takes optional option-argument must be written in the 'stuck' form. - * when you give a revision parameter to a command, make sure the parameter is + * When you give a revision parameter to a command, make sure the parameter is not ambiguous with a name of a file in the work tree. E.g. do not write `git log -1 HEAD` but write `git log -1 HEAD --`; the former will not work if you happen to have a file called `HEAD` in the work tree. - * many commands allow a long option `--option` to be abbreviated + * Many commands allow a long option `--option` to be abbreviated only to their unique prefix (e.g. if there is no other option whose name begins with `opt`, you may be able to spell `--opt` to invoke the `--option` flag), but you should fully spell them out diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt index 758bf39ba3..80517b4eb2 100644 --- a/Documentation/gitcredentials.txt +++ b/Documentation/gitcredentials.txt @@ -132,7 +132,7 @@ because the hostnames differ. Nor would it match `foo.example.com`; Git compares hostnames exactly, without considering whether two hosts are part of the same domain. Likewise, a config entry for `http://example.com` would not match: Git compares the protocols exactly. However, you may use wildcards in -the domain name and other pattern matching techniques as with the `http.<url>.*` +the domain name and other pattern matching techniques as with the `http.<URL>.*` options. If the "pattern" URL does include a path component, then this too must match @@ -147,7 +147,7 @@ CONFIGURATION OPTIONS Options for a credential context can be configured either in `credential.*` (which applies to all credentials), or -`credential.<url>.*`, where <url> matches the context as described +`credential.<URL>.*`, where <URL> matches the context as described above. The following options are available in either location: diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index b51959ff94..a16e62bc8c 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -698,6 +698,10 @@ and "0" meaning they were not. Only one parameter should be set to "1" when the hook runs. The hook running passing "1", "1" should not be possible. +SEE ALSO +-------- +linkgit:git-hook[1] + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt index 891c8da4fd..941858a6ec 100644 --- a/Documentation/gitsubmodules.txt +++ b/Documentation/gitsubmodules.txt @@ -226,7 +226,7 @@ Workflow for a third party library ---------------------------------- # Add a submodule - git submodule add <url> <path> + git submodule add <URL> <path> # Occasionally update the submodule to a new version: git -C <path> checkout <new version> diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt index 47cf97f9be..59305265c5 100644 --- a/Documentation/gitworkflows.txt +++ b/Documentation/gitworkflows.txt @@ -394,7 +394,7 @@ request to do so by mail. Such a request looks like ------------------------------------- Please pull from - <url> <branch> + <URL> <branch> ------------------------------------- In that case, 'git pull' can do the fetch and merge in one go, as @@ -403,7 +403,7 @@ follows. .Push/pull: Merging remote topics [caption="Recipe: "] ===================================== -`git pull <url> <branch>` +`git pull <URL> <branch>` ===================================== Occasionally, the maintainer may get merge conflicts when they try to @@ -440,7 +440,7 @@ merge because you cannot format-patch merges): .format-patch/am: Keeping topics up to date [caption="Recipe: "] ===================================== -`git pull --rebase <url> <branch>` +`git pull --rebase <URL> <branch>` ===================================== You can then fix the conflicts during the rebase. Presumably you have diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index c077971335..aa2f41f5e7 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -312,7 +312,7 @@ Pathspecs are used on the command line of "git ls-files", "git ls-tree", "git add", "git grep", "git diff", "git checkout", and many other commands to limit the scope of operations to some subset of the tree or -worktree. See the documentation of each command for whether +working tree. See the documentation of each command for whether paths are relative to the current directory or toplevel. The pathspec syntax is as follows: + @@ -446,7 +446,7 @@ exclude;; interface than the <<def_plumbing,plumbing>>. [[def_per_worktree_ref]]per-worktree ref:: - Refs that are per-<<def_working_tree,worktree>>, rather than + Refs that are per-<<def_worktree,worktree>>, rather than global. This is presently only <<def_HEAD,HEAD>> and any refs that start with `refs/bisect/`, but might later include other unusual refs. @@ -669,3 +669,12 @@ The most notable example is `HEAD`. The tree of actual checked out files. The working tree normally contains the contents of the <<def_HEAD,HEAD>> commit's tree, plus any local changes that you have made but not yet committed. + +[[def_worktree]]worktree:: + A repository can have zero (i.e. bare repository) or one or + more worktrees attached to it. One "worktree" consists of a + "working tree" and repository metadata, most of which are + shared among other worktrees of a single repository, and + some of which are maintained separately per worktree + (e.g. the index, HEAD and pseudorefs like MERGE_HEAD, + per-worktree refs and per-worktree configuration file). diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index ef6bd420ae..0b4c1c8d98 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -20,7 +20,7 @@ built-in formats: * 'oneline' - <hash> <title line> + <hash> <title-line> + This is designed to be as compact as possible. @@ -29,17 +29,17 @@ This is designed to be as compact as possible. commit <hash> Author: <author> - <title line> + <title-line> * 'medium' commit <hash> Author: <author> - Date: <author date> + Date: <author-date> - <title line> + <title-line> - <full commit message> + <full-commit-message> * 'full' @@ -47,25 +47,25 @@ This is designed to be as compact as possible. Author: <author> Commit: <committer> - <title line> + <title-line> - <full commit message> + <full-commit-message> * 'fuller' commit <hash> Author: <author> - AuthorDate: <author date> + AuthorDate: <author-date> Commit: <committer> - CommitDate: <committer date> + CommitDate: <committer-date> - <title line> + <title-line> - <full commit message> + <full-commit-message> * 'reference' - <abbrev hash> (<title line>, <short author date>) + <abbrev-hash> (<title-line>, <short-author-date>) + This format is used to refer to another commit in a commit message and is the same as `--pretty='format:%C(auto)%h (%s, %ad)'`. By default, @@ -78,10 +78,10 @@ placeholders, its output is not affected by other options like From <hash> <date> From: <author> - Date: <author date> - Subject: [PATCH] <title line> + Date: <author-date> + Subject: [PATCH] <title-line> - <full commit message> + <full-commit-message> * 'mboxrd' + @@ -101,9 +101,9 @@ commits are displayed, but not the way the diff is shown e.g. with `git log --raw`. To get full object names in a raw diff format, use `--no-abbrev`. -* 'format:<string>' +* 'format:<format-string>' + -The 'format:<string>' format allows you to specify which information +The 'format:<format-string>' format allows you to specify which information you want to show. It works a little bit like printf format, with the notable exception that you get a newline with '%n' instead of '\n'. @@ -220,6 +220,12 @@ The placeholders are: 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. +** 'abbrev=<number>': Instead of using the default number of hexadecimal digits + (which will vary according to the number of objects in the repository with a + default of 7) of the abbreviated object name, use <number> digits, or as many + digits as needed to form a unique object name. ** 'match=<pattern>': Only consider tags matching the given `glob(7)` pattern, excluding the "refs/tags/" prefix. ** 'exclude=<pattern>': Do not consider tags matching the given @@ -273,12 +279,7 @@ endif::git-rev-list[] If any option is provided multiple times the last occurrence wins. + -The boolean options accept an optional value `[=<BOOL>]`. The values -`true`, `false`, `on`, `off` etc. are all accepted. See the "boolean" -sub-section in "EXAMPLES" in linkgit:git-config[1]. If a boolean -option is given with no value, it's enabled. -+ -** 'key=<K>': only show trailers with specified key. Matching is done +** 'key=<key>': only show trailers with specified <key>. Matching is done case-insensitively and trailing colon is optional. If option is given multiple times trailer lines matching any of the keys are shown. This option automatically enables the `only` option so that @@ -286,25 +287,25 @@ option is given with no value, it's enabled. desired it can be disabled with `only=false`. E.g., `%(trailers:key=Reviewed-by)` shows trailer lines with key `Reviewed-by`. -** 'only[=<BOOL>]': select whether non-trailer lines from the trailer +** 'only[=<bool>]': select whether non-trailer lines from the trailer block should be included. -** 'separator=<SEP>': specify a separator inserted between trailer +** 'separator=<sep>': specify a separator inserted between trailer lines. When this option is not given each trailer line is - terminated with a line feed character. The string SEP may contain + terminated with a line feed character. The string <sep> may contain the literal formatting codes described above. To use comma as separator one must use `%x2C` as it would otherwise be parsed as next option. E.g., `%(trailers:key=Ticket,separator=%x2C )` shows all trailer lines whose key is "Ticket" separated by a comma and a space. -** 'unfold[=<BOOL>]': make it behave as if interpret-trailer's `--unfold` +** 'unfold[=<bool>]': make it behave as if interpret-trailer's `--unfold` option was given. E.g., `%(trailers:only,unfold=true)` unfolds and shows all trailer lines. -** 'keyonly[=<BOOL>]': only show the key part of the trailer. -** 'valueonly[=<BOOL>]': only show the value part of the trailer. -** 'key_value_separator=<SEP>': specify a separator inserted between +** 'keyonly[=<bool>]': only show the key part of the trailer. +** 'valueonly[=<bool>]': only show the value part of the trailer. +** 'key_value_separator=<sep>': specify a separator inserted between trailer lines. When this option is not given each trailer key-value pair is separated by ": ". Otherwise it shares the same semantics - as 'separator=<SEP>' above. + as 'separator=<sep>' above. NOTE: Some placeholders may depend on other options given to the revision traversal engine. For example, the `%g*` reflog options will @@ -313,6 +314,11 @@ insert an empty string unless we are traversing reflog entries (e.g., by decoration format if `--decorate` was not already provided on the command line. +The boolean options accept an optional value `[=<bool-value>]`. The values +`true`, `false`, `on`, `off` etc. are all accepted. See the "boolean" +sub-section in "EXAMPLES" in linkgit:git-config[1]. If a boolean +option is given with no value, it's enabled. + If you add a `+` (plus sign) after '%' of a placeholder, a line-feed is inserted immediately before the expansion if and only if the placeholder expands to a non-empty string. diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 24569b06d1..fd4f4e26c9 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -122,19 +122,27 @@ again. Equivalent forms are `--min-parents=0` (any commit has 0 or more parents) and `--max-parents=-1` (negative numbers denote no upper limit). --first-parent:: - Follow only the first parent commit upon seeing a merge - commit. This option can give a better overview when - viewing the evolution of a particular topic branch, - because merges into a topic branch tend to be only about - adjusting to updated upstream from time to time, and - this option allows you to ignore the individual commits - brought in to your history by such a merge. + When finding commits to include, follow only the first + parent commit upon seeing a merge commit. This option + can give a better overview when viewing the evolution of + a particular topic branch, because merges into a topic + branch tend to be only about adjusting to updated upstream + from time to time, and this option allows you to ignore + the individual commits brought in to your history by such + a merge. ifdef::git-log[] + This option also changes default diff format for merge commits to `first-parent`, see `--diff-merges=first-parent` for details. endif::git-log[] +--exclude-first-parent-only:: + When finding commits to exclude (with a '{caret}'), follow only + the first parent commit upon seeing a merge commit. + This can be used to find the set of changes in a topic branch + from the point where it diverged from the remote branch, given + that arbitrary merges can be valid topic branch changes. + --not:: Reverses the meaning of the '{caret}' prefix (or lack thereof) for all following revision specifiers, up to the next `--not`. @@ -1047,7 +1055,7 @@ omitted. has no effect. `--date=format:...` feeds the format `...` to your system `strftime`, -except for %z and %Z, which are handled internally. +except for %s, %z, and %Z, which are handled internally. Use `--date=format:%c` to show the date in your system locale's preferred format. See the `strftime` manual for a complete list of format placeholders. When using `-local`, the correct syntax is diff --git a/Documentation/technical/bundle-format.txt b/Documentation/technical/bundle-format.txt index bac558d049..b9be8644cf 100644 --- a/Documentation/technical/bundle-format.txt +++ b/Documentation/technical/bundle-format.txt @@ -71,6 +71,11 @@ and the Git bundle v2 format cannot represent a shallow clone repository. == Capabilities Because there is no opportunity for negotiation, unknown capabilities cause 'git -bundle' to abort. The only known capability is `object-format`, which specifies -the hash algorithm in use, and can take the same values as the -`extensions.objectFormat` configuration value. +bundle' to abort. + +* `object-format` specifies the hash algorithm in use, and can take the same + values as the `extensions.objectFormat` configuration value. + +* `filter` specifies an object filter as in the `--filter` option in + linkgit:git-rev-list[1]. The resulting pack-file must be marked as a + `.promisor` pack-file after it is unbundled. diff --git a/Documentation/technical/commit-graph-format.txt b/Documentation/technical/commit-graph-format.txt index 87971c27dd..484b185ba9 100644 --- a/Documentation/technical/commit-graph-format.txt +++ b/Documentation/technical/commit-graph-format.txt @@ -93,7 +93,7 @@ CHUNK DATA: 2 bits of the lowest byte, storing the 33rd and 34th bit of the commit time. - Generation Data (ID: {'G', 'D', 'A', 'T' }) (N * 4 bytes) [Optional] + Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional] * This list of 4-byte values store corrected commit date offsets for the commits, arranged in the same order as commit data chunk. * If the corrected commit date offset cannot be stored within 31 bits, @@ -104,7 +104,7 @@ CHUNK DATA: by compatible versions of Git and in case of split commit-graph chains, the topmost layer also has Generation Data chunk. - Generation Data Overflow (ID: {'G', 'D', 'O', 'V' }) [Optional] + Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional] * This list of 8-byte values stores the corrected commit date offsets for commits with corrected commit date offsets that cannot be stored within 31 bits. @@ -156,3 +156,11 @@ CHUNK DATA: TRAILER: H-byte HASH-checksum of all of the above. + +== Historical Notes: + +The Generation Data (GDA2) and Generation Data Overflow (GDO2) chunks have +the number '2' in their chunk IDs because a previous version of Git wrote +possibly erroneous data in these chunks with the IDs "GDAT" and "GDOV". By +changing the IDs, newer versions of Git will silently ignore those older +chunks and write the new information without trusting the incorrect data. diff --git a/Documentation/technical/multi-pack-index.txt b/Documentation/technical/multi-pack-index.txt index 86f40f2490..f2221d2b44 100644 --- a/Documentation/technical/multi-pack-index.txt +++ b/Documentation/technical/multi-pack-index.txt @@ -17,13 +17,14 @@ is not feasible due to storage space or excessive repack times. The multi-pack-index (MIDX for short) stores a list of objects and their offsets into multiple packfiles. It contains: -- A list of packfile names. -- A sorted list of object IDs. -- A list of metadata for the ith object ID including: - - A value j referring to the jth packfile. - - An offset within the jth packfile for the object. -- If large offsets are required, we use another list of large +* A list of packfile names. +* A sorted list of object IDs. +* A list of metadata for the ith object ID including: +** A value j referring to the jth packfile. +** An offset within the jth packfile for the object. +* If large offsets are required, we use another list of large offsets similar to version 2 pack-indexes. +- An optional list of objects in pseudo-pack order (used with MIDX bitmaps). Thus, we can provide O(log N) lookup time for any number of packfiles. @@ -87,11 +88,6 @@ Future Work helpful to organize packfiles by object type (commit, tree, blob, etc.) and use this metadata to help that maintenance. -- The partial clone feature records special "promisor" packs that - may point to objects that are not stored locally, but available - on request to a server. The multi-pack-index does not currently - track these promisor packs. - Related Links ------------- [0] https://bugs.chromium.org/p/git/issues/detail?id=6 diff --git a/Documentation/technical/pack-format.txt b/Documentation/technical/pack-format.txt index 8d2f42f29e..6d3efb7d16 100644 --- a/Documentation/technical/pack-format.txt +++ b/Documentation/technical/pack-format.txt @@ -376,6 +376,11 @@ CHUNK DATA: [Optional] Object Large Offsets (ID: {'L', 'O', 'F', 'F'}) 8-byte offsets into large packfiles. + [Optional] Bitmap pack order (ID: {'R', 'I', 'D', 'X'}) + A list of MIDX positions (one per object in the MIDX, num_objects in + total, each a 4-byte unsigned integer in network byte order), sorted + according to their relative bitmap/pseudo-pack positions. + TRAILER: Index checksum of the above contents. @@ -456,9 +461,5 @@ In short, a MIDX's pseudo-pack is the de-duplicated concatenation of objects in packs stored by the MIDX, laid out in pack order, and the packs arranged in MIDX order (with the preferred pack coming first). -Finally, note that the MIDX's reverse index is not stored as a chunk in -the multi-pack-index itself. This is done because the reverse index -includes the checksum of the pack or MIDX to which it belongs, which -makes it impossible to write in the MIDX. To avoid races when rewriting -the MIDX, a MIDX reverse index includes the MIDX's checksum in its -filename (e.g., `multi-pack-index-xyz.rev`). +The MIDX's reverse index is stored in the optional 'RIDX' chunk within +the MIDX itself. diff --git a/Documentation/technical/protocol-v2.txt b/Documentation/technical/protocol-v2.txt index 21e8258ccf..8a877d27e2 100644 --- a/Documentation/technical/protocol-v2.txt +++ b/Documentation/technical/protocol-v2.txt @@ -125,11 +125,11 @@ command can be requested at a time. empty-request = flush-pkt command-request = command capability-list - [command-args] + delim-pkt + command-args flush-pkt command = PKT-LINE("command=" key LF) - command-args = delim-pkt - *command-specific-arg + command-args = *command-specific-arg command-specific-args are packet line framed arguments defined by each individual command. diff --git a/Documentation/technical/reftable.txt b/Documentation/technical/reftable.txt index d7c3b645cf..6a67cc4174 100644 --- a/Documentation/technical/reftable.txt +++ b/Documentation/technical/reftable.txt @@ -443,7 +443,7 @@ Obj block format Object blocks are optional. Writers may choose to omit object blocks, especially if readers will not use the object name to ref mapping. -Object blocks use unique, abbreviated 2-32 object name keys, mapping to +Object blocks use unique, abbreviated 2-31 byte object name keys, mapping to ref blocks containing references pointing to that object directly, or as the peeled value of an annotated tag. Like ref blocks, object blocks use the file's standard block size. The abbreviation length is available in diff --git a/Documentation/technical/rerere.txt b/Documentation/technical/rerere.txt index af5f9fc24f..35d4541433 100644 --- a/Documentation/technical/rerere.txt +++ b/Documentation/technical/rerere.txt @@ -14,9 +14,9 @@ conflicts before writing them to the rerere database. Different conflict styles and branch names are normalized by stripping the labels from the conflict markers, and removing the common ancestor -version from the `diff3` conflict style. Branches that are merged -in different order are normalized by sorting the conflict hunks. More -on each of those steps in the following sections. +version from the `diff3` or `zdiff3` conflict styles. Branches that +are merged in different order are normalized by sorting the conflict +hunks. More on each of those steps in the following sections. Once these two normalization operations are applied, a conflict ID is calculated based on the normalized conflict, which is later used by @@ -42,8 +42,8 @@ get a conflict like the following: >>>>>>> AC Doing the analogous with AC2 (forking a branch ABAC2 off of branch AB -and then merging branch AC2 into it), using the diff3 conflict style, -we get a conflict like the following: +and then merging branch AC2 into it), using the diff3 or zdiff3 +conflict style, we get a conflict like the following: <<<<<<< HEAD B diff --git a/Documentation/urls-remotes.txt b/Documentation/urls-remotes.txt index bd184cd653..86d0008f94 100644 --- a/Documentation/urls-remotes.txt +++ b/Documentation/urls-remotes.txt @@ -26,14 +26,14 @@ config file would appear like this: ------------ [remote "<name>"] - url = <url> + url = <URL> pushurl = <pushurl> push = <refspec> fetch = <refspec> ------------ The `<pushurl>` is used for pushes only. It is optional and defaults -to `<url>`. +to `<URL>`. Named file in `$GIT_DIR/remotes` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -67,10 +67,10 @@ This file should have the following format: ------------ - <url>#<head> + <URL>#<head> ------------ -`<url>` is required; `#<head>` is optional. +`<URL>` is required; `#<head>` is optional. Depending on the operation, git will use one of the following refspecs, if you don't provide one on the command line. |