diff options
Diffstat (limited to 'Documentation')
71 files changed, 1011 insertions, 326 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 711cb9171e..0e27b5395d 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -499,6 +499,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/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index b20bc8e914..63a2ef5449 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -905,19 +905,34 @@ Sending emails with Git is a two-part process; before you can prepare the emails themselves, you'll need to prepare the patches. Luckily, this is pretty simple: ---- -$ git format-patch --cover-letter -o psuh/ master..psuh ----- - -The `--cover-letter` parameter tells `format-patch` to create a cover letter -template for you. You will need to fill in the template before you're ready -to send - but for now, the template will be next to your other patches. - -The `-o psuh/` parameter tells `format-patch` to place the patch files into a -directory. This is useful because `git send-email` can take a directory and -send out all the patches from there. - -`master..psuh` tells `format-patch` to generate patches for the difference -between `master` and `psuh`. It will make one patch file per commit. After you +$ git format-patch --cover-letter -o psuh/ --base=auto psuh@{u}..psuh +---- + + . The `--cover-letter` option tells `format-patch` to create a + cover letter template for you. You will need to fill in the + template before you're ready to send - but for now, the template + will be next to your other patches. + + . The `-o psuh/` option tells `format-patch` to place the patch + files into a directory. This is useful because `git send-email` + can take a directory and send out all the patches from there. + + . The `--base=auto` option tells the command to record the "base + commit", on which the recipient is expected to apply the patch + series. The `auto` value will cause `format-patch` to compute + the base commit automatically, which is the merge base of tip + commit of the remote-tracking branch and the specified revision + range. + + . The `psuh@{u}..psuh` option tells `format-patch` to generate + patches for the commits you created on the `psuh` branch since it + forked from its upstream (which is `origin/master` if you + followed the example in the "Set up your workspace" section). If + you are already on the `psuh` branch, you can just say `@{u}`, + which means "commits on the current branch since it forked from + its upstream", which is the same thing. + +The command will make one patch file per commit. After you run, you can go have a look at each of the patches with your favorite text editor and make sure everything looks alright; however, it's not recommended to make code fixups via the patch file. It's a better idea to make the change the diff --git a/Documentation/MyFirstObjectWalk.txt b/Documentation/MyFirstObjectWalk.txt index 45eb84d8b4..ca267941f3 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.*/ @@ -624,9 +640,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, @@ -697,7 +718,7 @@ First, we'll need to `#include "list-objects-filter-options.h"` and set up the ---- static void walken_object_walk(struct rev_info *rev) { - struct list_objects_filter_options filter_options = {}; + struct list_objects_filter_options filter_options = { 0 }; ... ---- diff --git a/Documentation/RelNotes/2.34.1.txt b/Documentation/RelNotes/2.34.1.txt new file mode 100644 index 0000000000..ad404e9aa0 --- /dev/null +++ b/Documentation/RelNotes/2.34.1.txt @@ -0,0 +1,23 @@ +Git v2.34.1 Release Notes +========================= + +This release is primarily to fix a handful of regressions in Git 2.34. + +Fixes since v2.34 +----------------- + + * "git grep" looking in a blob that has non-UTF8 payload was + completely broken when linked with certain versions of PCREv2 + library in the latest release. + + * "git pull" with any strategy when the other side is behind us + should succeed as it is a no-op, but doesn't. + + * An earlier change in 2.34.0 caused JGit application (that abused + GIT_EDITOR mechanism when invoking "git config") to get stuck with + a SIGTTOU signal; it has been reverted. + + * An earlier change that broke .gitignore matching has been reverted. + + * SubmittingPatches document gained a syntactically incorrect mark-up, + which has been corrected. diff --git a/Documentation/RelNotes/2.35.0.txt b/Documentation/RelNotes/2.35.0.txt new file mode 100644 index 0000000000..d69b50d180 --- /dev/null +++ b/Documentation/RelNotes/2.35.0.txt @@ -0,0 +1,412 @@ +Git 2.35 Release Notes +====================== + +Updates since Git 2.34 +---------------------- + +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 + + * "git status --porcelain=v2" now show the number of stash entries + with --show-stash like the normal output does. + + * "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. + + * The use of errno as a means to carry the nature of error in the ref + API implementation has been reworked and reduced. + + * Teach and encourage first-time contributors to this project to + state the base commit when they submit their topic. + + * 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 +----------------- + + * "git grep" looking in a blob that has non-UTF8 payload was + completely broken when linked with certain versions of PCREv2 + library in the latest release. + + * Other code cleanup, docfix, build fix, etc. + + * "git pull" with any strategy when the other side is behind us + should succeed as it is a no-op, but doesn't. + + * An earlier change in 2.34.0 caused JGit application (that abused + GIT_EDITOR mechanism when invoking "git config") to get stuck with + a SIGTTOU signal; it has been reverted. + + * An earlier change that broke .gitignore matching has been reverted. + + * Things like "git -c branch.sort=bogus branch new HEAD", i.e. the + operation modes of the "git branch" command that do not need the + sort key information, no longer errors out by seeing a bogus sort + key. + (merge 98e7ab6d42 jc/fix-ref-sorting-parse later to maint). + + * The compatibility implementation for unsetenv(3) were written to + mimic ancient, non-POSIX, variant seen in an old glibc; it has been + changed to return an integer to match the more modern era. + (merge a38989bd5b jc/unsetenv-returns-an-int later to maint). + + * 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/SubmittingPatches b/Documentation/SubmittingPatches index e409022d93..92b80d94d4 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 @@ -144,8 +151,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 +279,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 +387,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] @@ -448,7 +473,7 @@ their trees themselves. entitled "What's cooking in git.git" and "What's in git.git" giving the status of various proposed changes. -== GitHub CI[[GHCI]]] +== GitHub CI[[GHCI]] With an account at GitHub, you can use GitHub CI to test your changes on Linux, Mac and Windows. See @@ -463,7 +488,7 @@ Follow these steps for the initial setup: After the initial setup, CI will run whenever you push new changes to your fork of Git on GitHub. You can monitor the test state of all your -branches here: https://github.com/<Your GitHub handle>/git/actions/workflows/main.yml +branches here: `https://github.com/<Your GitHub handle>/git/actions/workflows/main.yml` If a branch did not pass all test cases then it is marked with a red cross. In that case you can click on the failing job and navigate to diff --git a/Documentation/config.txt b/Documentation/config.txt index 1167e88e34..b168f02dc3 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -262,11 +262,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 +288,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. + diff --git a/Documentation/config/branch.txt b/Documentation/config/branch.txt index d323d7327f..1e0c7af014 100644 --- a/Documentation/config/branch.txt +++ b/Documentation/config/branch.txt @@ -7,7 +7,8 @@ branch.autoSetupMerge:: automatic setup is done; `true` -- automatic setup is done when the starting point is a remote-tracking branch; `always` -- automatic setup is done when the starting point is either a - local branch or remote-tracking + local branch or remote-tracking branch; `inherit` -- if the starting point + has a tracking configuration, it is copied to the new branch. This option defaults to true. branch.autoSetupRebase:: diff --git a/Documentation/config/gpg.txt b/Documentation/config/gpg.txt index 4f30c7dbdd..0cb189a077 100644 --- a/Documentation/config/gpg.txt +++ b/Documentation/config/gpg.txt @@ -34,7 +34,7 @@ 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 @@ -44,7 +44,7 @@ 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 signatures 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/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/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-branch.txt b/Documentation/git-branch.txt index 8af42eff89..731e340cbc 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -16,7 +16,7 @@ SYNOPSIS [--points-at <object>] [--format=<format>] [(-r | --remotes) | (-a | --all)] [--list] [<pattern>...] -'git branch' [--track | --no-track] [-f] <branchname> [<start-point>] +'git branch' [--track[=(direct|inherit)] | --no-track] [-f] <branchname> [<start-point>] 'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>] 'git branch' --unset-upstream [<branchname>] 'git branch' (-m | -M) [<oldbranch>] <newbranch> @@ -206,24 +206,34 @@ This option is only applicable in non-verbose mode. Display the full sha1s in the output listing rather than abbreviating them. -t:: ---track:: +--track[=(direct|inherit)]:: When creating a new branch, set up `branch.<name>.remote` and - `branch.<name>.merge` configuration entries to mark the - start-point branch as "upstream" from the new branch. This + `branch.<name>.merge` configuration entries to set "upstream" tracking + configuration for the new branch. This configuration will tell git to show the relationship between the two branches in `git status` and `git branch -v`. Furthermore, it directs `git pull` without arguments to pull from the upstream when the new branch is checked out. + -This behavior is the default when the start point is a remote-tracking branch. +The exact upstream branch is chosen depending on the optional argument: +`-t`, `--track`, or `--track=direct` means to use the start-point branch +itself as the upstream; `--track=inherit` means to copy the upstream +configuration of the start-point branch. ++ +`--track=direct` is the default when the start point is a remote-tracking branch. Set the branch.autoSetupMerge configuration variable to `false` if you want `git switch`, `git checkout` and `git branch` to always behave as if `--no-track` were given. Set it to `always` if you want this behavior when the -start-point is either a local or remote-tracking branch. +start-point is either a local or remote-tracking branch. Set it to +`inherit` if you want to copy the tracking configuration from the +branch point. ++ +See linkgit:git-pull[1] and linkgit:git-config[1] for additional discussion on +how the `branch.<name>.remote` and `branch.<name>.merge` options are used. --no-track:: Do not set up "upstream" configuration, even if the - branch.autoSetupMerge configuration variable is true. + branch.autoSetupMerge configuration variable is set. --set-upstream:: As this option had confusing syntax, it is no longer supported. diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index d473c9bf38..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,18 +145,18 @@ 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. -t:: ---track:: +--track[=(direct|inherit)]:: When creating a new branch, set up "upstream" configuration. See "--track" in 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..984d194934 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -9,10 +9,10 @@ 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] @@ -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 @@ -211,7 +211,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 +294,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..2285effb36 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 @@ -145,8 +145,8 @@ See also <<FILES>>. read from or written to if `extensions.worktreeConfig` is present. If not it's the same as `--local`. --f config-file:: ---file config-file:: +-f <config-file>:: +--file <config-file>:: For writing options: write to the specified file rather than the repository `.git/config`. + @@ -155,7 +155,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 +246,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-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..44ea63cc6d 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -9,14 +9,14 @@ SYNOPSIS -------- [verse] 'git help' [-a|--all [--[no-]verbose]] - [[-i|--info] [-m|--man] [-w|--web]] [COMMAND|GUIDE] + [[-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. 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-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..48cc7c0b6f 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>] @@ -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-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-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-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..2bebc32566 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git remote' [-v | --verbose] -'git remote add' [-t <branch>] [-m <master>] [-f] [--[no-]tags] [--mirror=(fetch|push)] <name> <url> +'git remote add' [-t <branch>] [-m <master>] [-f] [--[no-]tags] [--mirror=(fetch|push)] <name> <URL> 'git remote rename' <old> <new> 'git remote remove' <name> 'git remote set-head' <name> (-a | --auto | -d | --delete | <branch>) @@ -18,7 +18,7 @@ SYNOPSIS '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-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-send-email.txt b/Documentation/git-send-email.txt index 3db4eab4ba..41cd8cb424 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -9,7 +9,8 @@ git-send-email - Send a collection of patches as emails SYNOPSIS -------- [verse] -'git send-email' [<options>] <file|directory|rev-list options>... +'git send-email' [<options>] <file|directory>... +'git send-email' [<options>] <format-patch options> 'git send-email' --dump-aliases @@ -19,7 +20,8 @@ Takes the patches given on the command line and emails them out. Patches can be specified as files, directories (which will send all files in the directory), or directly as a revision list. In the last case, any format accepted by linkgit:git-format-patch[1] can -be passed to git send-email. +be passed to git send-email, as well as options understood by +linkgit:git-format-patch[1]. The header of the email is configurable via command-line options. If not specified on the command line, the user will be prompted with a ReadLine 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..b81dbe0654 100644 --- a/Documentation/git-sparse-checkout.txt +++ b/Documentation/git-sparse-checkout.txt @@ -11,7 +11,7 @@ given by a list of patterns. SYNOPSIS -------- [verse] -'git sparse-checkout <subcommand> [options]' +'git sparse-checkout <subcommand> [<options>]' DESCRIPTION @@ -30,28 +30,36 @@ COMMANDS 'list':: Describe the 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 config settings + (extensions.worktreeConfig, core.sparseCheckout, + core.sparseCheckoutCone) if they are not already enabled, 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. +When the `--stdin` option is provided, the patterns are read from +standard in as a newline-delimited list instead of from the arguments. + -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 `--cone` is passed or `core.sparseCheckoutCone` is enabled, the +input list is considered a list of directories instead of +sparse-checkout patterns. This allows for better performance with a +limited set of patterns (see 'CONE PATTERN SET' below). 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. 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. This may become the default in the future; --no-cone +can be passed to request non-cone mode. + -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. +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,23 +68,6 @@ 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, @@ -93,12 +84,35 @@ 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 --------------- @@ -107,7 +121,7 @@ SPARSE CHECKOUT 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 +directory. 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. @@ -117,10 +131,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-stash.txt b/Documentation/git-stash.txt index be6084ccef..6e15f47525 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -13,7 +13,7 @@ SYNOPSIS 'git stash' drop [-q|--quiet] [<stash>] 'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>] 'git stash' branch <branchname> [<stash>] -'git stash' [push [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet] +'git stash' [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet] [-u|--include-untracked] [-a|--all] [-m|--message <message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...]] @@ -47,7 +47,7 @@ stash index (e.g. the integer `n` is equivalent to `stash@{n}`). COMMANDS -------- -push [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [-m|--message <message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...]:: +push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [-m|--message <message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...]:: Save your local modifications to a new 'stash entry' and roll them back to HEAD (in the working tree and in the index). @@ -60,7 +60,7 @@ subcommand from making an unwanted stash entry. The two exceptions to this are `stash -p` which acts as alias for `stash push -p` and pathspec elements, which are allowed after a double hyphen `--` for disambiguation. -save [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [<message>]:: +save [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [<message>]:: This option is deprecated in favour of 'git stash push'. It differs from "stash push" in that it cannot take pathspec. @@ -205,6 +205,16 @@ to learn how to operate the `--patch` mode. The `--patch` option implies `--keep-index`. You can use `--no-keep-index` to override this. +-S:: +--staged:: + This option is only valid for `push` and `save` commands. ++ +Stash only the changes that are currently staged. This is similar to +basic `git commit` except the state is committed to the stash instead +of current branch. ++ +The `--patch` option has priority over this one. + --pathspec-from-file=<file>:: This option is only valid for `push` command. + @@ -341,6 +351,24 @@ $ edit/build/test remaining parts $ git commit foo -m 'Remaining parts' ---------------------------------------------------------------- +Saving unrelated changes for future use:: + +When you are in the middle of massive changes and you find some +unrelated issue that you don't want to forget to fix, you can do the +change(s), stage them, and use `git stash push --staged` to stash them +out for future use. This is similar to committing the staged changes, +only the commit ends-up being in the stash and not on the current branch. ++ +---------------------------------------------------------------- +# ... hack hack hack ... +$ git add --patch foo # add unrelated changes to the index +$ git stash push --staged # save these changes to the stash +# ... hack hack hack, finish curent changes ... +$ git commit -m 'Massive' # commit fully tested changes +$ git switch fixup-branch # switch to another branch +$ git stash pop # to finish work on the saved changes +---------------------------------------------------------------- + Recovering stash entries that were cleared/dropped erroneously:: If you mistakenly drop or clear stash entries, they cannot be recovered diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 4a2c3e0408..54a4b29b47 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -314,6 +314,14 @@ Line Notes ------------------------------------------------------------ .... +Stash Information +^^^^^^^^^^^^^^^^^ + +If `--show-stash` is given, one line is printed showing the number of stash +entries if non-zero: + + # stash <N> + Changed Tracked Entries ^^^^^^^^^^^^^^^^^^^^^^^ 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 5c438cd505..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:: @@ -152,7 +151,7 @@ should result in deletion of the path). attached to a terminal, regardless of `--quiet`. -t:: ---track:: +--track [direct|inherit]:: When creating a new branch, set up "upstream" configuration. `-c` is implied. See `--track` in linkgit:git-branch[1] for details. 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..9e862fbcf7 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>] 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/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/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/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..43a86fa562 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -1047,7 +1047,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/multi-pack-index.txt b/Documentation/technical/multi-pack-index.txt index 86f40f2490..b39c69da8c 100644 --- a/Documentation/technical/multi-pack-index.txt +++ b/Documentation/technical/multi-pack-index.txt @@ -17,12 +17,12 @@ 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. Thus, we can provide O(log N) lookup time for any number @@ -87,11 +87,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/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/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. |