diff options
Diffstat (limited to 'Documentation')
94 files changed, 2501 insertions, 1295 deletions
diff --git a/Documentation/BreakingChanges.adoc b/Documentation/BreakingChanges.adoc index ac9a84c17b..c6bd94986c 100644 --- a/Documentation/BreakingChanges.adoc +++ b/Documentation/BreakingChanges.adoc @@ -178,6 +178,11 @@ references. + These features will be removed. +* Support for "--stdin" option in the "name-rev" command was + deprecated (and hidden from the documentation) in the Git 2.40 + timeframe, in preference to its synonym "--annotate-stdin". Git 3.0 + removes the support for "--stdin" altogether. + * The git-whatchanged(1) command has outlived its usefulness more than 10 years ago, and takes more keystrokes to type than its rough equivalent `git log --raw`. We have nominated the command for diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index a0e7041c54..6350949f2e 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -315,6 +315,9 @@ For C programs: encouraged to have a blank line between the end of the declarations and the first statement in the block. + - Do not explicitly initialize global variables to 0 or NULL; + instead, let BSS take care of the zero initialization. + - NULL pointers shall be written as NULL, not as 0. - When declaring pointers, the star sides with the variable @@ -861,6 +864,9 @@ Markup: _<git-dir>_ _<key-id>_ +Characters are also surrounded by underscores: + _LF_, _CR_, _CR_/_LF_, _NUL_, _EOF_ + Git's Asciidoc processor has been tailored to treat backticked text as complex synopsis. When literal and placeholders are mixed, you can use the backtick notation which will take care of correctly typesetting @@ -874,6 +880,17 @@ Markup: As a side effect, backquoted placeholders are correctly typeset, but this style is not recommended. + When documenting multiple related `git config` variables, place them on + a separate line instead of separating them by commas. For example, do + not write this: + `core.var1`, `core.var2`:: + Description common to `core.var1` and `core.var2`. + +Instead write this: + `core.var1`:: + `core.var2`:: + Description common to `core.var1` and `core.var2`. + Synopsis Syntax The synopsis (a paragraph with [synopsis] attribute) is automatically diff --git a/Documentation/Makefile b/Documentation/Makefile index 671267a8ac..df2ce187eb 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -109,6 +109,7 @@ SP_ARTICLES += howto/coordinate-embargoed-releases API_DOCS = $(patsubst %.adoc,%,$(filter-out technical/api-index-skel.adoc technical/api-index.adoc, $(wildcard technical/api-*.adoc))) SP_ARTICLES += $(API_DOCS) +TECH_DOCS += BreakingChanges TECH_DOCS += DecisionMaking TECH_DOCS += ReviewingGuidelines TECH_DOCS += MyFirstContribution @@ -316,8 +317,8 @@ cmds_txt = cmds-ancillaryinterrogators.adoc \ $(cmds_txt): cmd-list.made -cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT) - $(QUIET_GEN)$(PERL_PATH) ./cmd-list.perl .. . $(cmds_txt) && \ +cmd-list.made: cmd-list.sh ../command-list.txt $(MAN1_TXT) + $(QUIET_GEN)$(SHELL_PATH) ./cmd-list.sh .. . $(cmds_txt) && \ date >$@ mergetools-%.adoc: generate-mergetool-list.sh ../git-mergetool--lib.sh $(wildcard ../mergetools/*) @@ -397,9 +398,9 @@ user-manual.html: user-manual.xml $(XSLT) git.info: user-manual.texi $(QUIET_MAKEINFO)$(MAKEINFO) --no-split -o $@ user-manual.texi -user-manual.texi: user-manual.xml +user-manual.texi: user-manual.xml fix-texi.sh $(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout >$@+ && \ - $(PERL_PATH) fix-texi.perl <$@+ >$@ && \ + $(SHELL_PATH) fix-texi.sh <$@+ >$@ && \ $(RM) $@+ user-manual.pdf: user-manual.xml @@ -509,7 +510,12 @@ lint-docs-meson: awk "/^manpages = {$$/ {flag=1 ; next } /^}$$/ { flag=0 } flag { gsub(/^ \047/, \"\"); gsub(/\047 : [157],\$$/, \"\"); print }" meson.build | \ grep -v -e '#' -e '^$$' | \ sort >tmp-meson-diff/meson.adoc && \ - ls git*.adoc scalar.adoc | grep -v -e git-bisect-lk2009.adoc -e git-tools.adoc >tmp-meson-diff/actual.adoc && \ + ls git*.adoc scalar.adoc | \ + grep -v -e git-bisect-lk2009.adoc \ + -e git-pack-redundant.adoc \ + -e git-tools.adoc \ + -e git-whatchanged.adoc \ + >tmp-meson-diff/actual.adoc && \ if ! cmp tmp-meson-diff/meson.adoc tmp-meson-diff/actual.adoc; then \ echo "Meson man pages differ from actual man pages:"; \ diff -u tmp-meson-diff/meson.adoc tmp-meson-diff/actual.adoc; \ diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc index afcf4b46c1..aca7212cfe 100644 --- a/Documentation/MyFirstContribution.adoc +++ b/Documentation/MyFirstContribution.adoc @@ -40,14 +40,6 @@ the list by sending an email to <git+subscribe@vger.kernel.org> The https://lore.kernel.org/git[archive] of this mailing list is available to view in a browser. -==== https://groups.google.com/forum/#!forum/git-mentoring[git-mentoring@googlegroups.com] - -This mailing list is targeted to new contributors and was created as a place to -post questions and receive answers outside of the public eye of the main list. -Veteran contributors who are especially interested in helping mentor newcomers -are present on the list. In order to avoid search indexers, group membership is -required to view messages; anyone can join and no approval is required. - ==== https://web.libera.chat/#git-devel[#git-devel] on Libera Chat This IRC channel is for conversations between Git contributors. If someone is @@ -150,15 +142,31 @@ command in `builtin/psuh.c`. Create that file, and within it, write the entry point for your command in a function matching the style and signature: ---- -int cmd_psuh(int argc, const char **argv, const char *prefix) +int cmd_psuh(int argc UNUSED, const char **argv UNUSED, + const char *prefix UNUSED, struct repository *repo UNUSED) ---- +A few things to note: + +* A subcommand implementation takes its command line arguments + in `int argc` + `const char **argv`, like `main()` would. + +* It also takes two extra parameters, `prefix` and `repo`. What + they mean will not be discussed until much later. + +* Because this first example will not use any of the parameters, + your compiler will give warnings on unused parameters. As the + list of these four parameters is mandated by the API to add + new built-in commands, you cannot omit them. Instead, you add + `UNUSED` to each of them to tell the compiler that you *know* + you are not (yet) using it. + We'll also need to add the declaration of psuh; open up `builtin.h`, find the declaration for `cmd_pull`, and add a new line for `psuh` immediately before it, in order to keep the declarations alphabetically sorted: ---- -int cmd_psuh(int argc, const char **argv, const char *prefix); +int cmd_psuh(int argc, const char **argv, const char *prefix, struct repository *repo); ---- Be sure to `#include "builtin.h"` in your `psuh.c`. You'll also need to @@ -174,7 +182,8 @@ Throughout the tutorial, we will mark strings for translation as necessary; you should also do so when writing your user-facing commands in the future. ---- -int cmd_psuh(int argc, const char **argv, const char *prefix) +int cmd_psuh(int argc UNUSED, const char **argv UNUSED, + const char *prefix UNUSED, struct repository *repo UNUSED) { printf(_("Pony saying hello goes here.\n")); return 0; @@ -287,8 +296,9 @@ on the reference implementation linked at the top of this document. It's probably useful to do at least something besides printing out a string. Let's start by having a look at everything we get. -Modify your `cmd_psuh` implementation to dump the args you're passed, keeping -existing `printf()` calls in place: +Modify your `cmd_psuh` implementation to dump the args you're passed, +keeping existing `printf()` calls in place; because the args are now +used, remove the `UNUSED` macro from them: ---- int i; @@ -312,7 +322,8 @@ on the command line, including the name of our command. (If `prefix` is empty for you, try `cd Documentation/ && ../bin-wrappers/git psuh`). That's not so helpful. So what other context can we get? -Add a line to `#include "config.h"`. Then, add the following bits to the +Add a line to `#include "config.h"` and `#include "repository.h"`. +Then, add the following bits to the function body: function body: ---- @@ -320,18 +331,18 @@ function body: ... - git_config(git_default_config, NULL); - if (git_config_get_string_tmp("user.name", &cfg_name) > 0) + repo_config(repo, git_default_config, NULL); + if (repo_config_get_string_tmp(repo, "user.name", &cfg_name)) printf(_("No name is found in config\n")); else printf(_("Your name: %s\n"), cfg_name); ---- -`git_config()` will grab the configuration from config files known to Git and -apply standard precedence rules. `git_config_get_string_tmp()` will look up +`repo_config()` will grab the configuration from config files known to Git and +apply standard precedence rules. `repo_config_get_string_tmp()` will look up a specific key ("user.name") and give you the value. There are a number of single-key lookup functions like this one; you can see them all (and more info -about how to use `git_config()`) in `Documentation/technical/api-config.adoc`. +about how to use `repo_config()`) in `Documentation/technical/api-config.adoc`. You should see that the name printed matches the one you see when you run: @@ -364,9 +375,10 @@ status_init_config(&s, git_status_config); ---- But as we drill down, we can find that `status_init_config()` wraps a call -to `git_config()`. Let's modify the code we wrote in the previous commit. +to `repo_config()`. Let's modify the code we wrote in the previous commit. Be sure to include the header to allow you to use `struct wt_status`: + ---- #include "wt-status.h" ---- @@ -379,8 +391,8 @@ prepare it, and print its contents: ... - wt_status_prepare(the_repository, &status); - git_config(git_default_config, &status); + wt_status_prepare(repo, &status); + repo_config(repo, git_default_config, &status); ... diff --git a/Documentation/MyFirstObjectWalk.adoc b/Documentation/MyFirstObjectWalk.adoc index 102a465a48..413a9fdb05 100644 --- a/Documentation/MyFirstObjectWalk.adoc +++ b/Documentation/MyFirstObjectWalk.adoc @@ -43,7 +43,7 @@ Open up a new file `builtin/walken.c` and set up the command handler: #include "builtin.h" #include "trace.h" -int cmd_walken(int argc, const char **argv, const char *prefix) +int cmd_walken(int argc, const char **argv, const char *prefix, struct repository *repo) { trace_printf(_("cmd_walken incoming...\n")); return 0; @@ -86,7 +86,7 @@ int cmd_walken(int argc, const char **argv, const char *prefix) Also add the relevant line in `builtin.h` near `cmd_version()`: ---- -int cmd_walken(int argc, const char **argv, const char *prefix); +int cmd_walken(int argc, const char **argv, const char *prefix, struct repository *repo); ---- Include the command in `git.c` in `commands[]` near the entry for `version`, @@ -96,10 +96,23 @@ maintaining alphabetical ordering: { "walken", cmd_walken, RUN_SETUP }, ---- -Add it to the `Makefile` near the line for `builtin/worktree.o`: +Add an entry for the new command in the both the Make and Meson build system, +before the entry for `worktree`: +- In the `Makefile`: ---- +... BUILTIN_OBJS += builtin/walken.o +... +---- + +- In the `meson.build` file: +---- +builtin_sources = [ + ... + 'builtin/walken.c', + ... +] ---- Build and test out your command, without forgetting to ensure the `DEVELOPER` @@ -193,7 +206,7 @@ initialization functions. Next, we should have a look at any relevant configuration settings (i.e., settings readable and settable from `git config`). This is done by providing a -callback to `git_config()`; within that callback, you can also invoke methods +callback to `repo_config()`; within that callback, you can also invoke methods from other components you may need that need to intercept these options. Your callback will be invoked once per each configuration value which Git knows about (global, local, worktree, etc.). @@ -221,14 +234,14 @@ static int git_walken_config(const char *var, const char *value, } ---- -Make sure to invoke `git_config()` with it in your `cmd_walken()`: +Make sure to invoke `repo_config()` with it in your `cmd_walken()`: ---- -int cmd_walken(int argc, const char **argv, const char *prefix) +int cmd_walken(int argc, const char **argv, const char *prefix, struct repository *repo) { ... - git_config(git_walken_config, NULL); + repo_config(repo, git_walken_config, NULL); ... } @@ -250,14 +263,14 @@ We'll also need to include the `revision.h` header: ... -int cmd_walken(int argc, const char **argv, const char *prefix) +int cmd_walken(int argc, const char **argv, const char *prefix, struct repository *repo) { /* This can go wherever you like in your declarations.*/ struct rev_info rev; ... - /* This should go after the git_config() call. */ - repo_init_revisions(the_repository, &rev, prefix); + /* This should go after the repo_config() call. */ + repo_init_revisions(repo, &rev, prefix); ... } @@ -287,6 +300,7 @@ static void final_rev_info_setup(struct rev_info *rev) ==== Instead of using the shorthand `add_head_to_pending()`, you could do something like this: + ---- struct setup_revision_opt opt; @@ -295,6 +309,7 @@ something like this: opt.revarg_opt = REVARG_COMMITTISH; setup_revisions(argc, argv, rev, &opt); ---- + Using a `setup_revision_opt` gives you finer control over your walk's starting point. ==== @@ -303,7 +318,7 @@ Then let's invoke `final_rev_info_setup()` after the call to `repo_init_revisions()`: ---- -int cmd_walken(int argc, const char **argv, const char *prefix) +int cmd_walken(int argc, const char **argv, const char *prefix, struct repository *repo) { ... diff --git a/Documentation/RelNotes/2.50.0.adoc b/Documentation/RelNotes/2.50.0.adoc new file mode 100644 index 0000000000..e85747335b --- /dev/null +++ b/Documentation/RelNotes/2.50.0.adoc @@ -0,0 +1,441 @@ +Git v2.50 Release Notes +======================= + +UI, Workflows & Features +------------------------ + + * A post-processing filter for "diff --raw" output has been + introduced. + + * "git repack" learned "--combine-cruft-below-size" option that + controls how cruft-packs are combined. + + * TCP keepalive behaviour on http transports can now be configured by + calling cURL library. + + * Incrementally updating multi-pack index files. + + * "git reflog" learns "drop" subcommand, that discards the entire + reflog data for a ref. + + * A new userdiff driver for ".ini" format configuration files has + been added. + + * The job to coalesce loose objects into packfiles in "git + maintenance" now has configurable batch size. + + * "git clone" still gave the message about the default branch name; + this message has been turned into an advice message that can be + turned off. + + * "git rev-list" learns machine-parsable output format that delimits + each field with NUL. + + * "git maintenance" learns a new task to expire reflog entries. + + * Auth-related (and unrelated) error handling in send-email has been + made more robust. + + * Updating multiple references have only been possible in an all-or-nothing + fashion with transactions, but it can be more efficient to batch + multiple updates even when some of them are allowed to fail in a + best-effort manner. A new "best effort batches of updates" mode + has been introduced. + + * "git help --build-options" reports SHA-1 and SHA-256 backends used + in the build. + + * "git cat-file --batch" and friends learned to allow "--filter=" to + omit certain objects, just like the transport layer does. + + * "git blame --porcelain" mode now talks about unblamable lines and + lines that are blamed to an ignored commit. + + * The build procedure installs bash (but not zsh) completion script. + + * send-email has been updated to work better with Outlook's SMTP server. + + * "git diff --minimal" used to give non-minimal output when its + optimization kicked in, which has been disabled. + + * "git index-pack --fix-thin" used to abort to prevent a cycle in + delta chains from forming in a corner case even when there is no + such cycle. + + * Make repository clean-up tasks that "gc" can do available to "git + maintenance" front-end. + + * Bundle-URI feature did not use refs recorded in the bundle other + than normal branches as anchoring points to optimize the follow-up + fetch during "git clone"; now it is told to utilize all. + + * The `send-email` documentation has been updated with OAuth2.0 + related examples. + + * Two of the "scalar" subcommands that add a repository that hasn't + been under "scalar"'s control are taught an option not to enable the + scheduled maintenance on it. + + * The userdiff pattern for shell scripts has been updated to cope + with more bash-isms. + + * "git merge-tree" learned an option to see if it resolves cleanly + without actually creating a result. + + * The commit title in the "rebase -i" todo file are now prefixed with + '#', just like a merge commit being replayed. + + * "git receive-pack" optionally learns not to care about connectivity + check, which can be useful when the repository arranges to ensure + connectivity by some other means. + + * "git notes --help" documentation updates. + + +Performance, Internal Implementation, Development Support etc. +-------------------------------------------------------------- + + * A handful of built-in command implementations have been rewritten + to use the repository instance supplied by git.c:run_builtin(), its + caller. + + * "git fsck" becomes more careful when checking the refs. + + * "git fast-export | git fast-import" learns to deal with commit and + tag objects with embedded signatures a bit better. This is highly + experimental and the format of the data stream may change in the + future without compatibility guarantees. + + * The code paths to check whether a refname X is available (by seeing + if another ref X/Y exists, etc.) have been optimized. + + * First step of deprecating and removing merge-recursive. + + * In protocol v2 where the refs advertisement is constrained, we try + to tell the server side not to limit the advertisement when there + is no specific need to, which has been the source of confusion and + recent bugs. Revamp the logic to simplify. + + * Update meson based build procedure for breaking changes support. + + * Enable -Wunreachable-code for developer builds. + + * Ensure what we write in assert() does not have side effects, + and introduce ASSERT() macro to mark those that cannot be + mechanically checked for lack of side effects. + + * Give more meaningful error return values from block writer layer of + the reftable ref-API backend. + + * Make the code in reftable library less reliant on the service + routines it used to borrow from Git proper, to make it easier to + use by external users of the library. + + * CI update. + + * The object layer has been updated to take an explicit repository + instance as a parameter in more code paths. + + * Some warnings from "-Wsign-compare" for builtin/rm.c have been + squelched. + + * A few traditional unit tests have been rewritten to use the clar + framework. + + * Some warnings from "-Wsign-compare" for pathspec.c have been + squelched. + + * "make test" used to have a hard dependency on (basic) Perl; tests + have been rewritten help environment with NO_PERL test the build as + much as possible. + + * Remove remnants of the recursive merge strategy backend, which was + superseded by the ort merge strategy. + + * Optimize the code to dedup references recorded in a bundle file. + + * Update parse-options API to catch mistakes to pass address of an + integral variable of a wrong type/size. + + * Since a call to repo_config() can be called with repo set to NULL + these days, a command that is marked as RUN_SETUP in the builtin + command table does not have to check repo with NULL before making + the call. + + * Overhaul of the reftable API. + + * Reduce requirement for Perl in our documentation build and a few + scripts. + + * The build procedure based on Meson learned to drive the + benchmarking tests. + + * Code clean-up for meson-based build infrastructure. + + * Add an equivalent to "make hdr-check" target to meson based builds. + + * Further code clean-up in the object-store layer. + + * Build performance fix. + + * Teach "git send-email" to also consult `hostname -f` for mail + domain to compute the identity given to SMTP servers. + + * The dependency on the_repository variable has been reduced from the + code paths in "git replay". + + * Support to create a loose object file with unknown object type has + been dropped. + + * The code path to access the "packed-refs" file while "fsck" is + taught to mmap the file, instead of reading the whole file into + memory. + + * Assorted fixes for issues found with CodeQL. + + * Remove the leftover hints to the test framework to mark tests that + do not pass the leak checker tests, as they should no longer be + needed. + + * When a stale .midx file refers to .pack files that no longer exist, + we ended up checking for these non-existent files repeatedly, which + has been optimized by memoizing the non-existence. + + * Build settings have been improved for BSD based systems. + + * Newer version of libcURL detected curl_easy_setopt() calls we made + with platform-natural "int" when we should have used "long", which + all have been corrected. + + * Tests that compare $HOME and $(pwd), which should be the same + directory unless the tests chdir's around, would fail when the user + enters the test directory via symbolic links, which has been + corrected. + + +Fixes since v2.49 +----------------- + + * The refname exclusion logic in the packed-ref backend has been + broken for some time, which confused upload-pack to advertise + different set of refs. This has been corrected. + (merge 10e8a9352b tb/refs-exclude-fixes later to maint). + + * The merge-recursive and merge-ort machinery crashed in corner cases + when certain renames are involved. + (merge 3adba40858 en/merge-process-renames-crash-fix later to maint). + + * Certain "cruft" objects would have never been refreshed when there + are multiple cruft packs in the repository, which has been + corrected. + (merge 08f612ba70 tb/multi-cruft-pack-refresh-fix later to maint). + + * The xdiff code on 32-bit platform misbehaved when an insanely large + context size is given, which has been corrected. + (merge d39e28e68c rs/xdiff-context-length-fix later to maint). + + * GitHub Actions CI switched on a CI/CD variable that does not exist + when choosing what packages to install etc., which has been + corrected. + (merge ee89f7c79d kn/ci-meson-check-build-docs-fix later to maint). + + * Using "git name-rev --stdin" as an example, improve the framework to + prepare tests to pretend to be in the future where the breaking + changes have already happened. + (merge de3dec1187 jc/name-rev-stdin later to maint). + + * An earlier code refactoring of the hash machinery missed a few + required calls to init_fn. + (merge d39f04b638 jh/hash-init-fixes later to maint). + + * A documentation page was left out from formatting and installation, + which has been corrected. + (merge ae85116f18 pw/build-breaking-changes-doc later to maint). + + * The bash command line completion script (in contrib/) has been + updated to cope with remote repository nicknames with slashes in + them. + (merge 778d2f1760 dm/completion-remote-names-fix later to maint). + + * "Dubious ownership" checks on Windows has been tightened up. + (merge 5bb88e89ef js/mingw-admins-are-special later to maint). + + * Layout configuration in vimdiff backend didn't work as advertised, + which has been corrected. + (merge 93bab2d04b fr/vimdiff-layout-fixes later to maint). + + * Fix our use of zlib corner cases. + (merge 1cb2f293f5 jk/zlib-inflate-fixes later to maint). + + * Fix lockfile contention in reftable code on Windows. + (merge 0a3dceabf1 ps/mingw-creat-excl-fix later to maint). + + * "git-merge-file" documentation source, which has lines that look + like conflict markers, lacked custom conflict marker size defined, + which has been corrected.. + (merge d3b5832381 pw/custom-conflict-marker-size-for-merge-related-docs later to maint). + + * Squelch false-positive from sparse. + (merge da87b58014 dd/sparse-glibc-workaround later to maint). + + * Adjust to the deprecation of use of Ubuntu 20.04 GitHub Actions CI. + (merge 832d9f6d0b js/ci-github-update-ubuntu later to maint). + + * Work around CI breakage due to fedora base image getting updated. + (merge 8a471a663b js/ci-fedora-gawk later to maint). + + * A ref transaction corner case fix. + (merge b9fadeead7 jt/ref-transaction-abort-fix later to maint). + + * Random build fixes. + (merge 85e1d6819f ps/misc-build-fixes later to maint). + + * "git fetch [<remote>]" with only the configured fetch refspec + should be the only thing to update refs/remotes/<remote>/HEAD, + but the code was overly eager to do so in other cases. + + * Incorrect sorting of refs with bytes with high-bit set on platforms + with signed char led to a BUG, which has been corrected. + + * "make perf" fixes. + (merge 1665f12fa0 pb/perf-test-fixes later to maint). + + * Doc mark-up updates. + (merge 5a5565ec44 ja/doc-reset-mv-rm-markup-updates later to maint). + + * Work around false positive from CodeQL checker. + (merge 0f558141ed js/range-check-codeql-workaround later to maint). + + * "git log --{left,right}-only A...B", when A and B does not share + any common ancestor, now behaves as expected. + (merge e7ef4be7c2 mh/left-right-limited later to maint). + + * Document the convention to disable hooks altogether by setting the + hooksPath configuration variable to /dev/null. + (merge 1b2eee94f1 ds/doc-disable-hooks later to maint). + + * Make sure outage of third-party sites that supply P4, Git-LFS, and + JGit we use for testing would not prevent our CI jobs from running + at all. + + * Various build tweaks, including CSPRNG selection on some platforms. + (merge cdda67de03 rj/build-tweaks later to maint). + + * Developer support fix.. + (merge 32b74b9809 js/git-perf-env-override later to maint). + + * Fix for scheduled maintenance tasks on platforms using launchctl. + (merge eb2d7beb0e jh/gc-launchctl-schedule-fix later to maint). + + * Update to arm64 Windows port (part of which had been reverted as it + broke builds for existing platforms, which may need to be redone in + future releases). + + * hashmap API clean-up to ensure hashmap_clear() leaves a cleared map + in a reusable state. + (merge 9481877de3 en/hashmap-clear-fix later to maint). + + * "git mv a a/b dst" would ask to move the directory 'a' itself, as + well as its contents, in a single destination directory, which is + a contradicting request that is impossible to satisfy. This case is + now detected and the command errors out. + (merge 974f0d4664 ps/mv-contradiction-fix later to maint). + + * Further refinement on CI messages when an optional external + software is unavailable (e.g. due to third-party service outage). + (merge 956acbefbd jc/ci-skip-unavailable-external-software later to maint). + + * Test result aggregation did not work in Meson based CI jobs. + (merge bd38ed5be1 ps/ci-test-aggreg-fix-for-meson later to maint). + + * Code clean-up around stale CI elements and building with Visual Studio. + (merge a7b060f67f js/ci-buildsystems-cleanup later to maint). + + * "git add 'f?o'" did not add 'foo' if 'f?o', an unusual pathname, + also existed on the working tree, which has been corrected. + (merge ec727e189c kj/glob-path-with-special-char later to maint). + + * The fallback implementation of open_nofollow() depended on + open("symlink", O_NOFOLLOW) to set errno to ELOOP, but a few BSD + derived systems use different errno, which has been worked around. + (merge f47bcc3413 cf/wrapper-bsd-eloop later to maint). + + * Use-after-free fix in the sequencer. + (merge 5dbaec628d pw/sequencer-reflog-use-after-free later to maint). + + * win+Meson CI pipeline, unlike other pipelines for Windows, + used to build artifacts in developer mode, which has been changed to + build them in release mode for consistency. + (merge 184abdcf05 js/ci-build-win-in-release-mode later to maint). + + * CI settings at GitLab has been updated to run MSVC based Meson job + automatically (as opposed to be done only upon manual request). + (merge 6389579b2f ps/ci-gitlab-enable-msvc-meson-job later to maint). + + * "git apply" and "git add -i/-p" code paths no longer unnecessarily + expand sparse-index while working. + (merge ecf9ba20e3 ds/sparse-apply-add-p later to maint). + + * Avoid adding directory path to a sparse-index tree entries to the + name-hash, since they would bloat the hashtable without anybody + querying for them. This was done already for a single threaded + part of the code, but now the multi-threaded code also does the + same. + (merge 2e60aabc75 am/sparse-index-name-hash-fix later to maint). + + * Recent versions of Perl started warning against "! A =~ /pattern/" + which does not negate the result of the matching. As it turns out + that the problematic function is not even called, it was removed. + (merge 67cae845d2 op/cvsserver-perl-warning later to maint). + + * "git apply --index/--cached" when applying a deletion patch in + reverse failed to give the mode bits of the path "removed" by the + patch to the file it creates, which has been corrected. + + * "git verify-refs" errored out in a repository in which + linked worktrees were prepared with Git 2.43 or lower. + (merge d5b3c38b8a sj/ref-contents-check-fix later to maint). + + * Update total_ram() function on BSD variants. + + * Update online_cpus() function on BSD variants. + + * Revert a botched bswap.h change that broke ntohll() functions on + big-endian systems with __builtin_bswap32/64(). + + * Fixes for GitHub Actions Coverity job. + (merge 3cc4fc1ebd js/github-ci-win-coverity-fix later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge 227c4f33a0 ja/doc-block-delimiter-markup-fix later to maint). + (merge 2bfd3b3685 ab/decorate-code-cleanup later to maint). + (merge 5337daddc7 am/dir-dedup-decl-of-repository later to maint). + (merge 554051d691 en/diff-rename-follow-fix later to maint). + (merge a18c18b470 en/random-cleanups later to maint). + (merge 5af21c9acb hj/doc-rev-list-ancestry-fix later to maint). + (merge 26d76ca284 aj/doc-restore-p-update later to maint). + (merge 2c0dcb9754 cc/lop-remote later to maint). + (merge 7b399322a2 ja/doc-branch-markup later to maint). + (merge ee434e1807 pw/doc-pack-refs-markup-fix later to maint). + (merge c000918eb7 tb/bitamp-typofix later to maint). + (merge fa8cd29676 js/imap-send-peer-cert-verify later to maint). + (merge 98b423bc1c rs/clear-commit-marks-simplify later to maint). + (merge 133d065dd6 ta/bulk-checkin-signed-compare-false-warning-fix later to maint). + (merge d2827dc31e es/meson-build-skip-coccinelle later to maint). + (merge ee8edb7156 dk/vimdiff-doc-fix later to maint). + (merge 107d889303 md/t1403-path-is-file later to maint). + (merge abd4192b07 js/comma-semicolon-confusion later to maint). + (merge 27b7264206 ab/environment-clean-header later to maint). + (merge ff4a749354 as/typofix-in-env-h-header later to maint). + (merge 86eef3541e az/tighten-string-array-constness later to maint). + (merge 25292c301d lo/remove-log-reencode-from-rev-info later to maint). + (merge 1aa50636fd jk/p5332-testfix later to maint). + (merge 42cf4ac552 ps/ci-resurrect-p4-on-github later to maint). + (merge 104add8368 js/diff-codeql-false-positive-workaround later to maint). + (merge f62977b93c en/get-tree-entry-doc later to maint). + (merge e5dd0a05ed ly/am-split-stgit-leakfix later to maint). + (merge bac220e154 rc/t1001-test-path-is-file later to maint). + (merge 91db6c735d ly/reftable-writer-leakfix later to maint). + (merge 20e4e9ad0b jc/doc-synopsis-option-markup later to maint). + (merge cddcee7f64 es/meson-configure-build-options-fix later to maint). + (merge cea9f55f00 wk/sparse-checkout-doc-fix later to maint). diff --git a/Documentation/RelNotes/2.51.0.adoc b/Documentation/RelNotes/2.51.0.adoc new file mode 100644 index 0000000000..89645da210 --- /dev/null +++ b/Documentation/RelNotes/2.51.0.adoc @@ -0,0 +1,84 @@ +Git v2.51 Release Notes +======================= + +UI, Workflows & Features +------------------------ + + * Userdiff patterns for the R language have been added. + + * Documentation for "git send-email" has been updated with a bit more + credential helper and OAuth information. + + * "git cat-file --batch" learns to understand %(objectmode) atom to + allow the caller to tell missing objects (due to repository + corruption) and submodules (whose commit objects are OK to be + missing) apart. + + * "git diff --no-index dirA dirB" can limit the comparison with + pathspec at the end of the command line, just like normal "git + diff". + + * "git subtree" (in contrib/) learned to grok GPG signing its commits. + + +Performance, Internal Implementation, Development Support etc. +-------------------------------------------------------------- + + * "git pack-objects" learned to find delta bases from blobs at the + same path, using the --path-walk API. + + * CodingGuidelines update. + + * Add settings for Solaris 10 & 11. + + * Meson-based build/test framework now understands TAP output + generated by our tests. + + * "Do not explicitly initialize to zero" rule has been clarified in + the CodingGuidelines document. + + +Fixes since v2.50 +----------------- + + * A memory-leak in an error code path has been plugged. + (merge 7082da85cb ly/commit-graph-graph-write-leakfix later to maint). + + * A memory-leak in an error code path has been plugged. + (merge aedebdb6b9 ly/fetch-pack-leakfix later to maint). + + * Some leftover references to documentation source files that no + longer exist, due to recent ".txt" -> ".adoc" renaming, have been + corrected. + (merge 3717a5775a jw/doc-txt-to-adoc-refs later to maint). + + * "git stash -p <pathspec>" improvements. + (merge 468817bab2 pw/stash-p-pathspec-fixes later to maint). + + * "git send-email" incremented its internal message counter when a + message was edited, which made logic that treats the first message + specially misbehave, which has been corrected. + (merge 2cc27b3501 ag/send-email-edit-threading-fix later to maint). + + * "git stash" recorded a wrong branch name when submodules are + present in the current checkout, which has been corrected. + (merge ffb36c64f2 kj/stash-onbranch-submodule-fix later to maint). + + * When asking to apply mailmap to both author and committer field + while showing a commit object, the field that appears later was not + correctly parsed and replaced, which has been corrected. + (merge abf94a283f sa/multi-mailmap-fix later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge b257adb571 lo/my-first-ow-doc-update later to maint). + (merge 8b34b6a220 ly/sequencer-update-squash-is-fixup-only later to maint). + (merge 5dceb8bd05 ly/do-not-localize-bug-messages later to maint). + (merge 61372dd613 ly/commit-buffer-reencode-leakfix later to maint). + (merge 81cd1eef7d ly/pack-bitmap-root-leakfix later to maint). + (merge bfc9f9cc64 ly/submodule-update-failure-leakfix later to maint). + (merge 65dff89c6b ma/doc-diff-cc-headers later to maint). + (merge efb61591ee jm/bundle-uri-debug-output-to-fp later to maint). + (merge a3d278bb64 ly/prepare-show-merge-leakfix later to maint). + (merge 1fde1c5daf ac/preload-index-wo-the-repository later to maint). + (merge 855cfc65ae rm/t2400-modernize later to maint). + (merge 2939494284 ly/run-builtin-use-passed-in-repo later to maint). diff --git a/Documentation/ToolsForGit.adoc b/Documentation/ToolsForGit.adoc index ae7690b45d..a842c13327 100644 --- a/Documentation/ToolsForGit.adoc +++ b/Documentation/ToolsForGit.adoc @@ -34,6 +34,7 @@ This is adapted from Linux's suggestion in its CodingStyle document: - To follow the rules in CodingGuidelines, it's useful to put the following in GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: + ---- ;; note the first part is useful for C editing, too ((nil . ((indent-tabs-mode . t) diff --git a/Documentation/asciidoc.conf.in b/Documentation/asciidoc.conf.in index f2aef6cb79..9d9139306e 100644 --- a/Documentation/asciidoc.conf.in +++ b/Documentation/asciidoc.conf.in @@ -43,7 +43,7 @@ ifdef::doctype-book[] endif::doctype-book[] [literal-inlinemacro] -{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'<emphasis>\1</emphasis>', re.sub(r'([\[\s|()>]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1<literal>\2</literal>', re.sub(r'(\.\.\.?)([^\]$.])', r'<literal>\1</literal>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))} +{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'<emphasis>\1</emphasis>', re.sub(r'([\[\s|()>]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@\\\*\/_^\$]+\.?)+|,)',r'\1<literal>\2</literal>', re.sub(r'(\.\.\.?)([^\]$.])', r'<literal>\1</literal>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))} endif::backend-docbook[] @@ -75,18 +75,18 @@ git-relative-html-prefix= <a href="{git-relative-html-prefix}{target}.html">{target}{0?({0})}</a> [literal-inlinemacro] -{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'<em>\1</em>', re.sub(r'([\[\s|()>]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1<code>\2</code>', re.sub(r'(\.\.\.?)([^\]$.])', r'<code>\1</code>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))} +{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'<em>\1</em>', re.sub(r'([\[\s|()>]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,\\\*\/_^\$]+\.?)+)',r'\1<code>\2</code>', re.sub(r'(\.\.\.?)([^\]$.])', r'<code>\1</code>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))} endif::backend-xhtml11[] ifdef::backend-docbook[] ifdef::doctype-manpage[] [paradef-default] -synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!<phrase>\\0</phrase>!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.]\\+\\|…\\)!\\1<literal>\\2</literal>!g;s!<[-a-zA-Z0-9.]\\+>!<emphasis>\\0</emphasis>!g'" +synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!<phrase>\\0</phrase>!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1<literal>\\2</literal>!g;s!<[-a-zA-Z0-9.]\\+>!<emphasis>\\0</emphasis>!g'" endif::doctype-manpage[] endif::backend-docbook[] ifdef::backend-xhtml11[] [paradef-default] -synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!<span>\\0</span>!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.]\\+\\|…\\)!\\1<code>\\2</code>!g;s!<[-a-zA-Z0-9.]\\+>!<em>\\0</em>!g'" +synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!<span>\\0</span>!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1<code>\\2</code>!g;s!<[-a-zA-Z0-9.]\\+>!<em>\\0</em>!g'" endif::backend-xhtml11[] diff --git a/Documentation/asciidoctor-extensions.rb.in b/Documentation/asciidoctor-extensions.rb.in index 2494f17a51..8b7b161349 100644 --- a/Documentation/asciidoctor-extensions.rb.in +++ b/Documentation/asciidoctor-extensions.rb.in @@ -49,8 +49,8 @@ module Git def process parent, reader, attrs outlines = reader.lines.map do |l| - l.gsub(/(\.\.\.?)([^\]$.])/, '`\1`\2') - .gsub(%r{([\[\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\$]+)}, '\1{empty}`\2`{empty}') + l.gsub(/(\.\.\.?)([^\]$\. ])/, '{empty}`\1`{empty}\2') + .gsub(%r{([\[\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\$\\\*]+)}, '\1{empty}`\2`{empty}') .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\1__') .gsub(']', ']{empty}') end @@ -71,8 +71,9 @@ module Git # unhandled math; pass source to alt and required mathphrase element; dblatex will process alt as LaTeX math %(<inlineequation><alt><![CDATA[#{equation = node.text}]]></alt><mathphrase><![CDATA[#{equation}]]></mathphrase></inlineequation>) elsif type == :monospaced - node.text.gsub(/(\.\.\.?)([^\]$.])/, '<literal>\1</literal>\2') - .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<literal>\2</literal>') + node.text.gsub(/(\.\.\.?)([^\]$\.])/, '<literal>\1</literal>\2') + .gsub(/^\.\.\.?$/, '<literal>\0</literal>') + .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@/_^\$\\\*]+\.{0,2})+|,)}, '\1<literal>\2</literal>') .gsub(/(<[-a-zA-Z0-9.]+>)/, '<emphasis>\1</emphasis>') else open, close, supports_phrase = QUOTE_TAGS[type] @@ -100,7 +101,8 @@ module Git def convert_inline_quoted node if node.type == :monospaced node.text.gsub(/(\.\.\.?)([^\]$.])/, '<code>\1</code>\2') - .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<code>\2</code>') + .gsub(/^\.\.\.?$/, '<code>\0</code>') + .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,/_^\$\\\*]+\.{0,2})+)}, '\1<code>\2</code>') .gsub(/(<[-a-zA-Z0-9.]+>)/, '<em>\1</em>') else diff --git a/Documentation/blame-options.adoc b/Documentation/blame-options.adoc index aa77406d4e..19ea187238 100644 --- a/Documentation/blame-options.adoc +++ b/Documentation/blame-options.adoc @@ -125,7 +125,8 @@ take effect. another commit will be marked with a `?` in the blame output. If the `blame.markUnblamableLines` config option is set, then those lines touched by an ignored commit that we could not attribute to another revision are - marked with a '*'. + marked with a '*'. In the porcelain modes, we print 'ignored' and + 'unblamable' on a newline respectively. --ignore-revs-file <file>:: Ignore revisions listed in `file`, which must be in the same format as an diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl deleted file mode 100755 index 0a0c1b3f61..0000000000 --- a/Documentation/cmd-list.perl +++ /dev/null @@ -1,80 +0,0 @@ -#!/usr/bin/perl -w - -use File::Compare qw(compare); - -sub format_one { - my ($source_dir, $out, $nameattr) = @_; - my ($name, $attr) = @$nameattr; - my ($path) = "$source_dir/Documentation/$name.adoc"; - my ($state, $description); - my $mansection; - $state = 0; - open I, '<', "$path" or die "No such file $path.adoc"; - while (<I>) { - if (/^(?:git|scalar)[a-z0-9-]*\(([0-9])\)$/) { - $mansection = $1; - next; - } - if (/^NAME$/) { - $state = 1; - next; - } - if ($state == 1 && /^----$/) { - $state = 2; - next; - } - next if ($state != 2); - chomp; - $description = $_; - last; - } - close I; - if (!defined $description) { - die "No description found in $path.adoc"; - } - if (my ($verify_name, $text) = ($description =~ /^($name) - (.*)/)) { - print $out "linkgit:$name\[$mansection\]::\n\t"; - if ($attr =~ / deprecated /) { - print $out "(deprecated) "; - } - print $out "$text.\n\n"; - } - else { - die "Description does not match $name: $description"; - } -} - -my ($source_dir, $build_dir, @categories) = @ARGV; - -open IN, "<$source_dir/command-list.txt"; -while (<IN>) { - last if /^### command list/; -} - -my %cmds = (); -for (sort <IN>) { - next if /^#/; - - chomp; - my ($name, $cat, $attr) = /^(\S+)\s+(.*?)(?:\s+(.*))?$/; - $attr = '' unless defined $attr; - push @{$cmds{$cat}}, [$name, " $attr "]; -} -close IN; - -for my $out (@categories) { - my ($cat) = $out =~ /^cmds-(.*)\.adoc$/; - my ($path) = "$build_dir/$out"; - open O, '>', "$path+" or die "Cannot open output file $out+"; - for (@{$cmds{$cat}}) { - format_one($source_dir, \*O, $_); - } - close O; - - if (-f "$path" && compare("$path", "$path+") == 0) { - unlink "$path+"; - } - else { - rename "$path+", "$path"; - } -} diff --git a/Documentation/cmd-list.sh b/Documentation/cmd-list.sh new file mode 100755 index 0000000000..077def3b72 --- /dev/null +++ b/Documentation/cmd-list.sh @@ -0,0 +1,104 @@ +#!/bin/sh + +set -e + +format_one () { + source_dir="$1" + command="$2" + attributes="$3" + + path="$source_dir/Documentation/$command.adoc" + if ! test -f "$path" + then + echo >&2 "No such file $path" + exit 1 + fi + + state=0 + while read line + do + case "$state" in + 0) + case "$line" in + git*\(*\)|scalar*\(*\)) + mansection="${line##*\(}" + mansection="${mansection%\)}" + ;; + NAME) + state=1;; + esac + ;; + 1) + if test "$line" = "----" + then + state=2 + fi + ;; + 2) + description="$line" + break + ;; + esac + done <"$path" + + if test -z "$mansection" + then + echo "No man section found in $path" >&2 + exit 1 + fi + + if test -z "$description" + then + echo >&2 "No description found in $path" + exit 1 + fi + + case "$description" in + "$command - "*) + text="${description#$command - }" + + printf "linkgit:%s[%s]::\n\t" "$command" "$mansection" + case "$attributes" in + *" deprecated "*) + printf "(deprecated) " + ;; + esac + printf "$text.\n\n" + ;; + *) + echo >&2 "Description does not match $command: $description" + exit 1 + ;; + esac +} + +source_dir="$1" +build_dir="$2" +shift 2 + +for out +do + category="${out#cmds-}" + category="${category%.adoc}" + path="$build_dir/$out" + + while read command command_category attributes + do + case "$command" in + "#"*) + continue;; + esac + + case "$command_category" in + "$category") + format_one "$source_dir" "$command" " $attributes ";; + esac + done <"$source_dir/command-list.txt" >"$build_dir/$out+" + + if cmp "$build_dir/$out+" "$build_dir/$out" >/dev/null 2>&1 + then + rm "$build_dir/$out+" + else + mv "$build_dir/$out+" "$build_dir/$out" + fi +done diff --git a/Documentation/config/branch.adoc b/Documentation/config/branch.adoc index 432b9cd2c0..e35ea7ac64 100644 --- a/Documentation/config/branch.adoc +++ b/Documentation/config/branch.adoc @@ -1,41 +1,42 @@ -branch.autoSetupMerge:: - Tells 'git branch', 'git switch' and 'git checkout' to set up new branches +`branch.autoSetupMerge`:: + Tells `git branch`, `git switch` and `git checkout` to set up new branches so that linkgit:git-pull[1] will appropriately merge from the starting point branch. Note that even if this option is not set, this behavior can be chosen per-branch using the `--track` - and `--no-track` options. The valid settings are: `false` -- no - 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 branch; `inherit` -- if the starting point - has a tracking configuration, it is copied to the new - branch; `simple` -- automatic setup is done only when the starting point + and `--no-track` options. This option defaults to `true`. The valid settings + are: +`false`;; no 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 branch +`inherit`;; if the starting point has a tracking configuration, it is copied to the new + branch +`simple`;; automatic setup is done only when the starting point is a remote-tracking branch and the new branch has the same name as the - remote branch. This option defaults to true. + remote branch. -branch.autoSetupRebase:: - When a new branch is created with 'git branch', 'git switch' or 'git checkout' +`branch.autoSetupRebase`:: + When a new branch is created with `git branch`, `git switch` or `git checkout` that tracks another branch, this variable tells Git to set - up pull to rebase instead of merge (see "branch.<name>.rebase"). - When `never`, rebase is never automatically set to true. - When `local`, rebase is set to true for tracked branches of - other local branches. - When `remote`, rebase is set to true for tracked branches of - remote-tracking branches. - When `always`, rebase will be set to true for all tracking - branches. - See "branch.autoSetupMerge" for details on how to set up a - branch to track another branch. - This option defaults to never. + up pull to rebase instead of merge (see `branch.<name>.rebase`). + The valid settings are: +`never`;; rebase is never automatically set to true. +`local`;; rebase is set to true for tracked branches of other local branches. +`remote`;; rebase is set to true for tracked branches of remote-tracking branches. +`always`;; rebase will be set to true for all tracking branches. -branch.sort:: ++ +See `branch.autoSetupMerge` for details on how to set up a branch to track another branch. +This option defaults to `never`. + +`branch.sort`:: This variable controls the sort ordering of branches when displayed by - linkgit:git-branch[1]. Without the "--sort=<value>" option provided, the + linkgit:git-branch[1]. Without the `--sort=<value>` option provided, the value of this variable will be used as the default. See linkgit:git-for-each-ref[1] field names for valid values. -branch.<name>.remote:: - When on branch <name>, it tells 'git fetch' and 'git push' +`branch.<name>.remote`:: + When on branch _<name>_, it tells `git fetch` and `git push` which remote to fetch from or push to. The remote to push to may be overridden with `remote.pushDefault` (for all branches). The remote to push to, for the current branch, may be further @@ -46,58 +47,58 @@ branch.<name>.remote:: Additionally, `.` (a period) is the current local repository (a dot-repository), see `branch.<name>.merge`'s final note below. -branch.<name>.pushRemote:: - When on branch <name>, it overrides `branch.<name>.remote` for +`branch.<name>.pushRemote`:: + When on branch _<name>_, it overrides `branch.<name>.remote` for pushing. It also overrides `remote.pushDefault` for pushing - from branch <name>. When you pull from one place (e.g. your + from branch _<name>_. When you pull from one place (e.g. your upstream) and push to another place (e.g. your own publishing repository), you would want to set `remote.pushDefault` to specify the remote to push to for all branches, and use this option to override it for a specific branch. -branch.<name>.merge:: - Defines, together with branch.<name>.remote, the upstream branch - for the given branch. It tells 'git fetch'/'git pull'/'git rebase' which - branch to merge and can also affect 'git push' (see push.default). - When in branch <name>, it tells 'git fetch' the default - refspec to be marked for merging in FETCH_HEAD. The value is +`branch.<name>.merge`:: + Defines, together with `branch.<name>.remote`, the upstream branch + for the given branch. It tells `git fetch`/`git pull`/`git rebase` which + branch to merge and can also affect `git push` (see `push.default`). + When in branch _<name>_, it tells `git fetch` the default + refspec to be marked for merging in `FETCH_HEAD`. The value is handled like the remote part of a refspec, and must match a ref which is fetched from the remote given by - "branch.<name>.remote". - The merge information is used by 'git pull' (which first calls - 'git fetch') to lookup the default branch for merging. Without - this option, 'git pull' defaults to merge the first refspec fetched. + `branch.<name>.remote`. + The merge information is used by `git pull` (which first calls + `git fetch`) to lookup the default branch for merging. Without + this option, `git pull` defaults to merge the first refspec fetched. Specify multiple values to get an octopus merge. - If you wish to setup 'git pull' so that it merges into <name> from + If you wish to setup `git pull` so that it merges into <name> from another branch in the local repository, you can point branch.<name>.merge to the desired branch, and use the relative path - setting `.` (a period) for branch.<name>.remote. + setting `.` (a period) for `branch.<name>.remote`. -branch.<name>.mergeOptions:: - Sets default options for merging into branch <name>. The syntax and +`branch.<name>.mergeOptions`:: + Sets default options for merging into branch _<name>_. The syntax and supported options are the same as those of linkgit:git-merge[1], but option values containing whitespace characters are currently not supported. -branch.<name>.rebase:: - When true, rebase the branch <name> on top of the fetched branch, +`branch.<name>.rebase`:: + When true, rebase the branch _<name>_ on top of the fetched branch, instead of merging the default branch from the default remote when - "git pull" is run. See "pull.rebase" for doing this in a non + `git pull` is run. See `pull.rebase` for doing this in a non branch-specific manner. + -When `merges` (or just 'm'), pass the `--rebase-merges` option to 'git rebase' +When `merges` (or just `m`), pass the `--rebase-merges` option to `git rebase` so that the local merge commits are included in the rebase (see linkgit:git-rebase[1] for details). + -When the value is `interactive` (or just 'i'), the rebase is run in interactive +When the value is `interactive` (or just `i`), the rebase is run in interactive mode. + *NOTE*: this is a possibly dangerous operation; do *not* use it unless you understand the implications (see linkgit:git-rebase[1] for details). -branch.<name>.description:: +`branch.<name>.description`:: Branch description, can be edited with `git branch --edit-description`. Branch description is - automatically added to the format-patch cover letter or - request-pull summary. + automatically added to the `format-patch` cover letter or + `request-pull` summary. diff --git a/Documentation/config/checkout.adoc b/Documentation/config/checkout.adoc index a323022993..e35d212969 100644 --- a/Documentation/config/checkout.adoc +++ b/Documentation/config/checkout.adoc @@ -1,9 +1,9 @@ -checkout.defaultRemote:: +`checkout.defaultRemote`:: When you run `git checkout <something>` or `git switch <something>` and only have one remote, it may implicitly fall back on checking out and tracking e.g. `origin/<something>`. This stops working as soon - as you have more than one remote with a `<something>` + as you have more than one remote with a _<something>_ reference. This setting allows for setting the name of a preferred remote that should always win when it comes to disambiguation. The typical use-case is to set this to @@ -12,17 +12,17 @@ checkout.defaultRemote:: Currently this is used by linkgit:git-switch[1] and linkgit:git-checkout[1] when `git checkout <something>` or `git switch <something>` -will checkout the `<something>` branch on another remote, +will checkout the _<something>_ branch on another remote, and by linkgit:git-worktree[1] when `git worktree add` refers to a remote branch. This setting might be used for other checkout-like commands or functionality in the future. -checkout.guess:: +`checkout.guess`:: Provides the default value for the `--guess` or `--no-guess` option in `git checkout` and `git switch`. See linkgit:git-switch[1] and linkgit:git-checkout[1]. -checkout.workers:: +`checkout.workers`:: The number of parallel workers to use when updating the working tree. The default is one, i.e. sequential execution. If set to a value less than one, Git will use as many workers as the number of logical cores @@ -30,13 +30,13 @@ checkout.workers:: all commands that perform checkout. E.g. checkout, clone, reset, sparse-checkout, etc. + -Note: Parallel checkout usually delivers better performance for repositories +NOTE: Parallel checkout usually delivers better performance for repositories located on SSDs or over NFS. For repositories on spinning disks and/or machines with a small number of cores, the default sequential checkout often performs better. The size and compression level of a repository might also influence how well the parallel version performs. -checkout.thresholdForParallelism:: +`checkout.thresholdForParallelism`:: When running parallel checkout with a small number of files, the cost of subprocess spawning and inter-process communication might outweigh the parallelization gains. This setting allows you to define the minimum diff --git a/Documentation/config/commit.adoc b/Documentation/config/commit.adoc index d3f4624fd2..208ae76c81 100644 --- a/Documentation/config/commit.adoc +++ b/Documentation/config/commit.adoc @@ -8,10 +8,11 @@ endif::git-commit[] This setting overrides the default of the `--cleanup` option in `git commit`. {see-git-commit} Changing the default can be useful when you always want to keep lines that begin - with the comment character `#` in your log message, in which case you + with the comment character (`core.commentChar`, default `#`) + in your log message, in which case you would do `git config commit.cleanup whitespace` (note that you will - have to remove the help lines that begin with `#` in the commit log - template yourself, if you do this). + have to remove the help lines that begin with the comment character + in the commit log template yourself, if you do this). `commit.gpgSign`:: A boolean to specify whether all commits should be GPG signed. diff --git a/Documentation/config/core.adoc b/Documentation/config/core.adoc index 8f6d8e7754..9fde1ab63a 100644 --- a/Documentation/config/core.adoc +++ b/Documentation/config/core.adoc @@ -512,6 +512,11 @@ centrally configure your Git hooks instead of configuring them on a per-repository basis, or as a more flexible and centralized alternative to having an `init.templateDir` where you've changed default hooks. ++ +You can also disable all hooks entirely by setting `core.hooksPath` +to `/dev/null`. This is usually only advisable for expert users and +on a per-command basis using configuration parameters of the form +`git -c core.hooksPath=/dev/null ...`. core.editor:: Commands such as `commit` and `tag` that let you edit diff --git a/Documentation/config/feature.adoc b/Documentation/config/feature.adoc index f061b64b74..cb49ff2604 100644 --- a/Documentation/config/feature.adoc +++ b/Documentation/config/feature.adoc @@ -20,6 +20,10 @@ walking fewer objects. + * `pack.allowPackReuse=multi` may improve the time it takes to create a pack by reusing objects from multiple packs instead of just one. ++ +* `pack.usePathWalk` may speed up packfile creation and make the packfiles be +significantly smaller in the presence of certain filename collisions with Git's +default name-hash. feature.manyFiles:: Enable config options that optimize for repos with many files in the diff --git a/Documentation/config/fmt-merge-msg.adoc b/Documentation/config/fmt-merge-msg.adoc index 3fbf40e24f..696ba0531a 100644 --- a/Documentation/config/fmt-merge-msg.adoc +++ b/Documentation/config/fmt-merge-msg.adoc @@ -1,19 +1,19 @@ -merge.branchdesc:: +`merge.branchdesc`:: In addition to branch names, populate the log message with the branch description text associated with them. Defaults to false. -merge.log:: +`merge.log`:: In addition to branch names, populate the log message with at most the specified number of one-line descriptions from the actual commits that are being merged. Defaults to false, and true is a synonym for 20. -merge.suppressDest:: +`merge.suppressDest`:: By adding a glob that matches the names of integration branches to this multi-valued configuration variable, the default merge message computed for merges into these - integration branches will omit "into <branch name>" from + integration branches will omit "into _<branch-name>_" from its title. + An element with an empty value can be used to clear the list diff --git a/Documentation/config/gitcvs.adoc b/Documentation/config/gitcvs.adoc index 02da427fd9..31d7be3992 100644 --- a/Documentation/config/gitcvs.adoc +++ b/Documentation/config/gitcvs.adoc @@ -47,7 +47,8 @@ gitcvs.dbDriver:: May not contain double colons (`:`). Default: 'SQLite'. See linkgit:git-cvsserver[1]. -gitcvs.dbUser, gitcvs.dbPass:: +gitcvs.dbUser:: +gitcvs.dbPass:: Database user and password. Only useful if setting `gitcvs.dbDriver`, since SQLite has no concept of database users and/or passwords. 'gitcvs.dbUser' supports variable substitution (see diff --git a/Documentation/config/http.adoc b/Documentation/config/http.adoc index 22a8803dea..9da5c298cc 100644 --- a/Documentation/config/http.adoc +++ b/Documentation/config/http.adoc @@ -289,13 +289,32 @@ for most push problems, but can increase memory consumption significantly since the entire buffer is allocated even for small pushes. -http.lowSpeedLimit, http.lowSpeedTime:: +http.lowSpeedLimit:: +http.lowSpeedTime:: If the HTTP transfer speed, in bytes per second, is less than 'http.lowSpeedLimit' for longer than 'http.lowSpeedTime' seconds, the transfer is aborted. Can be overridden by the `GIT_HTTP_LOW_SPEED_LIMIT` and `GIT_HTTP_LOW_SPEED_TIME` environment variables. +http.keepAliveIdle:: + Specifies how long in seconds to wait on an idle connection + before sending TCP keepalive probes (if supported by the OS). If + unset, curl's default value is used. Can be overridden by the + `GIT_HTTP_KEEPALIVE_IDLE` environment variable. + +http.keepAliveInterval:: + Specifies how long in seconds to wait between TCP keepalive + probes (if supported by the OS). If unset, curl's default value + is used. Can be overridden by the `GIT_HTTP_KEEPALIVE_INTERVAL` + environment variable. + +http.keepAliveCount:: + Specifies how many TCP keepalive probes to send before giving up + and terminating the connection (if supported by the OS). If + unset, curl's default value is used. Can be overridden by the + `GIT_HTTP_KEEPALIVE_COUNT` environment variable. + http.noEPSV:: A boolean which disables using of EPSV ftp command by curl. This can be helpful with some "poor" ftp servers which don't diff --git a/Documentation/config/maintenance.adoc b/Documentation/config/maintenance.adoc index 72a9d6cf81..2f71934218 100644 --- a/Documentation/config/maintenance.adoc +++ b/Documentation/config/maintenance.adoc @@ -61,6 +61,11 @@ maintenance.loose-objects.auto:: loose objects is at least the value of `maintenance.loose-objects.auto`. The default value is 100. +maintenance.loose-objects.batchSize:: + This integer config option controls the maximum number of loose objects + written into a packfile during the `loose-objects` task. The default is + fifty thousand. Use value `0` to indicate no limit. + maintenance.incremental-repack.auto:: This integer config option controls how often the `incremental-repack` task should be run as part of `git maintenance run --auto`. If zero, @@ -69,3 +74,29 @@ maintenance.incremental-repack.auto:: Otherwise, a positive value implies the command should run when the number of pack-files not in the multi-pack-index is at least the value of `maintenance.incremental-repack.auto`. The default value is 10. + +maintenance.reflog-expire.auto:: + This integer config option controls how often the `reflog-expire` task + should be run as part of `git maintenance run --auto`. If zero, then + the `reflog-expire` task will not run with the `--auto` option. A + negative value will force the task to run every time. Otherwise, a + positive value implies the command should run when the number of + expired reflog entries in the "HEAD" reflog is at least the value of + `maintenance.loose-objects.auto`. The default value is 100. + +maintenance.rerere-gc.auto:: + This integer config option controls how often the `rerere-gc` task + should be run as part of `git maintenance run --auto`. If zero, then + the `rerere-gc` task will not run with the `--auto` option. A negative + value will force the task to run every time. Otherwise, any positive + value implies the command will run when the "rr-cache" directory exists + and has at least one entry, regardless of whether it is stale or not. + This heuristic may be refined in the future. The default value is 1. + +maintenance.worktree-prune.auto:: + This integer config option controls how often the `worktree-prune` task + should be run as part of `git maintenance run --auto`. If zero, then + the `worktree-prune` task will not run with the `--auto` option. A + negative value will force the task to run every time. Otherwise, a + positive value implies the command should run when the number of + prunable worktrees exceeds the value. The default value is 1. diff --git a/Documentation/config/merge.adoc b/Documentation/config/merge.adoc index d2d0f21a71..86359f6dd2 100644 --- a/Documentation/config/merge.adoc +++ b/Documentation/config/merge.adoc @@ -1,9 +1,9 @@ -merge.conflictStyle:: +`merge.conflictStyle`:: Specify the style in which conflicted hunks are written out to working tree files upon merge. The default is "merge", which - shows a `<<<<<<<` conflict marker, changes made by one side, + 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 `|||||||` + a +>>>>>>>+ marker. An alternate style, "diff3", adds a +|||||||+ 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 @@ -13,17 +13,17 @@ merge.conflictStyle:: the conflict region when those matching lines appear near either the beginning or end of a conflict region. -merge.defaultToUpstream:: +`merge.defaultToUpstream`:: If merge is called without any commit argument, merge the upstream branches configured for the current branch by using their last observed values stored in their remote-tracking branches. The values of the `branch.<current branch>.merge` that name the - branches at the remote named by `branch.<current branch>.remote` + branches at the remote named by `branch.<current-branch>.remote` are consulted, and then they are mapped via `remote.<remote>.fetch` to their corresponding remote-tracking branches, and the tips of these tracking branches are merged. Defaults to true. -merge.ff:: +`merge.ff`:: By default, Git does not create an extra merge commit when merging a commit that is a descendant of the current commit. Instead, the tip of the current branch is fast-forwarded. When set to `false`, @@ -33,42 +33,46 @@ merge.ff:: allowed (equivalent to giving the `--ff-only` option from the command line). -merge.verifySignatures:: - If true, this is equivalent to the --verify-signatures command +`merge.verifySignatures`:: + If true, this is equivalent to the `--verify-signatures` command line option. See linkgit:git-merge[1] for details. include::fmt-merge-msg.adoc[] -merge.renameLimit:: +`merge.renameLimit`:: The number of files to consider in the exhaustive portion of rename detection during a merge. If not specified, defaults - to the value of diff.renameLimit. If neither - merge.renameLimit nor diff.renameLimit are specified, + to the value of `diff.renameLimit`. If neither + `merge.renameLimit` nor `diff.renameLimit` are specified, currently defaults to 7000. This setting has no effect if rename detection is turned off. -merge.renames:: - Whether Git detects renames. If set to "false", rename detection - is disabled. If set to "true", basic rename detection is enabled. +`merge.renames`:: + Whether Git detects renames. If set to `false`, rename detection + is disabled. If set to `true`, basic rename detection is enabled. Defaults to the value of diff.renames. -merge.directoryRenames:: +`merge.directoryRenames`:: Whether Git detects directory renames, affecting what happens at merge time to new files added to a directory on one side of history when that directory was renamed on the other side of - history. If merge.directoryRenames is set to "false", directory - rename detection is disabled, meaning that such new files will be - left behind in the old directory. If set to "true", directory - rename detection is enabled, meaning that such new files will be - moved into the new directory. If set to "conflict", a conflict - will be reported for such paths. If merge.renames is false, - merge.directoryRenames is ignored and treated as false. Defaults - to "conflict". - -merge.renormalize:: + history. Possible values are: ++ +-- +`false`;; Directory rename detection is disabled, meaning that such new files will be + left behind in the old directory. +`true`;; Directory rename detection is enabled, meaning that such new files will be + moved into the new directory. +`conflict`;; A conflict will be reported for such paths. +-- ++ +If `merge.renames` is `false`, `merge.directoryRenames` is ignored and treated +as `false`. Defaults to `conflict`. + +`merge.renormalize`:: Tell Git that canonical representation of files in the repository has changed over time (e.g. earlier commits record - text files with CRLF line endings, but recent ones use LF line + text files with _CRLF_ line endings, but recent ones use _LF_ line endings). In such a repository, for each file where a three-way content merge is needed, Git can convert the data recorded in commits to a canonical form before performing a @@ -76,35 +80,35 @@ merge.renormalize:: see section "Merging branches with differing checkin/checkout attributes" in linkgit:gitattributes[5]. -merge.stat:: - Whether to print the diffstat between ORIG_HEAD and the merge result +`merge.stat`:: + Whether to print the diffstat between `ORIG_HEAD` and the merge result at the end of the merge. True by default. -merge.autoStash:: - When set to true, automatically create a temporary stash entry +`merge.autoStash`:: + When set to `true`, automatically create a temporary stash entry before the operation begins, and apply it after the operation ends. This means that you can run merge on a dirty worktree. However, use with care: the final stash application after a successful merge might result in non-trivial conflicts. This option can be overridden by the `--no-autostash` and `--autostash` options of linkgit:git-merge[1]. - Defaults to false. + Defaults to `false`. -merge.tool:: +`merge.tool`:: Controls which merge tool is used by linkgit:git-mergetool[1]. The list below shows the valid built-in values. Any other value is treated as a custom merge tool and requires - that a corresponding mergetool.<tool>.cmd variable is defined. + that a corresponding `mergetool.<tool>.cmd` variable is defined. -merge.guitool:: +`merge.guitool`:: Controls which merge tool is used by linkgit:git-mergetool[1] when the - -g/--gui flag is specified. The list below shows the valid built-in values. + `-g`/`--gui` flag is specified. The list below shows the valid built-in values. Any other value is treated as a custom merge tool and requires that a - corresponding mergetool.<guitool>.cmd variable is defined. + corresponding `mergetool.<guitool>.cmd` variable is defined. include::{build_dir}/mergetools-merge.adoc[] -merge.verbosity:: +`merge.verbosity`:: Controls the amount of output shown by the recursive merge strategy. Level 0 outputs nothing except a final error message if conflicts were detected. Level 1 outputs only @@ -112,15 +116,15 @@ merge.verbosity:: above outputs debugging information. The default is level 2. Can be overridden by the `GIT_MERGE_VERBOSITY` environment variable. -merge.<driver>.name:: +`merge.<driver>.name`:: Defines a human-readable name for a custom low-level merge driver. See linkgit:gitattributes[5] for details. -merge.<driver>.driver:: +`merge.<driver>.driver`:: Defines the command that implements a custom low-level merge driver. See linkgit:gitattributes[5] for details. -merge.<driver>.recursive:: +`merge.<driver>.recursive`:: Names a low-level merge driver to be used when performing an internal merge between common ancestors. See linkgit:gitattributes[5] for details. diff --git a/Documentation/config/mergetool.adoc b/Documentation/config/mergetool.adoc index 00bf665aa0..6be506145c 100644 --- a/Documentation/config/mergetool.adoc +++ b/Documentation/config/mergetool.adoc @@ -1,24 +1,24 @@ -mergetool.<tool>.path:: +`mergetool.<tool>.path`:: Override the path for the given tool. This is useful in case - your tool is not in the PATH. + your tool is not in the `$PATH`. -mergetool.<tool>.cmd:: +`mergetool.<tool>.cmd`:: Specify the command to invoke the specified merge tool. The specified command is evaluated in shell with the following - variables available: 'BASE' is the name of a temporary file + variables available: `BASE` is the name of a temporary file containing the common base of the files to be merged, if available; - 'LOCAL' is the name of a temporary file containing the contents of - the file on the current branch; 'REMOTE' is the name of a temporary + `LOCAL` is the name of a temporary file containing the contents of + the file on the current branch; `REMOTE` is the name of a temporary file containing the contents of the file from the branch being - merged; 'MERGED' contains the name of the file to which the merge + merged; `MERGED` contains the name of the file to which the merge tool should write the results of a successful merge. -mergetool.<tool>.hideResolved:: +`mergetool.<tool>.hideResolved`:: Allows the user to override the global `mergetool.hideResolved` value for a specific tool. See `mergetool.hideResolved` for the full description. -mergetool.<tool>.trustExitCode:: +`mergetool.<tool>.trustExitCode`:: For a custom merge command, specify whether the exit code of the merge command can be used to determine whether the merge was successful. If this is not set to true then the merge target file @@ -26,7 +26,7 @@ mergetool.<tool>.trustExitCode:: if the file has been updated; otherwise, the user is prompted to indicate the success of the merge. -mergetool.meld.hasOutput:: +`mergetool.meld.hasOutput`:: Older versions of `meld` do not support the `--output` option. Git will attempt to detect whether `meld` supports `--output` by inspecting the output of `meld --help`. Configuring @@ -35,7 +35,7 @@ mergetool.meld.hasOutput:: to `true` tells Git to unconditionally use the `--output` option, and `false` avoids using `--output`. -mergetool.meld.useAutoMerge:: +`mergetool.meld.useAutoMerge`:: When the `--auto-merge` is given, meld will merge all non-conflicting parts automatically, highlight the conflicting parts, and wait for user decision. Setting `mergetool.meld.useAutoMerge` to `true` tells @@ -45,15 +45,15 @@ mergetool.meld.useAutoMerge:: value of `false` avoids using `--auto-merge` altogether, and is the default value. -mergetool.<vimdiff variant>.layout:: - Configure the split window layout for vimdiff's `<variant>`, which is any of `vimdiff`, +`mergetool.<variant>.layout`:: + Configure the split window layout for vimdiff's _<variant>_, which is any of `vimdiff`, `nvimdiff`, `gvimdiff`. Upon launching `git mergetool` with `--tool=<variant>` (or without `--tool` - if `merge.tool` is configured as `<variant>`), Git will consult + if `merge.tool` is configured as _<variant>_), Git will consult `mergetool.<variant>.layout` to determine the tool's layout. If the - variant-specific configuration is not available, `vimdiff`'s is used as + variant-specific configuration is not available, `vimdiff` ' s is used as fallback. If that too is not available, a default layout with 4 windows - will be used. To configure the layout, see the `BACKEND SPECIFIC HINTS` + will be used. To configure the layout, see the 'BACKEND SPECIFIC HINTS' ifdef::git-mergetool[] section. endif::[] @@ -61,39 +61,39 @@ ifndef::git-mergetool[] section in linkgit:git-mergetool[1]. endif::[] -mergetool.hideResolved:: +`mergetool.hideResolved`:: During a merge, Git will automatically resolve as many conflicts as - possible and write the 'MERGED' file containing conflict markers around - any conflicts that it cannot resolve; 'LOCAL' and 'REMOTE' normally - represent the versions of the file from before Git's conflict - resolution. This flag causes 'LOCAL' and 'REMOTE' to be overwritten so + possible and write the `$MERGED` file containing conflict markers around + any conflicts that it cannot resolve; `$LOCAL` and `$REMOTE` normally + are the versions of the file from before Git`s conflict + resolution. This flag causes `$LOCAL` and `$REMOTE` to be overwritten so that only the unresolved conflicts are presented to the merge tool. Can be configured per-tool via the `mergetool.<tool>.hideResolved` configuration variable. Defaults to `false`. -mergetool.keepBackup:: +`mergetool.keepBackup`:: After performing a merge, the original file with conflict markers can be saved as a file with a `.orig` extension. If this variable is set to `false` then this file is not preserved. Defaults to `true` (i.e. keep the backup files). -mergetool.keepTemporaries:: +`mergetool.keepTemporaries`:: When invoking a custom merge tool, Git uses a set of temporary files to pass to the tool. If the tool returns an error and this variable is set to `true`, then these temporary files will be preserved; otherwise, they will be removed after the tool has exited. Defaults to `false`. -mergetool.writeToTemp:: - Git writes temporary 'BASE', 'LOCAL', and 'REMOTE' versions of +`mergetool.writeToTemp`:: + Git writes temporary `BASE`, `LOCAL`, and `REMOTE` versions of conflicting files in the worktree by default. Git will attempt to use a temporary directory for these files when set `true`. Defaults to `false`. -mergetool.prompt:: +`mergetool.prompt`:: Prompt before each invocation of the merge resolution program. -mergetool.guiDefault:: +`mergetool.guiDefault`:: Set `true` to use the `merge.guitool` by default (equivalent to specifying the `--gui` argument), or `auto` to select `merge.guitool` or `merge.tool` depending on the presence of a `DISPLAY` environment diff --git a/Documentation/config/pack.adoc b/Documentation/config/pack.adoc index da527377fa..75402d5579 100644 --- a/Documentation/config/pack.adoc +++ b/Documentation/config/pack.adoc @@ -155,6 +155,10 @@ pack.useSparse:: commits contain certain types of direct renames. Default is `true`. +pack.usePathWalk:: + Enable the `--path-walk` option by default for `git pack-objects` + processes. See linkgit:git-pack-objects[1] for full details. + pack.preferBitmapTips:: When selecting which commits will receive bitmaps, prefer a commit at the tip of any reference that is a suffix of any value diff --git a/Documentation/config/promisor.adoc b/Documentation/config/promisor.adoc index 9192acfd24..2638b01f83 100644 --- a/Documentation/config/promisor.adoc +++ b/Documentation/config/promisor.adoc @@ -26,5 +26,5 @@ promisor.acceptFromServer:: server will be accepted. By accepting a promisor remote, the client agrees that the server might omit objects that are lazily fetchable from this promisor remote from its responses - to "fetch" and "clone" requests from the client. See - linkgit:gitprotocol-v2[5]. + to "fetch" and "clone" requests from the client. Name and URL + comparisons are case sensitive. See linkgit:gitprotocol-v2[5]. diff --git a/Documentation/config/remote.adoc b/Documentation/config/remote.adoc index 25fe219d10..91e46f66f5 100644 --- a/Documentation/config/remote.adoc +++ b/Documentation/config/remote.adoc @@ -108,7 +108,8 @@ the values inherited from a lower priority configuration files (e.g. `$HOME/.gitconfig`). remote.<name>.followRemoteHEAD:: - How linkgit:git-fetch[1] should handle updates to `remotes/<name>/HEAD`. + How linkgit:git-fetch[1] should handle updates to `remotes/<name>/HEAD` + when fetching using the configured refspecs of a remote. The default value is "create", which will create `remotes/<name>/HEAD` if it exists on the remote, but not locally; this will not touch an already existing local reference. Setting it to "warn" will print diff --git a/Documentation/config/sendemail.adoc b/Documentation/config/sendemail.adoc index 5ffcfc9f2a..54f1248e64 100644 --- a/Documentation/config/sendemail.adoc +++ b/Documentation/config/sendemail.adoc @@ -1,32 +1,32 @@ sendemail.identity:: A configuration identity. When given, causes values in the - 'sendemail.<identity>' subsection to take precedence over - values in the 'sendemail' section. The default identity is + `sendemail.<identity>` subsection to take precedence over + values in the `sendemail` section. The default identity is the value of `sendemail.identity`. sendemail.smtpEncryption:: See linkgit:git-send-email[1] for description. Note that this - setting is not subject to the 'identity' mechanism. + setting is not subject to the `identity` mechanism. sendemail.smtpSSLCertPath:: Path to ca-certificates (either a directory or a single file). Set it to an empty string to disable certificate verification. sendemail.<identity>.*:: - Identity-specific versions of the 'sendemail.*' parameters + Identity-specific versions of the `sendemail.*` parameters found below, taking precedence over those when this identity is selected, through either the command-line or `sendemail.identity`. sendemail.multiEdit:: - If true (default), a single editor instance will be spawned to edit + If `true` (default), a single editor instance will be spawned to edit files you have to edit (patches when `--annotate` is used, and the - summary when `--compose` is used). If false, files will be edited one + summary when `--compose` is used). If `false`, files will be edited one after the other, spawning a new editor each time. sendemail.confirm:: Sets the default for whether to confirm before sending. Must be - one of 'always', 'never', 'cc', 'compose', or 'auto'. See `--confirm` + one of `always`, `never`, `cc`, `compose`, or `auto`. See `--confirm` in the linkgit:git-send-email[1] documentation for the meaning of these values. @@ -51,7 +51,7 @@ sendemail.aliasesFile:: sendemail.aliasFileType:: Format of the file(s) specified in sendemail.aliasesFile. Must be - one of 'mutt', 'mailrc', 'pine', 'elm', 'gnus', or 'sendmail'. + one of `mutt`, `mailrc`, `pine`, `elm`, `gnus`, or `sendmail`. + What an alias file in each format looks like can be found in the documentation of the email program of the same name. The @@ -101,7 +101,7 @@ sendemail.signedOffCc (deprecated):: sendemail.smtpBatchSize:: Number of messages to be sent per connection, after that a relogin - will happen. If the value is 0 or undefined, send all messages in + will happen. If the value is `0` or undefined, send all messages in one connection. See also the `--batch-size` option of linkgit:git-send-email[1]. @@ -111,5 +111,5 @@ sendemail.smtpReloginDelay:: sendemail.forbidSendmailVariables:: To avoid common misconfiguration mistakes, linkgit:git-send-email[1] - will abort with a warning if any configuration options for "sendmail" + will abort with a warning if any configuration options for `sendmail` exist. Set this variable to bypass the check. diff --git a/Documentation/diff-generate-patch.adoc b/Documentation/diff-generate-patch.adoc index e5c813c96f..7b6cdd1980 100644 --- a/Documentation/diff-generate-patch.adoc +++ b/Documentation/diff-generate-patch.adoc @@ -138,7 +138,7 @@ or like this (when the `--cc` option is used): + [synopsis] index <hash>,<hash>..<hash> -mode <mode>,<mode>`..`<mode> +mode <mode>,<mode>..<mode> new file mode <mode> deleted file mode <mode>,<mode> + diff --git a/Documentation/fix-texi.perl b/Documentation/fix-texi.perl deleted file mode 100755 index ff7d78f620..0000000000 --- a/Documentation/fix-texi.perl +++ /dev/null @@ -1,15 +0,0 @@ -#!/usr/bin/perl -w - -while (<>) { - if (/^\@setfilename/) { - $_ = "\@setfilename git.info\n"; - } elsif (/^\@direntry/) { - print '@dircategory Development -@direntry -* Git: (git). A fast distributed revision control system -@end direntry -'; } - unless (/^\@direntry/../^\@end direntry/) { - print; - } -} diff --git a/Documentation/fix-texi.sh b/Documentation/fix-texi.sh new file mode 100755 index 0000000000..bc300f7b0f --- /dev/null +++ b/Documentation/fix-texi.sh @@ -0,0 +1,21 @@ +#!/bin/sh + +awk ' + /^@setfilename/{ + print "@setfilename git.info" + next + } + /^@direntry/{ + direntry=1 + print "@dircategory Development" + print "@direntry" + print "* Git: (git). A fast distributed revision control system" + print "@end direntry" + next + } + /^@end direntry/{ + direntry=0 + next + } + !direntry +' diff --git a/Documentation/fsck-msgids.adoc b/Documentation/fsck-msgids.adoc index b14bc44ca4..0ba4f9a27e 100644 --- a/Documentation/fsck-msgids.adoc +++ b/Documentation/fsck-msgids.adoc @@ -16,6 +16,13 @@ `badObjectSha1`:: (ERROR) An object has a bad sha1. +`badPackedRefEntry`:: + (ERROR) The "packed-refs" file contains an invalid entry. + +`badPackedRefHeader`:: + (ERROR) The "packed-refs" file contains an invalid + header. + `badParentSha1`:: (ERROR) A commit object has a bad parent sha1. @@ -52,6 +59,12 @@ `emptyName`:: (WARN) A path contains an empty name. +`emptyPackedRefsFile`:: + (INFO) "packed-refs" file is empty. Report to the + git@vger.kernel.org mailing list if you see this error. As only + very early versions of Git would create such an empty + "packed_refs" file, we might tighten this rule in the future. + `extraHeaderEntry`:: (IGNORE) Extra headers found after `tagger`. @@ -176,6 +189,13 @@ `nullSha1`:: (WARN) Tree contains entries pointing to a null sha1. +`packedRefEntryNotTerminated`:: + (ERROR) The "packed-refs" file contains an entry that is + not terminated by a newline. + +`packedRefUnsorted`:: + (ERROR) The "packed-refs" file is not sorted. + `refMissingNewline`:: (INFO) A loose ref that does not end with newline(LF). As valid implementations of Git never created such a loose ref diff --git a/Documentation/git-bisect.adoc b/Documentation/git-bisect.adoc index 82f944dc03..58dbb74a15 100644 --- a/Documentation/git-bisect.adoc +++ b/Documentation/git-bisect.adoc @@ -495,6 +495,7 @@ $ git bisect old HEAD~10 # the tenth commit from now is marked as old ------------ + or: ++ ------------ $ git bisect start --term-old broken --term-new fixed $ git bisect fixed diff --git a/Documentation/git-blame.adoc b/Documentation/git-blame.adoc index f75ed44790..e438d28625 100644 --- a/Documentation/git-blame.adoc +++ b/Documentation/git-blame.adoc @@ -135,10 +135,11 @@ header elements later. The porcelain format generally suppresses commit information that has already been seen. For example, two lines that are blamed to the same commit will both be shown, but the details for that commit will be shown -only once. This is more efficient, but may require more state be kept by -the reader. The `--line-porcelain` option can be used to output full -commit information for each line, allowing simpler (but less efficient) -usage like: +only once. Information which is specific to individual lines will not be +grouped together, like revs to be marked 'ignored' or 'unblamable'. This +is more efficient, but may require more state be kept by the reader. The +`--line-porcelain` option can be used to output full commit information +for each line, allowing simpler (but less efficient) usage like: # count the number of lines attributed to each author git blame --line-porcelain file | diff --git a/Documentation/git-branch.adoc b/Documentation/git-branch.adoc index 7a073a36d6..c0afddc424 100644 --- a/Documentation/git-branch.adoc +++ b/Documentation/git-branch.adoc @@ -7,23 +7,23 @@ git-branch - List, create, or delete branches SYNOPSIS -------- -[verse] -'git branch' [--color[=<when>] | --no-color] [--show-current] - [-v [--abbrev=<n> | --no-abbrev]] - [--column[=<options>] | --no-column] [--sort=<key>] - [--merged [<commit>]] [--no-merged [<commit>]] - [--contains [<commit>]] [--no-contains [<commit>]] - [--points-at <object>] [--format=<format>] - [(-r | --remotes) | (-a | --all)] - [--list] [<pattern>...] -'git branch' [--track[=(direct|inherit)] | --no-track] [-f] - [--recurse-submodules] <branchname> [<start-point>] -'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>] -'git branch' --unset-upstream [<branchname>] -'git branch' (-m | -M) [<oldbranch>] <newbranch> -'git branch' (-c | -C) [<oldbranch>] <newbranch> -'git branch' (-d | -D) [-r] <branchname>... -'git branch' --edit-description [<branchname>] +[synopsis] +git branch [--color[=<when>] | --no-color] [--show-current] + [-v [--abbrev=<n> | --no-abbrev]] + [--column[=<options>] | --no-column] [--sort=<key>] + [--merged [<commit>]] [--no-merged [<commit>]] + [--contains [<commit>]] [--no-contains [<commit>]] + [--points-at <object>] [--format=<format>] + [(-r|--remotes) | (-a|--all)] + [--list] [<pattern>...] +git branch [--track[=(direct|inherit)] | --no-track] [-f] + [--recurse-submodules] <branch-name> [<start-point>] +git branch (--set-upstream-to=<upstream>|-u <upstream>) [<branch-name>] +git branch --unset-upstream [<branch-name>] +git branch (-m|-M) [<old-branch>] <new-branch> +git branch (-c|-C) [<old-branch>] <new-branch> +git branch (-d|-D) [-r] <branch-name>... +git branch --edit-description [<branch-name>] DESCRIPTION ----------- @@ -49,173 +49,184 @@ With `--contains`, shows only the branches that contain the named commit named commit), `--no-contains` inverts it. With `--merged`, only branches merged into the named commit (i.e. the branches whose tip commits are reachable from the named commit) will be listed. With `--no-merged` only -branches not merged into the named commit will be listed. If the <commit> +branches not merged into the named commit will be listed. If the _<commit>_ argument is missing it defaults to `HEAD` (i.e. the tip of the current branch). -The command's second form creates a new branch head named <branchname> -which points to the current `HEAD`, or <start-point> if given. As a -special case, for <start-point>, 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`. +The command's second form creates a new branch head named _<branch-name>_ +which points to the current `HEAD`, or _<start-point>_ if given. As a +special case, for _<start-point>_, you may use `<rev-A>...<rev-B>` as a +shortcut for the merge base of _<rev-A>_ and _<rev-B>_ if there is exactly +one merge base. You can leave out at most one of _<rev-A>_ and _<rev-B>_, +in which case it defaults to `HEAD`. Note that this will create the new branch, but it will not switch the -working tree to it; use "git switch <newbranch>" to switch to the +working tree to it; use `git switch <new-branch>` to switch to the new branch. When a local branch is started off a remote-tracking branch, Git sets up the branch (specifically the `branch.<name>.remote` and `branch.<name>.merge` -configuration entries) so that 'git pull' will appropriately merge from +configuration entries) so that `git pull` will appropriately merge from the remote-tracking branch. This behavior may be changed via the global `branch.autoSetupMerge` configuration flag. That setting can be overridden by using the `--track` and `--no-track` options, and changed later using `git branch --set-upstream-to`. -With a `-m` or `-M` option, <oldbranch> will be renamed to <newbranch>. -If <oldbranch> had a corresponding reflog, it is renamed to match -<newbranch>, and a reflog entry is created to remember the branch -renaming. If <newbranch> exists, -M must be used to force the rename +With a `-m` or `-M` option, _<old-branch>_ will be renamed to _<new-branch>_. +If _<old-branch>_ had a corresponding reflog, it is renamed to match +_<new-branch>_, and a reflog entry is created to remember the branch +renaming. If _<new-branch>_ exists, `-M` must be used to force the rename to happen. The `-c` and `-C` options have the exact same semantics as `-m` and `-M`, except instead of the branch being renamed, it will be copied to a new name, along with its config and reflog. -With a `-d` or `-D` option, `<branchname>` will be deleted. You may +With a `-d` or `-D` option, _<branch-name>_ will be deleted. You may specify more than one branch for deletion. If the branch currently has a reflog then the reflog will also be deleted. Use `-r` together with `-d` to delete remote-tracking branches. Note, that it only makes sense to delete remote-tracking branches if they no longer exist -in the remote repository or if 'git fetch' was configured not to fetch -them again. See also the 'prune' subcommand of linkgit:git-remote[1] for a +in the remote repository or if `git fetch` was configured not to fetch +them again. See also the `prune` subcommand of linkgit:git-remote[1] for a way to clean up all obsolete remote-tracking branches. OPTIONS ------- --d:: ---delete:: +`-d`:: +`--delete`:: Delete a branch. The branch must be fully merged in its upstream branch, or in `HEAD` if no upstream was set with `--track` or `--set-upstream-to`. --D:: +`-D`:: Shortcut for `--delete --force`. ---create-reflog:: +`--create-reflog`:: Create the branch's reflog. This activates recording of all changes made to the branch ref, enabling use of date - based sha1 expressions such as "<branchname>@\{yesterday}". + based sha1 expressions such as `<branch-name>@{yesterday}`. Note that in non-bare repositories, reflogs are usually enabled by default by the `core.logAllRefUpdates` config option. The negated form `--no-create-reflog` only overrides an earlier `--create-reflog`, but currently does not negate the setting of `core.logAllRefUpdates`. --f:: ---force:: - Reset <branchname> to <start-point>, even if <branchname> exists - already. Without `-f`, 'git branch' refuses to change an existing branch. +`-f`:: +`--force`:: + Reset _<branch-name>_ to _<start-point>_, even if _<branch-name>_ exists + already. Without `-f`, `git branch` refuses to change an existing branch. In combination with `-d` (or `--delete`), allow deleting the branch irrespective of its merged status, or whether it even points to a valid commit. In combination with `-m` (or `--move`), allow renaming the branch even if the new branch name already exists, the same applies for `-c` (or `--copy`). + -Note that 'git branch -f <branchname> [<start-point>]', even with '-f', -refuses to change an existing branch `<branchname>` that is checked out +Note that `git branch -f <branch-name> [<start-point>]`, even with `-f`, +refuses to change an existing branch _<branch-name>_ that is checked out in another worktree linked to the same repository. --m:: ---move:: +`-m`:: +`--move`:: Move/rename a branch, together with its config and reflog. --M:: +`-M`:: Shortcut for `--move --force`. --c:: ---copy:: +`-c`:: +`--copy`:: Copy a branch, together with its config and reflog. --C:: +`-C`:: Shortcut for `--copy --force`. ---color[=<when>]:: +`--color[=<when>]`:: Color branches to highlight current, local, and remote-tracking branches. - The value must be always (the default), never, or auto. + The value must be `always` (the default), `never`, or `auto`. ---no-color:: +`--no-color`:: Turn off branch colors, even when the configuration file gives the default to color output. Same as `--color=never`. --i:: ---ignore-case:: +`-i`:: +`--ignore-case`:: Sorting and filtering branches are case insensitive. ---omit-empty:: +`--omit-empty`:: Do not print a newline after formatted refs where the format expands to the empty string. ---column[=<options>]:: ---no-column:: +`--column[=<options>]`:: +`--no-column`:: Display branch listing in columns. See configuration variable `column.branch` for option syntax. `--column` and `--no-column` - without options are equivalent to 'always' and 'never' respectively. + without options are equivalent to `always` and `never` respectively. + This option is only applicable in non-verbose mode. --r:: ---remotes:: - List or delete (if used with -d) the remote-tracking branches. +`--sort=<key>`:: + Sort based on _<key>_. Prefix `-` to sort in descending + order of the value. You may use the `--sort=<key>` option + multiple times, in which case the last key becomes the primary + key. The keys supported are the same as those in linkgit:git-for-each-ref[1]. + Sort order defaults to the value configured for the + `branch.sort` variable if it exists, or to sorting based on the + full refname (including `refs/...` prefix). This lists + detached `HEAD` (if present) first, then local branches and + finally remote-tracking branches. See linkgit:git-config[1]. + +`-r`:: +`--remotes`:: + List or delete (if used with `-d`) the remote-tracking branches. Combine with `--list` to match the optional pattern(s). --a:: ---all:: +`-a`:: +`--all`:: List both remote-tracking branches and local branches. Combine with `--list` to match optional pattern(s). --l:: ---list:: +`-l`:: +`--list`:: List branches. With optional `<pattern>...`, e.g. `git branch --list 'maint-*'`, list only the branches that match the pattern(s). ---show-current:: - Print the name of the current branch. In detached HEAD state, +`--show-current`:: + Print the name of the current branch. In detached `HEAD` state, nothing is printed. --v:: --vv:: ---verbose:: +`-v`:: +`-vv`:: +`--verbose`:: When in list mode, show sha1 and commit subject line for each head, along with relationship to upstream branch (if any). If given twice, print the path of the linked worktree (if any) and the name of the upstream branch, as well (see also `git remote show <remote>`). Note that the - current worktree's HEAD will not have its path printed (it will always + current worktree's `HEAD` will not have its path printed (it will always be your current directory). --q:: ---quiet:: +`-q`:: +`--quiet`:: Be more quiet when creating or deleting a branch, suppressing non-error messages. ---abbrev=<n>:: +`--abbrev=<n>`:: In the verbose listing that show the commit object name, - show the shortest prefix that is at least '<n>' hexdigits + show the shortest prefix that is at least _<n>_ hexdigits long that uniquely refers the object. The default value is 7 and can be overridden by the `core.abbrev` config option. ---no-abbrev:: +`--no-abbrev`:: Display the full sha1s in the output listing rather than abbreviating them. --t:: ---track[=(direct|inherit)]:: +`-t`:: +`--track[=(direct|inherit)]`:: When creating a new branch, set up `branch.<name>.remote` and `branch.<name>.merge` configuration entries to set "upstream" tracking configuration for the new branch. This @@ -229,7 +240,7 @@ The exact upstream branch is chosen depending on the optional argument: itself as the upstream; `--track=inherit` means to copy the upstream configuration of the start-point branch. + -The branch.autoSetupMerge configuration variable specifies how `git switch`, +The `branch.autoSetupMerge` configuration variable specifies how `git switch`, `git checkout` and `git branch` should behave when neither `--track` nor `--no-track` are specified: + @@ -238,106 +249,94 @@ were given whenever the start-point is a remote-tracking branch. `false` behaves as if `--no-track` were given. `always` behaves as though `--track=direct` were given. `inherit` behaves as though `--track=inherit` were given. `simple` behaves as though `--track=direct` were given only when -the start-point is a remote-tracking branch and the new branch has the same +the _<start-point>_ is a remote-tracking branch and the new branch has the same name as the remote branch. + 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:: +`--no-track`:: Do not set up "upstream" configuration, even if the - branch.autoSetupMerge configuration variable is set. + `branch.autoSetupMerge` configuration variable is set. ---recurse-submodules:: - THIS OPTION IS EXPERIMENTAL! Causes the current command to +`--recurse-submodules`:: + THIS OPTION IS EXPERIMENTAL! Cause the current command to recurse into submodules if `submodule.propagateBranches` is enabled. See `submodule.propagateBranches` in linkgit:git-config[1]. Currently, only branch creation is supported. + -When used in branch creation, a new branch <branchname> will be created +When used in branch creation, a new branch _<branch-name>_ will be created in the superproject and all of the submodules in the superproject's -<start-point>. In submodules, the branch will point to the submodule -commit in the superproject's <start-point> but the branch's tracking +_<start-point>_. In submodules, the branch will point to the submodule +commit in the superproject's _<start-point>_ but the branch's tracking information will be set up based on the submodule's branches and remotes e.g. `git branch --recurse-submodules topic origin/main` will create the submodule branch "topic" that points to the submodule commit in the superproject's "origin/main", but tracks the submodule's "origin/main". ---set-upstream:: +`--set-upstream`:: As this option had confusing syntax, it is no longer supported. Please use `--track` or `--set-upstream-to` instead. --u <upstream>:: ---set-upstream-to=<upstream>:: - Set up <branchname>'s tracking information so <upstream> is - considered <branchname>'s upstream branch. If no <branchname> +`-u <upstream>`:: +`--set-upstream-to=<upstream>`:: + Set up _<branch-name>_'s tracking information so _<upstream>_ is + considered _<branch-name>_'s upstream branch. If no _<branch-name>_ is specified, then it defaults to the current branch. ---unset-upstream:: - Remove the upstream information for <branchname>. If no branch +`--unset-upstream`:: + Remove the upstream information for _<branch-name>_. If no branch is specified it defaults to the current branch. ---edit-description:: +`--edit-description`:: Open an editor and edit the text to explain what the branch is for, to be used by various other commands (e.g. `format-patch`, `request-pull`, and `merge` (if enabled)). Multi-line explanations may be used. ---contains [<commit>]:: - Only list branches which contain the specified commit (HEAD +`--contains [<commit>]`:: + Only list branches which contain _<commit>_ (`HEAD` if not specified). Implies `--list`. ---no-contains [<commit>]:: - Only list branches which don't contain the specified commit - (HEAD if not specified). Implies `--list`. +`--no-contains [<commit>]`:: + Only list branches which don't contain _<commit>_ + (`HEAD` if not specified). Implies `--list`. ---merged [<commit>]:: - Only list branches whose tips are reachable from the - specified commit (HEAD if not specified). Implies `--list`. +`--merged [<commit>]`:: + Only list branches whose tips are reachable from + _<commit>_ (`HEAD` if not specified). Implies `--list`. ---no-merged [<commit>]:: - Only list branches whose tips are not reachable from the - specified commit (HEAD if not specified). Implies `--list`. +`--no-merged [<commit>]`:: + Only list branches whose tips are not reachable from + _<commit>_ (`HEAD` if not specified). Implies `--list`. -<branchname>:: +`--points-at <object>`:: + Only list branches of _<object>_. + +`--format <format>`:: + A string that interpolates `%(fieldname)` from a branch ref being shown + and the object it points at. _<format>_ is the same as + that of linkgit:git-for-each-ref[1]. + +_<branch-name>_:: The name of the branch to create or delete. The new branch name must pass all checks defined by linkgit:git-check-ref-format[1]. Some of these checks may restrict the characters allowed in a branch name. -<start-point>:: +_<start-point>_:: The new branch head will point to this commit. It may be given as a branch name, a commit-id, or a tag. If this - option is omitted, the current HEAD will be used instead. + option is omitted, the current `HEAD` will be used instead. -<oldbranch>:: +_<old-branch>_:: The name of an existing branch. If this option is omitted, the name of the current branch will be used instead. -<newbranch>:: +_<new-branch>_:: The new name for an existing branch. The same restrictions as for - <branchname> apply. - ---sort=<key>:: - Sort based on the key given. Prefix `-` to sort in descending - order of the value. You may use the --sort=<key> option - multiple times, in which case the last key becomes the primary - key. The keys supported are the same as those in `git - for-each-ref`. Sort order defaults to the value configured for the - `branch.sort` variable if it exists, or to sorting based on the - full refname (including `refs/...` prefix). This lists - detached HEAD (if present) first, then local branches and - finally remote-tracking branches. See linkgit:git-config[1]. - - ---points-at <object>:: - Only list branches of the given object. - ---format <format>:: - A string that interpolates `%(fieldname)` from a branch ref being shown - and the object it points at. The format is the same as - that of linkgit:git-for-each-ref[1]. + _<branch-name>_ apply. CONFIGURATION ------------- @@ -374,7 +373,7 @@ $ git branch -D test <2> ------------ + <1> Delete the remote-tracking branches "todo", "html" and "man". The next - 'fetch' or 'pull' will create them again unless you configure them not to. + `git fetch` or `git pull` will create them again unless you configure them not to. See linkgit:git-fetch[1]. <2> Delete the "test" branch even if the "master" branch (or whichever branch is currently checked out) does not have all commits from the test branch. @@ -386,8 +385,8 @@ $ git branch -r -l '<remote>/<pattern>' <1> $ git for-each-ref 'refs/remotes/<remote>/<pattern>' <2> ------------ + -<1> Using `-a` would conflate <remote> with any local branches you happen to - have been prefixed with the same <remote> pattern. +<1> Using `-a` would conflate _<remote>_ with any local branches you happen to + have been prefixed with the same _<remote>_ pattern. <2> `for-each-ref` can take a wide range of options. See linkgit:git-for-each-ref[1] Patterns will normally need quoting. @@ -396,24 +395,24 @@ NOTES ----- If you are creating a branch that you want to switch to immediately, -it is easier to use the "git switch" command with its `-c` option to +it is easier to use the `git switch` command with its `-c` option to do the same thing with a single command. The options `--contains`, `--no-contains`, `--merged` and `--no-merged` serve four related but different purposes: - `--contains <commit>` is used to find all branches which will need - special attention if <commit> were to be rebased or amended, since those - branches contain the specified <commit>. + special attention if _<commit>_ were to be rebased or amended, since those + branches contain the specified _<commit>_. - `--no-contains <commit>` is the inverse of that, i.e. branches that don't - contain the specified <commit>. + contain the specified _<commit>_. - `--merged` is used to find all branches which can be safely deleted, - since those branches are fully contained by HEAD. + since those branches are fully contained by `HEAD`. - `--no-merged` is used to find branches which are candidates for merging - into HEAD, since those branches are not fully contained by HEAD. + into `HEAD`, since those branches are not fully contained by `HEAD`. include::ref-reachability-filters.adoc[] @@ -422,8 +421,8 @@ SEE ALSO linkgit:git-check-ref-format[1], linkgit:git-fetch[1], linkgit:git-remote[1], -link:user-manual.html#what-is-a-branch[``Understanding history: What is -a branch?''] in the Git User's Manual. +link:user-manual.html#what-is-a-branch["Understanding history: What is +a branch?"] in the Git User's Manual. GIT --- diff --git a/Documentation/git-cat-file.adoc b/Documentation/git-cat-file.adoc index d5890ae368..180d1ad363 100644 --- a/Documentation/git-cat-file.adoc +++ b/Documentation/git-cat-file.adoc @@ -9,8 +9,7 @@ SYNOPSIS -------- [verse] 'git cat-file' <type> <object> -'git cat-file' (-e | -p) <object> -'git cat-file' (-t | -s) [--allow-unknown-type] <object> +'git cat-file' (-e | -p | -t | -s) <object> 'git cat-file' (--textconv | --filters) [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>] 'git cat-file' (--batch | --batch-check | --batch-command) [--batch-all-objects] @@ -81,6 +80,25 @@ OPTIONS end-of-line conversion, etc). In this case, `<object>` has to be of the form `<tree-ish>:<path>`, or `:<path>`. +--filter=<filter-spec>:: +--no-filter:: + Omit objects from the list of printed objects. This can only be used in + combination with one of the batched modes. Excluded objects that have + been explicitly requested via any of the batch modes that read objects + via standard input (`--batch`, `--batch-check`) will be reported as + "filtered". Excluded objects in `--batch-all-objects` mode will not be + printed at all. The '<filter-spec>' may be one of the following: ++ +The form '--filter=blob:none' omits all blobs. ++ +The form '--filter=blob:limit=<n>[kmg]' omits blobs of size at least n +bytes or units. n may be zero. The suffixes k, m, and g can be used to name +units in KiB, MiB, or GiB. For example, 'blob:limit=1k' is the same as +'blob:limit=1024'. ++ +The form '--filter=object:type=(tag|commit|tree|blob)' omits all objects which +are not of the requested type. + --path=<path>:: For use with `--textconv` or `--filters`, to allow specifying an object name and a path separately, e.g. when it is difficult to figure out @@ -183,9 +201,6 @@ flush:: only once, even if it is stored multiple times in the repository. ---allow-unknown-type:: - Allow `-s` or `-t` to query broken/corrupt objects of unknown type. - --follow-symlinks:: With `--batch` or `--batch-check`, follow symlinks inside the repository when requesting objects with extended SHA-1 @@ -292,6 +307,11 @@ newline. The available atoms are: `objecttype`:: The type of the object (the same as `cat-file -t` reports). +`objectmode`:: + If the specified object has mode information (such as a tree or + index entry), the mode expressed as an octal integer. Otherwise, + empty string. + `objectsize`:: The size, in bytes, of the object (the same as `cat-file -s` reports). @@ -322,10 +342,10 @@ of `%(objectsize)` bytes), followed by a newline. For example, `--batch` without a custom format would produce: ------------- +----------- <oid> SP <type> SP <size> LF <contents> LF ------------- +----------- Whereas `--batch-check='%(objectname) %(objecttype)'` would produce: @@ -340,12 +360,27 @@ the repository, then `cat-file` will ignore any custom format and print: <object> SP missing LF ------------ +If a name is specified on stdin that is filtered out via `--filter=`, +then `cat-file` will ignore any custom format and print: + +------------ +<object> SP excluded LF +------------ + If a name is specified that might refer to more than one object (an ambiguous short sha), then `cat-file` will ignore any custom format and print: ------------ <object> SP ambiguous LF ------------ +If a name is specified that refers to a submodule entry in a tree and the +target object does not exist in the repository, then `cat-file` will ignore +any custom format and print (with the object ID of the submodule): + +------------ +<oid> SP submodule LF +------------ + If `--follow-symlinks` is used, and a symlink in the repository points outside the repository, then `cat-file` will ignore any custom format and print: diff --git a/Documentation/git-check-attr.adoc b/Documentation/git-check-attr.adoc index cb5a6c8f33..503b644657 100644 --- a/Documentation/git-check-attr.adoc +++ b/Documentation/git-check-attr.adoc @@ -76,6 +76,7 @@ EXAMPLES -------- In the examples, the following '.gitattributes' file is used: + --------------- *.java diff=java -crlf myAttr NoMyAttr.java !myAttr @@ -83,12 +84,14 @@ README caveat=unspecified --------------- * Listing a single attribute: ++ --------------- $ git check-attr diff org/example/MyClass.java org/example/MyClass.java: diff: java --------------- * Listing multiple attributes for a file: ++ --------------- $ git check-attr crlf diff myAttr -- org/example/MyClass.java org/example/MyClass.java: crlf: unset @@ -97,6 +100,7 @@ org/example/MyClass.java: myAttr: set --------------- * Listing all attributes for a file: ++ --------------- $ git check-attr --all -- org/example/MyClass.java org/example/MyClass.java: diff: java @@ -104,6 +108,7 @@ org/example/MyClass.java: myAttr: set --------------- * Listing an attribute for multiple files: ++ --------------- $ git check-attr myAttr -- org/example/MyClass.java org/example/NoMyAttr.java org/example/MyClass.java: myAttr: set @@ -111,6 +116,7 @@ org/example/NoMyAttr.java: myAttr: unspecified --------------- * Not all values are equally unambiguous: ++ --------------- $ git check-attr caveat README README: caveat: unspecified diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc index a66c53a5cd..ee83b6d9ba 100644 --- a/Documentation/git-checkout.adoc +++ b/Documentation/git-checkout.adoc @@ -7,54 +7,54 @@ git-checkout - Switch branches or restore working tree files SYNOPSIS -------- -[verse] -'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' [-f] <tree-ish> [--] <pathspec>... -'git checkout' [-f] <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul] -'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>... -'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul] -'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...] +[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 [-f] <tree-ish> [--] <pathspec>... +git checkout [-f] <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul] +git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>... +git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul] +git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...] DESCRIPTION ----------- Updates files in the working tree to match the version in the index -or the specified tree. If no pathspec was given, 'git checkout' will +or the specified tree. If no pathspec was given, `git checkout` will also update `HEAD` to set the specified branch as the current branch. -'git checkout' [<branch>]:: - To prepare for working on `<branch>`, switch to it by updating +`git checkout [<branch>]`:: + To prepare for working on _<branch>_, switch to it by updating the index and the files in the working tree, and by pointing `HEAD` at the branch. Local modifications to the files in the working tree are kept, so that they can be committed to the - `<branch>`. + _<branch>_. + -If `<branch>` is not found but there does exist a tracking branch in -exactly one remote (call it `<remote>`) with a matching name and +If _<branch>_ is not found but there does exist a tracking branch in +exactly one remote (call it _<remote>_) with a matching name and `--no-guess` is not specified, treat as equivalent to + ------------ $ git checkout -b <branch> --track <remote>/<branch> ------------ + -You could omit `<branch>`, in which case the command degenerates to +You could omit _<branch>_, in which case the command degenerates to "check out the current branch", which is a glorified no-op with rather expensive side-effects to show only the tracking information, if it 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 this case you can use the `--track` or `--no-track` options, - which will be passed to 'git branch'. As a convenience, + which will be passed to `git branch`. As a convenience, `--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 + ------------ @@ -67,30 +67,30 @@ successful (e.g., when the branch is in use in another worktree, not just the current branch stays the same, but the branch is not reset to the start-point, either). -'git checkout' --detach [<branch>]:: -'git checkout' [--detach] <commit>:: +`git checkout --detach [<branch>]`:: +`git checkout [--detach] <commit>`:: - Prepare to work on top of `<commit>`, by detaching `HEAD` at it + Prepare to work on top of _<commit>_, by detaching `HEAD` at it (see "DETACHED HEAD" section), and updating the index and the files in the working tree. Local modifications to the files in the working tree are kept, so that the resulting working tree will be the state recorded in the commit plus the local modifications. + -When the `<commit>` argument is a branch name, the `--detach` option can +When the _<commit>_ argument is a branch name, the `--detach` option can be used to detach `HEAD` at the tip of the branch (`git checkout <branch>` would check out that branch without detaching `HEAD`). + -Omitting `<branch>` detaches `HEAD` at the tip of the current branch. +Omitting _<branch>_ detaches `HEAD` at the tip of the current branch. -'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...:: -'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]:: +`git checkout [-f|--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]`:: Overwrite the contents of the files that match the pathspec. - When the `<tree-ish>` (most often a commit) is not given, + When the _<tree-ish>_ (most often a commit) is not given, overwrite working tree with the contents in the index. - When the `<tree-ish>` is given, overwrite both the index and - the working tree with the contents at the `<tree-ish>`. + When the _<tree-ish>_ is given, overwrite both the index and + the working tree with the contents at the _<tree-ish>_. + The index may contain unmerged entries because of a previous failed merge. By default, if you try to check out such an entry from the index, the @@ -100,7 +100,7 @@ specific side of the merge can be checked out of the index by using `--ours` or `--theirs`. With `-m`, changes made to the working tree file can be discarded to re-create the original conflicted merge result. -'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...]:: +`git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]`:: This is similar to the previous mode, but lets you use the interactive interface to show the "diff" output and choose which hunks to use in the result. See below for the description of @@ -108,19 +108,19 @@ file can be discarded to re-create the original conflicted merge result. OPTIONS ------- --q:: ---quiet:: +`-q`:: +`--quiet`:: Quiet, suppress feedback messages. ---progress:: ---no-progress:: +`--progress`:: +`--no-progress`:: Progress status is reported on the standard error stream by default when it is attached to a terminal, unless `--quiet` is specified. This flag enables progress reporting even if not attached to a terminal, regardless of `--quiet`. --f:: ---force:: +`-f`:: +`--force`:: When switching branches, proceed even if the index or the working tree differs from `HEAD`, and even if there are untracked files in the way. This is used to throw away local changes and @@ -129,13 +129,13 @@ OPTIONS When checking out paths from the index, do not fail upon unmerged entries; instead, unmerged entries are ignored. ---ours:: ---theirs:: +`--ours`:: +`--theirs`:: When checking out paths from the index, check out stage #2 - ('ours') or #3 ('theirs') for unmerged paths. + (`ours`) or #3 (`theirs`) for unmerged paths. + -Note that during `git rebase` and `git pull --rebase`, 'ours' and -'theirs' may appear swapped; `--ours` gives the version from the +Note that during `git rebase` and `git pull --rebase`, `ours` and +`theirs` may appear swapped; `--ours` gives the version from the branch the changes are rebased onto, while `--theirs` gives the version from the branch that holds your work that is being rebased. + @@ -149,22 +149,22 @@ 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>`, start it at - `<start-point>`, and check the resulting branch out; +`-b <new-branch>`:: + Create a new branch named _<new-branch>_, start it at + _<start-point>_, and check the resulting branch out; see linkgit:git-branch[1] for details. --B <new-branch>:: - Creates the branch `<new-branch>`, start it at `<start-point>`; - if it already exists, then reset it to `<start-point>`. And then +`-B <new-branch>`:: + Creates the branch _<new-branch>_, start it at _<start-point>_; + if it already exists, then reset it to _<start-point>_. And then check the resulting branch out. This is equivalent to running - "git branch" with "-f" followed by "git checkout" of that branch; + `git branch` with `-f` followed by `git checkout` of that branch; see linkgit:git-branch[1] for details. --t:: ---track[=(direct|inherit)]:: +`-t`:: +`--track[=(direct|inherit)]`:: When creating a new branch, set up "upstream" configuration. See - "--track" in linkgit:git-branch[1] for details. + `--track` in linkgit:git-branch[1] for details. + If no `-b` option is given, the name of the new branch will be derived from the remote-tracking branch, by looking at the local part of @@ -176,14 +176,14 @@ off of `origin/hack` (or `remotes/origin/hack`, or even guessing results in an empty name, the guessing is aborted. You can explicitly give a name with `-b` in such a case. ---no-track:: +`--no-track`:: Do not set up "upstream" configuration, even if the `branch.autoSetupMerge` configuration variable is true. ---guess:: ---no-guess:: - If `<branch>` is not found but there does exist a tracking - branch in exactly one remote (call it `<remote>`) with a +`--guess`:: +`--no-guess`:: + If _<branch>_ is not found but there does exist a tracking + branch in exactly one remote (call it _<remote>_) with a matching name, treat as equivalent to + ------------ @@ -192,10 +192,10 @@ $ git checkout -b <branch> --track <remote>/<branch> + If the branch exists in multiple remotes and one of them is named by the `checkout.defaultRemote` configuration variable, we'll use that -one for the purposes of disambiguation, even if the `<branch>` isn't +one for the purposes of disambiguation, even if the _<branch>_ isn't unique across all remotes. Set it to e.g. `checkout.defaultRemote=origin` to always checkout remote -branches from there if `<branch>` is ambiguous but exists on the +branches from there if _<branch>_ is ambiguous but exists on the 'origin' remote. See also `checkout.defaultRemote` in linkgit:git-config[1]. + @@ -204,28 +204,28 @@ linkgit:git-config[1]. The default behavior can be set via the `checkout.guess` configuration variable. --l:: +`-l`:: Create the new branch's reflog; see linkgit:git-branch[1] for details. --d:: ---detach:: +`-d`:: +`--detach`:: Rather than checking out a branch to work on it, check out a commit for inspection and discardable experiments. This is the default behavior of `git checkout <commit>` when - `<commit>` is not a branch name. See the "DETACHED HEAD" section + _<commit>_ is not a branch name. See the "DETACHED HEAD" section below for details. ---orphan <new-branch>:: - Create a new unborn branch, named `<new-branch>`, started from - `<start-point>` and switch to it. The first commit made on this +`--orphan <new-branch>`:: + Create a new unborn 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 +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 @@ -235,20 +235,20 @@ 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 working tree, by copying them from elsewhere, extracting a tarball, etc. ---ignore-skip-worktree-bits:: - In sparse checkout mode, `git checkout -- <paths>` would - update only entries matched by `<paths>` and sparse patterns +`--ignore-skip-worktree-bits`:: + In sparse checkout mode, `git checkout -- <path>...` would + update only entries matched by _<paths>_ and sparse patterns in `$GIT_DIR/info/sparse-checkout`. This option ignores - the sparse patterns and adds back any files in `<paths>`. + the sparse patterns and adds back any files in `<path>...`. --m:: ---merge:: +`-m`:: +`--merge`:: When switching branches, if you have local modifications to one or more files that are different between the current branch and the branch to @@ -269,40 +269,40 @@ used when checking out paths from a tree-ish. + When switching branches with `--merge`, staged changes may be lost. ---conflict=<style>:: +`--conflict=<style>`:: 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), "diff3", and "zdiff3". + `merge` (default), `diff3`, and `zdiff3`. --p:: ---patch:: +`-p`:: +`--patch`:: Interactively select hunks in the difference between the - `<tree-ish>` (or the index, if unspecified) and the working + _<tree-ish>_ (or the index, if unspecified) and the working tree. The chosen hunks are then applied in reverse to the - working tree (and if a `<tree-ish>` was specified, the index). + working tree (and if a _<tree-ish>_ was specified, the index). + This means that you can use `git checkout -p` to selectively discard -edits from your current working tree. See the ``Interactive Mode'' +edits from your current working tree. See the "Interactive Mode" section of linkgit:git-add[1] to learn how to operate the `--patch` mode. + Note that this option uses the no overlay mode by default (see also `--overlay`), and currently doesn't support overlay mode. ---ignore-other-worktrees:: +`--ignore-other-worktrees`:: `git checkout` refuses when the wanted branch is already checked out or otherwise in use by another worktree. This option makes it check the branch out anyway. In other words, the branch can be in use by more than one worktree. ---overwrite-ignore:: ---no-overwrite-ignore:: +`--overwrite-ignore`:: +`--no-overwrite-ignore`:: Silently overwrite ignored files when switching branches. This is the default behavior. Use `--no-overwrite-ignore` to abort the operation when the new branch contains ignored files. ---recurse-submodules:: ---no-recurse-submodules:: +`--recurse-submodules`:: +`--no-recurse-submodules`:: Using `--recurse-submodules` will update the content of all active submodules according to the commit recorded in the superproject. If local modifications in a submodule would be overwritten the checkout @@ -311,25 +311,25 @@ Note that this option uses the no overlay mode by default (see also Just like linkgit:git-submodule[1], this will detach `HEAD` of the submodule. ---overlay:: ---no-overlay:: +`--overlay`:: +`--no-overlay`:: In the default overlay mode, `git checkout` never removes files from the index or the working tree. When specifying `--no-overlay`, files that appear in the index and - working tree, but not in `<tree-ish>` are removed, to make them - match `<tree-ish>` exactly. + working tree, but not in _<tree-ish>_ are removed, to make them + match _<tree-ish>_ exactly. ---pathspec-from-file=<file>:: - Pathspec is passed in `<file>` instead of commandline args. If - `<file>` is exactly `-` then standard input is used. Pathspec - elements are separated by LF or CR/LF. Pathspec elements can be +`--pathspec-from-file=<file>`:: + Pathspec is passed in _<file>_ instead of commandline args. If + _<file>_ is exactly `-` then standard input is used. Pathspec + elements are separated by _LF_ or _CR_/_LF_. Pathspec elements can be quoted as explained for the configuration variable `core.quotePath` (see linkgit:git-config[1]). See also `--pathspec-file-nul` and global `--literal-pathspecs`. ---pathspec-file-nul:: +`--pathspec-file-nul`:: Only meaningful with `--pathspec-from-file`. Pathspec elements are - separated with NUL character and all other characters are taken + separated with _NUL_ character and all other characters are taken literally (including newlines and quotes). <branch>:: @@ -343,33 +343,33 @@ You can use the `@{-N}` syntax to refer to the N-th last branch/commit checked out using "git checkout" operation. You may also specify `-` which is synonymous to `@{-1}`. + -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`. +As a special case, you may use `<rev-a>...<rev-b>` as a shortcut for the +merge base of _<rev-a>_ and _<rev-b>_ if there is exactly one merge base. You can +leave out at most one of _<rev-a>_ and _<rev-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`. + -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`. +As a special case, you may use `<rev-a>...<rev-b>` as a shortcut for the +merge base of _<rev-a>_ and _<rev-b>_ if there is exactly one merge base. You can +leave out at most one of _<rev-a>_ and _<rev-b>_, in which case it defaults to `HEAD`. -<tree-ish>:: +_<tree-ish>_:: Tree to checkout from (when paths are given). If not specified, the index will be used. + -As a special case, you may use `"A...B"` as a shortcut for the -merge base of `A` and `B` if there is exactly one merge base. You can -leave out at most one of `A` and `B`, in which case it defaults to `HEAD`. +As a special case, you may use `<rev-a>...<rev-b>` as a shortcut for the +merge base of _<rev-a>_ and _<rev-b>_ if there is exactly one merge base. You can +leave out at most one of _<rev-a>_ and _<rev-b>_, in which case it defaults to `HEAD`. -\--:: +`--`:: Do not interpret any more arguments as options. -<pathspec>...:: +`<pathspec>...`:: Limits the paths affected by the operation. + For more details, see the 'pathspec' entry in linkgit:gitglossary[7]. @@ -391,7 +391,7 @@ a---b---c branch 'master' (refers to commit 'c') ------------ When a commit is created in this state, the branch is updated to refer to -the new commit. Specifically, 'git commit' creates a new commit `d`, whose +the new commit. Specifically, `git commit` creates a new commit `d`, whose parent is commit `c`, and then updates branch `master` to refer to new commit `d`. `HEAD` still refers to branch `master` and so indirectly now refers to commit `d`: @@ -510,11 +510,11 @@ ARGUMENT DISAMBIGUATION ----------------------- When there is only one argument given and it is not `--` (e.g. `git -checkout abc`), and when the argument is both a valid `<tree-ish>` -(e.g. a branch `abc` exists) and a valid `<pathspec>` (e.g. a file +checkout abc`), and when the argument is both a valid _<tree-ish>_ +(e.g. a branch `abc` exists) and a valid _<pathspec>_ (e.g. a file or a directory whose name is "abc" exists), Git would usually ask you to disambiguate. Because checking out a branch is so common an -operation, however, `git checkout abc` takes "abc" as a `<tree-ish>` +operation, however, `git checkout abc` takes "abc" as a _<tree-ish>_ in such a situation. Use `git checkout -- <pathspec>` if you want to checkout these paths out of the index. diff --git a/Documentation/git-column.adoc b/Documentation/git-column.adoc index 85fb87c94a..8e0047214d 100644 --- a/Documentation/git-column.adoc +++ b/Documentation/git-column.adoc @@ -50,6 +50,7 @@ EXAMPLES -------- Format data by columns: + ------------ $ seq 1 24 | git column --mode=column --padding=5 1 4 7 10 13 16 19 22 @@ -58,6 +59,7 @@ $ seq 1 24 | git column --mode=column --padding=5 ------------ Format data by rows: + ------------ $ seq 1 21 | git column --mode=row --padding=5 1 2 3 4 5 6 7 @@ -66,6 +68,7 @@ $ seq 1 21 | git column --mode=row --padding=5 ------------ List some tags in a table with unequal column widths: + ------------ $ git tag --list 'v2.4.*' --column=row,dense v2.4.0 v2.4.0-rc0 v2.4.0-rc1 v2.4.0-rc2 v2.4.0-rc3 diff --git a/Documentation/git-cvsserver.adoc b/Documentation/git-cvsserver.adoc index 4c475efeab..fe822f571d 100644 --- a/Documentation/git-cvsserver.adoc +++ b/Documentation/git-cvsserver.adoc @@ -125,9 +125,11 @@ creation in your platform (e.g. mkpasswd in Linux, encrypt in OpenBSD or pwhash in NetBSD) and paste it in the right location. Then provide your password via the pserver method, for example: + ------ cvs -d:pserver:someuser:somepassword@server:/path/repo.git co <HEAD_name> ------ + No special setup is needed for SSH access, other than having Git tools in the PATH. If you have clients that do not accept the CVS_SERVER environment variable, you can rename 'git-cvsserver' to `cvs`. @@ -138,6 +140,7 @@ CVS_SERVER directly in CVSROOT like ------ cvs -d ":ext;CVS_SERVER=git cvsserver:user@server/path/repo.git" co <HEAD_name> ------ + This has the advantage that it will be saved in your 'CVS/Root' files and you don't need to worry about always setting the correct environment variable. SSH users restricted to 'git-shell' don't need to override the default @@ -168,6 +171,7 @@ All configuration variables can also be overridden for a specific method of access. Valid method names are "ext" (for SSH access) and "pserver". The following example configuration would disable pserver access while still allowing access over SSH. + ------ [gitcvs] enabled=0 diff --git a/Documentation/git-daemon.adoc b/Documentation/git-daemon.adoc index ede7b935d6..99389f0388 100644 --- a/Documentation/git-daemon.adoc +++ b/Documentation/git-daemon.adoc @@ -7,21 +7,21 @@ git-daemon - A really simple server for Git repositories SYNOPSIS -------- -[verse] -'git daemon' [--verbose] [--syslog] [--export-all] - [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>] - [--strict-paths] [--base-path=<path>] [--base-path-relaxed] - [--user-path | --user-path=<path>] - [--interpolated-path=<pathtemplate>] - [--reuseaddr] [--detach] [--pid-file=<file>] - [--enable=<service>] [--disable=<service>] - [--allow-override=<service>] [--forbid-override=<service>] - [--access-hook=<path>] [--[no-]informative-errors] - [--inetd | - [--listen=<host-or-ipaddr>] [--port=<n>] - [--user=<user> [--group=<group>]]] - [--log-destination=(stderr|syslog|none)] - [<directory>...] +[synopsis] +git daemon [--verbose] [--syslog] [--export-all] + [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>] + [--strict-paths] [--base-path=<path>] [--base-path-relaxed] + [--user-path | --user-path=<path>] + [--interpolated-path=<pathtemplate>] + [--reuseaddr] [--detach] [--pid-file=<file>] + [--enable=<service>] [--disable=<service>] + [--allow-override=<service>] [--forbid-override=<service>] + [--access-hook=<path>] [--[no-]informative-errors] + [--inetd | + [--listen=<host-or-ipaddr>] [--port=<n>] + [--user=<user> [--group=<group>]]] + [--log-destination=(stderr|syslog|none)] + [<directory>...] DESCRIPTION ----------- @@ -32,111 +32,111 @@ that service if it is enabled. It verifies that the directory has the magic file "git-daemon-export-ok", and it will refuse to export any Git directory that hasn't explicitly been marked for export this way (unless the `--export-all` parameter is specified). If you -pass some directory paths as 'git daemon' arguments, the offers are limited to +pass some directory paths as `git daemon` arguments, the offers are limited to repositories within those directories. By default, only `upload-pack` service is enabled, which serves -'git fetch-pack' and 'git ls-remote' clients, which are invoked -from 'git fetch', 'git pull', and 'git clone'. +`git fetch-pack` and `git ls-remote` clients, which are invoked +from `git fetch`, `git pull`, and `git clone`. This is ideally suited for read-only updates, i.e., pulling from Git repositories. -An `upload-archive` also exists to serve 'git archive'. +An `upload-archive` also exists to serve `git archive`. OPTIONS ------- ---strict-paths:: +`--strict-paths`:: Match paths exactly (i.e. don't allow "/foo/repo" when the real path is "/foo/repo.git" or "/foo/repo/.git") and don't do user-relative paths. - 'git daemon' will refuse to start when this option is enabled and no + `git daemon` will refuse to start when this option is enabled and no directory arguments are provided. ---base-path=<path>:: +`--base-path=<path>`:: Remap all the path requests as relative to the given path. - This is sort of "Git root" - if you run 'git daemon' with - '--base-path=/srv/git' on example.com, then if you later try to pull - 'git://example.com/hello.git', 'git daemon' will interpret the path - as `/srv/git/hello.git`. - ---base-path-relaxed:: - If --base-path is enabled and repo lookup fails, with this option - 'git daemon' will attempt to lookup without prefixing the base path. - This is useful for switching to --base-path usage, while still + This is sort of "Git root" - if you run `git daemon` with + `--base-path=/srv/git` on `example.com`, then if you later try + to pull from `git://example.com/hello.git`, `git daemon` will + interpret the path as `/srv/git/hello.git`. + +`--base-path-relaxed`:: + If `--base-path` is enabled and repo lookup fails, with this option + `git daemon` will attempt to lookup without prefixing the base path. + This is useful for switching to `--base-path` usage, while still allowing the old paths. ---interpolated-path=<pathtemplate>:: +`--interpolated-path=<pathtemplate>`:: To support virtual hosting, an interpolated path template can be used to dynamically construct alternate paths. The template - supports %H for the target hostname as supplied by the client but - converted to all lowercase, %CH for the canonical hostname, - %IP for the server's IP address, %P for the port number, - and %D for the absolute path of the named repository. + supports `%H` for the target hostname as supplied by the client but + converted to all lowercase, `%CH` for the canonical hostname, + `%IP` for the server's IP address, `%P` for the port number, + and `%D` for the absolute path of the named repository. After interpolation, the path is validated against the directory list. ---export-all:: +`--export-all`:: Allow pulling from all directories that look like Git repositories (have the 'objects' and 'refs' subdirectories), even if they - do not have the 'git-daemon-export-ok' file. + do not have the `git-daemon-export-ok` file. ---inetd:: - Have the server run as an inetd service. Implies --syslog (may be - overridden with `--log-destination=`). - Incompatible with --detach, --port, --listen, --user and --group - options. +`--inetd`:: + Have the server run as an inetd service. Implies `--syslog` (may + be overridden with `--log-destination=`). + Incompatible with `--detach`, `--port`, `--listen`, `--user` and + `--group` options. ---listen=<host-or-ipaddr>:: +`--listen=<host-or-ipaddr>`:: Listen on a specific IP address or hostname. IP addresses can be either an IPv4 address or an IPv6 address if supported. If IPv6 - is not supported, then --listen=<hostname> is also not supported and - --listen must be given an IPv4 address. + is not supported, then `--listen=<hostname>` is also not supported + and `--listen` must be given an IPv4 address. Can be given more than once. Incompatible with `--inetd` option. ---port=<n>:: +`--port=<n>`:: Listen on an alternative port. Incompatible with `--inetd` option. ---init-timeout=<n>:: +`--init-timeout=<n>`:: Timeout (in seconds) between the moment the connection is established and the client request is received (typically a rather low value, since that should be basically immediate). ---timeout=<n>:: +`--timeout=<n>`:: Timeout (in seconds) for specific client sub-requests. This includes the time it takes for the server to process the sub-request and the time spent waiting for the next client's request. ---max-connections=<n>:: +`--max-connections=<n>`:: Maximum number of concurrent clients, defaults to 32. Set it to zero for no limit. ---syslog:: +`--syslog`:: Short for `--log-destination=syslog`. ---log-destination=<destination>:: +`--log-destination=<destination>`:: Send log messages to the specified destination. - Note that this option does not imply --verbose, + Note that this option does not imply `--verbose`, thus by default only error conditions will be logged. - The <destination> must be one of: + The _<destination>_ must be one of: + -- -stderr:: +`stderr`:: Write to standard error. Note that if `--detach` is specified, the process disconnects from the real standard error, making this destination effectively equivalent to `none`. -syslog:: +`syslog`:: Write to syslog, using the `git-daemon` identifier. -none:: +`none`:: Disable all logging. -- + The default destination is `syslog` if `--inetd` or `--detach` is specified, otherwise `stderr`. ---user-path:: ---user-path=<path>:: +`--user-path`:: +`--user-path=<path>`:: Allow {tilde}user notation to be used in requests. When specified with no parameter, a request to git://host/{tilde}alice/foo is taken as a request to access @@ -145,23 +145,23 @@ otherwise `stderr`. taken as a request to access `<path>/foo` repository in the home directory of user `alice`. ---verbose:: +`--verbose`:: Log details about the incoming connections and requested files. ---reuseaddr:: - Use SO_REUSEADDR when binding the listening socket. +`--reuseaddr`:: + Use `SO_REUSEADDR` when binding the listening socket. This allows the server to restart without waiting for old connections to time out. ---detach:: - Detach from the shell. Implies --syslog. +`--detach`:: + Detach from the shell. Implies `--syslog`. ---pid-file=<file>:: - Save the process id in 'file'. Ignored when the daemon +`--pid-file=<file>`:: + Save the process id in _<file>_. Ignored when the daemon is run under `--inetd`. ---user=<user>:: ---group=<group>:: +`--user=<user>`:: +`--group=<group>`:: Change daemon's uid and gid before entering the service loop. When only `--user` is given without `--group`, the primary group ID for the user is used. The values of @@ -170,43 +170,44 @@ otherwise `stderr`. + Giving these options is an error when used with `--inetd`; use the facility of inet daemon to achieve the same before spawning -'git daemon' if needed. +`git daemon` if needed. + Like many programs that switch user id, the daemon does not reset -environment variables such as `$HOME` when it runs git programs, +environment variables such as `HOME` when it runs git programs, e.g. `upload-pack` and `receive-pack`. When using this option, you may also want to set and export `HOME` to point at the home -directory of `<user>` before starting the daemon, and make sure any -Git configuration files in that directory are readable by `<user>`. +directory of _<user>_ before starting the daemon, and make sure any +Git configuration files in that directory are readable by _<user>_. ---enable=<service>:: ---disable=<service>:: +`--enable=<service>`:: +`--disable=<service>`:: Enable/disable the service site-wide per default. Note that a service disabled site-wide can still be enabled per repository if it is marked overridable and the repository enables the service with a configuration item. ---allow-override=<service>:: ---forbid-override=<service>:: +`--allow-override=<service>`:: +`--forbid-override=<service>`:: Allow/forbid overriding the site-wide default with per repository configuration. By default, all the services may be overridden. ---[no-]informative-errors:: +`--informative-errors`:: +`--no-informative-errors`:: When informative errors are turned on, git-daemon will report more verbose errors to the client, differentiating conditions like "no such repository" from "repository not exported". This is more convenient for clients, but may leak information about the existence of unexported repositories. When informative errors are not enabled, all errors report "access denied" to the - client. The default is --no-informative-errors. + client. The default is `--no-informative-errors`. ---access-hook=<path>:: +`--access-hook=<path>`:: Every time a client connects, first run an external command specified by the <path> with service name (e.g. "upload-pack"), - path to the repository, hostname (%H), canonical hostname - (%CH), IP address (%IP), and TCP port (%P) as its command-line + path to the repository, hostname (`%H`), canonical hostname + (`%CH`), IP address (`%IP`), and TCP port (`%P`) as its command-line arguments. The external command can decide to decline the service by exiting with a non-zero status (or to allow it by exiting with a zero status). It can also look at the $REMOTE_ADDR @@ -217,7 +218,7 @@ The external command can optionally write a single line to its standard output to be sent to the requestor as an error message when it declines the service. -<directory>:: +_<directory>_:: The remaining arguments provide a list of directories. If any directories are specified, then the `git-daemon` process will serve a requested directory only if it is contained in one of @@ -229,24 +230,24 @@ SERVICES These services can be globally enabled/disabled using the command-line options of this command. If finer-grained -control is desired (e.g. to allow 'git archive' to be run +control is desired (e.g. to allow `git archive` to be run against only in a few selected repositories the daemon serves), the per-repository configuration file can be used to enable or disable them. upload-pack:: - This serves 'git fetch-pack' and 'git ls-remote' + This serves `git fetch-pack` and `git ls-remote` clients. It is enabled by default, but a repository can disable it by setting `daemon.uploadpack` configuration item to `false`. upload-archive:: - This serves 'git archive --remote'. It is disabled by + This serves `git archive --remote`. It is disabled by default, but a repository can enable it by setting `daemon.uploadarch` configuration item to `true`. receive-pack:: - This serves 'git send-pack' clients, allowing anonymous + This serves `git send-pack` clients, allowing anonymous push. It is disabled by default, as there is _no_ authentication in the protocol (in other words, anybody can push anything into the repository, including removal @@ -300,7 +301,7 @@ default repository could be made as well. 'git daemon' as regular daemon for virtual hosts:: - To set up 'git daemon' as a regular, non-inetd service that + To set up `git daemon` as a regular, non-inetd service that handles repositories for multiple virtual hosts based on their IP addresses, start the daemon like this: + @@ -317,7 +318,7 @@ Repositories can still be accessed by hostname though, assuming they correspond to these IP addresses. selectively enable/disable services per repository:: - To enable 'git archive --remote' and disable 'git fetch' against + To enable `git archive --remote` and disable `git fetch` against a repository, have the following in the configuration file in the repository (that is the file 'config' next to `HEAD`, 'refs' and 'objects'). @@ -331,8 +332,8 @@ selectively enable/disable services per repository:: ENVIRONMENT ----------- -'git daemon' will set REMOTE_ADDR to the IP address of the client -that connected to it, if the IP address is available. REMOTE_ADDR will +`git daemon` will set `REMOTE_ADDR` to the IP address of the client +that connected to it, if the IP address is available. `REMOTE_ADDR` will be available in the environment of hooks called when services are performed. diff --git a/Documentation/git-diff-pairs.adoc b/Documentation/git-diff-pairs.adoc new file mode 100644 index 0000000000..f99fcd1ead --- /dev/null +++ b/Documentation/git-diff-pairs.adoc @@ -0,0 +1,60 @@ +git-diff-pairs(1) +================= + +NAME +---- +git-diff-pairs - Compare the content and mode of provided blob pairs + +SYNOPSIS +-------- +[synopsis] +git diff-pairs -z [<diff-options>] + +DESCRIPTION +----------- +Show changes for file pairs provided on stdin. Input for this command must be +in the NUL-terminated raw output format as generated by commands such as `git +diff-tree -z -r --raw`. By default, the outputted diffs are computed and shown +in the patch format when stdin closes. + +A single NUL byte may be written to stdin between raw input lines to compute +file pair diffs up to that point instead of waiting for stdin to close. A NUL +byte is also written to the output to delimit between these batches of diffs. + +Usage of this command enables the traditional diff pipeline to be broken up +into separate stages where `diff-pairs` acts as the output phase. Other +commands, such as `diff-tree`, may serve as a frontend to compute the raw +diff format used as input. + +Instead of computing diffs via `git diff-tree -p -M` in one step, `diff-tree` +can compute the file pairs and rename information without the blob diffs. This +output can be fed to `diff-pairs` to generate the underlying blob diffs as done +in the following example: + +----------------------------- +git diff-tree -z -r -M $a $b | +git diff-pairs -z +----------------------------- + +Computing the tree diff upfront with rename information allows patch output +from `diff-pairs` to be progressively computed over the course of potentially +multiple invocations. + +Pathspecs are not currently supported by `diff-pairs`. Pathspec limiting should +be performed by the upstream command generating the raw diffs used as input. + +Tree objects are not currently supported as input and are rejected. + +Abbreviated object IDs in the `diff-pairs` input are not supported. Outputted +object IDs can be abbreviated using the `--abbrev` option. + +OPTIONS +------- + +include::diff-options.adoc[] + +include::diff-generate-patch.adoc[] + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-diff.adoc b/Documentation/git-diff.adoc index dec173a345..272331afba 100644 --- a/Documentation/git-diff.adoc +++ b/Documentation/git-diff.adoc @@ -14,7 +14,7 @@ git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...] git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...] git diff [<options>] <commit>...<commit> [--] [<path>...] git diff [<options>] <blob> <blob> -git diff [<options>] --no-index [--] <path> <path> +git diff [<options>] --no-index [--] <path> <path> [<pathspec>...] DESCRIPTION ----------- @@ -31,14 +31,18 @@ files on disk. further add to the index but you still haven't. You can stage these changes by using linkgit:git-add[1]. -`git diff [<options>] --no-index [--] <path> <path>`:: +`git diff [<options>] --no-index [--] <path> <path> [<pathspec>...]`:: This form is to compare the given two paths on the filesystem. You can omit the `--no-index` option when running the command in a working tree controlled by Git and at least one of the paths points outside the working tree, or when running the command outside a working tree - controlled by Git. This form implies `--exit-code`. + controlled by Git. This form implies `--exit-code`. If both + paths point to directories, additional pathspecs may be + provided. These will limit the files included in the + difference. All such pathspecs must be relative as they + apply to both sides of the diff. `git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]`:: diff --git a/Documentation/git-fast-export.adoc b/Documentation/git-fast-export.adoc index 752e4b9b01..43bbb4f63c 100644 --- a/Documentation/git-fast-export.adoc +++ b/Documentation/git-fast-export.adoc @@ -27,17 +27,31 @@ OPTIONS Insert 'progress' statements every <n> objects, to be shown by 'git fast-import' during import. ---signed-tags=(verbatim|warn|warn-strip|strip|abort):: +--signed-tags=(verbatim|warn-verbatim|warn-strip|strip|abort):: Specify how to handle signed tags. Since any transformation - after the export can change the tag names (which can also happen - when excluding revisions) the signatures will not match. + after the export (or during the export, such as excluding + revisions) can change the hashes being signed, the signatures + may become invalid. + When asking to 'abort' (which is the default), this program will die when encountering a signed tag. With 'strip', the tags will silently be made unsigned, with 'warn-strip' they will be made unsigned but a warning will be displayed, with 'verbatim', they will be silently -exported and with 'warn', they will be exported, but you will see a -warning. +exported and with 'warn-verbatim' (or 'warn', a deprecated synonym), +they will be exported, but you will see a warning. 'verbatim' and +'warn-verbatim' should only be used if you know that no transformation +affecting tags or any commit in their history will be performed by you +or by fast-export or fast-import, or if you do not care that the +resulting tag will have an invalid signature. + +--signed-commits=(verbatim|warn-verbatim|warn-strip|strip|abort):: + Specify how to handle signed commits. Behaves exactly as + '--signed-tags', but for commits. Default is 'strip', which + is the same as how earlier versions of this command without + this option behaved. ++ +NOTE: This is highly experimental and the format of the data stream may +change in the future without compatibility guarantees. --tag-of-filtered-object=(abort|drop|rewrite):: Specify how to handle tags whose tagged object is filtered out. diff --git a/Documentation/git-fast-import.adoc b/Documentation/git-fast-import.adoc index 58a2eaa51a..250d866652 100644 --- a/Documentation/git-fast-import.adoc +++ b/Documentation/git-fast-import.adoc @@ -431,13 +431,22 @@ and control the current import process. More detailed discussion Create or update a branch with a new commit, recording one logical change to the project. +//// +Yes, it's intentional that the 'gpgsig' line doesn't have a trailing +`LF`; the definition of `data` has a byte-count prefix, so it +doesn't need an `LF` to act as a terminator (and `data` also already +includes an optional trailing `LF?` just in case you want to include +one). +//// + .... 'commit' SP <ref> LF mark? original-oid? ('author' (SP <name>)? SP LT <email> GT SP <when> LF)? 'committer' (SP <name>)? SP LT <email> GT SP <when> LF - ('encoding' SP <encoding>)? + ('gpgsig' SP <alg> LF data)? + ('encoding' SP <encoding> LF)? data ('from' SP <commit-ish> LF)? ('merge' SP <commit-ish> LF)* @@ -505,6 +514,18 @@ that was selected by the --date-format=<fmt> command-line option. See ``Date Formats'' above for the set of supported formats, and their syntax. +`gpgsig` +^^^^^^^^ + +The optional `gpgsig` command is used to include a PGP/GPG signature +that signs the commit data. + +Here <alg> specifies which hashing algorithm is used for this +signature, either `sha1` or `sha256`. + +NOTE: This is highly experimental and the format of the data stream may +change in the future without compatibility guarantees. + `encoding` ^^^^^^^^^^ The optional `encoding` command indicates the encoding of the commit diff --git a/Documentation/git-for-each-ref.adoc b/Documentation/git-for-each-ref.adoc index ffb97e62c2..5ef89fc0fe 100644 --- a/Documentation/git-for-each-ref.adoc +++ b/Documentation/git-for-each-ref.adoc @@ -441,6 +441,7 @@ Ref: %(*refname) A simple example showing the use of shell eval on the output, demonstrating the use of --shell. List the prefixes of all heads: + ------------ #!/bin/sh @@ -455,6 +456,7 @@ done A bit more elaborate report on tags, demonstrating that the format may be an entire script: + ------------ #!/bin/sh diff --git a/Documentation/git-fsck.adoc b/Documentation/git-fsck.adoc index 8f32800a83..11203ba925 100644 --- a/Documentation/git-fsck.adoc +++ b/Documentation/git-fsck.adoc @@ -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] [--[no-]references] [<object>...] DESCRIPTION ----------- @@ -104,6 +104,11 @@ care about this output and want to speed it up further. progress status even if the standard error stream is not directed to a terminal. +--[no-]references:: + Control whether to check the references database consistency + via 'git refs verify'. See linkgit:git-refs[1] for details. + The default is to check the references database. + CONFIGURATION ------------- diff --git a/Documentation/git-maintenance.adoc b/Documentation/git-maintenance.adoc index 0450d74aff..540b5cf68b 100644 --- a/Documentation/git-maintenance.adoc +++ b/Documentation/git-maintenance.adoc @@ -126,13 +126,17 @@ loose-objects:: objects that already exist in a pack-file; concurrent Git processes will examine the pack-file for the object data instead of the loose object. Second, it creates a new pack-file (starting with "loose-") - containing a batch of loose objects. The batch size is limited to 50 - thousand objects to prevent the job from taking too long on a - repository with many loose objects. The `gc` task writes unreachable - objects as loose objects to be cleaned up by a later step only if - they are not re-added to a pack-file; for this reason it is not - advisable to enable both the `loose-objects` and `gc` tasks at the - same time. + containing a batch of loose objects. ++ +The batch size defaults to fifty thousand objects to prevent the job from +taking too long on a repository with many loose objects. Use the +`maintenance.loose-objects.batchSize` config option to adjust this size, +including a value of `0` to remove the limit. ++ +The `gc` task writes unreachable objects as loose objects to be cleaned up +by a later step only if they are not re-added to a pack-file; for this +reason it is not advisable to enable both the `loose-objects` and `gc` +tasks at the same time. incremental-repack:: The `incremental-repack` job repacks the object directory @@ -158,6 +162,18 @@ pack-refs:: need to iterate across many references. See linkgit:git-pack-refs[1] for more information. +reflog-expire:: + The `reflog-expire` task deletes any entries in the reflog older than the + expiry threshold. See linkgit:git-reflog[1] for more information. + +rerere-gc:: + The `rerere-gc` task invokes garbage collection for stale entries in + the rerere cache. See linkgit:git-rerere[1] for more information. + +worktree-prune:: + The `worktree-prune` task deletes stale or broken worktrees. See + linkgit:git-worktree[1] for more information. + OPTIONS ------- --auto:: diff --git a/Documentation/git-merge-tree.adoc b/Documentation/git-merge-tree.adoc index cf0578f9b5..f824eea61f 100644 --- a/Documentation/git-merge-tree.adoc +++ b/Documentation/git-merge-tree.adoc @@ -65,6 +65,12 @@ OPTIONS default is to include these messages if there are merge conflicts, and to omit them otherwise. +--quiet:: + Disable all output from the program. Useful when you are only + interested in the exit status. Allows merge-tree to exit + early when it finds a conflict, and allows it to avoid writing + most objects created by merges. + --allow-unrelated-histories:: merge-tree will by default error out if the two branches specified share no common history. This flag can be given to override that diff --git a/Documentation/git-merge.adoc b/Documentation/git-merge.adoc index 64281d6d44..12aa859d16 100644 --- a/Documentation/git-merge.adoc +++ b/Documentation/git-merge.adoc @@ -8,13 +8,13 @@ git-merge - Join two or more development histories together SYNOPSIS -------- -[verse] -'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit] +[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>] [--into-name <branch>] [<commit>...] -'git merge' (--continue | --abort | --quit) +git merge (--continue | --abort | --quit) DESCRIPTION ----------- @@ -57,7 +57,7 @@ merge started (and especially if those changes were further modified after the merge was started), `git merge --abort` will in some cases be unable to reconstruct the original (pre-merge) changes. Therefore: -*Warning*: Running `git merge` with non-trivial uncommitted changes is +WARNING: Running `git merge` with non-trivial uncommitted changes is discouraged: while possible, it may leave you in a state that is hard to back out of in the case of a conflict. @@ -67,7 +67,7 @@ OPTIONS include::merge-options.adoc[] --m <msg>:: +`-m <msg>`:: Set the commit message to be used for the merge commit (in case one is created). + @@ -78,13 +78,13 @@ 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>:: +`--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 + _<branch>_, instead of the name of the real branch to which the merge is made. --F <file>:: ---file=<file>:: +`-F <file>`:: +`--file=<file>`:: Read the commit message to be used for the merge commit (in case one is created). + @@ -93,12 +93,12 @@ will be appended to the specified message. include::rerere-options.adoc[] ---overwrite-ignore:: ---no-overwrite-ignore:: +`--overwrite-ignore`:: +`--no-overwrite-ignore`:: Silently overwrite ignored files from the merge result. This is the default behavior. Use `--no-overwrite-ignore` to abort. ---abort:: +`--abort`:: Abort the current conflict resolution process, and try to reconstruct the pre-merge state. If an autostash entry is present, apply it to the worktree. @@ -114,17 +114,17 @@ which case `git merge --abort` applies the stash entry to the worktree whereas `git reset --merge` will save the stashed changes in the stash list. ---quit:: +`--quit`:: Forget about the current merge in progress. Leave the index and the working tree as-is. If `MERGE_AUTOSTASH` is present, the stash entry will be saved to the stash list. ---continue:: +`--continue`:: After a `git merge` stops due to conflicts you can conclude the merge by running `git merge --continue` (see "HOW TO RESOLVE CONFLICTS" section below). -<commit>...:: +`<commit>...`:: Commits, usually other branch heads, to merge into our branch. Specifying more than one commit will create a merge with more than two parents (affectionately called an Octopus merge). @@ -152,7 +152,7 @@ To avoid recording unrelated changes in the merge commit, `git pull` and `git merge` will also abort if there are any changes registered in the index relative to the `HEAD` commit. (Special narrow exceptions to this rule may exist depending on which merge -strategy is in use, but generally, the index must match HEAD.) +strategy is in use, but generally, the index must match `HEAD`.) If all named commits are already ancestors of `HEAD`, `git merge` will exit early with the message "Already up to date." @@ -195,11 +195,11 @@ happens: stage 2 from `HEAD`, and stage 3 from `MERGE_HEAD` (you can inspect the stages with `git ls-files -u`). The working tree files contain the result of the merge operation; i.e. 3-way - merge results with familiar conflict markers `<<<` `===` `>>>`. + merge results with familiar conflict markers +<<<+ `===` +>>>+. 5. A ref named `AUTO_MERGE` is written, pointing to a tree corresponding to the current content of the working tree (including conflict markers for textual conflicts). Note that this ref is only - written when the 'ort' merge strategy is used (the default). + written when the `ort` merge strategy is used (the default). 6. No other changes are made. In particular, the local modifications you had before you started merge will stay the same and the index entries for them stay as they were, @@ -231,7 +231,6 @@ git merge v1.2.3^0 git merge --ff-only v1.2.3 ---- - HOW CONFLICTS ARE PRESENTED --------------------------- @@ -260,7 +259,7 @@ And here is another line that is cleanly resolved or unmodified. ------------ The area where a pair of conflicting changes happened is marked with markers -`<<<<<<<`, `=======`, and `>>>>>>>`. The part before the `=======` ++<<<<<<<+, `=======`, and +>>>>>>>+. The part before the `=======` is typically your side, and the part afterwards is typically their side. The default format does not show what the original said in the conflicting @@ -270,7 +269,7 @@ 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 either "diff3" or "zdiff3". In "diff3" +configuration variable to either `diff3` or `zdiff3`. In `diff3` style, the above conflict may look like this: ------------ @@ -290,7 +289,7 @@ Git makes conflict resolution easy. And here is another line that is cleanly resolved or unmodified. ------------ -while in "zdiff3" style, it may look like this: +while in `zdiff3` style, it may look like this: ------------ Here are lines that are either unchanged from the common @@ -308,8 +307,8 @@ Git makes conflict resolution easy. And here is another line that is cleanly resolved or unmodified. ------------ -In addition to the `<<<<<<<`, `=======`, and `>>>>>>>` markers, it uses -another `|||||||` marker that is followed by the original text. You can +In addition to the +<<<<<<<+, `=======`, and +>>>>>>>+ markers, it uses +another +|||||||+ marker that is followed by the original text. You can tell that the original just stated a fact, and your side simply gave in to that statement and gave up, while the other side tried to have a more positive attitude. You can sometimes come up with a better resolution by @@ -390,8 +389,8 @@ include::merge-strategies.adoc[] CONFIGURATION ------------- -branch.<name>.mergeOptions:: - Sets default options for merging into branch <name>. The syntax and +`branch.<name>.mergeOptions`:: + Sets default options for merging into branch _<name>_. The syntax and supported options are the same as those of `git merge`, but option values containing whitespace characters are currently not supported. diff --git a/Documentation/git-mergetool.adoc b/Documentation/git-mergetool.adoc index 046c3258f0..77d0b50550 100644 --- a/Documentation/git-mergetool.adoc +++ b/Documentation/git-mergetool.adoc @@ -7,95 +7,95 @@ git-mergetool - Run merge conflict resolution tools to resolve merge conflicts SYNOPSIS -------- -[verse] -'git mergetool' [--tool=<tool>] [-y | --[no-]prompt] [<file>...] +[synopsis] +git mergetool [--tool=<tool>] [-y | --[no-]prompt] [<file>...] DESCRIPTION ----------- Use `git mergetool` to run one of several merge utilities to resolve -merge conflicts. It is typically run after 'git merge'. +merge conflicts. It is typically run after `git merge`. If one or more <file> parameters are given, the merge tool program will be run to resolve differences in each file (skipping those without conflicts). Specifying a directory will include all unresolved files in -that path. If no <file> names are specified, 'git mergetool' will run +that path. If no _<file>_ names are specified, `git mergetool` will run the merge tool program on every file with merge conflicts. OPTIONS ------- --t <tool>:: ---tool=<tool>:: - Use the merge resolution program specified by <tool>. - Valid values include emerge, gvimdiff, kdiff3, - meld, vimdiff, and tortoisemerge. Run `git mergetool --tool-help` - for the list of valid <tool> settings. +`-t <tool>`:: +`--tool=<tool>`:: + Use the merge resolution program specified by _<tool>_. + Valid values include `emerge`, `gvimdiff`, `kdiff3`, + `meld`, `vimdiff`, and `tortoisemerge`. Run `git mergetool --tool-help` + for the list of valid _<tool>_ settings. + -If a merge resolution program is not specified, 'git mergetool' +If a merge resolution program is not specified, `git mergetool` will use the configuration variable `merge.tool`. If the -configuration variable `merge.tool` is not set, 'git mergetool' +configuration variable `merge.tool` is not set, `git mergetool` will pick a suitable default. + You can explicitly provide a full path to the tool by setting the configuration variable `mergetool.<tool>.path`. For example, you can configure the absolute path to kdiff3 by setting -`mergetool.kdiff3.path`. Otherwise, 'git mergetool' assumes the -tool is available in PATH. +`mergetool.kdiff3.path`. Otherwise, `git mergetool` assumes the +tool is available in `$PATH`. + Instead of running one of the known merge tool programs, -'git mergetool' can be customized to run an alternative program +`git mergetool` can be customized to run an alternative program by specifying the command line to invoke in a configuration variable `mergetool.<tool>.cmd`. + -When 'git mergetool' is invoked with this tool (either through the +When `git mergetool` is invoked with this tool (either through the `-t` or `--tool` option or the `merge.tool` configuration -variable), the configured command line will be invoked with `$BASE` +variable), the configured command line will be invoked with `BASE` set to the name of a temporary file containing the common base for -the merge, if available; `$LOCAL` set to the name of a temporary +the merge, if available; `LOCAL` set to the name of a temporary file containing the contents of the file on the current branch; -`$REMOTE` set to the name of a temporary file containing the -contents of the file to be merged, and `$MERGED` set to the name +`REMOTE` set to the name of a temporary file containing the +contents of the file to be merged, and `MERGED` set to the name of the file to which the merge tool should write the result of the merge resolution. + If the custom merge tool correctly indicates the success of a merge resolution with its exit code, then the configuration variable `mergetool.<tool>.trustExitCode` can be set to `true`. -Otherwise, 'git mergetool' will prompt the user to indicate the +Otherwise, `git mergetool` will prompt the user to indicate the success of the resolution after the custom tool has exited. ---tool-help:: +`--tool-help`:: Print a list of merge tools that may be used with `--tool`. --y:: ---no-prompt:: +`-y`:: +`--no-prompt`:: Don't prompt before each invocation of the merge resolution program. This is the default if the merge resolution program is explicitly specified with the `--tool` option or with the `merge.tool` configuration variable. ---prompt:: +`--prompt`:: Prompt before each invocation of the merge resolution program to give the user a chance to skip the path. --g:: ---gui:: - When 'git-mergetool' is invoked with the `-g` or `--gui` option, +`-g`:: +`--gui`:: + When `git-mergetool` is invoked with the `-g` or `--gui` option, the default merge tool will be read from the configured `merge.guitool` variable instead of `merge.tool`. If `merge.guitool` is not set, we will fallback to the tool configured under `merge.tool`. This may be autoselected using the configuration variable `mergetool.guiDefault`. ---no-gui:: +`--no-gui`:: This overrides a previous `-g` or `--gui` setting or `mergetool.guiDefault` configuration and reads the default merge tool from the configured `merge.tool` variable. --O<orderfile>:: +`-O<orderfile>`:: Process files in the order specified in the - <orderfile>, which has one shell glob pattern per line. + _<orderfile>_, which has one shell glob pattern per line. This overrides the `diff.orderFile` configuration variable (see linkgit:git-config[1]). To cancel `diff.orderFile`, use `-O/dev/null`. diff --git a/Documentation/git-multi-pack-index.adoc b/Documentation/git-multi-pack-index.adoc index 631d5c7d15..b6cd0d7f85 100644 --- a/Documentation/git-multi-pack-index.adoc +++ b/Documentation/git-multi-pack-index.adoc @@ -38,10 +38,13 @@ write:: + -- --preferred-pack=<pack>:: - Optionally specify the tie-breaking pack used when - multiple packs contain the same object. `<pack>` must - contain at least one object. If not given, ties are - broken in favor of the pack with the lowest mtime. + When specified, break ties in favor of this pack when + there are additional copies of its objects in other + packs. Ties for objects not found in the preferred + pack are always resolved in favor of the copy in the + pack with the highest mtime. If unspecified, the pack + with the lowest mtime is used by default. The + preferred pack must have at least one object. --[no-]bitmap:: Control whether or not a multi-pack bitmap is written. diff --git a/Documentation/git-mv.adoc b/Documentation/git-mv.adoc index dc1bf61534..f707e998f7 100644 --- a/Documentation/git-mv.adoc +++ b/Documentation/git-mv.adoc @@ -8,19 +8,18 @@ git-mv - Move or rename a file, a directory, or a symlink SYNOPSIS -------- -[verse] -'git mv' [<options>] <source>... <destination> + +[synopsis] +git mv [-v] [-f] [-n] [-k] <source> <destination> +git mv [-v] [-f] [-n] [-k] <source>... <destination-directory> DESCRIPTION ----------- Move or rename a file, directory, or symlink. - git mv [-v] [-f] [-n] [-k] <source> <destination> - git mv [-v] [-f] [-n] [-k] <source> ... <destination-directory> - -In the first form, it renames <source>, which must exist and be either -a file, symlink or directory, to <destination>. -In the second form, the last argument has to be an existing +In the first form, it renames _<source>_, which must exist and be either +a file, symlink or directory, to _<destination>_. +In the second form, _<destination-directory>_ has to be an existing directory; the given sources will be moved into this directory. The index is updated after successful completion, but the change must still be @@ -28,20 +27,20 @@ committed. OPTIONS ------- --f:: ---force:: +`-f`:: +`--force`:: Force renaming or moving of a file even if the <destination> exists. --k:: +`-k`:: Skip move or rename actions which would lead to an error condition. An error happens when a source is neither existing nor controlled by Git, or when it would overwrite an existing file unless `-f` is given. --n:: ---dry-run:: +`-n`:: +`--dry-run`:: Do nothing; only show what would happen --v:: ---verbose:: +`-v`:: +`--verbose`:: Report the names of files as they are moved. SUBMODULES @@ -49,8 +48,8 @@ SUBMODULES Moving a submodule using a gitfile (which means they were cloned with a Git version 1.7.8 or newer) will update the gitfile and core.worktree setting to make the submodule work in the new location. -It also will attempt to update the submodule.<name>.path setting in -the linkgit:gitmodules[5] file and stage that file (unless -n is used). +It also will attempt to update the `submodule.<name>.path` setting in +the linkgit:gitmodules[5] file and stage that file (unless `-n` is used). BUGS ---- diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc index bcfe3dacd3..46a232ca71 100644 --- a/Documentation/git-notes.adoc +++ b/Documentation/git-notes.adoc @@ -87,6 +87,9 @@ In `--stdin` mode, take lines in the format on standard input, and copy the notes from each _<from-object>_ to its corresponding _<to-object>_. (The optional _<rest>_ is ignored so that the command can read the input given to the `post-rewrite` hook.) ++ +`--stdin` cannot be combined with object names given on the command +line. `append`:: Append new message(s) given by `-m` or `-F` options to an @@ -124,6 +127,10 @@ When done, the user can either finalize the merge with giving zero or one object from the command line, this is equivalent to specifying an empty note message to the `edit` subcommand. ++ +In `--stdin` mode, also remove the object names given on standard +input. In other words, `--stdin` can be combined with object names from +the command line. `prune`:: Remove all notes for non-existing/unreachable objects. @@ -144,26 +151,18 @@ OPTIONS Use the given note message (instead of prompting). If multiple `-m` options are given, their values are concatenated as separate paragraphs. - Lines starting with `#` and empty lines other than a - single line between paragraphs will be stripped out. - If you wish to keep them verbatim, use `--no-stripspace`. `-F <file>`:: `--file=<file>`:: Take the note message from the given file. Use `-` to read the note message from the standard input. - Lines starting with `#` and empty lines other than a - single line between paragraphs will be stripped out. - If you wish to keep them verbatim, use `--no-stripspace`. `-C <object>`:: `--reuse-message=<object>`:: Take the given blob object (for example, another note) as the note message. (Use `git notes copy <object>` instead to - copy notes between objects.). By default, message will be - copied verbatim, but if you wish to strip out the lines - starting with `#` and empty lines other than a single line - between paragraphs, use with `--stripspace` option. + copy notes between objects.) Implies `--no-stripspace` since + the default behavior is to copy the message verbatim. `-c <object>`:: `--reedit-message=<object>`:: @@ -174,21 +173,34 @@ OPTIONS Allow an empty note object to be stored. The default behavior is to automatically remove empty notes. -`--[no-]separator`:: `--separator=<paragraph-break>`:: +`--separator`:: +`--no-separator`:: Specify a string used as a custom inter-paragraph separator (a newline is added at the end as needed). If `--no-separator`, no separators will be added between paragraphs. Defaults to a blank line. -`--[no-]stripspace`:: - Strip leading and trailing whitespace from the note message. - Also strip out empty lines other than a single line between - paragraphs. Lines starting with `#` will be stripped out - in non-editor cases like `-m`, `-F` and `-C`, but not in - editor case like `git notes edit`, `-c`, etc. - -`--ref <ref>`:: +`--stripspace`:: +`--no-stripspace`:: + Clean up whitespace. Specifically (see + linkgit:git-stripspace[1]): ++ +-- +- remove trailing whitespace from all lines +- collapse multiple consecutive empty lines into one empty line +- remove empty lines from the beginning and end of the input +- add a missing `\n` to the last line if necessary. +-- ++ +`--stripspace` is the default except for +`-C`/`--reuse-message`. However, keep in mind that this depends on the +order of similar options. For example, for `-C <object> -m<message>`, +`--stripspace` will be used because the default for `-m` overrides the +previous `-C`. This is a known limitation that may be fixed in the +future. + +`--ref=<ref>`:: Manipulate the notes tree in _<ref>_. This overrides `GIT_NOTES_REF` and the `core.notesRef` configuration. The ref specifies the full refname when it begins with `refs/notes/`; when it @@ -200,9 +212,7 @@ OPTIONS object that does not have notes attached to it. `--stdin`:: - Also read the object names to remove notes from the standard - input (there is no reason you cannot combine this with object - names from the command line). + Only valid for `remove` and `copy`. See the respective subcommands. `-n`:: `--dry-run`:: diff --git a/Documentation/git-p4.adoc b/Documentation/git-p4.adoc index de5ee6748e..f97b786bf9 100644 --- a/Documentation/git-p4.adoc +++ b/Documentation/git-p4.adoc @@ -80,6 +80,7 @@ This: To reproduce the entire p4 history in Git, use the '@all' modifier on the depot path: + ------------ $ git p4 clone //depot/path/project@all ------------ @@ -89,19 +90,23 @@ Sync ~~~~ As development continues in the p4 repository, those changes can be included in the Git repository using: + ------------ $ git p4 sync ------------ + This command finds new changes in p4 and imports them as Git commits. P4 repositories can be added to an existing Git repository using 'git p4 sync' too: + ------------ $ mkdir repo-git $ cd repo-git $ git init $ git p4 sync //path/in/your/perforce/depot ------------ + This imports the specified depot into 'refs/remotes/p4/master' in an existing Git repository. The `--branch` option can be used to specify a different branch to @@ -125,6 +130,7 @@ and merge them with local uncommitted changes. Often, the p4 repository is the ultimate location for all code, thus a rebase workflow makes sense. This command does 'git p4 sync' followed by 'git rebase' to move local commits on top of updated p4 changes. + ------------ $ git p4 rebase ------------ @@ -140,16 +146,19 @@ will be created and populated if it does not already exist. To submit all changes that are in the current Git branch but not in the 'p4/master' branch, use: + ------------ $ git p4 submit ------------ To specify a branch other than the current one, use: + ------------ $ git p4 submit topicbranch ------------ To specify a single commit or a range of commits, use: + ------------ $ git p4 submit --commit <sha1> $ git p4 submit --commit <sha1..sha1> @@ -510,20 +519,24 @@ when cloning or syncing to have 'git p4' automatically find subdirectories in p4, and to generate these as branches in Git. For example, if the P4 repository structure is: + ---- //depot/main/... //depot/branch1/... ---- And "p4 branch -o branch1" shows a View line that looks like: + ---- //depot/main/... //depot/branch1/... ---- Then this 'git p4 clone' command: + ---- git p4 clone --detect-branches //depot@all ---- + produces a separate branch in 'refs/remotes/p4/' for //depot/main, called 'master', and one for //depot/branch1 called 'depot/branch1'. @@ -536,6 +549,7 @@ simple p4 branch specification, where the "source" and "destination" are the path elements in the p4 repository. The example above relied on the presence of the p4 branch. Without p4 branches, the same result will occur with: + ---- git init depot cd depot diff --git a/Documentation/git-pack-objects.adoc b/Documentation/git-pack-objects.adoc index 7f69ae4855..b1c5aa27da 100644 --- a/Documentation/git-pack-objects.adoc +++ b/Documentation/git-pack-objects.adoc @@ -10,13 +10,13 @@ SYNOPSIS -------- [verse] 'git pack-objects' [-q | --progress | --all-progress] [--all-progress-implied] - [--no-reuse-delta] [--delta-base-offset] [--non-empty] - [--local] [--incremental] [--window=<n>] [--depth=<n>] - [--revs [--unpacked | --all]] [--keep-pack=<pack-name>] - [--cruft] [--cruft-expiration=<time>] - [--stdout [--filter=<filter-spec>] | <base-name>] - [--shallow] [--keep-true-parents] [--[no-]sparse] - [--name-hash-version=<n>] < <object-list> + [--no-reuse-delta] [--delta-base-offset] [--non-empty] + [--local] [--incremental] [--window=<n>] [--depth=<n>] + [--revs [--unpacked | --all]] [--keep-pack=<pack-name>] + [--cruft] [--cruft-expiration=<time>] + [--stdout [--filter=<filter-spec>] | <base-name>] + [--shallow] [--keep-true-parents] [--[no-]sparse] + [--name-hash-version=<n>] [--path-walk] < <object-list> DESCRIPTION @@ -375,6 +375,17 @@ many different directories. At the moment, this version is not allowed when writing reachability bitmap files with `--write-bitmap-index` and it will be automatically changed to version `1`. +--path-walk:: + Perform compression by first organizing objects by path, then a + second pass that compresses across paths as normal. This has the + potential to improve delta compression especially in the presence + of filenames that cause collisions in Git's default name-hash + algorithm. ++ +Incompatible with `--delta-islands`, `--shallow`, or `--filter`. The +`--use-bitmap-index` option will be ignored in the presence of +`--path-walk.` + DELTA ISLANDS ------------- diff --git a/Documentation/git-pack-refs.adoc b/Documentation/git-pack-refs.adoc index 2dcabaf74c..652c549771 100644 --- a/Documentation/git-pack-refs.adoc +++ b/Documentation/git-pack-refs.adoc @@ -88,10 +88,10 @@ Do not pack refs matching the given `glob(7)` pattern. Repetitions of this optio accumulate exclusion patterns. Use `--no-exclude` to clear and reset the list of patterns. If a ref is already packed, including it with `--exclude` will not unpack it. - ++ When used with `--all`, pack only loose refs which do not match any of the provided `--exclude` patterns. - ++ When used with `--include`, refs provided to `--include`, minus refs that are provided to `--exclude` will be packed. diff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc index 153cb69a4f..956d3048f5 100644 --- a/Documentation/git-rebase.adoc +++ b/Documentation/git-rebase.adoc @@ -1107,10 +1107,12 @@ In that case, the fix is easy because 'git rebase' knows to skip changes that are already present in the new upstream (unless `--reapply-cherry-picks` is given). So if you say (assuming you're on 'topic') + ------------ $ git rebase subsystem ------------ you will end up with the fixed history + ------------ o---o---o---o---o---o---o---o master \ @@ -1145,6 +1147,7 @@ of the old 'subsystem', for example: You can then transplant the old `subsystem..topic` to the new tip by saying (for the reflog case, and assuming you are on 'topic' already): + ------------ $ git rebase --onto subsystem subsystem@{1} ------------ diff --git a/Documentation/git-receive-pack.adoc b/Documentation/git-receive-pack.adoc index 20aca92073..0956086d61 100644 --- a/Documentation/git-receive-pack.adoc +++ b/Documentation/git-receive-pack.adoc @@ -46,6 +46,18 @@ OPTIONS `$GIT_URL/info/refs?service=git-receive-pack` requests. See `--http-backend-info-refs` in linkgit:git-upload-pack[1]. +--skip-connectivity-check:: + Bypasses the connectivity checks that validate the existence of all + objects in the transitive closure of reachable objects. This option is + intended for server operators that want to implement their own object + connectivity validation outside of Git. This is useful in such cases + where the server-side knows additional information about how Git is + being used and thus can rely on certain guarantees to more efficiently + compute object connectivity that Git itself cannot make. Usage of this + option without a reliable external mechanism to ensure full reachable + object connectivity risks corrupting the repository and should not be + used in the general case. + PRE-RECEIVE HOOK ---------------- Before any ref is updated, if $GIT_DIR/hooks/pre-receive file exists diff --git a/Documentation/git-reflog.adoc b/Documentation/git-reflog.adoc index a929c52982..412f06b8fe 100644 --- a/Documentation/git-reflog.adoc +++ b/Documentation/git-reflog.adoc @@ -16,6 +16,7 @@ SYNOPSIS [--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...] 'git reflog delete' [--rewrite] [--updateref] [--dry-run | -n] [--verbose] <ref>@{<specifier>}... +'git reflog drop' [--all [--single-worktree] | <refs>...] 'git reflog exists' <ref> DESCRIPTION @@ -48,10 +49,14 @@ and not reachable from the current tip, are removed from the reflog. This is typically not used directly by end users -- instead, see linkgit:git-gc[1]. -The "delete" subcommand deletes single entries from the reflog. Its -argument must be an _exact_ entry (e.g. "`git reflog delete -master@{2}`"). This subcommand is also typically not used directly by -end users. +The "delete" subcommand deletes single entries from the reflog, but +not the reflog itself. Its argument must be an _exact_ entry (e.g. "`git +reflog delete master@{2}`"). This subcommand is also typically not used +directly by end users. + +The "drop" subcommand completely removes the reflog for the specified +references. This is in contrast to "expire" and "delete", both of which +can be used to delete reflog entries, but not the reflog itself. The "exists" subcommand checks whether a ref has a reflog. It exits with zero status if the reflog exists, and non-zero status if it does @@ -132,6 +137,16 @@ Options for `delete` `--dry-run`, and `--verbose`, with the same meanings as when they are used with `expire`. +Options for `drop` +~~~~~~~~~~~~~~~~~~ + +--all:: + Drop the reflogs of all references from all worktrees. + +--single-worktree:: + By default when `--all` is specified, reflogs from all working + trees are dropped. This option limits the processing to reflogs + from the current working tree only. GIT --- diff --git a/Documentation/git-repack.adoc b/Documentation/git-repack.adoc index 5852a5c973..d12c4985f6 100644 --- a/Documentation/git-repack.adoc +++ b/Documentation/git-repack.adoc @@ -11,7 +11,7 @@ SYNOPSIS [verse] 'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [-b] [-m] [--window=<n>] [--depth=<n>] [--threads=<n>] [--keep-pack=<pack-name>] - [--write-midx] [--name-hash-version=<n>] + [--write-midx] [--name-hash-version=<n>] [--path-walk] DESCRIPTION ----------- @@ -77,15 +77,18 @@ to the new separate pack will be written. Only useful with `--cruft -d`. --max-cruft-size=<n>:: - Repack cruft objects into packs as large as `<n>` bytes before - creating new packs. As long as there are enough cruft packs - smaller than `<n>`, repacking will cause a new cruft pack to - be created containing objects from any combined cruft packs, - along with any new unreachable objects. Cruft packs larger than - `<n>` will not be modified. When the new cruft pack is larger - than `<n>` bytes, it will be split into multiple packs, all of - which are guaranteed to be at most `<n>` bytes in size. Only - useful with `--cruft -d`. + Overrides `--max-pack-size` for cruft packs. Inherits the value of + `--max-pack-size` (if any) by default. See the documentation for + `--max-pack-size` for more details. + +--combine-cruft-below-size=<n>:: + When generating cruft packs without pruning, only repack + existing cruft packs whose size is strictly less than `<n>`, + where `<n>` represents a number of bytes, which can optionally + be suffixed with "k", "m", or "g". Cruft packs whose size is + greater than or equal to `<n>` are left as-is and not repacked. + Useful when you want to avoid repacking large cruft pack(s) in + repositories that have many and/or large unreachable objects. --expire-to=<dir>:: Write a cruft pack containing pruned objects (if any) to the @@ -255,6 +258,9 @@ linkgit:git-multi-pack-index[1]). Provide this argument to the underlying `git pack-objects` process. See linkgit:git-pack-objects[1] for full details. +--path-walk:: + Pass the `--path-walk` option to the underlying `git pack-objects` + process. See linkgit:git-pack-objects[1] for full details. CONFIGURATION ------------- diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc index 79ad5643ee..53ab88c545 100644 --- a/Documentation/git-reset.adoc +++ b/Documentation/git-reset.adoc @@ -7,23 +7,23 @@ git-reset - Reset current HEAD to the specified state SYNOPSIS -------- -[verse] -'git reset' [-q] [<tree-ish>] [--] <pathspec>... -'git reset' [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>] -'git reset' (--patch | -p) [<tree-ish>] [--] [<pathspec>...] -'git reset' [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>] +[synopsis] +git reset [-q] [<tree-ish>] [--] <pathspec>... +git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>] +git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...] +git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>] DESCRIPTION ----------- -In the first three forms, copy entries from `<tree-ish>` to the index. -In the last form, set the current branch head (`HEAD`) to `<commit>`, +In the first three forms, copy entries from _<tree-ish>_ to the index. +In the last form, set the current branch head (`HEAD`) to _<commit>_, optionally modifying index and working tree to match. -The `<tree-ish>`/`<commit>` defaults to `HEAD` in all forms. +The _<tree-ish>_/_<commit>_ defaults to `HEAD` in all forms. -'git reset' [-q] [<tree-ish>] [--] <pathspec>...:: -'git reset' [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]:: +`git reset [-q] [<tree-ish>] [--] <pathspec>...`:: +`git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]`:: These forms reset the index entries for all paths that match the - `<pathspec>` to their state at `<tree-ish>`. (It does not affect + _<pathspec>_ to their state at _<tree-ish>_. (It does not affect the working tree or the current branch.) + This means that `git reset <pathspec>` is the opposite of `git add @@ -37,30 +37,30 @@ and specifying a commit with `--source`, you can copy the contents of a path out of a commit to the index and to the working tree in one go. -'git reset' (--patch | -p) [<tree-ish>] [--] [<pathspec>...]:: +`git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]`:: Interactively select hunks in the difference between the index - and `<tree-ish>` (defaults to `HEAD`). The chosen hunks are applied + and _<tree-ish>_ (defaults to `HEAD`). The chosen hunks are applied in reverse to the index. + This means that `git reset -p` is the opposite of `git add -p`, i.e. -you can use it to selectively reset hunks. See the ``Interactive Mode'' +you can use it to selectively reset hunks. See the "Interactive Mode" section of linkgit:git-add[1] to learn how to operate the `--patch` mode. -'git reset' [<mode>] [<commit>]:: - This form resets the current branch head to `<commit>` and - possibly updates the index (resetting it to the tree of `<commit>`) and - the working tree depending on `<mode>`. Before the operation, `ORIG_HEAD` - is set to the tip of the current branch. If `<mode>` is omitted, - defaults to `--mixed`. The `<mode>` must be one of the following: +`git reset [<mode>] [<commit>]`:: + This form resets the current branch head to _<commit>_ and + possibly updates the index (resetting it to the tree of _<commit>_) and + the working tree depending on _<mode>_. Before the operation, `ORIG_HEAD` + is set to the tip of the current branch. If _<mode>_ is omitted, + defaults to `--mixed`. The _<mode>_ must be one of the following: + -- ---soft:: +`--soft`:: Does not touch the index file or the working tree at all (but - resets the head to `<commit>`, just like all modes do). This leaves + resets the head to _<commit>_, just like all modes do). This leaves all your changed files "Changes to be committed", as `git status` would put it. ---mixed:: +`--mixed`:: Resets the index but not the working tree (i.e., the changed files are preserved but not marked for commit) and reports what has not been updated. This is the default action. @@ -68,33 +68,33 @@ section of linkgit:git-add[1] to learn how to operate the `--patch` mode. If `-N` is specified, removed paths are marked as intent-to-add (see linkgit:git-add[1]). ---hard:: +`--hard`:: Resets the index and working tree. Any changes to tracked files in the - working tree since `<commit>` are discarded. Any untracked files or + working tree since _<commit>_ are discarded. Any untracked files or directories in the way of writing any tracked files are simply deleted. ---merge:: +`--merge`:: Resets the index and updates the files in the working tree that are - different between `<commit>` and `HEAD`, but keeps those which are + different between _<commit>_ and `HEAD`, but keeps those which are different between the index and working tree (i.e. which have changes which have not been added). - If a file that is different between `<commit>` and the index has + If a file that is different between _<commit>_ and the index has unstaged changes, reset is aborted. + In other words, `--merge` does something like a `git read-tree -u -m <commit>`, but carries forward unmerged index entries. ---keep:: +`--keep`:: Resets index entries and updates files in the working tree that are - different between `<commit>` and `HEAD`. - If a file that is different between `<commit>` and `HEAD` has local + different between _<commit>_ and `HEAD`. + If a file that is different between _<commit>_ and `HEAD` has local changes, reset is aborted. ---[no-]recurse-submodules:: - When the working tree is updated, using --recurse-submodules will +`--[no-]recurse-submodules`:: + When the working tree is updated, using `--recurse-submodules` will also recursively reset the working tree of all active submodules according to the commit recorded in the superproject, also setting - the submodules' HEAD to be detached at that commit. + the submodules' `HEAD` to be detached at that commit. -- See "Reset, restore and revert" in linkgit:git[1] for the differences @@ -104,31 +104,31 @@ between the three commands. OPTIONS ------- --q:: ---quiet:: +`-q`:: +`--quiet`:: Be quiet, only report errors. ---refresh:: ---no-refresh:: +`--refresh`:: +`--no-refresh`:: Refresh the index after a mixed reset. Enabled by default. ---pathspec-from-file=<file>:: - Pathspec is passed in `<file>` instead of commandline args. If - `<file>` is exactly `-` then standard input is used. Pathspec - elements are separated by LF or CR/LF. Pathspec elements can be +`--pathspec-from-file=<file>`:: + Pathspec is passed in _<file>_ instead of commandline args. If + _<file>_ is exactly `-` then standard input is used. Pathspec + elements are separated by _LF_ or _CR_/_LF_. Pathspec elements can be quoted as explained for the configuration variable `core.quotePath` (see linkgit:git-config[1]). See also `--pathspec-file-nul` and global `--literal-pathspecs`. ---pathspec-file-nul:: +`--pathspec-file-nul`:: Only meaningful with `--pathspec-from-file`. Pathspec elements are - separated with NUL character and all other characters are taken + separated with _NUL_ character and all other characters are taken literally (including newlines and quotes). -\--:: +`--`:: Do not interpret any more arguments as options. -<pathspec>...:: +`<pathspec>...`:: Limits the paths affected by the operation. + For more details, see the 'pathspec' entry in linkgit:gitglossary[7]. @@ -348,7 +348,7 @@ $ git commit ... <8> ------------ + <1> First, reset the history back one commit so that we remove the original - commit, but leave the working tree with all the changes. The -N ensures + commit, but leave the working tree with all the changes. The `-N` ensures that any new files added with `HEAD` are still marked so that `git add -p` will find them. <2> Next, we interactively select diff hunks to add using the `git add -p` @@ -458,7 +458,7 @@ working index HEAD target working index HEAD --keep B C C .... -`reset --merge` is meant to be used when resetting out of a conflicted +`git reset --merge` is meant to be used when resetting out of a conflicted merge. Any mergy operation guarantees that the working tree file that is involved in the merge does not have a local change with respect to the index before it starts, and that it writes the result out to the working tree. So if @@ -467,7 +467,7 @@ between the index and the working tree, then it means that we are not resetting out from a state that a mergy operation left after failing with a conflict. That is why we disallow `--merge` option in this case. -`reset --keep` is meant to be used when removing some of the last +`git reset --keep` is meant to be used when removing some of the last commits in the current branch while keeping changes in the working tree. If there could be conflicts between the changes in the commit we want to remove and the changes in the working tree we want to keep, diff --git a/Documentation/git-restore.adoc b/Documentation/git-restore.adoc index 751f01b441..877b7772e6 100644 --- a/Documentation/git-restore.adoc +++ b/Documentation/git-restore.adoc @@ -51,9 +51,6 @@ leave out at most one of _<rev-A>__ and _<rev-B>_, in which case it defaults to restore source and the restore location. See the "Interactive Mode" section of linkgit:git-add[1] to learn how to operate the `--patch` mode. -+ -Note that `--patch` can accept no pathspec and will prompt to restore -all modified paths. `-W`:: `--worktree`:: diff --git a/Documentation/git-rm.adoc b/Documentation/git-rm.adoc index 363a26934f..b5ead86796 100644 --- a/Documentation/git-rm.adoc +++ b/Documentation/git-rm.adoc @@ -7,10 +7,10 @@ git-rm - Remove files from the working tree and from the index SYNOPSIS -------- -[verse] -'git rm' [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch] - [--quiet] [--pathspec-from-file=<file> [--pathspec-file-nul]] - [--] [<pathspec>...] +[synopsis] +git rm [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch] + [--quiet] [--pathspec-from-file=<file> [--pathspec-file-nul]] + [--] [<pathspec>...] DESCRIPTION ----------- @@ -30,7 +30,7 @@ sparse-checkouts are in use (see linkgit:git-sparse-checkout[1]), OPTIONS ------- -<pathspec>...:: +`<pathspec>...`:: Files to remove. A leading directory name (e.g. `dir` to remove `dir/file1` and `dir/file2`) can be given to remove all files in the directory, and recursively all sub-directories, but this @@ -43,57 +43,57 @@ directories `d` and `d2`, there is a difference between using `git rm 'd*'` and `git rm 'd/*'`, as the former will also remove all of directory `d2`. + -For more details, see the 'pathspec' entry in linkgit:gitglossary[7]. +For more details, see the _<pathspec>_ entry in linkgit:gitglossary[7]. --f:: ---force:: +`-f`:: +`--force`:: Override the up-to-date check. --n:: ---dry-run:: +`-n`:: +`--dry-run`:: Don't actually remove any file(s). Instead, just show if they exist in the index and would otherwise be removed by the command. --r:: +`-r`:: Allow recursive removal when a leading directory name is given. -\--:: +`--`:: This option can be used to separate command-line options from the list of files, (useful when filenames might be mistaken for command-line options). ---cached:: +`--cached`:: Use this option to unstage and remove paths only from the index. Working tree files, whether modified or not, will be left alone. ---ignore-unmatch:: +`--ignore-unmatch`:: Exit with a zero status even if no files matched. ---sparse:: +`--sparse`:: Allow updating index entries outside of the sparse-checkout cone. Normally, `git rm` refuses to update index entries whose paths do not fit within the sparse-checkout cone. See linkgit:git-sparse-checkout[1] for more. --q:: ---quiet:: +`-q`:: +`--quiet`:: `git rm` normally outputs one line (in the form of an `rm` command) for each file removed. This option suppresses that output. ---pathspec-from-file=<file>:: - Pathspec is passed in `<file>` instead of commandline args. If - `<file>` is exactly `-` then standard input is used. Pathspec - elements are separated by LF or CR/LF. Pathspec elements can be +`--pathspec-from-file=<file>`:: + Pathspec is passed in _<file>_ instead of args. If + _<file>_ is exactly `-` then standard input is used. Pathspec + elements are separated by _LF_ or _CR_/_LF_. Pathspec elements can be quoted as explained for the configuration variable `core.quotePath` (see linkgit:git-config[1]). See also `--pathspec-file-nul` and global `--literal-pathspecs`. ---pathspec-file-nul:: +`--pathspec-file-nul`:: Only meaningful with `--pathspec-from-file`. Pathspec elements are - separated with NUL character and all other characters are taken + separated with _NUL_ character and all other characters are taken literally (including newlines and quotes). @@ -153,15 +153,15 @@ SUBMODULES ---------- Only submodules using a gitfile (which means they were cloned with a Git version 1.7.8 or newer) will be removed from the work -tree, as their repository lives inside the .git directory of the +tree, as their repository lives inside the `.git` directory of the superproject. If a submodule (or one of those nested inside it) -still uses a .git directory, `git rm` will move the submodules +still uses a `.git` directory, `git rm` moves the submodules git directory into the superprojects git directory to protect -the submodule's history. If it exists the submodule.<name> section +the submodule's history. If it exists the `submodule.<name>` section in the linkgit:gitmodules[5] file will also be removed and that file -will be staged (unless --cached or -n are used). +will be staged (unless `--cached` or `-n` are used). -A submodule is considered up to date when the HEAD is the same as +A submodule is considered up to date when the `HEAD` is the same as recorded in the index, no tracked files are modified and no untracked files that aren't ignored are present in the submodule's work tree. Ignored files are deemed expendable and won't stop a submodule's work diff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc index 7f223db42d..7bd09c254b 100644 --- a/Documentation/git-send-email.adoc +++ b/Documentation/git-send-email.adoc @@ -21,7 +21,7 @@ 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, as well as options understood by +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 @@ -35,11 +35,11 @@ There are two formats accepted for patch files: This is what linkgit:git-format-patch[1] generates. Most headers and MIME formatting are ignored. -2. The original format used by Greg Kroah-Hartman's 'send_lots_of_email.pl' +2. The original format used by Greg Kroah-Hartman's `send_lots_of_email.pl` script + -This format expects the first line of the file to contain the "Cc:" value -and the "Subject:" of the message as the second line. +This format expects the first line of the file to contain the `Cc:` value +and the `Subject:` of the message as the second line. OPTIONS @@ -54,13 +54,13 @@ Composing `sendemail.multiEdit`. --bcc=<address>,...:: - Specify a "Bcc:" value for each email. Default is the value of + Specify a `Bcc:` value for each email. Default is the value of `sendemail.bcc`. + This option may be specified multiple times. --cc=<address>,...:: - Specify a starting "Cc:" value for each email. + Specify a starting `Cc:` value for each email. Default is the value of `sendemail.cc`. + This option may be specified multiple times. @@ -69,14 +69,14 @@ This option may be specified multiple times. Invoke a text editor (see GIT_EDITOR in linkgit:git-var[1]) to edit an introductory message for the patch series. + -When `--compose` is used, git send-email will use the From, To, Cc, Bcc, -Subject, Reply-To, and In-Reply-To headers specified in the message. If -the body of the message (what you type after the headers and a blank -line) only contains blank (or Git: prefixed) lines, the summary won't be +When `--compose` is used, `git send-email` will use the `From`, `To`, `Cc`, +`Bcc`, `Subject`, `Reply-To`, and `In-Reply-To` headers specified in the +message. If the body of the message (what you type after the headers and a +blank line) only contains blank (or `Git:` prefixed) lines, the summary won't be sent, but the headers mentioned above will be used unless they are removed. + -Missing From or In-Reply-To headers will be prompted for. +Missing `From` or `In-Reply-To` headers will be prompted for. + See the CONFIGURATION section for `sendemail.multiEdit`. @@ -85,13 +85,13 @@ See the CONFIGURATION section for `sendemail.multiEdit`. the value of the `sendemail.from` configuration option is used. If neither the command-line option nor `sendemail.from` are set, then the user will be prompted for the value. The default for the prompt will be - the value of GIT_AUTHOR_IDENT, or GIT_COMMITTER_IDENT if that is not - set, as returned by "git var -l". + the value of `GIT_AUTHOR_IDENT`, or `GIT_COMMITTER_IDENT` if that is not + set, as returned by `git var -l`. --reply-to=<address>:: Specify the address where replies from recipients should go to. Use this if replies to messages should go to another address than what - is specified with the --from parameter. + is specified with the `--from` parameter. --in-reply-to=<identifier>:: Make the first mail (or all the mails with `--no-thread`) appear as a @@ -112,19 +112,32 @@ illustration below where `[PATCH v2 0/3]` is in reply to `[PATCH 0/2]`: [PATCH v2 2/3] New tests [PATCH v2 3/3] Implementation + -Only necessary if --compose is also set. If --compose +Only necessary if `--compose` is also set. If `--compose` is not set, this will be prompted for. +--[no-]outlook-id-fix:: + Microsoft Outlook SMTP servers discard the Message-ID sent via email and + assign a new random Message-ID, thus breaking threads. ++ +With `--outlook-id-fix`, `git send-email` uses a mechanism specific to +Outlook servers to learn the Message-ID the server assigned to fix the +threading. Use it only when you know that the server reports the +rewritten Message-ID the same way as Outlook servers do. ++ +Without this option specified, the fix is done by default when talking +to 'smtp.office365.com' or 'smtp-mail.outlook.com'. Use +`--no-outlook-id-fix` to disable even when talking to these two servers. + --subject=<string>:: Specify the initial subject of the email thread. - Only necessary if --compose is also set. If --compose + Only necessary if `--compose` is also set. If `--compose` is not set, this will be prompted for. --to=<address>,...:: Specify the primary recipient of the emails generated. Generally, this will be the upstream maintainer of the project involved. Default is the value of the `sendemail.to` configuration value; if that is unspecified, - and --to-cmd is not specified, this will be prompted for. + and `--to-cmd` is not specified, this will be prompted for. + This option may be specified multiple times. @@ -132,30 +145,30 @@ This option may be specified multiple times. When encountering a non-ASCII message or subject that does not declare its encoding, add headers/quoting to indicate it is encoded in <encoding>. Default is the value of the - 'sendemail.assume8bitEncoding'; if that is unspecified, this + `sendemail.assume8bitEncoding`; if that is unspecified, this will be prompted for if any non-ASCII files are encountered. + Note that no attempts whatsoever are made to validate the encoding. --compose-encoding=<encoding>:: Specify encoding of compose message. Default is the value of the - 'sendemail.composeEncoding'; if that is unspecified, UTF-8 is assumed. + `sendemail.composeEncoding`; if that is unspecified, UTF-8 is assumed. --transfer-encoding=(7bit|8bit|quoted-printable|base64|auto):: Specify the transfer encoding to be used to send the message over SMTP. - 7bit will fail upon encountering a non-ASCII message. quoted-printable + `7bit` will fail upon encountering a non-ASCII message. `quoted-printable` can be useful when the repository contains files that contain carriage - returns, but makes the raw patch email file (as saved from a MUA) much - harder to inspect manually. base64 is even more fool proof, but also - even more opaque. auto will use 8bit when possible, and quoted-printable - otherwise. + returns, but makes the raw patch email file (as saved from an MUA) much + harder to inspect manually. `base64` is even more fool proof, but also + even more opaque. `auto` will use `8bit` when possible, and + `quoted-printable` otherwise. + Default is the value of the `sendemail.transferEncoding` configuration value; if that is unspecified, default to `auto`. --xmailer:: --no-xmailer:: - Add (or prevent adding) the "X-Mailer:" header. By default, + Add (or prevent adding) the `X-Mailer:` header. By default, the header is added, but it can be turned off by setting the `sendemail.xmailer` configuration variable to `false`. @@ -165,9 +178,9 @@ Sending --envelope-sender=<address>:: Specify the envelope sender used to send the emails. This is useful if your default address is not the address that is - subscribed to a list. In order to use the 'From' address, set the - value to "auto". If you use the sendmail binary, you must have - suitable privileges for the -f parameter. Default is the value of the + subscribed to a list. In order to use the `From` address, set the + value to `auto`. If you use the `sendmail` binary, you must have + suitable privileges for the `-f` parameter. Default is the value of the `sendemail.envelopeSender` configuration variable; if that is unspecified, choosing the envelope sender is left to your MTA. @@ -176,27 +189,27 @@ Sending be sendmail-like; specifically, it must support the `-i` option. The command will be executed in the shell if necessary. Default is the value of `sendemail.sendmailCmd`. If unspecified, and if - --smtp-server is also unspecified, git-send-email will search - for `sendmail` in `/usr/sbin`, `/usr/lib` and $PATH. + `--smtp-server` is also unspecified, `git send-email` will search + for `sendmail` in `/usr/sbin`, `/usr/lib` and `$PATH`. --smtp-encryption=<encryption>:: Specify in what way encrypting begins for the SMTP connection. - Valid values are 'ssl' and 'tls'. Any other value reverts to plain + Valid values are `ssl` and `tls`. Any other value reverts to plain (unencrypted) SMTP, which defaults to port 25. Despite the names, both values will use the same newer version of TLS, - but for historic reasons have these names. 'ssl' refers to "implicit" + but for historic reasons have these names. `ssl` refers to "implicit" encryption (sometimes called SMTPS), that uses port 465 by default. - 'tls' refers to "explicit" encryption (often known as STARTTLS), + `tls` refers to "explicit" encryption (often known as STARTTLS), that uses port 25 by default. Other ports might be used by the SMTP server, which are not the default. Commonly found alternative port for - 'tls' and unencrypted is 587. You need to check your provider's + `tls` and unencrypted is 587. You need to check your provider's documentation or your server configuration to make sure for your own case. Default is the value of `sendemail.smtpEncryption`. --smtp-domain=<FQDN>:: Specifies the Fully Qualified Domain Name (FQDN) used in the HELO/EHLO command to the SMTP server. Some servers require the - FQDN to match your IP address. If not set, git send-email attempts + FQDN to match your IP address. If not set, `git send-email` attempts to determine your FQDN automatically. Default is the value of `sendemail.smtpDomain`. @@ -210,10 +223,10 @@ $ git send-email --smtp-auth="PLAIN LOGIN GSSAPI" ... + If at least one of the specified mechanisms matches the ones advertised by the SMTP server and if it is supported by the utilized SASL library, the mechanism -is used for authentication. If neither 'sendemail.smtpAuth' nor `--smtp-auth` +is used for authentication. If neither `sendemail.smtpAuth` nor `--smtp-auth` is specified, all mechanisms supported by the SASL library can be used. The -special value 'none' maybe specified to completely disable authentication -independently of `--smtp-user` +special value `none` maybe specified to completely disable authentication +independently of `--smtp-user`. --smtp-pass[=<password>]:: Password for SMTP-AUTH. The argument is optional: If no @@ -225,16 +238,16 @@ Furthermore, passwords need not be specified in configuration files or on the command line. If a username has been specified (with `--smtp-user` or a `sendemail.smtpUser`), but no password has been specified (with `--smtp-pass` or `sendemail.smtpPass`), then -a password is obtained using 'git-credential'. +a password is obtained using linkgit:git-credential[1]. --no-smtp-auth:: - Disable SMTP authentication. Short hand for `--smtp-auth=none` + Disable SMTP authentication. Short hand for `--smtp-auth=none`. --smtp-server=<host>:: If set, specifies the outgoing SMTP server to use (e.g. `smtp.example.com` or a raw IP address). If unspecified, and if `--sendmail-cmd` is also unspecified, the default is to search - for `sendmail` in `/usr/sbin`, `/usr/lib` and $PATH if such a + for `sendmail` in `/usr/sbin`, `/usr/lib` and `$PATH` if such a program is available, falling back to `localhost` otherwise. + For backward compatibility, this option can also specify a full pathname @@ -247,7 +260,7 @@ instead. Specifies a port different from the default port (SMTP servers typically listen to smtp port 25, but may also listen to submission port 587, or the common SSL smtp port 465); - symbolic port names (e.g. "submission" instead of 587) + symbolic port names (e.g. `submission` instead of 587) are also accepted. The port can also be set with the `sendemail.smtpServerPort` configuration variable. @@ -256,17 +269,17 @@ instead. Default value can be specified by the `sendemail.smtpServerOption` configuration option. + -The --smtp-server-option option must be repeated for each option you want +The `--smtp-server-option` option must be repeated for each option you want to pass to the server. Likewise, different lines in the configuration files must be used for each option. --smtp-ssl:: - Legacy alias for '--smtp-encryption ssl'. + Legacy alias for `--smtp-encryption ssl`. --smtp-ssl-cert-path:: Path to a store of trusted CA certificates for SMTP SSL/TLS certificate validation (either a directory that has been processed - by 'c_rehash', or a single file containing one or more PEM format + by `c_rehash`, or a single file containing one or more PEM format certificates concatenated together: see verify(1) -CAfile and -CApath for more information on these). Set it to an empty string to disable certificate verification. Defaults to the value of the @@ -285,18 +298,18 @@ must be used for each option. connection and authentication problems. --batch-size=<num>:: - Some email servers (e.g. smtp.163.com) limit the number emails to be + Some email servers (e.g. 'smtp.163.com') limit the number of emails to be sent per session (connection) and this will lead to a failure when sending many messages. With this option, send-email will disconnect after - sending $<num> messages and wait for a few seconds (see --relogin-delay) - and reconnect, to work around such a limit. You may want to - use some form of credential helper to avoid having to retype - your password every time this happens. Defaults to the + sending _<num>_ messages and wait for a few seconds + (see `--relogin-delay`) and reconnect, to work around such a limit. + You may want to use some form of credential helper to avoid having to + retype your password every time this happens. Defaults to the `sendemail.smtpBatchSize` configuration variable. --relogin-delay=<int>:: - Waiting $<int> seconds before reconnecting to SMTP server. Used together - with --batch-size option. Defaults to the `sendemail.smtpReloginDelay` + Waiting _<int>_ seconds before reconnecting to SMTP server. Used together + with `--batch-size` option. Defaults to the `sendemail.smtpReloginDelay` configuration variable. Automating @@ -305,7 +318,7 @@ Automating --no-to:: --no-cc:: --no-bcc:: - Clears any list of "To:", "Cc:", "Bcc:" addresses previously + Clears any list of `To:`, `Cc:`, `Bcc:` addresses previously set via config. --no-identity:: @@ -314,13 +327,13 @@ Automating --to-cmd=<command>:: Specify a command to execute once per patch file which - should generate patch file specific "To:" entries. + should generate patch file specific `To:` entries. Output of this command must be single email address per line. - Default is the value of 'sendemail.toCmd' configuration value. + Default is the value of `sendemail.toCmd` configuration value. --cc-cmd=<command>:: Specify a command to execute once per patch file which - should generate patch file specific "Cc:" entries. + should generate patch file specific `Cc:` entries. Output of this command must be single email address per line. Default is the value of `sendemail.ccCmd` configuration value. @@ -328,7 +341,7 @@ Automating Specify a command that is executed once per outgoing message and output RFC 2822 style header lines to be inserted into them. When the `sendemail.headerCmd` configuration variable is - set, its value is always used. When --header-cmd is provided + set, its value is always used. When `--header-cmd` is provided at the command line, its value takes precedence over the `sendemail.headerCmd` configuration variable. @@ -337,7 +350,7 @@ Automating --[no-]chain-reply-to:: If this is set, each email will be sent as a reply to the previous - email sent. If disabled with "--no-chain-reply-to", all emails after + email sent. If disabled with `--no-chain-reply-to`, all emails after the first will be sent as replies to the first email sent. When using this, it is recommended that the first file given be an overview of the entire patch series. Disabled by default, but the `sendemail.chainReplyTo` @@ -345,79 +358,80 @@ Automating --identity=<identity>:: A configuration identity. When given, causes values in the - 'sendemail.<identity>' subsection to take precedence over - values in the 'sendemail' section. The default identity is + `sendemail.<identity>` subsection to take precedence over + values in the `sendemail` section. The default identity is the value of `sendemail.identity`. --[no-]signed-off-by-cc:: - If this is set, add emails found in the `Signed-off-by` trailer or Cc: lines to the - cc list. Default is the value of `sendemail.signedOffByCc` configuration - value; if that is unspecified, default to --signed-off-by-cc. + If this is set, add emails found in the `Signed-off-by` trailer or `Cc:` + lines to the cc list. Default is the value of `sendemail.signedOffByCc` + configuration value; if that is unspecified, default to + `--signed-off-by-cc`. --[no-]cc-cover:: - If this is set, emails found in Cc: headers in the first patch of + If this is set, emails found in `Cc:` headers in the first patch of the series (typically the cover letter) are added to the cc list - for each email set. Default is the value of 'sendemail.ccCover' - configuration value; if that is unspecified, default to --no-cc-cover. + for each email set. Default is the value of `sendemail.ccCover` + configuration value; if that is unspecified, default to `--no-cc-cover`. --[no-]to-cover:: - If this is set, emails found in To: headers in the first patch of + If this is set, emails found in `To:` headers in the first patch of the series (typically the cover letter) are added to the to list - for each email set. Default is the value of 'sendemail.toCover' - configuration value; if that is unspecified, default to --no-to-cover. + for each email set. Default is the value of `sendemail.toCover` + configuration value; if that is unspecified, default to `--no-to-cover`. --suppress-cc=<category>:: Specify an additional category of recipients to suppress the auto-cc of: + -- -- 'author' will avoid including the patch author. -- 'self' will avoid including the sender. -- 'cc' will avoid including anyone mentioned in Cc lines in the patch header - except for self (use 'self' for that). -- 'bodycc' will avoid including anyone mentioned in Cc lines in the - patch body (commit message) except for self (use 'self' for that). -- 'sob' will avoid including anyone mentioned in the Signed-off-by trailers except - for self (use 'self' for that). -- 'misc-by' will avoid including anyone mentioned in Acked-by, +- `author` will avoid including the patch author. +- `self` will avoid including the sender. +- `cc` will avoid including anyone mentioned in Cc lines in the patch header + except for self (use `self` for that). +- `bodycc` will avoid including anyone mentioned in Cc lines in the + patch body (commit message) except for self (use `self` for that). +- `sob` will avoid including anyone mentioned in the Signed-off-by trailers except + for self (use `self` for that). +- `misc-by` will avoid including anyone mentioned in Acked-by, Reviewed-by, Tested-by and other "-by" lines in the patch body, - except Signed-off-by (use 'sob' for that). -- 'cccmd' will avoid running the --cc-cmd. -- 'body' is equivalent to 'sob' + 'bodycc' + 'misc-by'. -- 'all' will suppress all auto cc values. + except Signed-off-by (use `sob` for that). +- `cccmd` will avoid running the --cc-cmd. +- `body` is equivalent to `sob` + `bodycc` + `misc-by`. +- `all` will suppress all auto cc values. -- + Default is the value of `sendemail.suppressCc` configuration value; if -that is unspecified, default to 'self' if --suppress-from is -specified, as well as 'body' if --no-signed-off-cc is specified. +that is unspecified, default to `self` if `--suppress-from` is +specified, as well as `body` if `--no-signed-off-cc` is specified. --[no-]suppress-from:: - If this is set, do not add the From: address to the cc: list. + If this is set, do not add the `From:` address to the `Cc:` list. Default is the value of `sendemail.suppressFrom` configuration - value; if that is unspecified, default to --no-suppress-from. + value; if that is unspecified, default to `--no-suppress-from`. --[no-]thread:: - If this is set, the In-Reply-To and References headers will be + If this is set, the `In-Reply-To` and `References` headers will be added to each email sent. Whether each mail refers to the - previous email (`deep` threading per 'git format-patch' + previous email (`deep` threading per `git format-patch` wording) or to the first email (`shallow` threading) is - governed by "--[no-]chain-reply-to". + governed by `--[no-]chain-reply-to`. + -If disabled with "--no-thread", those headers will not be added -(unless specified with --in-reply-to). Default is the value of the +If disabled with `--no-thread`, those headers will not be added +(unless specified with `--in-reply-to`). Default is the value of the `sendemail.thread` configuration value; if that is unspecified, -default to --thread. +default to `--thread`. + It is up to the user to ensure that no In-Reply-To header already -exists when 'git send-email' is asked to add it (especially note that -'git format-patch' can be configured to do the threading itself). +exists when `git send-email` is asked to add it (especially note that +`git format-patch` can be configured to do the threading itself). Failure to do so may not produce the expected result in the recipient's MUA. --[no-]mailmap:: Use the mailmap file (see linkgit:gitmailmap[5]) to map all addresses to their canonical real name and email address. Additional - mailmap data specific to git-send-email may be provided using the + mailmap data specific to `git send-email` may be provided using the `sendemail.mailmap.file` or `sendemail.mailmap.blob` configuration values. Defaults to `sendemail.mailmap`. @@ -428,17 +442,17 @@ Administering Confirm just before sending: + -- -- 'always' will always confirm before sending -- 'never' will never confirm before sending -- 'cc' will confirm before sending when send-email has automatically - added addresses from the patch to the Cc list -- 'compose' will confirm before sending the first message when using --compose. -- 'auto' is equivalent to 'cc' + 'compose' +- `always` will always confirm before sending. +- `never` will never confirm before sending. +- `cc` will confirm before sending when send-email has automatically + added addresses from the patch to the Cc list. +- `compose` will confirm before sending the first message when using --compose. +- `auto` is equivalent to `cc` + `compose`. -- + Default is the value of `sendemail.confirm` configuration value; if that -is unspecified, default to 'auto' unless any of the suppress options -have been specified, in which case default to 'compose'. +is unspecified, default to `auto` unless any of the suppress options +have been specified, in which case default to `compose`. --dry-run:: Do everything except actually send the emails. @@ -447,10 +461,10 @@ have been specified, in which case default to 'compose'. When an argument may be understood either as a reference or as a file name, choose to understand it as a format-patch argument (`--format-patch`) or as a file name (`--no-format-patch`). By default, when such a conflict - occurs, git send-email will fail. + occurs, `git send-email` will fail. --quiet:: - Make git-send-email less verbose. One line per email should be + Make `git send-email` less verbose. One line per email should be all that is output. --[no-]validate:: @@ -461,7 +475,7 @@ have been specified, in which case default to 'compose'. * Invoke the sendemail-validate hook if present (see linkgit:githooks[5]). * Warn of patches that contain lines longer than 998 characters unless a suitable transfer encoding - ('auto', 'base64', or 'quoted-printable') is used; + (`auto`, `base64`, or `quoted-printable`) is used; this is due to SMTP limits as described by https://www.ietf.org/rfc/rfc5322.txt. -- @@ -480,13 +494,13 @@ Information Instead of the normal operation, dump the shorthand alias names from the configured alias file(s), one per line in alphabetical order. Note that this only includes the alias name and not its expanded email addresses. - See 'sendemail.aliasesFile' for more information about aliases. + See `sendemail.aliasesFile` for more information about aliases. --translate-aliases:: Instead of the normal operation, read from standard input and interpret each line as an email alias. Translate it according to the configured alias file(s). Output each translated name and email - address to standard output, one per line. See 'sendemail.aliasFile' + address to standard output, one per line. See `sendemail.aliasFile` for more information about aliases. CONFIGURATION @@ -496,12 +510,12 @@ include::includes/cmd-config-section-all.adoc[] include::config/sendemail.adoc[] -EXAMPLES --------- -Use gmail as the smtp server +EXAMPLES OF SMTP SERVERS +------------------------ +Use Gmail as the SMTP Server ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To use 'git send-email' to send your patches through the GMail SMTP server, -edit ~/.gitconfig to specify your account settings: +To use `git send-email` to send your patches through the Gmail SMTP server, +edit `~/.gitconfig` to specify your account settings: ---- [sendemail] @@ -511,10 +525,52 @@ edit ~/.gitconfig to specify your account settings: smtpServerPort = 587 ---- +Gmail does not allow using your regular password for `git send-email`. If you have multi-factor authentication set up on your Gmail account, you can -generate an app-specific password for use with 'git send-email'. Visit +generate an app-specific password for use with `git send-email`. Visit https://security.google.com/settings/security/apppasswords to create it. +Alternatively, instead of using an app-specific password, you can use +OAuth2.0 authentication with Gmail. OAuth2.0 is more secure than +app-specific passwords, and works regardless of whether you have multi-factor +authentication set up. `OAUTHBEARER` and `XOAUTH2` are common mechanisms used +for this type of authentication. Gmail supports both of them. As an example, +if you want to use `OAUTHBEARER`, edit your `~/.gitconfig` file and add +`smtpAuth = OAUTHBEARER` to your account settings: + +---- +[sendemail] + smtpEncryption = tls + smtpServer = smtp.gmail.com + smtpUser = yourname@gmail.com + smtpServerPort = 587 + smtpAuth = OAUTHBEARER +---- + +Another alternative is using a tool developed by Google known as +https://github.com/google/gmail-oauth2-tools/tree/master/go/sendgmail[sendgmail] +to send emails using `git send-email`. + +Use Microsoft Outlook as the SMTP Server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Unlike Gmail, Microsoft Outlook no longer supports app-specific passwords. +Therefore, OAuth2.0 authentication must be used for Outlook. Also, it only +supports `XOAUTH2` authentication mechanism. + +Edit `~/.gitconfig` to specify your account settings for Outlook and use its +SMTP server with `git send-email`: + +---- +[sendemail] + smtpEncryption = tls + smtpServer = smtp.office365.com + smtpUser = yourname@outlook.com + smtpServerPort = 587 + smtpAuth = XOAUTH2 +---- + +SENDING PATCHES +--------------- Once your commits are ready to be sent to the mailing list, run the following commands: @@ -523,15 +579,40 @@ following commands: $ git send-email outgoing/* The first time you run it, you will be prompted for your credentials. Enter the -app-specific or your regular password as appropriate. If you have credential -helper configured (see linkgit:git-credential[1]), the password will be saved in -the credential store so you won't have to type it the next time. +app-specific or your regular password as appropriate. + +If you have a credential helper configured (see linkgit:git-credential[1]), the +password will be saved in the credential store so you won't have to type it the +next time. + +If you are using OAuth2.0 authentication, you need to use an access token in +place of a password when prompted. Various OAuth2.0 token generators are +available online. Community maintained credential helpers are also available: + + - https://github.com/AdityaGarg8/git-credential-email[git-credential-gmail] + (cross platform, dedicated helper for authenticating Gmail accounts) + + - https://github.com/AdityaGarg8/git-credential-email[git-credential-outlook] + (cross platform, dedicated helper for authenticating Microsoft Outlook accounts) + + - https://github.com/AdityaGarg8/git-credential-email[git-credential-yahoo] + (cross platform, dedicated helper for authenticating Yahoo accounts) + +You can also see linkgit:gitcredentials[7] for more OAuth based authentication +helpers. Note: the following core Perl modules that may be installed with your distribution of Perl are required: -MIME::Base64, MIME::QuotedPrint, Net::Domain and Net::SMTP. + +https://metacpan.org/pod/MIME::Base64[MIME::Base64], +https://metacpan.org/pod/MIME::QuotedPrint[MIME::QuotedPrint], +https://metacpan.org/pod/Net::Domain[Net::Domain] and +https://metacpan.org/pod/Net::SMTP[Net::SMTP]. + These additional Perl modules are also required: -Authen::SASL and Mail::Address. + +https://metacpan.org/pod/Authen::SASL[Authen::SASL] and +https://metacpan.org/pod/Mail::Address[Mail::Address]. SEE ALSO diff --git a/Documentation/git-stripspace.adoc b/Documentation/git-stripspace.adoc index a293327581..37287f211f 100644 --- a/Documentation/git-stripspace.adoc +++ b/Documentation/git-stripspace.adoc @@ -37,7 +37,8 @@ OPTIONS ------- -s:: --strip-comments:: - Skip and remove all lines starting with a comment character (default '#'). + Skip and remove all lines starting with a comment character + (`core.commentChar`, default `#`). -c:: --comment-lines:: diff --git a/Documentation/git-switch.adoc b/Documentation/git-switch.adoc index f55315c51e..9f62abf9e2 100644 --- a/Documentation/git-switch.adoc +++ b/Documentation/git-switch.adoc @@ -7,11 +7,11 @@ git-switch - Switch branches SYNOPSIS -------- -[verse] -'git switch' [<options>] [--no-guess] <branch> -'git switch' [<options>] --detach [<start-point>] -'git switch' [<options>] (-c|-C) <new-branch> [<start-point>] -'git switch' [<options>] --orphan <new-branch> +[synopsis] +git switch [<options>] [--no-guess] <branch> +git switch [<options>] --detach [<start-point>] +git switch [<options>] (-c|-C) <new-branch> [<start-point>] +git switch [<options>] --orphan <new-branch> DESCRIPTION ----------- @@ -33,33 +33,33 @@ THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE. OPTIONS ------- -<branch>:: +_<branch>_:: Branch to switch to. -<new-branch>:: +_<new-branch>_:: Name for the new branch. -<start-point>:: +_<start-point>_:: The starting point for the new branch. Specifying a - `<start-point>` allows you to create a branch based on some - other point in history than where HEAD currently points. (Or, + _<start-point>_ allows you to create a branch based on some + other point in history than where `HEAD` currently points. (Or, in the case of `--detach`, allows you to inspect and detach from some other point.) + -You can use the `@{-N}` syntax to refer to the N-th last -branch/commit switched to using "git switch" or "git checkout" +You can use the `@{-<N>}` syntax to refer to the _<N>_-th last +branch/commit switched to using `git switch` or `git checkout` operation. You may also specify `-` which is synonymous to `@{-1}`. This is often used to switch quickly between two branches, or to undo a branch switch by mistake. + -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`. - --c <new-branch>:: ---create <new-branch>:: - Create a new branch named `<new-branch>` starting at - `<start-point>` before switching to the branch. This is the +As a special case, you may use `<rev-a>...<rev-b>` as a shortcut for the merge +base of _<rev-a>_ and _<rev-b>_ if there is exactly one merge base. You can leave +out at most one of _<rev-a>_ and _<rev-b>_, in which case it defaults to `HEAD`. + +`-c <new-branch>`:: +`--create <new-branch>`:: + Create a new branch named _<new-branch>_ starting at + _<start-point>_ before switching to the branch. This is the transactional equivalent of + ------------ @@ -67,32 +67,32 @@ $ git branch <new-branch> $ git switch <new-branch> ------------ + -that is to say, the branch is not reset/created unless "git switch" is +that is to say, the branch is not reset/created unless `git switch` is successful (e.g., when the branch is in use in another worktree, not just the current branch stays the same, but the branch is not reset to the start-point, either). --C <new-branch>:: ---force-create <new-branch>:: - Similar to `--create` except that if `<new-branch>` already - exists, it will be reset to `<start-point>`. This is a +`-C <new-branch>`:: +`--force-create <new-branch>`:: + Similar to `--create` except that if _<new-branch>_ already + exists, it will be reset to _<start-point>_. This is a convenient shortcut for: + ------------ -$ git branch -f <new-branch> -$ git switch <new-branch> +$ git branch -f _<new-branch>_ +$ git switch _<new-branch>_ ------------ --d:: ---detach:: +`-d`:: +`--detach`:: Switch to a commit for inspection and discardable experiments. See the "DETACHED HEAD" section in linkgit:git-checkout[1] for details. ---guess:: ---no-guess:: - If `<branch>` is not found but there does exist a tracking - branch in exactly one remote (call it `<remote>`) with a +`--guess`:: +`--no-guess`:: + If _<branch>_ is not found but there does exist a tracking + branch in exactly one remote (call it _<remote>_) with a matching name, treat as equivalent to + ------------ @@ -101,9 +101,9 @@ $ git switch -c <branch> --track <remote>/<branch> + If the branch exists in multiple remotes and one of them is named by the `checkout.defaultRemote` configuration variable, we'll use that -one for the purposes of disambiguation, even if the `<branch>` isn't +one for the purposes of disambiguation, even if the _<branch>_ isn't unique across all remotes. Set it to e.g. `checkout.defaultRemote=origin` -to always checkout remote branches from there if `<branch>` is +to always checkout remote branches from there if _<branch>_ is ambiguous but exists on the 'origin' remote. See also `checkout.defaultRemote` in linkgit:git-config[1]. + @@ -112,19 +112,19 @@ ambiguous but exists on the 'origin' remote. See also The default behavior can be set via the `checkout.guess` configuration variable. --f:: ---force:: +`-f`:: +`--force`:: An alias for `--discard-changes`. ---discard-changes:: +`--discard-changes`:: Proceed even if the index or the working tree differs from `HEAD`. Both the index and working tree are restored to match the switching target. If `--recurse-submodules` is specified, submodule content is also restored to match the switching target. This is used to throw away local changes. --m:: ---merge:: +`-m`:: +`--merge`:: If you have local modifications to one or more files that are different between the current branch and the branch to which you are switching, the command refuses to switch branches in @@ -138,25 +138,25 @@ paths are left unmerged, and you need to resolve the conflicts and mark the resolved paths with `git add` (or `git rm` if the merge should result in deletion of the path). ---conflict=<style>:: +`--conflict=<style>`:: 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), "diff3", and "zdiff3". + `merge` (default), `diff3`, and `zdiff3`. --q:: ---quiet:: +`-q`:: +`--quiet`:: Quiet, suppress feedback messages. ---progress:: ---no-progress:: +`--progress`:: +`--no-progress`:: Progress status is reported on the standard error stream by default when it is attached to a terminal, unless `--quiet` is specified. This flag enables progress reporting even if not attached to a terminal, regardless of `--quiet`. --t:: ---track [direct|inherit]:: +`-t`:: +`--track[ (direct|inherit)]`:: When creating a new branch, set up "upstream" configuration. `-c` is implied. See `--track` in linkgit:git-branch[1] for details. @@ -171,22 +171,22 @@ given name has no slash, or the above guessing results in an empty name, the guessing is aborted. You can explicitly give a name with `-c` in such a case. ---no-track:: +`--no-track`:: Do not set up "upstream" configuration, even if the `branch.autoSetupMerge` configuration variable is true. ---orphan <new-branch>:: - Create a new unborn branch, named `<new-branch>`. All +`--orphan <new-branch>`:: + Create a new unborn branch, named _<new-branch>_. All tracked files are removed. ---ignore-other-worktrees:: +`--ignore-other-worktrees`:: `git switch` refuses when the wanted ref is already checked out by another worktree. This option makes it check the ref out anyway. In other words, the ref can be held by more than one worktree. ---recurse-submodules:: ---no-recurse-submodules:: +`--recurse-submodules`:: +`--no-recurse-submodules`:: Using `--recurse-submodules` will update the content of all active submodules according to the commit recorded in the superproject. If nothing (or `--no-recurse-submodules`) is @@ -239,7 +239,7 @@ $ git switch - ------------ You can grow a new branch from any commit. For example, switch to -"HEAD~3" and create branch "fixup": +"`HEAD~3`" and create branch "`fixup`": ------------ $ git switch -c fixup HEAD~3 @@ -251,8 +251,8 @@ name: ------------ $ git switch new-topic -Branch 'new-topic' set up to track remote branch 'new-topic' from 'origin' -Switched to a new branch 'new-topic' +Branch `new-topic` set up to track remote branch `new-topic` from `origin` +Switched to a new branch `new-topic` ------------ To check out commit `HEAD~3` for temporary inspection or experiment diff --git a/Documentation/git-update-ref.adoc b/Documentation/git-update-ref.adoc index 9e6935d38d..9310ce9768 100644 --- a/Documentation/git-update-ref.adoc +++ b/Documentation/git-update-ref.adoc @@ -7,8 +7,10 @@ git-update-ref - Update the object name stored in a ref safely SYNOPSIS -------- -[verse] -'git update-ref' [-m <reason>] [--no-deref] (-d <ref> [<old-oid>] | [--create-reflog] <ref> <new-oid> [<old-oid>] | --stdin [-z]) +[synopsis] +git update-ref [-m <reason>] [--no-deref] -d <ref> [<old-oid>] +git update-ref [-m <reason>] [--no-deref] [--create-reflog] <ref> <new-oid> [<old-oid>] +git update-ref [-m <reason>] [--no-deref] --stdin [-z] [--batch-updates] DESCRIPTION ----------- @@ -57,6 +59,14 @@ performs all modifications together. Specify commands of the form: With `--create-reflog`, update-ref will create a reflog for each ref even if one would not ordinarily be created. +With `--batch-updates`, update-ref executes the updates in a batch but allows +individual updates to fail due to invalid or incorrect user input, applying only +the successful updates. However, system-related errors—such as I/O failures or +memory issues—will result in a full failure of all batched updates. Any failed +updates will be reported in the following format: + + rejected SP (<old-oid> | <old-target>) SP (<new-oid> | <new-target>) SP <rejection-reason> LF + Quote fields containing whitespace as if they were strings in C source code; i.e., surrounded by double-quotes and with backslash escapes. Use 40 "0" characters or the empty string to specify a zero value. To diff --git a/Documentation/git-var.adoc b/Documentation/git-var.adoc index 0680568dfd..b606c2d649 100644 --- a/Documentation/git-var.adoc +++ b/Documentation/git-var.adoc @@ -8,8 +8,8 @@ git-var - Show a Git logical variable SYNOPSIS -------- -[verse] -'git var' (-l | <variable>) +[synopsis] +git var (-l | <variable>) DESCRIPTION ----------- @@ -18,7 +18,7 @@ no value. OPTIONS ------- --l:: +`-l`:: Display the logical variables. In addition, all the variables of the Git configuration file .git/config are listed as well. (However, the configuration variables listing functionality @@ -32,58 +32,56 @@ EXAMPLES VARIABLES --------- -GIT_AUTHOR_IDENT:: +`GIT_AUTHOR_IDENT`:: The author of a piece of code. -GIT_COMMITTER_IDENT:: +`GIT_COMMITTER_IDENT`:: The person who put a piece of code into Git. -GIT_EDITOR:: +`GIT_EDITOR`:: Text editor for use by Git commands. The value is meant to be interpreted by the shell when it is used. Examples: `~/bin/vi`, `$SOME_ENVIRONMENT_VARIABLE`, `"C:\Program Files\Vim\gvim.exe" - --nofork`. The order of preference is the `$GIT_EDITOR` - environment variable, then `core.editor` configuration, then - `$VISUAL`, then `$EDITOR`, and then the default chosen at compile + --nofork`. The order of preference is `$GIT_EDITOR`, then + `core.editor` configuration value, then `$VISUAL`, then + `$EDITOR`, and then the default chosen at compile time, which is usually 'vi'. ifdef::git-default-editor[] The build you are using chose '{git-default-editor}' as the default. endif::git-default-editor[] -GIT_SEQUENCE_EDITOR:: +`GIT_SEQUENCE_EDITOR`:: Text editor used to edit the 'todo' file while running `git rebase -i`. Like `GIT_EDITOR`, the value is meant to be interpreted by - the shell when it is used. The order of preference is the - `$GIT_SEQUENCE_EDITOR` environment variable, then - `sequence.editor` configuration, and then the value of `git var - GIT_EDITOR`. + the shell when it is used. The order of preference is + `$GIT_SEQUENCE_EDITOR`, then `sequence.editor` configuration value, + and then the value of `git var GIT_EDITOR`. -GIT_PAGER:: +`GIT_PAGER`:: Text viewer for use by Git commands (e.g., 'less'). The value is meant to be interpreted by the shell. The order of preference - is the `$GIT_PAGER` environment variable, then `core.pager` - configuration, then `$PAGER`, and then the default chosen at - compile time (usually 'less'). + is `$GIT_PAGER`, then the value of `core.pager` configuration, then + `$PAGER`, and then the default chosen at compile time (usually `less`). ifdef::git-default-pager[] The build you are using chose '{git-default-pager}' as the default. endif::git-default-pager[] -GIT_DEFAULT_BRANCH:: +`GIT_DEFAULT_BRANCH`:: The name of the first branch created in newly initialized repositories. -GIT_SHELL_PATH:: +`GIT_SHELL_PATH`:: The path of the binary providing the POSIX shell for commands which use the shell. -GIT_ATTR_SYSTEM:: +`GIT_ATTR_SYSTEM`:: The path to the system linkgit:gitattributes[5] file, if one is enabled. -GIT_ATTR_GLOBAL:: +`GIT_ATTR_GLOBAL`:: The path to the global (per-user) linkgit:gitattributes[5] file. -GIT_CONFIG_SYSTEM:: +`GIT_CONFIG_SYSTEM`:: The path to the system configuration file, if one is enabled. -GIT_CONFIG_GLOBAL:: +`GIT_CONFIG_GLOBAL`:: The path to the global (per-user) configuration files, if any. Most path values contain only one value. However, some can contain multiple diff --git a/Documentation/git-verify-commit.adoc b/Documentation/git-verify-commit.adoc index aee4c40eac..ff5b8b97ef 100644 --- a/Documentation/git-verify-commit.adoc +++ b/Documentation/git-verify-commit.adoc @@ -7,26 +7,24 @@ git-verify-commit - Check the GPG signature of commits SYNOPSIS -------- -[verse] -'git verify-commit' [-v | --verbose] [--raw] <commit>... +[synopsis] +git verify-commit [-v | --verbose] [--raw] <commit>... DESCRIPTION ----------- -Validates the GPG signature created by 'git commit -S'. +Validates the GPG signature created by `git commit -S` +on the commit objects given on the command line. OPTIONS ------- ---raw:: +`--raw`:: Print the raw gpg status output to standard error instead of the normal human-readable output. --v:: ---verbose:: +`-v`:: +`--verbose`:: Print the contents of the commit object before validating it. -<commit>...:: - SHA-1 identifiers of Git commit objects. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-verify-pack.adoc b/Documentation/git-verify-pack.adoc index d7e886918a..b0462d8db3 100644 --- a/Documentation/git-verify-pack.adoc +++ b/Documentation/git-verify-pack.adoc @@ -8,43 +8,39 @@ git-verify-pack - Validate packed Git archive files SYNOPSIS -------- -[verse] -'git verify-pack' [-v | --verbose] [-s | --stat-only] [--] <pack>.idx... +[synopsis] +git verify-pack [-v | --verbose] [-s | --stat-only] [--] <pack>.idx... DESCRIPTION ----------- -Reads given idx file for packed Git archive created with the -'git pack-objects' command and verifies the idx file and the -corresponding pack file. +Read each idx file for packed Git archive given on the command line, +and verify the idx file and the corresponding pack file. OPTIONS ------- -<pack>.idx ...:: - The idx files to verify. - --v:: ---verbose:: +`-v`:: +`--verbose`:: After verifying the pack, show the list of objects contained in the pack and a histogram of delta chain length. --s:: ---stat-only:: +`-s`:: +`--stat-only`:: Do not verify the pack contents; only show the histogram of delta chain length. With `--verbose`, the list of objects is also shown. -\--:: +`--`:: Do not interpret any more arguments as options. OUTPUT FORMAT ------------- -When specifying the -v option the format used is: +When specifying the `-v` option the format used is: - SHA-1 type size size-in-packfile offset-in-packfile + object-name type size size-in-packfile offset-in-packfile for objects that are not deltified in the pack, and - SHA-1 type size size-in-packfile offset-in-packfile depth base-SHA-1 + object-name type size size-in-packfile offset-in-packfile depth base-object-name for objects that are deltified. diff --git a/Documentation/git-verify-tag.adoc b/Documentation/git-verify-tag.adoc index 81d50ecc4c..b3721a86f4 100644 --- a/Documentation/git-verify-tag.adoc +++ b/Documentation/git-verify-tag.adoc @@ -7,26 +7,24 @@ git-verify-tag - Check the GPG signature of tags SYNOPSIS -------- -[verse] -'git verify-tag' [-v | --verbose] [--format=<format>] [--raw] <tag>... +[synopsis] +git verify-tag [-v | --verbose] [--format=<format>] [--raw] <tag>... DESCRIPTION ----------- -Validates the gpg signature created by 'git tag'. +Validates the gpg signature created by `git tag` in the tag +objects listed on the command line. OPTIONS ------- ---raw:: +`--raw`:: Print the raw gpg status output to standard error instead of the normal human-readable output. --v:: ---verbose:: +`-v`:: +`--verbose`:: Print the contents of the tag object before validating it. -<tag>...:: - SHA-1 identifiers of Git tag objects. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-version.adoc b/Documentation/git-version.adoc index 80fa7754a6..9462043a14 100644 --- a/Documentation/git-version.adoc +++ b/Documentation/git-version.adoc @@ -22,6 +22,14 @@ OPTIONS --build-options:: Include additional information about how git was built for diagnostic purposes. ++ +The libraries used to implement the SHA-1 and SHA-256 algorithms are displayed +in the form `SHA-1: <option>` and `SHA-256: <option>`. Note that the SHA-1 +options `SHA1_APPLE`, `SHA1_OPENSSL`, and `SHA1_BLK` do not use a collision +detection algorithm and thus may be vulnerable to known SHA-1 collision +attacks. When a faster SHA-1 implementation without collision detection is used +for only non-cryptographic purposes, the algorithm is displayed in the form +`non-collision-detecting-SHA-1: <option>`. GIT --- diff --git a/Documentation/git-write-tree.adoc b/Documentation/git-write-tree.adoc index f22041a9dc..4c7100ea1e 100644 --- a/Documentation/git-write-tree.adoc +++ b/Documentation/git-write-tree.adoc @@ -8,8 +8,8 @@ git-write-tree - Create a tree object from the current index SYNOPSIS -------- -[verse] -'git write-tree' [--missing-ok] [--prefix=<prefix>/] +[synopsis] +git write-tree [--missing-ok] [--prefix=<prefix>/] DESCRIPTION ----------- @@ -18,23 +18,23 @@ tree object is printed to standard output. The index must be in a fully merged state. -Conceptually, 'git write-tree' sync()s the current index contents +Conceptually, `git write-tree` sync()s the current index contents into a set of tree files. In order to have that match what is actually in your directory right -now, you need to have done a 'git update-index' phase before you did the -'git write-tree'. +now, you need to have done a `git update-index` phase before you did the +`git write-tree`. OPTIONS ------- ---missing-ok:: - Normally 'git write-tree' ensures that the objects referenced by the +`--missing-ok`:: + Normally `git write-tree` ensures that the objects referenced by the directory exist in the object database. This option disables this check. ---prefix=<prefix>/:: +`--prefix=<prefix>/`:: Writes a tree object that represents a subdirectory - `<prefix>`. This can be used to write the tree object + _<prefix>_. This can be used to write the tree object for a subproject that is in the named subdirectory. GIT diff --git a/Documentation/gitattributes.adoc b/Documentation/gitattributes.adoc index a22d1ef1e1..f20041a323 100644 --- a/Documentation/gitattributes.adoc +++ b/Documentation/gitattributes.adoc @@ -531,13 +531,14 @@ must not send any response before it received the content and the final flush packet. Also note that the "value" of a "key=value" pair can contain the "=" character whereas the key would never contain that character. ------------------------- + +----------------------- packet: git> command=smudge packet: git> pathname=path/testfile.dat packet: git> 0000 packet: git> CONTENT packet: git> 0000 ------------------------- +----------------------- The filter is expected to respond with a list of "key=value" pairs terminated with a flush packet. If the filter does not experience @@ -559,6 +560,7 @@ packet: git< 0000 # empty list, keep "status=success" unchanged! If the result content is empty then the filter is expected to respond with a "success" status and a flush packet to signal the empty content. + ------------------------ packet: git< status=success packet: git< 0000 @@ -568,14 +570,16 @@ packet: git< 0000 # empty list, keep "status=success" unchanged! In case the filter cannot or does not want to process the content, it is expected to respond with an "error" status. ------------------------- + +----------------------- packet: git< status=error packet: git< 0000 ------------------------- +----------------------- If the filter experiences an error during processing, then it can send the status "error" after the content was (partially or completely) sent. + ------------------------ packet: git< status=success packet: git< 0000 @@ -589,10 +593,11 @@ In case the filter cannot or does not want to process the content as well as any future content for the lifetime of the Git process, then it is expected to respond with an "abort" status at any point in the protocol. ------------------------- + +----------------------- packet: git< status=abort packet: git< 0000 ------------------------- +----------------------- Git neither stops nor restarts the filter process in case the "error"/"abort" status is set. However, Git sets its exit code @@ -613,7 +618,8 @@ flag "can-delay" after the filter command and pathname. This flag denotes that the filter can delay filtering the current blob (e.g. to compensate network latencies) by responding with no content but with the status "delayed" and a flush packet. ------------------------- + +----------------------- packet: git> command=smudge packet: git> pathname=path/testfile.dat packet: git> can-delay=1 @@ -622,7 +628,7 @@ packet: git> CONTENT packet: git> 0000 packet: git< status=delayed packet: git< 0000 ------------------------- +----------------------- If the filter supports the "delay" capability then it must support the "list_available_blobs" command. If Git sends this command, then the @@ -647,10 +653,12 @@ packet: git< status=success packet: git< 0000 ------------------------ + After Git received the pathnames, it will request the corresponding blobs again. These requests contain a pathname and an empty content section. The filter is expected to respond with the smudged content in the usual way as explained above. + ------------------------ packet: git> command=smudge packet: git> pathname=path/testfile.dat diff --git a/Documentation/gitcli.adoc b/Documentation/gitcli.adoc index 04193ec907..1ea681b59d 100644 --- a/Documentation/gitcli.adoc +++ b/Documentation/gitcli.adoc @@ -209,13 +209,13 @@ $ git foo -o Arg However, this is *NOT* allowed for switches with an optional value, where the 'stuck' form must be used: + ---------------------------- $ git describe --abbrev HEAD # correct $ git describe --abbrev=10 HEAD # correct $ git describe --abbrev 10 HEAD # NOT WHAT YOU MEANT ---------------------------- - NOTES ON FREQUENTLY CONFUSED OPTIONS ------------------------------------ diff --git a/Documentation/gitprotocol-common.adoc b/Documentation/gitprotocol-common.adoc index cdc9d6e707..b4a5316ca4 100644 --- a/Documentation/gitprotocol-common.adoc +++ b/Documentation/gitprotocol-common.adoc @@ -21,11 +21,13 @@ ABNF Notation ABNF notation as described by RFC 5234 is used within the protocol documents, except the following replacement core rules are used: + ---- HEXDIG = DIGIT / "a" / "b" / "c" / "d" / "e" / "f" ---- We also define the following common rules: + ---- NUL = %x00 zero-id = 40*"0" diff --git a/Documentation/gitprotocol-v2.adoc b/Documentation/gitprotocol-v2.adoc index 5598c93e67..9a57005d77 100644 --- a/Documentation/gitprotocol-v2.adoc +++ b/Documentation/gitprotocol-v2.adoc @@ -54,7 +54,7 @@ In general a client can request to speak protocol v2 by sending `version=2` through the respective side-channel for the transport being used which inevitably sets `GIT_PROTOCOL`. More information can be found in linkgit:gitprotocol-pack[5] and linkgit:gitprotocol-http[5], as well as the -`GIT_PROTOCOL` definition in `git.txt`. In all cases the +`GIT_PROTOCOL` definition in linkgit:git[1]. In all cases the response from the server is the capability advertisement. Git Transport @@ -99,7 +99,7 @@ Uses the `--http-backend-info-refs` option to linkgit:git-upload-pack[1]. The server may need to be configured to pass this header's contents via -the `GIT_PROTOCOL` variable. See the discussion in `git-http-backend.txt`. +the `GIT_PROTOCOL` variable. See the discussion in linkgit:git-http-backend[1]. Capability Advertisement ------------------------ diff --git a/Documentation/gitweb.adoc b/Documentation/gitweb.adoc index 5e2b491ec2..4261f9e235 100644 --- a/Documentation/gitweb.adoc +++ b/Documentation/gitweb.adoc @@ -103,6 +103,7 @@ You can generate the projects list index file using the project_index action "Generating projects list using gitweb" section below. Example contents: + ----------------------------------------------------------------------- foo.git Joe+R+Hacker+<joe@example.com> foo/bar.git O+W+Ner+<owner@example.org> @@ -124,6 +125,7 @@ Generating projects list using gitweb We assume that GITWEB_CONFIG has its default Makefile value, namely 'gitweb_config.perl'. Put the following in 'gitweb_make_index.perl' file: + ---------------------------------------------------------------------------- read_config_file("gitweb_config.perl"); $projects_list = $projectroot; @@ -518,12 +520,14 @@ rules. If you use the rewrite rules from the example you *might* also need something like the following in your gitweb configuration file (`/etc/gitweb.conf` following example): + ---------------------------------------------------------------------------- @stylesheets = ("/some/absolute/path/gitweb.css"); $my_uri = "/"; $home_link = "/"; $per_request_config = 1; ---------------------------------------------------------------------------- + Nowadays though gitweb should create HTML base tag when needed (to set base URI for relative links), so it should work automatically. @@ -535,6 +539,7 @@ Apache virtual host and gitweb configuration files in the following way. The virtual host configuration (in Apache configuration file) should look like this: + -------------------------------------------------------------------------- <VirtualHost *:80> ServerName git.example.org @@ -575,9 +580,11 @@ like this: Here actual project root is passed to gitweb via `GITWEB_PROJECT_ROOT` environment variable from a web server, so you need to put the following line in gitweb configuration file (`/etc/gitweb.conf` in above example): + -------------------------------------------------------------------------- $projectroot = $ENV{'GITWEB_PROJECTROOT'} || "/pub/git"; -------------------------------------------------------------------------- + *Note* that this requires to be set for each request, so either `$per_request_config` must be false, or the above must be put in code referenced by `$per_request_config`; @@ -604,9 +611,11 @@ the third and the fourth. PATH_INFO usage ~~~~~~~~~~~~~~~ If you enable PATH_INFO usage in gitweb by putting + ---------------------------------------------------------------------------- $feature{'pathinfo'}{'default'} = [1]; ---------------------------------------------------------------------------- + in your gitweb configuration file, it is possible to set up your server so that it consumes and produces URLs in the form @@ -636,6 +645,7 @@ complementary static files (stylesheet, favicon, JavaScript): </Directory> </VirtualHost> ---------------------------------------------------------------------------- + The rewrite rule guarantees that existing static files will be properly served, whereas any other URL will be passed to gitweb as PATH_INFO parameter. @@ -647,6 +657,7 @@ for fetching" section). A possible workaround for the latter is the following: in your project root dir (e.g. `/pub/git`) have the projects named *without* a .git extension (e.g. `/pub/git/project` instead of `/pub/git/project.git`) and configure Apache as follows: + ---------------------------------------------------------------------------- <VirtualHost *:80> ServerAlias git.example.com diff --git a/Documentation/gitweb.conf.adoc b/Documentation/gitweb.conf.adoc index 85983587fc..1348e9b125 100644 --- a/Documentation/gitweb.conf.adoc +++ b/Documentation/gitweb.conf.adoc @@ -603,6 +603,7 @@ Many gitweb features can be enabled (or disabled) and configured using the Each `%feature` hash element is a hash reference and has the following structure: + ---------------------------------------------------------------------- "<feature-name>" => { "sub" => <feature-sub-(subroutine)>, @@ -613,6 +614,7 @@ structure: Some features cannot be overridden per project. For those features the structure of appropriate `%feature` hash element has a simpler form: + ---------------------------------------------------------------------- "<feature-name>" => { "override" => 0, diff --git a/Documentation/howto/recover-corrupted-object-harder.adoc b/Documentation/howto/recover-corrupted-object-harder.adoc index 5efb4fe81f..86a1ba75cf 100644 --- a/Documentation/howto/recover-corrupted-object-harder.adoc +++ b/Documentation/howto/recover-corrupted-object-harder.adoc @@ -125,7 +125,7 @@ static int try_zlib(unsigned char *buf, int len) { /* make this absurdly large so we don't have to loop */ static unsigned char out[1024*1024]; - z_stream z; + struct z_stream_s z; int ret; memset(&z, 0, sizeof(z)); @@ -278,7 +278,7 @@ int main(int argc, char **argv) static unsigned char buf[25 * 1024 * 1024]; static unsigned char out[25 * 1024 * 1024]; int len; - z_stream z; + struct z_stream_s z; int ret; len = read(0, buf, sizeof(buf)); diff --git a/Documentation/merge-options.adoc b/Documentation/merge-options.adoc index 0022185201..078f4f6157 100644 --- a/Documentation/merge-options.adoc +++ b/Documentation/merge-options.adoc @@ -1,23 +1,23 @@ ---commit:: ---no-commit:: +`--commit`:: +`--no-commit`:: Perform the merge and commit the result. This option can - be used to override --no-commit. + be used to override `--no-commit`. ifdef::git-pull[] Only useful when merging. endif::git-pull[] + -With --no-commit perform the merge and stop just before creating +With `--no-commit` perform the merge and stop just before creating a merge commit, to give the user a chance to inspect and further tweak the merge result before committing. + Note that fast-forward updates do not create a merge commit and -therefore there is no way to stop those merges with --no-commit. +therefore there is no way to stop those merges with `--no-commit`. Thus, if you want to ensure your branch is not changed or updated -by the merge command, use --no-ff with --no-commit. +by the merge command, use `--no-ff` with `--no-commit`. ---edit:: --e:: ---no-edit:: +`--edit`:: +`-e`:: +`--no-edit`:: Invoke an editor before committing successful mechanical merge to further edit the auto-generated merge message, so that the user can explain and justify the merge. The `--no-edit` option can be @@ -35,17 +35,17 @@ they run `git merge`. To make it easier to adjust such scripts to the updated behaviour, the environment variable `GIT_MERGE_AUTOEDIT` can be set to `no` at the beginning of them. ---cleanup=<mode>:: +`--cleanup=<mode>`:: This option determines how the merge message will be cleaned up before committing. See linkgit:git-commit[1] for more details. In addition, if - the '<mode>' is given a value of `scissors`, scissors will be appended + the _<mode>_ is given a value of `scissors`, scissors will be appended to `MERGE_MSG` before being passed on to the commit machinery in the case of a merge conflict. ifdef::git-merge[] ---ff:: ---no-ff:: ---ff-only:: +`--ff`:: +`--no-ff`:: +`--ff-only`:: Specifies how a merge is handled when the merged-in history is already a descendant of the current history. `--ff` is the default unless merging an annotated (and possibly signed) tag @@ -53,13 +53,13 @@ ifdef::git-merge[] hierarchy, in which case `--no-ff` is assumed. endif::git-merge[] ifdef::git-pull[] ---ff-only:: +`--ff-only`:: Only update to the new history if there is no divergent local history. This is the default when no method for reconciling divergent histories is provided (via the --rebase=* flags). ---ff:: ---no-ff:: +`--ff`:: +`--no-ff`:: When merging rather than rebasing, specifies how a merge is handled when the merged-in history is already a descendant of the current history. If merging is requested, `--ff` is the @@ -81,40 +81,40 @@ With `--ff-only`, resolve the merge as a fast-forward when possible. When not possible, refuse to merge and exit with a non-zero status. endif::git-merge[] --S[<keyid>]:: ---gpg-sign[=<keyid>]:: ---no-gpg-sign:: - GPG-sign the resulting merge commit. The `keyid` argument is +`-S[<key-id>]`:: +`--gpg-sign[=<key-id>]`:: +`--no-gpg-sign`:: + GPG-sign the resulting merge commit. The _<key-id>_ argument is optional and defaults to the committer identity; if specified, it must be stuck to the option without a space. `--no-gpg-sign` is useful to countermand both `commit.gpgSign` configuration variable, and earlier `--gpg-sign`. ---log[=<n>]:: ---no-log:: +`--log[=<n>]`:: +`--no-log`:: In addition to branch names, populate the log message with - one-line descriptions from at most <n> actual commits that are being + one-line descriptions from at most _<n>_ actual commits that are being merged. See also linkgit:git-fmt-merge-msg[1]. ifdef::git-pull[] Only useful when merging. endif::git-pull[] + -With --no-log do not list one-line descriptions from the +With `--no-log` do not list one-line descriptions from the actual commits being merged. include::signoff-option.adoc[] ---stat:: --n:: ---no-stat:: +`--stat`:: +`-n`:: +`--no-stat`:: Show a diffstat at the end of the merge. The diffstat is also controlled by the configuration option merge.stat. + -With -n or --no-stat do not show a diffstat at the end of the +With `-n` or `--no-stat` do not show a diffstat at the end of the merge. ---squash:: ---no-squash:: +`--squash`:: +`--no-squash`:: Produce the working tree and index state as if a real merge happened (except for the merge information), but do not actually make a commit, move the `HEAD`, or record `$GIT_DIR/MERGE_HEAD` @@ -123,16 +123,16 @@ merge. the current branch whose effect is the same as merging another branch (or more in case of an octopus). + -With --no-squash perform the merge and commit the result. This -option can be used to override --squash. +With `--no-squash` perform the merge and commit the result. This +option can be used to override `--squash`. + -With --squash, --commit is not allowed, and will fail. +With `--squash`, `--commit` is not allowed, and will fail. ifdef::git-pull[] + Only useful when merging. endif::git-pull[] ---[no-]verify:: +`--[no-]verify`:: By default, the pre-merge and commit-msg hooks are run. When `--no-verify` is given, these are bypassed. See also linkgit:githooks[5]. @@ -140,21 +140,21 @@ ifdef::git-pull[] Only useful when merging. endif::git-pull[] --s <strategy>:: ---strategy=<strategy>:: +`-s <strategy>`:: +`--strategy=<strategy>`:: Use the given merge strategy; can be supplied more than once to specify them in the order they should be tried. If there is no `-s` option, a built-in list of strategies is used instead (`ort` when merging a single head, `octopus` otherwise). --X <option>:: ---strategy-option=<option>:: +`-X <option>`:: +`--strategy-option=<option>`:: Pass merge strategy specific option through to the merge strategy. ---verify-signatures:: ---no-verify-signatures:: +`--verify-signatures`:: +`--no-verify-signatures`:: Verify that the tip commit of the side branch being merged is signed with a valid key, i.e. a key that has a valid uid: in the default trust model, this means the signing key has been signed by @@ -165,22 +165,22 @@ ifdef::git-pull[] Only useful when merging. endif::git-pull[] ---summary:: ---no-summary:: - Synonyms to --stat and --no-stat; these are deprecated and will be +`--summary`:: +`--no-summary`:: + Synonyms to `--stat` and `--no-stat`; these are deprecated and will be removed in the future. ifndef::git-pull[] --q:: ---quiet:: - Operate quietly. Implies --no-progress. +`-q`:: +`--quiet`:: + Operate quietly. Implies `--no-progress`. --v:: ---verbose:: +`-v`:: +`--verbose`:: Be verbose. ---progress:: ---no-progress:: +`--progress`:: +`--no-progress`:: Turn progress on/off explicitly. If neither is specified, progress is shown if standard error is connected to a terminal. Note that not all merge strategies may support progress @@ -188,8 +188,8 @@ ifndef::git-pull[] endif::git-pull[] ---autostash:: ---no-autostash:: +`--autostash`:: +`--no-autostash`:: Automatically create a temporary stash entry before the operation begins, record it in the ref `MERGE_AUTOSTASH` and apply it after the operation ends. This means @@ -197,13 +197,13 @@ endif::git-pull[] with care: the final stash application after a successful merge might result in non-trivial conflicts. ---allow-unrelated-histories:: +`--allow-unrelated-histories`:: By default, `git merge` command refuses to merge histories that do not share a common ancestor. This option can be used to override this safety when merging histories of two projects that started their lives independently. As that is a very rare occasion, no configuration variable to enable - this by default exists and will not be added. + this by default exists or will be added. ifdef::git-pull[] + Only useful when merging. diff --git a/Documentation/merge-strategies.adoc b/Documentation/merge-strategies.adoc index 93822ebc4e..2ba43f84e7 100644 --- a/Documentation/merge-strategies.adoc +++ b/Documentation/merge-strategies.adoc @@ -6,7 +6,7 @@ backend 'merge strategies' to be chosen with `-s` option. Some strategies can also take their own options, which can be passed by giving `-X<option>` arguments to `git merge` and/or `git pull`. -ort:: +`ort`:: This is the default merge strategy when pulling or merging one branch. This strategy can only resolve two heads using a 3-way merge algorithm. When there is more than one common @@ -29,26 +29,26 @@ descendant. Otherwise, Git will treat this case as a conflict, suggesting as a resolution a submodule commit that is descendant of the conflicting ones, if one exists. + -The 'ort' strategy can take the following options: +The `ort` strategy can take the following options: -ours;; +`ours`;; This option forces conflicting hunks to be auto-resolved cleanly by favoring 'our' version. Changes from the other tree that do not conflict with our side are reflected in the merge result. For a binary file, the entire contents are taken from our side. + -This should not be confused with the 'ours' merge strategy, which does not +This should not be confused with the `ours` merge strategy, which does not even look at what the other tree contains at all. It discards everything the other tree did, declaring 'our' history contains all that happened in it. -theirs;; - This is the opposite of 'ours'; note that, unlike 'ours', there is - no 'theirs' merge strategy to confuse this merge option with. +`theirs`;; + This is the opposite of `ours`; note that, unlike `ours`, there is + no `theirs` merge strategy to confuse this merge option with. -ignore-space-change;; -ignore-all-space;; -ignore-space-at-eol;; -ignore-cr-at-eol;; +`ignore-space-change`;; +`ignore-all-space`;; +`ignore-space-at-eol`;; +`ignore-cr-at-eol`;; Treats lines with the indicated type of whitespace change as unchanged for the sake of a three-way merge. Whitespace changes mixed with other changes to a line are not ignored. @@ -61,7 +61,7 @@ ignore-cr-at-eol;; version includes a substantial change, 'their' version is used; * Otherwise, the merge proceeds in the usual way. -renormalize;; +`renormalize`;; This runs a virtual check-out and check-in of all three stages of any file which needs a three-way merge. This option is meant to be used when merging branches with different clean @@ -69,92 +69,81 @@ renormalize;; branches with differing checkin/checkout attributes" in linkgit:gitattributes[5] for details. -no-renormalize;; +`no-renormalize`;; Disables the `renormalize` option. This overrides the `merge.renormalize` configuration variable. -find-renames[=<n>];; +`find-renames[=<n>]`;; Turn on rename detection, optionally setting the similarity threshold. This is the default. This overrides the - 'merge.renames' configuration variable. + `merge.renames` configuration variable. See also linkgit:git-diff[1] `--find-renames`. -rename-threshold=<n>;; +`rename-threshold=<n>`;; Deprecated synonym for `find-renames=<n>`. -subtree[=<path>];; - This option is a more advanced form of 'subtree' strategy, where - the strategy makes a guess on how two trees must be shifted to - match with each other when merging. Instead, the specified path - is prefixed (or stripped from the beginning) to make the shape of - two trees to match. +`no-renames`;; + Turn off rename detection. This overrides the `merge.renames` + configuration variable. + See also linkgit:git-diff[1] `--no-renames`. -recursive:: - This can only resolve two heads using a 3-way merge - algorithm. When there is more than one common - ancestor that can be used for 3-way merge, it creates a - merged tree of the common ancestors and uses that as - the reference tree for the 3-way merge. This has been - reported to result in fewer merge conflicts without - causing mismerges by tests done on actual merge commits - taken from Linux 2.6 kernel development history. - Additionally this can detect and handle merges involving - renames. It does not make use of detected copies. This was - the default strategy for resolving two heads from Git v0.99.9k - until v2.33.0. -+ -For a path that is a submodule, the same caution as 'ort' applies to this -strategy. -+ -The 'recursive' strategy takes the same options as 'ort'. However, -there are three additional options that 'ort' ignores (not documented -above) that are potentially useful with the 'recursive' strategy: +`histogram`;; + Deprecated synonym for `diff-algorithm=histogram`. -patience;; +`patience`;; Deprecated synonym for `diff-algorithm=patience`. -diff-algorithm=[patience|minimal|histogram|myers];; +`diff-algorithm=(histogram|minimal|myers|patience)`;; Use a different diff algorithm while merging, which can help avoid mismerges that occur due to unimportant matching lines (such as braces from distinct functions). See also linkgit:git-diff[1] `--diff-algorithm`. Note that `ort` - specifically uses `diff-algorithm=histogram`, while `recursive` - defaults to the `diff.algorithm` config setting. + defaults to `diff-algorithm=histogram`, while regular diffs + currently default to the `diff.algorithm` config setting. -no-renames;; - Turn off rename detection. This overrides the `merge.renames` - configuration variable. - See also linkgit:git-diff[1] `--no-renames`. +`subtree[=<path>]`;; + This option is a more advanced form of 'subtree' strategy, where + the strategy makes a guess on how two trees must be shifted to + match with each other when merging. Instead, the specified path + is prefixed (or stripped from the beginning) to make the shape of + two trees to match. + +`recursive`:: + This is now a synonym for `ort`. It was an alternative + implementation until v2.49.0, but was redirected to mean `ort` + in v2.50.0. The previous recursive strategy was the default + strategy for resolving two heads from Git v0.99.9k until + v2.33.0. -resolve:: +`resolve`:: This can only resolve two heads (i.e. the current branch and another branch you pulled from) using a 3-way merge algorithm. It tries to carefully detect criss-cross merge ambiguities. It does not handle renames. -octopus:: +`octopus`:: This resolves cases with more than two heads, but refuses to do a complex merge that needs manual resolution. It is primarily meant to be used for bundling topic branch heads together. This is the default merge strategy when pulling or merging more than one branch. -ours:: +`ours`:: This resolves any number of heads, but the resulting tree of the merge is always that of the current branch head, effectively ignoring all changes from all other branches. It is meant to be used to supersede old development history of side - branches. Note that this is different from the -Xours option to - the 'recursive' merge strategy. + branches. Note that this is different from the `-Xours` option to + the `ort` merge strategy. -subtree:: +`subtree`:: This is a modified `ort` strategy. When merging trees A and B, if B corresponds to a subtree of A, B is first adjusted to match the tree structure of A, instead of reading the trees at the same level. This adjustment is also done to the common ancestor tree. -With the strategies that use 3-way merge (including the default, 'ort'), +With the strategies that use 3-way merge (including the default, `ort`), if a change is made on both branches, but later reverted on one of the branches, that change will be present in the merged result; some people find this behavior confusing. It occurs because only the heads and the merge base diff --git a/Documentation/mergetools/vimdiff.adoc b/Documentation/mergetools/vimdiff.adoc index befa86d692..abfd426f74 100644 --- a/Documentation/mergetools/vimdiff.adoc +++ b/Documentation/mergetools/vimdiff.adoc @@ -86,7 +86,7 @@ command. + -- When `MERGED` is not present in the layout, you must "mark" one of the -buffers with an asterisk. That will become the buffer you need to edit and +buffers with an arobase (`@`). That will become the buffer you need to edit and save after resolving the conflicts. .... ------------------------------------------ @@ -183,13 +183,13 @@ latter will be used as fallback if the variant-specific one is not set). In addition, for backwards compatibility with previous Git versions, you can also append `1`, `2` or `3` to either `vimdiff` or any of the variants (ex: `vimdiff3`, `nvimdiff1`, etc...) to use a predefined layout. -In other words, using `--tool=[g,n,]vimdiffx` is the same as using -`--tool=[g,n,]vimdiff` and setting configuration variable -`mergetool.[g,n,]vimdiff.layout` to... +In other words, using `--tool=[g|n]vimdiff<x>` is the same as using +`--tool=[g|n]vimdiff` and setting configuration variable +`mergetool.[g|n]vimdiff.layout` to... - * `x=1`: `"@LOCAL, REMOTE"` - * `x=2`: `"LOCAL, MERGED, REMOTE"` - * `x=3`: `"MERGED"` + * `<x>=1`: `"@LOCAL, REMOTE"` + * `<x>=2`: `"LOCAL, MERGED, REMOTE"` + * `<x>=3`: `"MERGED"` -Example: using `--tool=gvimdiff2` will open `gvim` with three columns (LOCAL, -MERGED and REMOTE). +Example: using `--tool=gvimdiff2` will open `gvim` with three columns (`LOCAL`, +`MERGED` and `REMOTE`). diff --git a/Documentation/meson.build b/Documentation/meson.build index 594546d68b..2fe1a1369d 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -42,6 +42,7 @@ manpages = { 'git-diagnose.adoc' : 1, 'git-diff-files.adoc' : 1, 'git-diff-index.adoc' : 1, + 'git-diff-pairs.adoc' : 1, 'git-difftool.adoc' : 1, 'git-diff-tree.adoc' : 1, 'git-diff.adoc' : 1, @@ -96,7 +97,6 @@ manpages = { 'git-notes.adoc' : 1, 'git-p4.adoc' : 1, 'git-pack-objects.adoc' : 1, - 'git-pack-redundant.adoc' : 1, 'git-pack-refs.adoc' : 1, 'git-patch-id.adoc' : 1, 'git-prune-packed.adoc' : 1, @@ -158,7 +158,6 @@ manpages = { 'git-verify-tag.adoc' : 1, 'git-version.adoc' : 1, 'git-web--browse.adoc' : 1, - 'git-whatchanged.adoc' : 1, 'git-worktree.adoc' : 1, 'git-write-tree.adoc' : 1, 'git.adoc' : 1, @@ -205,11 +204,20 @@ manpages = { 'gitworkflows.adoc' : 7, } +manpages_breaking_changes = { + 'git-pack-redundant.adoc' : 1, + 'git-whatchanged.adoc' : 1, +} + +if not get_option('breaking_changes') + manpages += manpages_breaking_changes +endif + docs_backend = get_option('docs_backend') if docs_backend == 'auto' - if find_program('asciidoc', dirs: program_path, required: false).found() + if find_program('asciidoc', dirs: program_path, native: true, required: false).found() docs_backend = 'asciidoc' - elif find_program('asciidoctor', dirs: program_path, required: false).found() + elif find_program('asciidoctor', dirs: program_path, native: true, required: false).found() docs_backend = 'asciidoctor' else error('Neither asciidoc nor asciidoctor were found.') @@ -217,7 +225,7 @@ if docs_backend == 'auto' endif if docs_backend == 'asciidoc' - asciidoc = find_program('asciidoc', dirs: program_path) + asciidoc = find_program('asciidoc', dirs: program_path, native: true) asciidoc_html = 'xhtml11' asciidoc_docbook = 'docbook' xmlto_extra = [ ] @@ -242,11 +250,21 @@ if docs_backend == 'asciidoc' '--attribute=build_dir=' + meson.current_build_dir(), ] + pager_opt = get_option('default_pager') + if pager_opt != '' and pager_opt != 'less' + asciidoc_common_options += '-agit-default-pager=' + pager_opt + endif + + editor_opt = get_option('default_editor') + if editor_opt != '' and editor_opt != 'vi' + asciidoc_common_options += '-agit-default-editor=' + editor_opt + endif + documentation_deps = [ asciidoc_conf, ] elif docs_backend == 'asciidoctor' - asciidoctor = find_program('asciidoctor', dirs: program_path) + asciidoctor = find_program('asciidoctor', dirs: program_path, native: true) asciidoc_html = 'xhtml5' asciidoc_docbook = 'docbook5' xmlto_extra = [ @@ -279,6 +297,16 @@ elif docs_backend == 'asciidoctor' '--require', 'asciidoctor-extensions', ] + pager_opt = get_option('default_pager') + if pager_opt != '' and pager_opt != 'less' + asciidoc_common_options += '-agit-default-pager=' + pager_opt + endif + + editor_opt = get_option('default_editor') + if editor_opt != '' and editor_opt != 'vi' + asciidoc_common_options += '-agit-default-editor=' + editor_opt + endif + documentation_deps = [ asciidoctor_extensions, ] @@ -288,7 +316,7 @@ if get_option('breaking_changes') asciidoc_common_options += ['--attribute', 'with-breaking-changes'] endif -xmlto = find_program('xmlto', dirs: program_path) +xmlto = find_program('xmlto', dirs: program_path, native: true) cmd_lists = [ 'cmds-ancillaryinterrogators.adoc', @@ -307,12 +335,12 @@ cmd_lists = [ documentation_deps += custom_target( command: [ - perl, + shell, '@INPUT@', meson.project_source_root(), meson.current_build_dir(), ] + cmd_lists, - input: 'cmd-list.perl', + input: 'cmd-list.sh', output: cmd_lists ) @@ -409,7 +437,7 @@ if get_option('docs').contains('html') pointing_to: 'git.html', ) - xsltproc = find_program('xsltproc', dirs: program_path) + xsltproc = find_program('xsltproc', dirs: program_path, native: true) user_manual_xml = custom_target( command: asciidoc_common_options + [ @@ -440,6 +468,7 @@ if get_option('docs').contains('html') ) articles = [ + 'BreakingChanges.adoc', 'DecisionMaking.adoc', 'MyFirstContribution.adoc', 'MyFirstObjectWalk.adoc', @@ -479,7 +508,9 @@ endif # Sanity check that we are not missing any tests present in 't/'. This check # only runs once at configure time and is thus best-effort, only. Furthermore, # it only verifies man pages for the sake of simplicity. -configured_manpages = manpages.keys() + [ 'git-bisect-lk2009.adoc', 'git-tools.adoc' ] +configured_manpages = manpages.keys() +configured_manpages += manpages_breaking_changes.keys() +configured_manpages += [ 'git-bisect-lk2009.adoc', 'git-tools.adoc' ] actual_manpages = run_command(shell, '-c', 'ls git*.adoc scalar.adoc', check: true, env: script_environment, diff --git a/Documentation/rerere-options.adoc b/Documentation/rerere-options.adoc index c3321ddea2..b0b920144a 100644 --- a/Documentation/rerere-options.adoc +++ b/Documentation/rerere-options.adoc @@ -1,5 +1,5 @@ ---rerere-autoupdate:: ---no-rerere-autoupdate:: +`--rerere-autoupdate`:: +`--no-rerere-autoupdate`:: After the rerere mechanism reuses a recorded resolution on the current conflict to update the files in the working tree, allow it to also update the index with the result of diff --git a/Documentation/rev-list-options.adoc b/Documentation/rev-list-options.adoc index ee5c5c9489..ae8765644c 100644 --- a/Documentation/rev-list-options.adoc +++ b/Documentation/rev-list-options.adoc @@ -361,6 +361,30 @@ ifdef::git-rev-list[] --progress=<header>:: Show progress reports on stderr as objects are considered. The `<header>` text will be printed with each progress update. + +-z:: + Instead of being newline-delimited, each outputted object and its + accompanying metadata is delimited using NUL bytes. Output is printed + in the following form: ++ +----------------------------------------------------------------------- +<OID> NUL [<token>=<value> NUL]... +----------------------------------------------------------------------- ++ +Additional object metadata, such as object paths or boundary objects, is +printed using the `<token>=<value>` form. Token values are printed as-is +without any encoding/truncation. An OID entry never contains a '=' character +and thus is used to signal the start of a new object record. Examples: ++ +----------------------------------------------------------------------- +<OID> NUL +<OID> NUL path=<path> NUL +<OID> NUL boundary=yes NUL +<OID> NUL missing=yes NUL [<token>=<value> NUL]... +----------------------------------------------------------------------- ++ +This mode is only compatible with the `--objects`, `--boundary`, and +`--missing` output options. endif::git-rev-list[] History Simplification @@ -429,6 +453,7 @@ filtered for `foo`, they look different and equal, respectively.) In the following, we will always refer to the same example history to illustrate the differences between simplification settings. We assume that you are filtering for a file `foo` in this commit graph: + ----------------------------------------------------------------------- .-A---M---N---O---P---Q / / / / / / @@ -436,6 +461,7 @@ that you are filtering for a file `foo` in this commit graph: \ / / / / / `-------------' X ----------------------------------------------------------------------- + The horizontal line of history A---Q is taken to be the first parent of each merge. The commits are: @@ -640,7 +666,7 @@ commits affected by that topic, we may only want to view the subset of ----------------------------------------------------------------------- E \ - G---H---I---J + C---G---H---I---J \ L--M ----------------------------------------------------------------------- diff --git a/Documentation/scalar.adoc b/Documentation/scalar.adoc index 7e4259c674..4bd5b150e8 100644 --- a/Documentation/scalar.adoc +++ b/Documentation/scalar.adoc @@ -9,12 +9,12 @@ SYNOPSIS -------- [verse] scalar clone [--single-branch] [--branch <main-branch>] [--full-clone] - [--[no-]src] <url> [<enlistment>] + [--[no-]src] [--[no-]tags] [--[no-]maintenance] <url> [<enlistment>] scalar list -scalar register [<enlistment>] +scalar register [--[no-]maintenance] [<enlistment>] scalar unregister [<enlistment>] scalar run ( all | config | commit-graph | fetch | loose-objects | pack-files ) [<enlistment>] -scalar reconfigure [ --all | <enlistment> ] +scalar reconfigure [--maintenance=(enable|disable|keep)] [ --all | <enlistment> ] scalar diagnose [<enlistment>] scalar delete <enlistment> @@ -97,6 +97,11 @@ cloning. If the HEAD at the remote did not point at any branch when A sparse-checkout is initialized by default. This behavior can be turned off via `--full-clone`. +--[no-]maintenance:: + By default, `scalar clone` configures the enlistment to use Git's + background maintenance feature. Use the `--no-maintenance` to skip + this configuration. + List ~~~~ @@ -117,6 +122,12 @@ Note: when this subcommand is called in a worktree that is called `src/`, its parent directory is considered to be the Scalar enlistment. If the worktree is _not_ called `src/`, it itself will be considered to be the Scalar enlistment. +--[no-]maintenance:: + By default, `scalar register` configures the enlistment to use Git's + background maintenance feature. Use the `--no-maintenance` to skip + this configuration. This does not disable any maintenance that may + already be enabled in other ways. + Unregister ~~~~~~~~~~ @@ -149,8 +160,18 @@ After a Scalar upgrade, or when the configuration of a Scalar enlistment was somehow corrupted or changed by mistake, this subcommand allows to reconfigure the enlistment. -With the `--all` option, all enlistments currently registered with Scalar -will be reconfigured. Use this option after each Scalar upgrade. +--all:: + When `--all` is specified, reconfigure all enlistments currently + registered with Scalar by the `scalar.repo` config key. Use this + option after each upgrade to get the latest features. + +--maintenance=(enable|disable|keep):: + By default, Scalar configures the enlistment to use Git's + background maintenance feature; this is the same as using the + `enable` value for this option. Use the `disable` value to + remove each considered enlistment from background maintenance. + Use `keep' to leave the background maintenance configuration + untouched for these repositories. Diagnose ~~~~~~~~ diff --git a/Documentation/technical/api-parse-options.adoc b/Documentation/technical/api-parse-options.adoc index 61fa6ee167..880eb94642 100644 --- a/Documentation/technical/api-parse-options.adoc +++ b/Documentation/technical/api-parse-options.adoc @@ -211,11 +211,13 @@ There are some macros to easily define options: Use of `--no-option` will clear the list of preceding values. `OPT_INTEGER(short, long, &int_var, description)`:: - Introduce an option with integer argument. - The integer is put into `int_var`. + Introduce an option with integer argument. The argument must be a + integer and may include a suffix of 'k', 'm' or 'g' to + scale the provided value by 1024, 1024^2 or 1024^3 respectively. + The scaled value is put into `int_var`. -`OPT_MAGNITUDE(short, long, &unsigned_long_var, description)`:: - Introduce an option with a size argument. The argument must be a +`OPT_UNSIGNED(short, long, &unsigned_long_var, description)`:: + Introduce an option with an unsigned integer argument. The argument must be a non-negative integer and may include a suffix of 'k', 'm' or 'g' to scale the provided value by 1024, 1024^2 or 1024^3 respectively. The scaled value is put into `unsigned_long_var`. diff --git a/Documentation/technical/api-path-walk.adoc b/Documentation/technical/api-path-walk.adoc index 3e089211fb..34c905eb9c 100644 --- a/Documentation/technical/api-path-walk.adoc +++ b/Documentation/technical/api-path-walk.adoc @@ -56,6 +56,14 @@ better off using the revision walk API instead. the revision walk so that the walk emits commits marked with the `UNINTERESTING` flag. +`edge_aggressive`:: + For performance reasons, usually only the boundary commits are + explored to find UNINTERESTING objects. However, in the case of + shallow clones it can be helpful to mark all trees and blobs + reachable from UNINTERESTING tip commits as UNINTERESTING. This + matches the behavior of `--objects-edge-aggressive` in the + revision API. + `pl`:: This pattern list pointer allows focusing the path-walk search to a set of patterns, only emitting paths that match the given @@ -69,4 +77,5 @@ Examples See example usages in: `t/helper/test-path-walk.c`, + `builtin/pack-objects.c`, `builtin/backfill.c` diff --git a/Documentation/technical/build-systems.adoc b/Documentation/technical/build-systems.adoc index d9dafb407c..3c5237b9fd 100644 --- a/Documentation/technical/build-systems.adoc +++ b/Documentation/technical/build-systems.adoc @@ -32,7 +32,10 @@ that generally have somebody running test pipelines against regularly: - OpenBSD The platforms which must be supported by the tool should be aligned with our -[platform support policy](platform-support.txt). +platform support policy (see platform-support.adoc). +// once we lose AsciiDoc compatibility, we can start writing the above as: +// xref:platform-support.adoc#platform-support-policy[platform support policy] +// or something like that, but until then.... === Auto-detection of supported features diff --git a/Documentation/technical/bundle-uri.adoc b/Documentation/technical/bundle-uri.adoc index 91d3a13e32..12283fa9ed 100644 --- a/Documentation/technical/bundle-uri.adoc +++ b/Documentation/technical/bundle-uri.adoc @@ -232,13 +232,13 @@ will interact with bundle URIs according to the following flow: are present in the client repository. If some are missing, then the client delays unbundling until other bundles have been unbundled, making those OIDs present. When all required OIDs are present, the - client unbundles that data using a refspec. The default refspec is - `+refs/heads/*:refs/bundles/*`, but this can be configured. These refs - are stored so that later `git fetch` negotiations can communicate each - bundled ref as a `have`, reducing the size of the fetch over the Git - protocol. To allow pruning refs from this ref namespace, Git may - introduce a numbered namespace (such as `refs/bundles/<i>/*`) such that - stale bundle refs can be deleted. + client unbundles that data using a refspec. The refspec used is + `+refs/*:refs/bundles/*`. These refs are stored so that later + `git fetch` negotiations can communicate each bundled ref as a `have`, + reducing the size of the fetch over the Git protocol. To allow pruning + refs from this ref namespace, Git may introduce a numbered namespace + (such as `refs/bundles/<i>/*`) such that stale bundle refs can be + deleted. 3. If the file is instead a bundle list, then the client inspects the `bundle.mode` to see if the list is of the `all` or `any` form. diff --git a/Documentation/technical/multi-pack-index.adoc b/Documentation/technical/multi-pack-index.adoc index cc063b30be..ffda70aa13 100644 --- a/Documentation/technical/multi-pack-index.adoc +++ b/Documentation/technical/multi-pack-index.adoc @@ -164,19 +164,81 @@ objects_nr($H2) + objects_nr($H1) + i (in the C implementation, this is often computed as `i + m->num_objects_in_base`). +=== Pseudo-pack order for incremental MIDXs + +The original implementation of multi-pack reachability bitmaps defined +the pseudo-pack order in linkgit:gitformat-pack[5] (see the section +titled "multi-pack-index reverse indexes") roughly as follows: + +____ +In short, a MIDX's pseudo-pack is the de-duplicated concatenation of +objects in packs stored by the MIDX, laid out in pack order, and the +packs arranged in MIDX order (with the preferred pack coming first). +____ + +In the incremental MIDX design, we extend this definition to include +objects from multiple layers of the MIDX chain. The pseudo-pack order +for incremental MIDXs is determined by concatenating the pseudo-pack +ordering for each layer of the MIDX chain in order. Formally two objects +`o1` and `o2` are compared as follows: + +1. If `o1` appears in an earlier layer of the MIDX chain than `o2`, then + `o1` sorts ahead of `o2`. + +2. Otherwise, if `o1` and `o2` appear in the same MIDX layer, and that + MIDX layer has no base, then if one of `pack(o1)` and `pack(o2)` is + preferred and the other is not, then the preferred one sorts ahead of + the non-preferred one. If there is a base layer (i.e. the MIDX layer + is not the first layer in the chain), then if `pack(o1)` appears + earlier in that MIDX layer's pack order, then `o1` sorts ahead of + `o2`. Likewise if `pack(o2)` appears earlier, then the opposite is + true. + +3. Otherwise, `o1` and `o2` appear in the same pack, and thus in the + same MIDX layer. Sort `o1` and `o2` by their offset within their + containing packfile. + +Note that the preferred pack is a property of the MIDX chain, not the +individual layers themselves. Fundamentally we could introduce a +per-layer preferred pack, but this is less relevant now that we can +perform multi-pack reuse across the set of packs in a MIDX. + +=== Reachability bitmaps and incremental MIDXs + +Each layer of an incremental MIDX chain may have its objects (and the +objects from any previous layer in the same MIDX chain) represented in +its own `*.bitmap` file. + +The structure of a `*.bitmap` file belonging to an incremental MIDX +chain is identical to that of a non-incremental MIDX bitmap, or a +classic single-pack bitmap. Since objects are added to the end of the +incremental MIDX's pseudo-pack order (see above), it is possible to +extend a bitmap when appending to the end of a MIDX chain. + +(Note: it is possible likewise to compress a contiguous sequence of MIDX +incremental layers, and their `*.bitmap` files into a single layer and +`*.bitmap`, but this is not yet implemented.) + +The object positions used are global within the pseudo-pack order, so +subsequent layers will have, for example, `m->num_objects_in_base` +number of `0` bits in each of their four type bitmaps. This follows from +the fact that we only write type bitmap entries for objects present in +the layer immediately corresponding to the bitmap). + +Note also that only the bitmap pertaining to the most recent layer in an +incremental MIDX chain is used to store reachability information about +the interesting and uninteresting objects in a reachability query. +Earlier bitmap layers are only used to look up commit and pseudo-merge +bitmaps from that layer, as well as the type-level bitmaps for objects +in that layer. + +To simplify the implementation, type-level bitmaps are iterated +simultaneously, and their results are OR'd together to avoid recursively +calling internal bitmap functions. + Future Work ----------- -- The multi-pack-index allows many packfiles, especially in a context - where repacking is expensive (such as a very large repo), or - unexpected maintenance time is unacceptable (such as a high-demand - build machine). However, the multi-pack-index needs to be rewritten - in full every time. We can extend the format to be incremental, so - writes are fast. By storing a small "tip" multi-pack-index that - points to large "base" MIDX files, we can keep writes fast while - still reducing the number of binary searches required for object - lookups. - - If the multi-pack-index is extended to store a "stable object order" (a function Order(hash) = integer that is constant for a given hash, even as the multi-pack-index is updated) then MIDX bitmaps could be diff --git a/Documentation/technical/sparse-checkout.adoc b/Documentation/technical/sparse-checkout.adoc index 67134bb768..0f750ef3e3 100644 --- a/Documentation/technical/sparse-checkout.adoc +++ b/Documentation/technical/sparse-checkout.adoc @@ -66,7 +66,7 @@ sparsity patterns: patterns from $GIT_DIR/info/sparse-checkout used to reasons: (1) users in cone mode specify directories rather than patterns (their directories are transformed into patterns, but users may think you are talking about non-cone mode if you use the - word "patterns"), and (b) the sparse specification might + word "patterns"), and (2) the sparse specification might transiently differ in the working tree or index from the sparsity patterns (see "Sparse specification vs. sparsity patterns"). @@ -356,8 +356,6 @@ understanding these differences can be beneficial. The behavior for these commands somewhat depends upon the merge strategy being used: * `ort` behaves as described above - * `recursive` tries to not vivify files unnecessarily, but does sometimes - vivify files without conflicts. * `octopus` and `resolve` will always vivify any file changed in the merge relative to the first parent, which is rather suboptimal. |