diff options
Diffstat (limited to 'Documentation')
167 files changed, 4715 insertions, 2248 deletions
diff --git a/Documentation/BreakingChanges.adoc b/Documentation/BreakingChanges.adoc index bdfad29d8a..f8d2eba061 100644 --- a/Documentation/BreakingChanges.adoc +++ b/Documentation/BreakingChanges.adoc @@ -118,6 +118,53 @@ Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>, <20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>, <CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>. +* The default storage format for references in newly created repositories will + be changed from "files" to "reftable". The "reftable" format provides + multiple advantages over the "files" format: ++ + ** It is impossible to store two references that only differ in casing on + case-insensitive filesystems with the "files" format. This issue is common + on Windows and macOS platforms. As the "reftable" backend does not use + filesystem paths to encode reference names this problem goes away. + ** Similarly, macOS normalizes path names that contain unicode characters, + which has the consequence that you cannot store two names with unicode + characters that are encoded differently with the "files" backend. Again, + this is not an issue with the "reftable" backend. + ** Deleting references with the "files" backend requires Git to rewrite the + complete "packed-refs" file. In large repositories with many references + this file can easily be dozens of megabytes in size, in extreme cases it + may be gigabytes. The "reftable" backend uses tombstone markers for + deleted references and thus does not have to rewrite all of its data. + ** Repository housekeeping with the "files" backend typically performs + all-into-one repacks of references. This can be quite expensive, and + consequently housekeeping is a tradeoff between the number of loose + references that accumulate and slow down operations that read references, + and compressing those loose references into the "packed-refs" file. The + "reftable" backend uses geometric compaction after every write, which + amortizes costs and ensures that the backend is always in a + well-maintained state. + ** Operations that write multiple references at once are not atomic with the + "files" backend. Consequently, Git may see in-between states when it reads + references while a reference transaction is in the process of being + committed to disk. + ** Writing many references at once is slow with the "files" backend because + every reference is created as a separate file. The "reftable" backend + significantly outperforms the "files" backend by multiple orders of + magnitude. + ** The reftable backend uses a binary format with prefix compression for + reference names. As a result, the format uses less space compared to the + "packed-refs" file. ++ +Users that get immediate benefit from the "reftable" backend could continue to +opt-in to the "reftable" format manually by setting the "init.defaultRefFormat" +config. But defaults matter, and we think that overall users will have a better +experience with less platform-specific quirks when they use the new backend by +default. ++ +A prerequisite for this change is that the ecosystem is ready to support the +"reftable" format. Most importantly, alternative implementations of Git like +JGit, libgit2 and Gitoxide need to support it. + === Removals * Support for grafting commits has long been superseded by git-replace(1). @@ -178,6 +225,20 @@ 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 + removal, have changed the command to refuse to work unless the + `--i-still-use-this` option is given, and asked the users to report + when they do so. So far there hasn't been a single complaint. ++ +The command will be removed. + == Superseded features that will not be deprecated Some features have gained newer replacements that aim to improve the design in diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index a0e7041c54..224f0978a8 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -298,6 +298,17 @@ For C programs: . since late 2021 with 44ba10d6, we have had variables declared in the for loop "for (int i = 0; i < 10; i++)". + . since late 2023 with 8277dbe987 we have been using the bool type + from <stdbool.h>. + + C99 features we have test balloons for: + + . since late 2024 with v2.48.0-rc0~20, we have test balloons for + compound literal syntax, e.g., (struct foo){ .member = value }; + our hope is that no platforms we care about have trouble using + them, and officially adopt its wider use in mid 2026. Do not add + more use of the syntax until that happens. + New C99 features that we cannot use yet: . %z and %zu as a printf() argument for a size_t (the %z being for @@ -315,6 +326,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 @@ -610,8 +624,9 @@ For C programs: - `S_init()` initializes a structure without allocating the structure itself. - - `S_release()` releases a structure's contents without freeing the - structure. + - `S_release()` releases a structure's contents without reinitializing + the structure for immediate reuse, and without freeing the structure + itself. - `S_clear()` is equivalent to `S_release()` followed by `S_init()` such that the structure is directly usable after clearing it. When @@ -861,6 +876,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 +892,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..6fb83d0c6e 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 @@ -496,9 +497,26 @@ $(LINT_DOCS_FSCK_MSGIDS): ../fsck.h fsck-msgids.adoc $(call mkdir_p_parent_template) $(QUIET_GEN)$(PERL_PATH) lint-fsck-msgids.perl \ ../fsck.h fsck-msgids.adoc $@ - lint-docs-fsck-msgids: $(LINT_DOCS_FSCK_MSGIDS) +## Lint: delimited sections +LINT_DOCS_DELIMITED_SECTIONS = $(patsubst %.adoc,.build/lint-docs/delimited-sections/%.ok,$(MAN_TXT)) +$(LINT_DOCS_DELIMITED_SECTIONS): lint-delimited-sections.perl +$(LINT_DOCS_DELIMITED_SECTIONS): .build/lint-docs/delimited-sections/%.ok: %.adoc + $(call mkdir_p_parent_template) + $(QUIET_LINT_DELIMSEC)$(PERL_PATH) lint-delimited-sections.perl $< >$@ +.PHONY: lint-docs-delimited-sections +lint-docs-delimited-sections: $(LINT_DOCS_DELIMITED_SECTIONS) + +## Lint: Documentation style +LINT_DOCS_DOC_STYLE = $(patsubst %.adoc,.build/lint-docs/doc-style/%.ok,$(DOC_DEP_TXT)) +$(LINT_DOCS_DOC_STYLE): lint-documentation-style.perl +$(LINT_DOCS_DOC_STYLE): .build/lint-docs/doc-style/%.ok: %.adoc + $(call mkdir_p_parent_template) + $(QUIET_LINT_DOCSTYLE)$(PERL_PATH) lint-documentation-style.perl $< >$@ +.PHONY: lint-docs-doc-style +lint-docs-doc-style: $(LINT_DOCS_DOC_STYLE) + lint-docs-manpages: $(QUIET_GEN)./lint-manpages.sh @@ -509,7 +527,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; \ @@ -522,6 +545,8 @@ lint-docs: lint-docs-fsck-msgids lint-docs: lint-docs-gitlink lint-docs: lint-docs-man-end-blurb lint-docs: lint-docs-man-section-order +lint-docs: lint-docs-delimited-sections +lint-docs: lint-docs-doc-style lint-docs: lint-docs-manpages lint-docs: lint-docs-meson diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc index afcf4b46c1..02ba8ba5f6 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 @@ -60,6 +52,15 @@ respond to you. It's better to ask your questions in the channel so that you can be answered if you disconnect and so that others can learn from the conversation. +==== https://discord.gg/GRFVkzgxRd[#discord] on Discord +This is an unofficial Git Discord server for everyone, from people just +starting out with Git to those who develop it. It's a great place to ask +questions, share tips, and connect with the broader Git community in real time. + +The server has channels for general discussions and specific channels for those +who use Git and those who develop it. The server's search functionality also +allows you to find previous conversations and answers to common questions. + [[getting-started]] == Getting Started @@ -150,15 +151,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 +191,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 +305,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 +331,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 +340,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 +384,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 +400,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); ... @@ -896,10 +917,13 @@ Now you should be able to go and check out your newly created branch on GitHub. === Sending a PR to GitGitGadget In order to have your code tested and formatted for review, you need to start by -opening a Pull Request against `gitgitgadget/git`. Head to -https://github.com/gitgitgadget/git and open a PR either with the "New pull -request" button or the convenient "Compare & pull request" button that may -appear with the name of your newly pushed branch. +opening a Pull Request against either `gitgitgadget/git` or `git/git`. Head to +https://github.com/gitgitgadget/git or https://github.com/git/git and open a PR +either with the "New pull request" button or the convenient "Compare & pull +request" button that may appear with the name of your newly pushed branch. + +The differences between using `gitgitgadget/git` and `git/git` as your base can +be found [here](https://gitgitgadget.github.io/#should-i-use-gitgitgadget-on-gitgitgadgets-git-fork-or-on-gits-github-mirror) Review the PR's title and description, as they're used by GitGitGadget respectively as the subject and body of the cover letter for your change. Refer diff --git a/Documentation/MyFirstObjectWalk.adoc b/Documentation/MyFirstObjectWalk.adoc index d6e9dfdbbe..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; @@ -83,23 +83,36 @@ int cmd_walken(int argc, const char **argv, const char *prefix) } ---- -Also add the relevant line in `builtin.h` near `cmd_whatchanged()`: +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 `whatchanged`, +Include the command in `git.c` in `commands[]` near the entry for `version`, 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/1.6.2.4.adoc b/Documentation/RelNotes/1.6.2.4.adoc index f4bf1d0986..053dbb604d 100644 --- a/Documentation/RelNotes/1.6.2.4.adoc +++ b/Documentation/RelNotes/1.6.2.4.adoc @@ -37,3 +37,4 @@ exec >/var/tmp/1 echo O=$(git describe maint) O=v1.6.2.3-38-g318b847 git shortlog --no-merges $O..maint +--- diff --git a/Documentation/RelNotes/2.43.7.adoc b/Documentation/RelNotes/2.43.7.adoc new file mode 100644 index 0000000000..95702a036e --- /dev/null +++ b/Documentation/RelNotes/2.43.7.adoc @@ -0,0 +1,73 @@ +Git v2.43.7 Release Notes +========================= + +This release includes fixes for CVE-2025-27613, CVE-2025-27614, +CVE-2025-46334, CVE-2025-46835, CVE-2025-48384, CVE-2025-48385, and +CVE-2025-48386. + +Fixes since v2.43.6 +------------------- + + * CVE-2025-27613, Gitk: + + When a user clones an untrusted repository and runs Gitk without + additional command arguments, any writable file can be created and + truncated. The option "Support per-file encoding" must have been + enabled. The operation "Show origin of this line" is affected as + well, regardless of the option being enabled or not. + + * CVE-2025-27614, Gitk: + + A Git repository can be crafted in such a way that a user who has + cloned the repository can be tricked into running any script + supplied by the attacker by invoking `gitk filename`, where + `filename` has a particular structure. + + * CVE-2025-46334, Git GUI (Windows only): + + A malicious repository can ship versions of sh.exe or typical + textconv filter programs such as astextplain. On Windows, path + lookup can find such executables in the worktree. These programs + are invoked when the user selects "Git Bash" or "Browse Files" from + the menu. + + * CVE-2025-46835, Git GUI: + + When a user clones an untrusted repository and is tricked into + editing a file located in a maliciously named directory in the + repository, then Git GUI can create and overwrite any writable + file. + + * CVE-2025-48384, Git: + + When reading a config value, Git strips any trailing carriage + return and line feed (CRLF). When writing a config entry, values + with a trailing CR are not quoted, causing the CR to be lost when + the config is later read. When initializing a submodule, if the + submodule path contains a trailing CR, the altered path is read + resulting in the submodule being checked out to an incorrect + location. If a symlink exists that points the altered path to the + submodule hooks directory, and the submodule contains an executable + post-checkout hook, the script may be unintentionally executed + after checkout. + + * CVE-2025-48385, Git: + + When cloning a repository Git knows to optionally fetch a bundle + advertised by the remote server, which allows the server-side to + offload parts of the clone to a CDN. The Git client does not + perform sufficient validation of the advertised bundles, which + allows the remote side to perform protocol injection. + + This protocol injection can cause the client to write the fetched + bundle to a location controlled by the adversary. The fetched + content is fully controlled by the server, which can in the worst + case lead to arbitrary code execution. + + * CVE-2025-48386, Git: + + The wincred credential helper uses a static buffer (`target`) as a + unique key for storing and comparing against internal storage. This + credential helper does not properly bounds check the available + space remaining in the buffer before appending to it with + `wcsncat()`, leading to potential buffer overflows. diff --git a/Documentation/RelNotes/2.44.4.adoc b/Documentation/RelNotes/2.44.4.adoc new file mode 100644 index 0000000000..8db4d5b537 --- /dev/null +++ b/Documentation/RelNotes/2.44.4.adoc @@ -0,0 +1,7 @@ +Git v2.44.4 Release Notes +========================= + +This release merges up the fixes that appears in v2.43.7 to address +the following CVEs: CVE-2025-27613, CVE-2025-27614, CVE-2025-46334, +CVE-2025-46835, CVE-2025-48384, CVE-2025-48385, and CVE-2025-48386. +See the release notes for v2.43.7 for details. diff --git a/Documentation/RelNotes/2.45.4.adoc b/Documentation/RelNotes/2.45.4.adoc new file mode 100644 index 0000000000..5b50d8daf0 --- /dev/null +++ b/Documentation/RelNotes/2.45.4.adoc @@ -0,0 +1,7 @@ +Git v2.45.4 Release Notes +========================= + +This release merges up the fixes that appears in v2.43.7, and v2.44.4 +to address the following CVEs: CVE-2025-27613, CVE-2025-27614, +CVE-2025-46334, CVE-2025-46835, CVE-2025-48384, CVE-2025-48385, and +CVE-2025-48386. See the release notes for v2.43.7 for details. diff --git a/Documentation/RelNotes/2.46.4.adoc b/Documentation/RelNotes/2.46.4.adoc new file mode 100644 index 0000000000..622f4c752f --- /dev/null +++ b/Documentation/RelNotes/2.46.4.adoc @@ -0,0 +1,7 @@ +Git v2.46.4 Release Notes +========================= + +This release merges up the fixes that appears in v2.43.7, v2.44.4, and +v2.45.4 to address the following CVEs: CVE-2025-27613, CVE-2025-27614, +CVE-2025-46334, CVE-2025-46835, CVE-2025-48384, CVE-2025-48385, and +CVE-2025-48386. See the release notes for v2.43.7 for details. diff --git a/Documentation/RelNotes/2.47.3.adoc b/Documentation/RelNotes/2.47.3.adoc new file mode 100644 index 0000000000..bc2a2b833b --- /dev/null +++ b/Documentation/RelNotes/2.47.3.adoc @@ -0,0 +1,8 @@ +Git v2.47.3 Release Notes +========================= + +This release merges up the fixes that appears in v2.43.7, v2.44.4, +v2.45.4, and v2.46.4 to address the following CVEs: CVE-2025-27613, +CVE-2025-27614, CVE-2025-46334, CVE-2025-46835, CVE-2025-48384, +CVE-2025-48385, and CVE-2025-48386. See the release notes for v2.43.7 +for details. diff --git a/Documentation/RelNotes/2.48.2.adoc b/Documentation/RelNotes/2.48.2.adoc new file mode 100644 index 0000000000..f3f2f90c2b --- /dev/null +++ b/Documentation/RelNotes/2.48.2.adoc @@ -0,0 +1,8 @@ +Git v2.48.2 Release Notes +========================= + +This release merges up the fixes that appears in v2.43.7, v2.44.4, +v2.45.4, v2.46.4, and v2.47.3 to address the following CVEs: +CVE-2025-27613, CVE-2025-27614, CVE-2025-46334, CVE-2025-46835, +CVE-2025-48384, CVE-2025-48385, and CVE-2025-48386. See the release +notes for v2.43.7 for details. diff --git a/Documentation/RelNotes/2.49.0.adoc b/Documentation/RelNotes/2.49.0.adoc index a173eb1930..494c83096f 100644 --- a/Documentation/RelNotes/2.49.0.adoc +++ b/Documentation/RelNotes/2.49.0.adoc @@ -285,3 +285,4 @@ Fixes since v2.48 (merge 832f56f06a jc/doc-boolean-synonyms later to maint). (merge 3eeed876a9 ac/doc-http-ssl-type-config later to maint). (merge c268e3285d jc/breaking-changes-early-adopter-option later to maint). + (merge 0d03fda6a5 pb/doc-follow-remote-head later to maint). diff --git a/Documentation/RelNotes/2.49.1.adoc b/Documentation/RelNotes/2.49.1.adoc new file mode 100644 index 0000000000..c619e8b495 --- /dev/null +++ b/Documentation/RelNotes/2.49.1.adoc @@ -0,0 +1,12 @@ +Git v2.49.1 Release Notes +========================= + +This release merges up the fixes that appear in v2.43.7, v2.44.4, +v2.45.4, v2.46.4, v2.47.3, and v2.48.2 to address the following CVEs: +CVE-2025-27613, CVE-2025-27614, CVE-2025-46334, CVE-2025-46835, +CVE-2025-48384, CVE-2025-48385, and CVE-2025-48386. See the release +notes for v2.43.7 for details. + +It also contains some updates to various CI bits to work around +and/or to adjust to the deprecation of use of Ubuntu 20.04 GitHub +Actions CI, updates to to Fedora base image. 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.50.1.adoc b/Documentation/RelNotes/2.50.1.adoc new file mode 100644 index 0000000000..aa4a71adbc --- /dev/null +++ b/Documentation/RelNotes/2.50.1.adoc @@ -0,0 +1,8 @@ +Git v2.50.1 Release Notes +========================= + +This release merges up the fixes that appear in v2.43.7, v2.44.4, +v2.45.4, v2.46.4, v2.47.3, v2.48.2, and v2.49.1 to address the +following CVEs: CVE-2025-27613, CVE-2025-27614, CVE-2025-46334, +CVE-2025-46835, CVE-2025-48384, CVE-2025-48385, and +CVE-2025-48386. See the release notes for v2.43.7 for details. diff --git a/Documentation/RelNotes/2.51.0.adoc b/Documentation/RelNotes/2.51.0.adoc new file mode 100644 index 0000000000..a73ea3e808 --- /dev/null +++ b/Documentation/RelNotes/2.51.0.adoc @@ -0,0 +1,341 @@ +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. + + * "git whatchanged" that is longer to type than "git log --raw" + which is its modern rough equivalent has outlived its usefulness + more than 10 years ago. Plan to deprecate and remove it. + + * An interchange format for stash entries is defined, and subcommand + of "git stash" to import/export has been added. + + * "git merge/pull" has been taught the "--compact-summary" option to + use the compact-summary format, intead of diffstat, when showing + the summary of the incoming changes. + + * "git imap-send" has been broken for a long time, which has been + resurrected and then taught to talk OAuth2.0 etc. + + * Some error messages from "git imap-send" has been updated. + + * When "git daemon" sees a signal while attempting to accept() a new + client, instead of retrying, it skipped it by mistake, which has + been corrected. + + * The reftable ref backend has matured enough; Git 3.0 will make it + the default format in a newly created repositories by default. + + * "netrc" credential helper has been improved to understand textual + service names (like smtp) in addition to the numeric port numbers + (like 25). + + * Lift the limitation to use changed-path filter in "git log" so that + it can be used for a pathspec with multiple literal paths. + + * Clean up the way how signature on commit objects are exported to + and imported from fast-import stream. + + * Remove unsupported, unused, and unsupportable old option from "git + log". + + * Document recently added "git imap-send --list" with an example. + + * "git pull" learned to pay attention to pull.autostash configuration + variable, which overrides rebase/merge.autostash. + + * "git for-each-ref" learns "--start-after" option to help + applications that want to page its output. + + * "git switch" and "git restore" are declared to be no longer + experimental. + + * "git -c alias.foo=bar foo -h baz" reported "'foo' is aliased to + 'bar'" and then went on to run "git foo -h baz", which was + unexpected. Tighten the rule so that alias expansion is reported + only when "-h" is the sole option. + + +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. + + * A test helper "test_seq" function learned the "-f <fmt>" option, + which allowed us to simplify a lot of test scripts. + + * A lot of stale stuff has been removed from the contrib/ hierarchy. + + * "git push" and "git fetch" are taught to update refs in batches to + gain performance. + + * Some code paths in "git prune" used to ignore the passed-in + repository object and used the `the_repository` singleton instance + instead, which has been corrected. + + * Update ".clang-format" and ".editorconfig" to match our style guide + a bit better. + + * "make coccicheck" succeeds even when spatch made suggestions, which + has been updated to fail in such a case. + + * Code clean-up around object access API. + + * Define .precision to more canned parse-options type to avoid bugs + coming from using a variable with a wrong type to capture the + parsed values. + + * Flipping the default hash function to SHA-256 at Git 3.0 boundary + is planned. + + * Declare weather-balloon we raised for "bool" type 18 months ago a + success and officially allow using the type in our codebase. + + * GIT_TEST_INSTALLED was not honored in the recent topic related to + SHA256 hashes, which has been corrected. + + * The pop_most_recent_commit() function can have quite expensive + worst case performance characteristics, which has been optimized by + using prio-queue data structure. + + * Move structure definition from unrelated header file to where it + belongs. + + * To help our developers, document what C99 language features are + being considered for adoption, in addition to what past experiments + have already decided. + + * The reftable unit tests are now ported to the "clar" unit testing + framework. + + * Redefine where the multi-pack-index sits in the object subsystem, + which recently was restructured to allow multiple backends that + support a single object source that belongs to one repository. A + MIDX does span multiple "object sources". + + * Reduce implicit assumption and dependence on the_repository in the + object-file subsystem. + + +Fixes since v2.50 +----------------- + +Unless otherwise noted, all the changes in 2.50.X maintenance track, +including security updates, are included in this release. + + * 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). + + * "git maintenance" lacked the care "git gc" had to avoid holding + onto the repository lock for too long during packing refs, which + has been remedied. + (merge 1b5074e614 ps/maintenance-ref-lock later to maint). + + * Avoid regexp_constraint and instead use comparison_constraint when + listing functions to exclude from application of coccinelle rules, + as spatch can be built with different regexp engine X-<. + (merge f2ad545813 jc/cocci-avoid-regexp-constraint later to maint). + + * Updating submodules from the upstream did not work well when + submodule's HEAD is detached, which has been improved. + (merge ca62f524c1 jk/submodule-remote-lookup-cleanup later to maint). + + * Remove unnecessary check from "git daemon" code. + (merge 0c856224d2 cb/daemon-fd-check-fix later to maint). + + * Use of sysctl() system call to learn the total RAM size used on + BSDs has been corrected. + (merge 781c1cf571 cb/total-ram-bsd-fix later to maint). + + * Drop FreeBSD 4 support and declare that we support only FreeBSD 12 + or later, which has memmem() supported. + (merge 0392f976a7 bs/config-mak-freebsd later to maint). + + * A diff-filter with negative-only specification like "git log + --diff-filter=d" did not trigger correctly, which has been fixed. + (merge 375ac087c5 jk/all-negative-diff-filter-fix later to maint). + + * A failure to open the index file for writing due to conflicting + access did not state what went wrong, which has been corrected. + (merge 9455397a5c hy/read-cache-lock-error-fix later to maint). + + * Tempfile removal fix in the codepath to sign commits with SSH keys. + (merge 4498127b04 re/ssh-sign-buffer-fix later to maint). + + * Code and test clean-up around string-list API. + (merge 6e5b26c3ff sj/string-list later to maint). + + * "git apply -N" should start from the current index and register + only new files, but it instead started from an empty index, which + has been corrected. + (merge 2b49d97fcb rp/apply-intent-to-add-fix later to maint). + + * Leakfix with a new and a bit invasive test on pack-bitmap files. + (merge bfd5522e98 ly/load-bitmap-leakfix later to maint). + + * "git fetch --prune" used to be O(n^2) expensive when there are many + refs, which has been corrected. + (merge 87d8d8c5d0 ph/fetch-prune-optim later to maint). + + * When a ref creation at refs/heads/foo/bar fails, the files backend + now removes refs/heads/foo/ if the directory is otherwise not used. + (merge a3a7f20516 ps/refs-files-remove-empty-parent later to maint). + + * "pack-objects" has been taught to avoid pointing into objects in + cruft packs from midx. + + * "git remote" now detects remote names that overlap with each other + (e.g., remote nickname "outer" and "outer/inner" are used at the + same time), as it will lead to overlapping remote-tracking + branches. + (merge a5a727c448 jk/remote-avoid-overlapping-names later to maint). + + * The gpg.program configuration variable, which names a pathname to + the (custom) GPG compatible program, can now be spelled with ~tilde + expansion. + (merge 7d275cd5c0 jb/gpg-program-variable-is-a-pathname later to maint). + + * Our <sane-ctype.h> header file relied on that the system-supplied + <ctype.h> header is not later included, which would override our + macro definitions, but "amazon linux" broke this assumption. Fix + this by preemptively including <ctype.h> near the beginning of + <sane-ctype.h> ourselves. + (merge 9d3b33125f ps/sane-ctype-workaround later to maint). + + * Clean-up compat/bswap.h mess. + (merge f4ac32c03a ss/compat-bswap-revamp later to maint). + + * Meson-based build did not handle libexecdir setting correctly, + which has been corrected. + (merge 056dbe8612 rj/meson-libexecdir-fix later to maint). + + * Document that we do not require "real" name when signing your + patches off. + (merge 1f0fed312a bc/contribution-under-non-real-names later to maint). + + * "git commit" that concludes a conflicted merge failed to notice and remove + existing comment added automatically (like "# Conflicts:") when the + core.commentstring is set to 'auto'. + (merge 92b7c7c9f5 ac/auto-comment-char-fix later to maint). + + * "git rebase -i" with bogus rebase.instructionFormat configuration + failed to produce the todo file after recording the state files, + leading to confused "git status"; this has been corrected. + (merge ade14bffd7 ow/rebase-verify-insn-fmt-before-initializing-state later to maint). + + * A few file descriptors left unclosed upon program completion in a + few test helper programs are now closed. + (merge 0f1b33815b hl/test-helper-fd-close later to maint). + + * Interactive prompt code did not correctly strip CRLF from the end + of line on Windows. + (merge 711a20827b js/prompt-crlf-fix later to maint). + + * The config API had a set of convenience wrapper functions that + implicitly use the_repository instance; they have been removed and + inlined at the calling sites. + + * "git add/etc -p" now honor the diff.context configuration variable, + and also they learn to honor the -U<n> command-line option. + (merge 2b3ae04011 lm/add-p-context later to maint). + + * The case where a new submodule takes a path where there used to be a + completely different subproject is now dealt with a bit better than + before. + (merge 5ed8c5b465 kj/renamed-submodule later to maint). + + * The deflate codepath in "git archive --format=zip" had a + longstanding bug coming from misuse of zlib API, which has been + corrected. + + * 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). + (merge ff73f375bb jg/mailinfo-leakfix later to maint). + (merge 996f14c02b jj/doc-branch-markup-fix later to maint). + (merge 1e77de1864 cb/ci-freebsd-update-to-14.3 later to maint). + (merge b0e9d25865 jk/fix-leak-send-pack later to maint). + (merge f3a9558c8c bs/remote-helpers-doc-markup-fix later to maint). + (merge c4e9775c60 kh/doc-config-subcommands later to maint). + (merge de404249ab ps/perlless-test-fixes later to maint). + (merge 953049eed8 ts/merge-orig-head-doc-fix later to maint). + (merge 0c83bbc704 rj/freebsd-sysinfo-build-fix later to maint). + (merge ad7780b38f ps/doc-pack-refs-auto-with-files-backend-fix later to maint). + (merge f4fa8a3687 rh/doc-glob-pathspec-fix later to maint). + (merge b27be108c8 ja/doc-git-log-markup later to maint). + (merge 14d7583beb pw/config-kvi-remove-path later to maint). + (merge f31abb421d jc/do-not-scan-argv-without-parsing later to maint). + (merge 26552cb62a jk/unleak-reflog-expire-entry later to maint). + (merge 339d95fda9 jc/ci-print-test-failures-fix later to maint). + (merge 8c3add51a8 cb/meson-avoid-broken-macos-pcre2 later to maint). + (merge 5247da07b8 ps/meson-clar-decls-fix later to maint). + (merge f3ef347bb2 ch/t7450-recursive-clone-test-fix later to maint). + (merge 4ac3302a1a jc/doc-release-vs-clear later to maint). + (merge 3bdd897413 ms/meson-with-ancient-git-wo-ls-files-dedup later to maint). + (merge cca758d324 kh/doc-fast-import-historical later to maint). + (merge 9b0781196a jc/test-hashmap-is-still-here later to maint). + (merge 1bad05bacc jk/revert-squelch-compiler-warning later to maint). + (merge 3a7e783d9c dl/squelch-maybe-uninitialized later to maint). diff --git a/Documentation/RelNotes/2.52.0.adoc b/Documentation/RelNotes/2.52.0.adoc new file mode 100644 index 0000000000..fa72515358 --- /dev/null +++ b/Documentation/RelNotes/2.52.0.adoc @@ -0,0 +1,145 @@ +Git v2.52 Release Notes +======================= + +UI, Workflows & Features +------------------------ + + * The "list" subcommand of "git refs" acts as a front-end for + "git for-each-ref". + + * "git cmd --help-all" now works outside repositories. + + * "git diff-tree" learned "--max-depth" option. + + * A new subcommand "git repo" gives users a way to grab various + repository characteristics. + + +Performance, Internal Implementation, Development Support etc. +-------------------------------------------------------------- + + * string_list_split*() family of functions have been extended to + simplify common use cases. + + * Arrays of strbuf is often a wrong data structure to use, and + strbuf_split*() family of functions that create them often have + better alternatives. Update several code paths and replace + strbuf_split*(). + + * Revision traversal limited with pathspec, like "git log dir/*", + used to ignore changed-paths Bloom filter when the pathspec + contained wildcards; now they take advantage of the filter when + they can. + + * Doc lint updates to encourage the newer and easier-to-use + `synopsis` format, with fixes to a handful of existing uses. + + * Remove dependency on the_repository and other globals from the + commit-graph code, and other changes unrelated to de-globaling. + + * Discord has been added to the first contribution documentation as + another way to ask for help. + + +Fixes since v2.51 +----------------- + +Unless otherwise noted, all the changes in 2.51.X maintenance track, +including security updates, are included in this release. + + * During interactive rebase, using 'drop' on a merge commit lead to + an error, which was incorrect. + (merge 4d491ade8f js/rebase-i-allow-drop-on-a-merge later to maint). + + * "git refs migrate" to migrate the reflog entries from a refs + backend to another had a handful of bugs squashed. + (merge 465eff81de ps/reflog-migrate-fixes later to maint). + + * "git remote rename origin upstream" failed to move origin/HEAD to + upstream/HEAD when origin/HEAD is unborn and performed other + renames extremely inefficiently, which has been corrected. + (merge 16c4fa26b9 ps/remote-rename-fix later to maint). + + * "git describe" has been optimized by using better data structure. + (merge 08bb69d70f rs/describe-with-prio-queue later to maint). + + * "git push" had a code path that led to BUG() but it should have + been a die(), as it is a response to a usual but invalid end-user + action to attempt pushing an object that does not exist. + (merge dfbfc2221b dl/push-missing-object-error later to maint). + + * Various bugs about rename handling in "ort" merge strategy have + been fixed. + (merge f6ecb603ff en/ort-rename-fixes later to maint). + + * "git jump" (in contrib/) fails to parse the diff header correctly + when a file has a space in its name, which has been corrected. + (merge 621ce9c1c6 gh/git-jump-pathname-with-sp later to maint). + + * "git diff --no-index" run inside a subdirectory under control of a + Git repository operated at the top of the working tree and stripped + the prefix from the output, and oddballs like "-" (stdin) did not + work correctly because of it. Correct the set-up by undoing what + the set-up sequence did to cwd and prefix. + (merge e1d3d61a45 jc/diff-no-index-in-subdir later to maint). + + * Various options to "git diff" that makes comparison ignore certain + aspects of the differences (like "space changes are ignored", + "differences in lines that match these regular expressions are + ignored") did not work well with "--name-only" and friends. + (merge b55e6d36eb ly/diff-name-only-with-diff-from-content later to maint). + + * Documentation for "git rebase" has been updated. + (merge 3f7f2b0359 je/doc-rebase later to maint). + + * The start_delayed_progress() function in the progress eye-candy API + did not clear its internal state, making an initial delay value + larger than 1 second ineffective, which has been corrected. + (merge 457534d041 js/progress-delay-fix later to maint). + + * The compatObjectFormat extension is used to hide an incomplete + feature that is not yet usable for any purpose other than + developing the feature further. Document it as such to discourage + its use by mere mortals. + (merge 716d905792 bc/doc-compat-object-format-not-working later to maint). + + * "git log -L..." compared trees of multiple parents with the tree of the + merge result in an unnecessarily inefficient way. + (merge 0a15bb634c sg/line-log-merge-optim later to maint). + + * Under a race against another process that is repacking the + repository, especially a partially cloned one, "git fetch" may + mistakenly think some objects we do have are missing, which has + been corrected. + (merge 8f32a5a6c0 jk/fetch-check-graph-objects-fix later to maint). + + * "git fetch" can clobber a symref that is dangling when the + remote-tracking HEAD is set to auto update, which has been + corrected. + + * "git describe <blob>" misbehaves and/or crashes in some corner + cases, which has been taught to exit with failure gracefully. + (merge 7c10e48e81 jk/describe-blob later to maint). + + * Manual page for "gitk" is updated with the current maintainer's + name. + (merge bcb20dda83 js/doc-gitk-history later to maint). + + * Update the instruction to use of GGG in the MyFirstContribution + document to say that a GitHub PR could be made against `git/git` + instead of `gitgitgadget/git`. + (merge 37001cdbc4 ds/doc-ggg-pr-fork-clarify later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge 823d537fa7 kh/doc-git-log-markup-fix later to maint). + (merge cf7efa4f33 rj/t6137-cygwin-fix later to maint). + (merge 529a60a885 ua/t1517-short-help-tests later to maint). + (merge 22d421fed9 ac/deglobal-fmt-merge-log-config later to maint). + (merge 741f36c7d9 kr/clone-synopsis-fix later to maint). + (merge a60203a015 dk/t7005-editor-updates later to maint). + (merge 7d4a5fef7d ds/doc-count-objects-fix later to maint). + (merge 16684b6fae ps/reftable-libgit2-cleanup later to maint). + (merge f38786baa7 ja/asciidoc-doctor-verbatim-fixes later to maint). + (merge 374579c6d4 kh/doc-interpret-trailers-markup-fix later to maint). + (merge 44dce6541c kh/doc-config-typofix later to maint). + (merge 785628b173 js/doc-sending-patch-via-thunderbird later to maint). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 958e3cc3d5..86ca7f6a78 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -408,8 +408,15 @@ your patch differs from project to project, so it may be different from that of the project you are accustomed to. [[real-name]] -Also notice that a real name is used in the `Signed-off-by` trailer. Please -don't hide your real name. +Please use a known identity in the `Signed-off-by` trailer, since we cannot +accept anonymous contributions. It is common, but not required, to use some form +of your real name. We realize that some contributors are not comfortable doing +so or prefer to contribute under a pseudonym or preferred name and we can accept +your patch either way, as long as the name and email you use are distinctive, +identifying, and not misleading. + +The goal of this policy is to allow us to have sufficient information to contact +you if questions arise about your contribution. [[commit-trailers]] If you like, you can put extra trailers at the end: 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..ff9ea0a294 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..fe64a62d96 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..1fb948fc76 100644 --- a/Documentation/blame-options.adoc +++ b/Documentation/blame-options.adoc @@ -75,7 +75,8 @@ include::line-range-format.adoc[] iso format is used. For supported values, see the discussion of the --date option at linkgit:git-log[1]. ---[no-]progress:: +--progress:: +--no-progress:: Progress status is reported on the standard error stream by default when it is attached to a terminal. This flag enables progress reporting even if not attached to a @@ -125,7 +126,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..a4db9fa5c8 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. + `branch.<name>.merge` to the desired branch, and use the relative path + 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..3fbe83eef1 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 @@ -691,12 +696,6 @@ core.unsetenvvars:: Defaults to `PERL5LIB` to account for the fact that Git for Windows insists on using its own Perl interpreter. -core.restrictinheritedhandles:: - Windows-only: override whether spawned processes inherit only standard - file handles (`stdin`, `stdout` and `stderr`) or all handles. Can be - `auto`, `true` or `false`. Defaults to `auto`, which means `true` on - Windows 7 and later, and `false` on older Windows versions. - core.createObject:: You can set this to 'link', in which case a hardlink followed by a delete of the source are used to make sure that object creation diff --git a/Documentation/config/extensions.adoc b/Documentation/config/extensions.adoc index 9e2f321a6d..829f2523fc 100644 --- a/Documentation/config/extensions.adoc +++ b/Documentation/config/extensions.adoc @@ -14,6 +14,10 @@ compatObjectFormat:: compatObjectFormat. As well as being able to use oids encoded in compatObjectFormat in addition to oids encoded with objectFormat to locally specify objects. ++ +Note that the functionality enabled by this extension is incomplete and subject +to change. It currently exists only to allow development and testing of +the underlying feature and is not designed to be enabled by end users. noop:: This extension does not change git's behavior at all. It is useful only diff --git a/Documentation/config/feature.adoc b/Documentation/config/feature.adoc index cb49ff2604..924f5ff4e3 100644 --- a/Documentation/config/feature.adoc +++ b/Documentation/config/feature.adoc @@ -24,6 +24,12 @@ 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. ++ +* `init.defaultRefFormat=reftable` causes newly initialized repositories to use +the reftable format for storing references. This new format solves issues with +case-insensitive filesystems, compresses better and performs significantly +better with many use cases. Refer to Documentation/technical/reftable.adoc for +more information on this new storage format. 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/format.adoc b/Documentation/config/format.adoc index 7410e930e5..ab0710e86a 100644 --- a/Documentation/config/format.adoc +++ b/Documentation/config/format.adoc @@ -68,9 +68,15 @@ format.encodeEmailHeaders:: Defaults to true. format.pretty:: +ifndef::with-breaking-changes[] The default pretty format for log/show/whatchanged command. See linkgit:git-log[1], linkgit:git-show[1], linkgit:git-whatchanged[1]. +endif::with-breaking-changes[] +ifdef::with-breaking-changes[] + The default pretty format for log/show command. + See linkgit:git-log[1], linkgit:git-show[1]. +endif::with-breaking-changes[] format.thread:: The default threading style for 'git format-patch'. Can be 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/gpg.adoc b/Documentation/config/gpg.adoc index 5cf32b179d..240e46c050 100644 --- a/Documentation/config/gpg.adoc +++ b/Documentation/config/gpg.adoc @@ -1,5 +1,5 @@ gpg.program:: - Use this custom program instead of "`gpg`" found on `$PATH` when + Pathname of the program to use instead of "`gpg`" when making or verifying a PGP signature. The program must support the same command-line interface as GPG, namely, to verify a detached signature, "`gpg --verify $signature - <$file`" is run, and the 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/imap.adoc b/Documentation/config/imap.adoc index 3d28f72643..4682a6bd03 100644 --- a/Documentation/config/imap.adoc +++ b/Documentation/config/imap.adoc @@ -1,7 +1,9 @@ imap.folder:: The folder to drop the mails into, which is typically the Drafts - folder. For example: "INBOX.Drafts", "INBOX/Drafts" or - "[Gmail]/Drafts". Required. + folder. For example: `INBOX.Drafts`, `INBOX/Drafts` or + `[Gmail]/Drafts`. The IMAP folder to interact with MUST be specified; + the value of this configuration variable is used as the fallback + default value when the `--folder` option is not given. imap.tunnel:: Command used to set up a tunnel to the IMAP server through which @@ -40,5 +42,6 @@ imap.authMethod:: Specify the authentication method for authenticating with the IMAP server. If Git was built with the NO_CURL option, or if your curl version is older than 7.34.0, or if you're running git-imap-send with the `--no-curl` - option, the only supported method is 'CRAM-MD5'. If this is not set - then 'git imap-send' uses the basic IMAP plaintext LOGIN command. + option, the only supported methods are `PLAIN`, `CRAM-MD5`, `OAUTHBEARER` + and `XOAUTH2`. If this is not set then `git imap-send` uses the basic IMAP + plaintext `LOGIN` command. diff --git a/Documentation/config/log.adoc b/Documentation/config/log.adoc index 9003a82191..f20cc25cd7 100644 --- a/Documentation/config/log.adoc +++ b/Documentation/config/log.adoc @@ -1,64 +1,76 @@ -log.abbrevCommit:: - If true, makes linkgit:git-log[1], linkgit:git-show[1], and - linkgit:git-whatchanged[1] assume `--abbrev-commit`. You may +`log.abbrevCommit`:: + If `true`, make +ifndef::with-breaking-changes[] + linkgit:git-log[1], linkgit:git-show[1], and + linkgit:git-whatchanged[1] +endif::with-breaking-changes[] +ifdef::with-breaking-changes[] + linkgit:git-log[1] and linkgit:git-show[1] +endif::with-breaking-changes[] + assume `--abbrev-commit`. You may override this option with `--no-abbrev-commit`. -log.date:: - Set the default date-time mode for the 'log' command. - Setting a value for log.date is similar to using 'git log''s +`log.date`:: + Set the default date-time mode for the `log` command. + Setting a value for log.date is similar to using `git log`'s `--date` option. See linkgit:git-log[1] for details. + If the format is set to "auto:foo" and the pager is in use, format "foo" will be used for the date format. Otherwise, "default" will be used. -log.decorate:: +`log.decorate`:: Print out the ref names of any commits that are shown by the log - command. If 'short' is specified, the ref name prefixes 'refs/heads/', - 'refs/tags/' and 'refs/remotes/' will not be printed. If 'full' is - specified, the full ref name (including prefix) will be printed. - If 'auto' is specified, then if the output is going to a terminal, - the ref names are shown as if 'short' were given, otherwise no ref - names are shown. This is the same as the `--decorate` option - of the `git log`. + command. Possible values are: ++ +-- +`short`;; the ref name prefixes `refs/heads/`, `refs/tags/` and + `refs/remotes/` are not printed. +`full`;; the full ref name (including prefix) are printed. +`auto`;; if the output is going to a terminal, + the ref names are shown as if `short` were given, otherwise no ref + names are shown. +-- ++ +This is the same as the `--decorate` option of the `git log`. -log.initialDecorationSet:: +`log.initialDecorationSet`:: By default, `git log` only shows decorations for certain known ref namespaces. If 'all' is specified, then show all refs as decorations. -log.excludeDecoration:: +`log.excludeDecoration`:: Exclude the specified patterns from the log decorations. This is similar to the `--decorate-refs-exclude` command-line option, but the config option can be overridden by the `--decorate-refs` option. -log.diffMerges:: +`log.diffMerges`:: Set diff format to be used when `--diff-merges=on` is specified, see `--diff-merges` in linkgit:git-log[1] for details. Defaults to `separate`. -log.follow:: +`log.follow`:: If `true`, `git log` will act as if the `--follow` option was used when a single <path> is given. This has the same limitations as `--follow`, i.e. it cannot be used to follow multiple files and does not work well on non-linear history. -log.graphColors:: +`log.graphColors`:: A list of colors, separated by commas, that can be used to draw history lines in `git log --graph`. -log.showRoot:: +`log.showRoot`:: If true, the initial commit will be shown as a big creation event. This is equivalent to a diff against an empty tree. Tools like linkgit:git-log[1] or linkgit:git-whatchanged[1], which normally hide the root commit will now show it. True by default. -log.showSignature:: +`log.showSignature`:: If true, makes linkgit:git-log[1], linkgit:git-show[1], and linkgit:git-whatchanged[1] assume `--show-signature`. -log.mailmap:: +`log.mailmap`:: If true, makes linkgit:git-log[1], linkgit:git-show[1], and linkgit:git-whatchanged[1] assume `--use-mailmap`, otherwise assume `--no-use-mailmap`. True by default. 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..15a4c14c38 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,45 @@ 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 - at the end of the merge. True by default. - -merge.autoStash:: - When set to true, automatically create a temporary stash entry +`merge.stat`:: + What, if anything, to print between `ORIG_HEAD` and the merge result + at the end of the merge. Possible values are: ++ +-- +`false`;; Show nothing. +`true`;; Show `git diff --diffstat --summary ORIG_HEAD`. +`compact`;; Show `git diff --compact-summary ORIG_HEAD`. +-- ++ +but any unrecognised value (e.g., a value added by a future version of +Git) is taken as `true` instead of triggering an error. Defaults to +`true`. + +`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 +126,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..7064f5a462 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/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/pull.adoc b/Documentation/config/pull.adoc index 9349e09261..125c930f72 100644 --- a/Documentation/config/pull.adoc +++ b/Documentation/config/pull.adoc @@ -29,5 +29,21 @@ pull.octopus:: The default merge strategy to use when pulling multiple branches at once. +pull.autoStash:: + When set to true, automatically create a temporary stash entry + to record the local changes before the operation begins, and + restore them after the operation completes. When your "git + pull" rebases (instead of merges), this may be convenient, since + unlike merging pull that tolerates local changes that do not + interfere with the merge, rebasing pull refuses to work with any + local changes. ++ +If `pull.autostash` is set (either to true or false), +`merge.autostash` and `rebase.autostash` are ignored. If +`pull.autostash` is not set at all, depending on the value of +`pull.rebase`, `merge.autostash` or `rebase.autostash` is used +instead. Can be overridden by the `--[no-]autostash` command line +option. + pull.twohead:: The default merge strategy to use when pulling a single branch. diff --git a/Documentation/config/remote.adoc b/Documentation/config/remote.adoc index 4118c219c1..91e46f66f5 100644 --- a/Documentation/config/remote.adoc +++ b/Documentation/config/remote.adoc @@ -101,21 +101,22 @@ remote.<name>.serverOption:: The default set of server options used when fetching from this remote. These server options can be overridden by the `--server-option=` command line arguments. ++ +This is a multi-valued variable, and an empty value can be used in a higher +priority configuration file (e.g. `.git/config` in a repository) to clear +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, but will not touch an - already existing local reference. Setting to "warn" will print - a message if the remote has a different value, than the local one and + if it exists on the remote, but not locally; this will not touch an + already existing local reference. Setting it to "warn" will print + a message if the remote has a different value than the local one; in case there is no local reference, it behaves like "create". A variant on "warn" is "warn-if-not-$branch", which behaves like "warn", but if `HEAD` on the remote is `$branch` it will be silent. - Setting to "always" will silently update it to the value on the remote. - Finally, setting it to "never" will never change or create the local - reference. -+ -This is a multi-valued variable, and an empty value can be used in a higher -priority configuration file (e.g. `.git/config` in a repository) to clear -the values inherited from a lower priority configuration files (e.g. -`$HOME/.gitconfig`). + Setting it to "always" will silently update `remotes/<name>/HEAD` to + the value on the remote. Finally, setting it to "never" will never + change or create the local reference. diff --git a/Documentation/config/repack.adoc b/Documentation/config/repack.adoc index c79af6d7b8..e9e78dcb19 100644 --- a/Documentation/config/repack.adoc +++ b/Documentation/config/repack.adoc @@ -39,3 +39,10 @@ repack.cruftThreads:: a cruft pack and the respective parameters are not given over the command line. See similarly named `pack.*` configuration variables for defaults and meaning. + +repack.midxMustContainCruft:: + When set to true, linkgit:git-repack[1] will unconditionally include + cruft pack(s), if any, in the multi-pack index when invoked with + `--write-midx`. When false, cruft packs are only included in the MIDX + when necessary (e.g., because they might be required to form a + reachability closure with MIDX bitmaps). Defaults to true. diff --git a/Documentation/config/sendemail.adoc b/Documentation/config/sendemail.adoc index 5ffcfc9f2a..4722334657 100644 --- a/Documentation/config/sendemail.adoc +++ b/Documentation/config/sendemail.adoc @@ -1,38 +1,38 @@ 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. sendemail.mailmap:: - If true, makes linkgit:git-send-email[1] assume `--mailmap`, - otherwise assume `--no-mailmap`. False by default. + If `true`, makes linkgit:git-send-email[1] assume `--mailmap`, + otherwise assume `--no-mailmap`. `False` by default. sendemail.mailmap.file:: The location of a linkgit:git-send-email[1] specific augmenting @@ -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 @@ -96,12 +96,17 @@ sendemail.xmailer:: linkgit:git-send-email[1] command-line options. See its documentation for details. +sendemail.outlookidfix:: + If `true`, makes linkgit:git-send-email[1] assume `--outlook-id-fix`, + and if `false` assume `--no-outlook-id-fix`. If not specified, it will + behave the same way as if `--outlook-id-fix` is not specified. + sendemail.signedOffCc (deprecated):: Deprecated alias for `sendemail.signedOffByCc`. 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 +116,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-context-options.adoc b/Documentation/diff-context-options.adoc new file mode 100644 index 0000000000..e161260358 --- /dev/null +++ b/Documentation/diff-context-options.adoc @@ -0,0 +1,10 @@ +`-U<n>`:: +`--unified=<n>`:: + Generate diffs with _<n>_ lines of context. Defaults to `diff.context` + or 3 if the config option is unset. + +`--inter-hunk-context=<n>`:: + Show the context between diff hunks, up to the specified _<number>_ + of lines, thereby fusing hunks that are close to each other. + Defaults to `diff.interHunkContext` or 0 if the config option + is unset. diff --git a/Documentation/diff-format.adoc b/Documentation/diff-format.adoc index 80e36e153d..9f7e988241 100644 --- a/Documentation/diff-format.adoc +++ b/Documentation/diff-format.adoc @@ -103,6 +103,7 @@ if the file was renamed on any side of history. With followed by the name of the path in the merge commit. Examples for `-c` and `--cc` without `--combined-all-paths`: + ------------------------------------------------ ::100644 100644 100644 fabadb8 cc95eb0 4866510 MM desc.c ::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM bar.sh 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/diff-options.adoc b/Documentation/diff-options.adoc index 640eb6e7db..ae31520f7f 100644 --- a/Documentation/diff-options.adoc +++ b/Documentation/diff-options.adoc @@ -37,32 +37,32 @@ endif::git-diff[] endif::git-format-patch[] ifdef::git-log[] --m:: +`-m`:: Show diffs for merge commits in the default format. This is similar to `--diff-merges=on`, except `-m` will produce no output unless `-p` is given as well. --c:: +`-c`:: Produce combined diff output for merge commits. Shortcut for `--diff-merges=combined -p`. ---cc:: +`--cc`:: Produce dense combined diff output for merge commits. Shortcut for `--diff-merges=dense-combined -p`. ---dd:: +`--dd`:: Produce diff with respect to first parent for both merge and regular commits. Shortcut for `--diff-merges=first-parent -p`. ---remerge-diff:: +`--remerge-diff`:: Produce remerge-diff output for merge commits. Shortcut for `--diff-merges=remerge -p`. ---no-diff-merges:: +`--no-diff-merges`:: Synonym for `--diff-merges=off`. ---diff-merges=<format>:: +`--diff-merges=<format>`:: Specify diff format to be used for merge commits. Default is {diff-merges-default} unless `--first-parent` is in use, in which case `first-parent` is the default. @@ -70,48 +70,54 @@ ifdef::git-log[] The following formats are supported: + -- -off, none:: +`off`:: +`none`:: Disable output of diffs for merge commits. Useful to override implied value. -on, m:: +`on`:: +`m`:: Make diff output for merge commits to be shown in the default format. The default format can be changed using `log.diffMerges` configuration variable, whose default value is `separate`. -first-parent, 1:: +`first-parent`:: +`1`:: Show full diff with respect to first parent. This is the same format as `--patch` produces for non-merge commits. -separate:: +`separate`:: Show full diff with respect to each of parents. Separate log entry and diff is generated for each parent. -combined, c:: +`combined`:: +`c`:: Show differences from each of the parents to the merge result simultaneously instead of showing pairwise diff between a parent and the result one at a time. Furthermore, it lists only files which were modified from all parents. -dense-combined, cc:: +`dense-combined`:: +`cc`:: Further compress output produced by `--diff-merges=combined` by omitting uninteresting hunks whose contents in the parents have only two variants and the merge result picks one of them without modification. -remerge, r:: - Remerge two-parent merge commits to create a temporary tree +`remerge`:: +`r`:: Remerge two-parent merge commits to create a temporary tree object--potentially containing files with conflict markers and such. A diff is then shown between that temporary tree and the actual merge commit. +-- + The output emitted when this option is used is subject to change, and so is its interaction with other options (unless explicitly documented). --- ---combined-all-paths:: + +`--combined-all-paths`:: Cause combined diffs (used for merge commits) to list the name of the file from all parents. It thus only has effect when `--diff-merges=[dense-]combined` is in use, and @@ -499,7 +505,8 @@ endif::git-format-patch[] Turn off rename detection, even when the configuration file gives the default to do so. -`--[no-]rename-empty`:: +`--rename-empty`:: +`--no-rename-empty`:: Whether to use empty blobs as rename source. ifndef::git-format-patch[] @@ -887,5 +894,33 @@ endif::git-format-patch[] reverted with `--ita-visible-in-index`. Both options are experimental and could be removed in future. +--max-depth=<depth>:: + For each pathspec given on command line, descend at most `<depth>` + levels of directories. A value of `-1` means no limit. + Cannot be combined with wildcards in the pathspec. + Given a tree containing `foo/bar/baz`, the following list shows the + matches generated by each set of options: ++ +-- + - `--max-depth=0 -- foo`: `foo` + + - `--max-depth=1 -- foo`: `foo/bar` + + - `--max-depth=1 -- foo/bar`: `foo/bar/baz` + + - `--max-depth=1 -- foo foo/bar`: `foo/bar/baz` + + - `--max-depth=2 -- foo`: `foo/bar/baz` +-- ++ +If no pathspec is given, the depth is measured as if all +top-level entries were specified. Note that this is different +than measuring from the root, in that `--max-depth=0` would +still return `foo`. This allows you to still limit depth while +asking for a subset of the top-level entries. ++ +Note that this option is only supported for diffs between tree objects, +not against the index or working tree. + For more detailed explanation on these common options, see also linkgit:gitdiffcore[7]. diff --git a/Documentation/fetch-options.adoc b/Documentation/fetch-options.adoc index b01372e4b3..d3ac31f4e2 100644 --- a/Documentation/fetch-options.adoc +++ b/Documentation/fetch-options.adoc @@ -1,4 +1,5 @@ ---[no-]all:: +--all:: +--no-all:: Fetch all remotes, except for the ones that has the `remote.<name>.skipFetchAll` configuration variable set. This overrides the configuration variable fetch.all`. @@ -88,7 +89,8 @@ This is incompatible with `--recurse-submodules=[yes|on-demand]` and takes precedence over the `fetch.output` config option. ifndef::git-pull[] ---[no-]write-fetch-head:: +--write-fetch-head:: +--no-write-fetch-head:: Write the list of remote refs fetched in the `FETCH_HEAD` file directly under `$GIT_DIR`. This is the default. Passing `--no-write-fetch-head` from the command line tells @@ -118,13 +120,16 @@ ifndef::git-pull[] Allow several <repository> and <group> arguments to be specified. No <refspec>s may be specified. ---[no-]auto-maintenance:: ---[no-]auto-gc:: +--auto-maintenance:: +--no-auto-maintenance:: +--auto-gc:: +--no-auto-gc:: Run `git maintenance run --auto` at the end to perform automatic repository maintenance if needed. (`--[no-]auto-gc` is a synonym.) This is enabled by default. ---[no-]write-commit-graph:: +--write-commit-graph:: +--no-write-commit-graph:: Write a commit-graph after fetching. This overrides the config setting `fetch.writeCommitGraph`. endif::git-pull[] 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/for-each-ref-options.adoc b/Documentation/for-each-ref-options.adoc new file mode 100644 index 0000000000..f13efb5f25 --- /dev/null +++ b/Documentation/for-each-ref-options.adoc @@ -0,0 +1,85 @@ +`<pattern>...`:: + If one or more _<pattern>_ parameters are given, only refs are shown that + match against at least one pattern, either using `fnmatch`(3) or + literally, in the latter case matching completely or from the + beginning up to a slash. + +`--stdin`:: + The list of patterns is read from standard input instead of from + the argument list. + +`--count=<count>`:: + Stop after showing _<count>_ refs. + +`--sort=<key>`:: + Sort on the field name _<key>_. Prefix `-` to sort in + descending order of the value. When unspecified, + `refname` is used. You may use the `--sort=<key>` option + multiple times, in which case the last key becomes the primary + key. + +`--format[=<format>]`:: + A string that interpolates `%(fieldname)` from a ref being shown and + the object it points at. In addition, the string literal `%%` + renders as `%` and `%xx` - where `xx` are hex digits - renders as + the character with hex code `xx`. For example, `%00` interpolates to + `\0` (_NUL_), `%09` to `\t` (_TAB_), and `%0a` to `\n` (_LF_). + +When unspecified, _<format>_ defaults to `%(objectname) SPC %(objecttype) +TAB %(refname)`. + +`--color[=<when>]`:: + Respect any colors specified in the `--format` option. The + _<when__ field must be one of `always`, `never`, or `auto` (if + `<when>` is absent, behave as if `always` was given). + +`--shell`:: +`--perl`:: +`--python`:: +`--tcl`:: + If given, strings that substitute `%(fieldname)` + placeholders are quoted as string literals suitable for + the specified host language. This is meant to produce + a scriptlet that can directly be "eval"ed. + +`--points-at=<object>`:: + Only list refs which points at the given object. + +`--merged[=<object>]`:: + Only list refs whose tips are reachable from the + specified commit (`HEAD` if not specified). + +`--no-merged[=<object>]`:: + Only list refs whose tips are not reachable from _<object>_(`HEAD` if not + specified). + +`--contains[=<object>]`:: + Only list refs which contain _<object>_(`HEAD` if not specified). + +`--no-contains[=<object>]`:: + Only list refs which don't contain _<object>_ (`HEAD` + if not specified). + +`--ignore-case`:: + Sorting and filtering refs are case insensitive. + +`--omit-empty`:: + Do not print a newline after formatted refs where the format expands + to the empty string. + +`--exclude=<excluded-pattern>`:: + If one or more `--exclude` options are given, only refs which do not + match any _<excluded-pattern>_ parameters are shown. Matching is done + using the same rules as _<pattern>_ above. + +`--include-root-refs`:: + List root refs (`HEAD` and pseudorefs) apart from regular refs. + +`--start-after=<marker>`:: + Allows paginating the output by skipping references up to and including the + specified marker. When paging, it should be noted that references may be + deleted, modified or added between invocations. Output will only yield those + references which follow the marker lexicographically. Output begins from the + first reference that would come after the marker alphabetically. Cannot be + used with `--sort=<key>` or `--stdin` options, or the _<pattern>_ argument(s) + to limit the refs. 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-add.adoc b/Documentation/git-add.adoc index eba0b419ce..b7a735824d 100644 --- a/Documentation/git-add.adoc +++ b/Documentation/git-add.adoc @@ -104,6 +104,8 @@ This effectively runs `add --interactive`, but bypasses the initial command menu and directly jumps to the `patch` subcommand. See ``Interactive mode'' for details. +include::diff-context-options.adoc[] + `-e`:: `--edit`:: Open the diff vs. the index in an editor and let the user diff --git a/Documentation/git-am.adoc b/Documentation/git-am.adoc index 221070de48..b23b4fba20 100644 --- a/Documentation/git-am.adoc +++ b/Documentation/git-am.adoc @@ -48,7 +48,8 @@ OPTIONS --keep-non-patch:: Pass `-b` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]). ---[no-]keep-cr:: +--keep-cr:: +--no-keep-cr:: With `--keep-cr`, call 'git mailsplit' (see linkgit:git-mailsplit[1]) with the same option, to prevent it from stripping CR at the end of lines. `am.keepcr` configuration variable can be used to specify the diff --git a/Documentation/git-apply.adoc b/Documentation/git-apply.adoc index 952518b8af..6c71ee69da 100644 --- a/Documentation/git-apply.adoc +++ b/Documentation/git-apply.adoc @@ -75,13 +75,14 @@ OPTIONS tree. If `--check` is in effect, merely check that it would apply cleanly to the index entry. +-N:: --intent-to-add:: When applying the patch only to the working tree, mark new files to be added to the index later (see `--intent-to-add` - option in linkgit:git-add[1]). This option is ignored unless - running in a Git repository and `--index` is not specified. - Note that `--index` could be implied by other options such - as `--cached` or `--3way`. + option in linkgit:git-add[1]). This option is ignored if + `--index` or `--cached` are used, and has no effect outside a Git + repository. Note that `--index` could be implied by other options + such as `--3way`. -3:: --3way:: diff --git a/Documentation/git-backfill.adoc b/Documentation/git-backfill.adoc index 95623051f7..b8394dcf22 100644 --- a/Documentation/git-backfill.adoc +++ b/Documentation/git-backfill.adoc @@ -57,7 +57,8 @@ OPTIONS blobs seen at a given path. The default minimum batch size is 50,000. -`--[no-]sparse`:: +`--sparse`:: +`--no-sparse`:: Only download objects if they appear at a path that matches the current sparse-checkout. If the sparse-checkout feature is enabled, then `--sparse` is assumed and can be disabled with `--no-sparse`. 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..c139f55a16 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] @@ -63,8 +62,10 @@ OPTIONS or to ask for a "blob" with `<object>` being a tag object that points at it. ---[no-]mailmap:: ---[no-]use-mailmap:: +--mailmap:: +--no-mailmap:: +--use-mailmap:: +--no-use-mailmap:: Use mailmap file to map author, committer and tagger names and email addresses to canonical real names and email addresses. See linkgit:git-shortlog[1]. @@ -81,6 +82,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 +203,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 +309,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 +344,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 +362,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..15a37a38e3 100644 --- a/Documentation/git-check-attr.adoc +++ b/Documentation/git-check-attr.adoc @@ -19,7 +19,8 @@ For every pathname, this command will list if each attribute is 'unspecified', OPTIONS ------- --a, --all:: +-a:: +--all:: List all attributes that are associated with the specified paths. If this option is used, then 'unspecified' attributes will not be included in the output. @@ -76,6 +77,7 @@ EXAMPLES -------- In the examples, the following '.gitattributes' file is used: + --------------- *.java diff=java -crlf myAttr NoMyAttr.java !myAttr @@ -83,12 +85,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 +101,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 +109,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 +117,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-check-ignore.adoc b/Documentation/git-check-ignore.adoc index 3e3b4e3446..a6c6c1b6e5 100644 --- a/Documentation/git-check-ignore.adoc +++ b/Documentation/git-check-ignore.adoc @@ -25,11 +25,13 @@ subject to exclude rules; but see `--no-index'. OPTIONS ------- --q, --quiet:: +-q:: +--quiet:: Don't output anything, just set exit status. This is only valid with a single pathname. --v, --verbose:: +-v:: +--verbose:: Instead of printing the paths that are excluded, for each path that matches an exclude pattern, print the exclude pattern together with the path. (Matching an exclude pattern usually @@ -49,7 +51,8 @@ linkgit:gitignore[5]. below). If `--stdin` is also given, input paths are separated with a NUL character instead of a linefeed character. --n, --non-matching:: +-n:: +--non-matching:: Show given paths which don't match any pattern. This only makes sense when `--verbose` is enabled, otherwise it would not be possible to distinguish between paths which match a diff --git a/Documentation/git-check-ref-format.adoc b/Documentation/git-check-ref-format.adoc index 2aacfd1808..0c3abf9146 100644 --- a/Documentation/git-check-ref-format.adoc +++ b/Documentation/git-check-ref-format.adoc @@ -98,7 +98,8 @@ a branch. OPTIONS ------- ---[no-]allow-onelevel:: +--allow-onelevel:: +--no-allow-onelevel:: Controls whether one-level refnames are accepted (i.e., refnames that do not contain multiple `/`-separated components). The default is `--no-allow-onelevel`. diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc index a66c53a5cd..ff1cb29bc1 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,42 @@ 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:: +include::diff-context-options.adoc[] + +`--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,28 +313,28 @@ 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>:: +`<branch>`:: Branch to checkout; if it refers to a branch (i.e., a name that, when prepended with "refs/heads/", is a valid ref), then that branch is checked out. Otherwise, if it refers to a valid @@ -343,33 +345,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 +393,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 +512,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-clone.adoc b/Documentation/git-clone.adoc index 510b91b5c0..57cdfb7620 100644 --- a/Documentation/git-clone.adoc +++ b/Documentation/git-clone.adoc @@ -16,7 +16,7 @@ git clone [--template=<template-directory>] [--depth <depth>] [--[no-]single-branch] [--[no-]tags] [--recurse-submodules[=<pathspec>]] [--[no-]shallow-submodules] [--[no-]remote-submodules] [--jobs <n>] [--sparse] [--[no-]reject-shallow] - [--filter=<filter-spec>] [--also-filter-submodules]] [--] <repository> + [--filter=<filter-spec> [--also-filter-submodules]] [--] <repository> [<directory>] DESCRIPTION @@ -272,7 +272,8 @@ corresponding `--mirror` and `--no-tags` options instead. reachable from a specified remote branch or tag. This option can be specified multiple times. -`--[no-]single-branch`:: +`--single-branch`:: +`--no-single-branch`:: Clone only the history leading to the tip of a single branch, either specified by the `--branch` option or the primary branch remote's `HEAD` points at. @@ -282,15 +283,16 @@ corresponding `--mirror` and `--no-tags` options instead. branch when `--single-branch` clone was made, no remote-tracking branch is created. -`--[no-]tags`:: +`--tags`:: +`--no-tags`:: Control whether or not tags will be cloned. When `--no-tags` is given, the option will be become permanent by setting the `remote.<remote>.tagOpt=--no-tags` configuration. This ensures that future `git pull` and `git fetch` won't follow any tags. Subsequent explicit tag fetches will still work (see linkgit:git-fetch[1]). - - By default, tags are cloned and passing `--tags` is thus typically a - no-op, unless it cancels out a previous `--no-tags`. ++ +By default, tags are cloned and passing `--tags` is thus typically a +no-op, unless it cancels out a previous `--no-tags`. + Can be used in conjunction with `--single-branch` to clone and maintain a branch with no references other than a single cloned @@ -313,10 +315,12 @@ the clone is finished. This option is ignored if the cloned repository does not have a worktree/checkout (i.e. if any of `--no-checkout`/`-n`, `--bare`, or `--mirror` is given) -`--[no-]shallow-submodules`:: +`--shallow-submodules`:: +`--no-shallow-submodules`:: All submodules which are cloned will be shallow with a depth of 1. -`--[no-]remote-submodules`:: +`--remote-submodules`:: +`--no-remote-submodules`:: All submodules which are cloned will use the status of the submodule's remote-tracking branch to update the submodule, rather than the superproject's recorded SHA-1. Equivalent to passing `--remote` to 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-commit-graph.adoc b/Documentation/git-commit-graph.adoc index 50b5016804..e9558173c0 100644 --- a/Documentation/git-commit-graph.adoc +++ b/Documentation/git-commit-graph.adoc @@ -34,7 +34,8 @@ OPTIONS object directory, `git commit-graph ...` will exit with non-zero status. ---[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. diff --git a/Documentation/git-commit.adoc b/Documentation/git-commit.adoc index dc219025f1..54c207ad45 100644 --- a/Documentation/git-commit.adoc +++ b/Documentation/git-commit.adoc @@ -76,6 +76,8 @@ OPTIONS which changes to commit. See linkgit:git-add[1] for details. +include::diff-context-options.adoc[] + `-C <commit>`:: `--reuse-message=<commit>`:: Take an existing _<commit>_ object, and reuse the log message @@ -212,7 +214,8 @@ include::signoff-option.adoc[] each trailer would appear, and other details. `-n`:: -`--[no-]verify`:: +`--verify`:: +`--no-verify`:: Bypass the `pre-commit` and `commit-msg` hooks. See also linkgit:githooks[5]. @@ -279,6 +282,7 @@ variable (see linkgit:git-config[1]). + -- It is a rough equivalent for: + ------ $ git reset --soft HEAD^ $ ... do something else to come up with the right tree ... diff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc index 936e0c5130..36d2845152 100644 --- a/Documentation/git-config.adoc +++ b/Documentation/git-config.adoc @@ -10,9 +10,9 @@ SYNOPSIS -------- [verse] 'git config list' [<file-option>] [<display-option>] [--includes] -'git config get' [<file-option>] [<display-option>] [--includes] [--all] [--regexp] [--value=<value>] [--fixed-value] [--default=<default>] <name> -'git config set' [<file-option>] [--type=<type>] [--all] [--value=<value>] [--fixed-value] <name> <value> -'git config unset' [<file-option>] [--all] [--value=<value>] [--fixed-value] <name> +'git config get' [<file-option>] [<display-option>] [--includes] [--all] [--regexp] [--value=<pattern>] [--fixed-value] [--default=<default>] [--url=<url>] <name> +'git config set' [<file-option>] [--type=<type>] [--all] [--value=<pattern>] [--fixed-value] <name> <value> +'git config unset' [<file-option>] [--all] [--value=<pattern>] [--fixed-value] <name> 'git config rename-section' [<file-option>] <old-name> <new-name> 'git config remove-section' [<file-option>] <name> 'git config edit' [<file-option>] @@ -26,7 +26,7 @@ escaped. Multiple lines can be added to an option by using the `--append` option. If you want to update or unset an option which can occur on multiple -lines, a `value-pattern` (which is an extended regular expression, +lines, `--value=<pattern>` (which is an extended regular expression, unless the `--fixed-value` option is given) needs to be given. Only the existing values that match the pattern are updated or unset. If you want to handle the lines that do *not* match the pattern, just @@ -109,7 +109,7 @@ OPTIONS --replace-all:: Default behavior is to replace at most one line. This replaces - all lines matching the key (and optionally the `value-pattern`). + all lines matching the key (and optionally `--value=<pattern>`). --append:: Adds a new line to the option without altering any existing @@ -200,11 +200,19 @@ See also <<FILES>>. section in linkgit:gitrevisions[7] for a more complete list of ways to spell blob names. +`--value=<pattern>`:: +`--no-value`:: + With `get`, `set`, and `unset`, match only against + _<pattern>_. The pattern is an extended regular expression unless + `--fixed-value` is given. ++ +Use `--no-value` to unset _<pattern>_. + --fixed-value:: - When used with the `value-pattern` argument, treat `value-pattern` as + When used with `--value=<pattern>`, treat _<pattern>_ as an exact string instead of a regular expression. This will restrict the name/value pairs that are matched to only those where the value - is exactly equal to the `value-pattern`. + is exactly equal to _<pattern>_. --type <type>:: 'git config' will ensure that any input or output is valid under the given @@ -259,6 +267,12 @@ Valid `<type>`'s include: Output only the names of config variables for `list` or `get`. +`--show-names`:: +`--no-show-names`:: + With `get`, show config keys in addition to their values. The + default is `--no-show-names` unless `--url` is given and there + are no subsections in _<name>_. + --show-origin:: Augment the output of all queried config options with the origin type (file, standard input, blob, command line) and @@ -281,7 +295,8 @@ Valid `<type>`'s include: When the color setting for `name` is undefined, the command uses `color.ui` as fallback. ---[no-]includes:: +--includes:: +--no-includes:: Respect `include.*` directives in config files when looking up values. Defaults to `off` when a specific file is given (e.g., using `--file`, `--global`, etc) and `on` when searching all diff --git a/Documentation/git-count-objects.adoc b/Documentation/git-count-objects.adoc index 97f9f12610..eeee6b9f7f 100644 --- a/Documentation/git-count-objects.adoc +++ b/Documentation/git-count-objects.adoc @@ -28,6 +28,8 @@ size: disk space consumed by loose objects, in KiB (unless -H is specified) + in-pack: the number of in-pack objects + +packs: the number of pack files ++ size-pack: disk space consumed by the packs, in KiB (unless -H is specified) + prune-packable: the number of loose objects that are also present in 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-difftool.adoc b/Documentation/git-difftool.adoc index d596205eaf..064bc68347 100644 --- a/Documentation/git-difftool.adoc +++ b/Documentation/git-difftool.adoc @@ -77,7 +77,8 @@ with custom merge tool commands and has the same value as `$MERGED`. --tool-help:: Print a list of diff tools that may be used with `--tool`. ---[no-]symlinks:: +--symlinks:: +--no-symlinks:: 'git difftool''s default behavior is to create symlinks to the working tree when run in `--dir-diff` mode and the right-hand side of the comparison yields the same content as the file in @@ -94,7 +95,8 @@ instead. `--no-symlinks` is the default on Windows. Additionally, `$BASE` is set in the environment. -g:: ---[no-]gui:: +--gui:: +--no-gui:: When 'git-difftool' is invoked with the `-g` or `--gui` option the default diff tool will be read from the configured `diff.guitool` variable instead of `diff.tool`. This may be @@ -104,7 +106,8 @@ instead. `--no-symlinks` is the default on Windows. fallback in the order of `merge.guitool`, `diff.tool`, `merge.tool` until a tool is found. ---[no-]trust-exit-code:: +--trust-exit-code:: +--no-trust-exit-code:: Errors reported by the diff tool are ignored by default. Use `--trust-exit-code` to make 'git-difftool' exit when an invoked diff tool returns a non-zero exit code. diff --git a/Documentation/git-fast-export.adoc b/Documentation/git-fast-export.adoc index 752e4b9b01..297b57bb2e 100644 --- a/Documentation/git-fast-export.adoc +++ b/Documentation/git-fast-export.adoc @@ -27,17 +27,48 @@ 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. ++ +When exported, a signature starts with: ++ +gpgsig <git-hash-algo> <signature-format> ++ +where <git-hash-algo> is the Git object hash so either "sha1" or +"sha256", and <signature-format> is the signature type, so "openpgp", +"x509", "ssh" or "unknown". ++ +For example, an OpenPGP signature on a SHA-1 commit starts with +`gpgsig sha1 openpgp`, while an SSH signature on a SHA-256 commit +starts with `gpgsig sha256 ssh`. ++ +While all the signatures of a commit are exported, an importer may +choose to accept only some of them. For example +linkgit:git-fast-import[1] currently stores at most one signature per +Git hash algorithm in each commit. ++ +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..3144ffcdb6 100644 --- a/Documentation/git-fast-import.adoc +++ b/Documentation/git-fast-import.adoc @@ -111,7 +111,8 @@ Locations of Marks Files Like --import-marks but instead of erroring out, silently skips the file if it does not exist. ---[no-]relative-marks:: +--relative-marks:: +--no-relative-marks:: After specifying --relative-marks the paths specified with --import-marks= and --export-marks= are relative to an internal directory in the current repository. @@ -182,7 +183,7 @@ amount of memory usage and processing time. Assuming the frontend is able to keep up with fast-import and feed it a constant stream of data, import times for projects holding 10+ years of history and containing 100,000+ individual commits are generally completed in just 1-2 -hours on quite modest (~$2,000 USD) hardware. +hours on quite modest hardware (~$2,000 USD in 2007). Most bottlenecks appear to be in foreign source data access (the source just cannot extract revisions fast enough) or disk IO (fast-import @@ -431,13 +432,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 <algo> SP <format> LF data)? + ('encoding' SP <encoding> LF)? data ('from' SP <commit-ish> LF)? ('merge' SP <commit-ish> LF)* @@ -505,6 +515,44 @@ 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 +or other cryptographic signature that signs the commit data. + +.... + 'gpgsig' SP <git-hash-algo> SP <signature-format> LF data +.... + +The `gpgsig` command takes two arguments: + +* `<git-hash-algo>` specifies which Git object format this signature + applies to, either `sha1` or `sha256`. This allows to know which + representation of the commit was signed (the SHA-1 or the SHA-256 + version) which helps with both signature verification and + interoperability between repos with different hash functions. + +* `<signature-format>` specifies the type of signature, such as + `openpgp`, `x509`, `ssh`, or `unknown`. This is a convenience for + tools that process the stream, so they don't have to parse the ASCII + armor to identify the signature type. + +A commit may have at most one signature for the SHA-1 object format +(stored in the "gpgsig" header) and one for the SHA-256 object format +(stored in the "gpgsig-sha256" header). + +See below for a detailed description of the `data` command which +contains the raw signature data. + +Signatures are not yet checked in the current implementation +though. (Already setting the `extensions.compatObjectFormat` +configuration option might help with verifying both SHA-1 and SHA-256 +object format signatures when it will be implemented.) + +NOTE: This is highly experimental and the format of the `gpgsig` +command may change in the future without compatibility guarantees. + `encoding` ^^^^^^^^^^ The optional `encoding` command indicates the encoding of the commit @@ -558,9 +606,11 @@ Marks must be declared (via `mark`) before they can be used. The special case of restarting an incremental import from the current branch value should be written as: + ---- from refs/heads/branch^0 ---- + The `^0` suffix is necessary as fast-import does not permit a branch to start from itself, and the branch is created in memory before the `from` command is even read from the input. Adding `^0` will force diff --git a/Documentation/git-fmt-merge-msg.adoc b/Documentation/git-fmt-merge-msg.adoc index 0f3328956d..6d91620be9 100644 --- a/Documentation/git-fmt-merge-msg.adoc +++ b/Documentation/git-fmt-merge-msg.adoc @@ -35,7 +35,8 @@ OPTIONS Do not list one-line descriptions from the actual commits being merged. ---[no-]summary:: +--summary:: +--no-summary:: Synonyms to --log and --no-log; these are deprecated and will be removed in the future. diff --git a/Documentation/git-for-each-ref.adoc b/Documentation/git-for-each-ref.adoc index ffb97e62c2..c02cb7f886 100644 --- a/Documentation/git-for-each-ref.adoc +++ b/Documentation/git-for-each-ref.adoc @@ -7,106 +7,28 @@ git-for-each-ref - Output information on each ref SYNOPSIS -------- -[verse] -'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl] +[synopsis] +git for-each-ref [--count=<count>] [--shell|--perl|--python|--tcl] [(--sort=<key>)...] [--format=<format>] - [--include-root-refs] [ --stdin | <pattern>... ] - [--points-at=<object>] + [--include-root-refs] [--points-at=<object>] [--merged[=<object>]] [--no-merged[=<object>]] [--contains[=<object>]] [--no-contains[=<object>]] - [--exclude=<pattern> ...] + [(--exclude=<pattern>)...] [--start-after=<marker>] + [ --stdin | (<pattern>...)] DESCRIPTION ----------- -Iterate over all refs that match `<pattern>` and show them -according to the given `<format>`, after sorting them according -to the given set of `<key>`. If `<count>` is given, stop after -showing that many refs. The interpolated values in `<format>` +Iterate over all refs that match _<pattern>_ and show them +according to the given _<format>_, after sorting them according +to the given set of _<key>_. If _<count>_ is given, stop after +showing that many refs. The interpolated values in _<format>_ can optionally be quoted as string literals in the specified host language allowing their direct evaluation in that language. OPTIONS ------- -<pattern>...:: - If one or more patterns are given, only refs are shown that - match against at least one pattern, either using fnmatch(3) or - literally, in the latter case matching completely or from the - beginning up to a slash. - ---stdin:: - If `--stdin` is supplied, then the list of patterns is read from - standard input instead of from the argument list. - ---count=<count>:: - By default the command shows all refs that match - `<pattern>`. This option makes it stop after showing - that many refs. - ---sort=<key>:: - A field name to sort on. Prefix `-` to sort in - descending order of the value. When unspecified, - `refname` is used. You may use the --sort=<key> option - multiple times, in which case the last key becomes the primary - key. - ---format=<format>:: - A string that interpolates `%(fieldname)` from a ref being shown and - the object it points at. In addition, the string literal `%%` - renders as `%` and `%xx` - where `xx` are hex digits - renders as - the character with hex code `xx`. For example, `%00` interpolates to - `\0` (NUL), `%09` to `\t` (TAB), and `%0a` to `\n` (LF). -+ -When unspecified, `<format>` defaults to `%(objectname) SPC %(objecttype) -TAB %(refname)`. - ---color[=<when>]:: - Respect any colors specified in the `--format` option. The - `<when>` field must be one of `always`, `never`, or `auto` (if - `<when>` is absent, behave as if `always` was given). - ---shell:: ---perl:: ---python:: ---tcl:: - If given, strings that substitute `%(fieldname)` - placeholders are quoted as string literals suitable for - the specified host language. This is meant to produce - a scriptlet that can directly be `eval`ed. - ---points-at=<object>:: - Only list refs which points at the given object. - ---merged[=<object>]:: - Only list refs whose tips are reachable from the - specified commit (HEAD if not specified). - ---no-merged[=<object>]:: - Only list refs whose tips are not reachable from the - specified commit (HEAD if not specified). - ---contains[=<object>]:: - Only list refs which contain the specified commit (HEAD if not - specified). - ---no-contains[=<object>]:: - Only list refs which don't contain the specified commit (HEAD - if not specified). - ---ignore-case:: - Sorting and filtering refs are case insensitive. - ---omit-empty:: - Do not print a newline after formatted refs where the format expands - to the empty string. - ---exclude=<pattern>:: - If one or more patterns are given, only refs which do not match - any excluded pattern(s) are shown. Matching is done using the - same rules as `<pattern>` above. - ---include-root-refs:: - List root refs (HEAD and pseudorefs) apart from regular refs. +include::for-each-ref-options.adoc[] FIELD NAMES ----------- @@ -117,44 +39,44 @@ keys. For all objects, the following names can be used: -refname:: - The name of the ref (the part after $GIT_DIR/). +`refname`:: + The name of the ref (the part after `$GIT_DIR/`). For a non-ambiguous short name of the ref append `:short`. - The option core.warnAmbiguousRefs is used to select the strict - abbreviation mode. If `lstrip=<N>` (`rstrip=<N>`) is appended, strips `<N>` + The option `core.warnAmbiguousRefs` is used to select the strict + abbreviation mode. If `lstrip=<n>` (`rstrip=<n>`) is appended, strip _<n>_ slash-separated path components from the front (back) of the refname (e.g. `%(refname:lstrip=2)` turns `refs/tags/foo` into `foo` and `%(refname:rstrip=2)` turns `refs/tags/foo` into `refs`). - If `<N>` is a negative number, strip as many path components as - necessary from the specified end to leave `-<N>` path components + If _<n>_ is a negative number, strip as many path components as + necessary from the specified end to leave `-<n>` path components (e.g. `%(refname:lstrip=-2)` turns `refs/tags/foo` into `tags/foo` and `%(refname:rstrip=-1)` turns `refs/tags/foo` into `refs`). When the ref does not have enough components, the result becomes an empty string if - stripping with positive <N>, or it becomes the full refname if - stripping with negative <N>. Neither is an error. + stripping with positive _<n>_, or it becomes the full refname if + stripping with negative _<N>_. Neither is an error. + `strip` can be used as a synonym to `lstrip`. -objecttype:: +`objecttype`:: The type of the object (`blob`, `tree`, `commit`, `tag`). -objectsize:: +`objectsize`:: The size of the object (the same as 'git cat-file -s' reports). Append `:disk` to get the size, in bytes, that the object takes up on - disk. See the note about on-disk sizes in the `CAVEATS` section below. -objectname:: + disk. See the note about on-disk sizes in the 'CAVEATS' section below. +`objectname`:: The object name (aka SHA-1). For a non-ambiguous abbreviation of the object name append `:short`. For an abbreviation of the object name with desired length append - `:short=<length>`, where the minimum length is MINIMUM_ABBREV. The + `:short=<length>`, where the minimum length is `MINIMUM_ABBREV`. The length may be exceeded to ensure unique object names. -deltabase:: +`deltabase`:: This expands to the object name of the delta base for the given object, if it is stored as a delta. Otherwise it expands to the null object name (all zeroes). -upstream:: +`upstream`:: The name of a local ref which can be considered ``upstream'' from the displayed ref. Respects `:short`, `:lstrip` and `:rstrip` in the same way as `refname` above. Additionally @@ -176,100 +98,103 @@ Has no effect if the ref does not have tracking information associated with it. All the options apart from `nobracket` are mutually exclusive, but if used together the last option is selected. -push:: +`push`:: The name of a local ref which represents the `@{push}` location for the displayed ref. Respects `:short`, `:lstrip`, `:rstrip`, `:track`, `:trackshort`, `:remotename`, and `:remoteref` options as `upstream` does. Produces an empty string if no `@{push}` ref is configured. -HEAD:: - '*' if HEAD matches current ref (the checked out branch), ' ' +`HEAD`:: + `*` if `HEAD` matches current ref (the checked out branch), ' ' otherwise. -color:: +`color`:: Change output color. Followed by `:<colorname>`, where color names are described under Values in the "CONFIGURATION FILE" section of linkgit:git-config[1]. For example, `%(color:bold red)`. -align:: +`align`:: Left-, middle-, or right-align the content between - %(align:...) and %(end). The "align:" is followed by + `%(align:...)` and `%(end)`. The "`align:`" is followed by `width=<width>` and `position=<position>` in any order - separated by a comma, where the `<position>` is either left, - right or middle, default being left and `<width>` is the total + separated by a comma, where the _<position>_ is either `left`, + `right` or `middle`, default being `left` and _<width>_ is the total length of the content with alignment. For brevity, the "width=" and/or "position=" prefixes may be omitted, and bare - <width> and <position> used instead. For instance, + _<width>_ and _<position>_ used instead. For instance, `%(align:<width>,<position>)`. If the contents length is more than the width then no alignment is performed. If used with - `--quote` everything in between %(align:...) and %(end) is + `--quote` everything in between `%(align:...)` and `%(end)` is quoted, but if nested then only the topmost level performs quoting. -if:: - Used as %(if)...%(then)...%(end) or - %(if)...%(then)...%(else)...%(end). If there is an atom with - value or string literal after the %(if) then everything after - the %(then) is printed, else if the %(else) atom is used, then +`if`:: + Used as `%(if)...%(then)...%(end)` or + `%(if)...%(then)...%(else)...%(end)`. If there is an atom with + value or string literal after the `%(if)` then everything after + the `%(then)` is printed, else if the `%(else)` atom is used, then everything after %(else) is printed. We ignore space when - evaluating the string before %(then), this is useful when we - use the %(HEAD) atom which prints either "*" or " " and we - want to apply the 'if' condition only on the 'HEAD' ref. - Append ":equals=<string>" or ":notequals=<string>" to compare - the value between the %(if:...) and %(then) atoms with the + evaluating the string before `%(then)`, this is useful when we + use the `%(HEAD)` atom which prints either "`*`" or " " and we + want to apply the 'if' condition only on the `HEAD` ref. + Append "`:equals=<string>`" or "`:notequals=<string>`" to compare + the value between the `%(if:...)` and `%(then)` atoms with the given string. -symref:: +`symref`:: The ref which the given symbolic ref refers to. If not a symbolic ref, nothing is printed. Respects the `:short`, `:lstrip` and `:rstrip` options in the same way as `refname` above. -signature:: +`signature`:: The GPG signature of a commit. -signature:grade:: - Show "G" for a good (valid) signature, "B" for a bad - signature, "U" for a good signature with unknown validity, "X" - for a good signature that has expired, "Y" for a good - signature made by an expired key, "R" for a good signature - made by a revoked key, "E" if the signature cannot be - checked (e.g. missing key) and "N" for no signature. - -signature:signer:: +`signature:grade`:: + Show +`G`;; for a good (valid) signature +`B`;; for a bad signature +`U`;; for a good signature with unknown validity +`X`;; for a good signature that has expired +`Y`;; for a good signature made by an expired key +`R`;; for a good signature made by a revoked key +`E`;; if the signature cannot be checked (e.g. missing key) +`N`;; for no signature. + +`signature:signer`:: The signer of the GPG signature of a commit. -signature:key:: +`signature:key`:: The key of the GPG signature of a commit. -signature:fingerprint:: +`signature:fingerprint`:: The fingerprint of the GPG signature of a commit. -signature:primarykeyfingerprint:: +`signature:primarykeyfingerprint`:: The primary key fingerprint of the GPG signature of a commit. -signature:trustlevel:: +`signature:trustlevel`:: The trust level of the GPG signature of a commit. Possible outputs are `ultimate`, `fully`, `marginal`, `never` and `undefined`. -worktreepath:: +`worktreepath`:: The absolute path to the worktree in which the ref is checked out, if it is checked out in any linked worktree. Empty string otherwise. -ahead-behind:<committish>:: +`ahead-behind:<commit-ish>`:: Two integers, separated by a space, demonstrating the number of commits ahead and behind, respectively, when comparing the output - ref to the `<committish>` specified in the format. + ref to the _<committish>_ specified in the format. -is-base:<committish>:: - In at most one row, `(<committish>)` will appear to indicate the ref +`is-base:<commit-ish>`:: + In at most one row, `(<commit-ish>)` will appear to indicate the ref that is most likely the ref used as a starting point for the branch - that produced `<committish>`. This choice is made using a heuristic: + that produced _<commit-ish>_. This choice is made using a heuristic: choose the ref that minimizes the number of commits in the - first-parent history of `<committish>` and not in the first-parent + first-parent history of _<commit-ish>_ and not in the first-parent history of the ref. + For example, consider the following figure of first-parent histories of @@ -303,29 +228,29 @@ common first-parent ancestor of `B` and `C` and ties are broken by the earliest ref in the sorted order. + Note that this token will not appear if the first-parent history of -`<committish>` does not intersect the first-parent histories of the +_<commit-ish>_ does not intersect the first-parent histories of the filtered refs. -describe[:options]:: +`describe[:<option>,...]`:: A human-readable name, like linkgit:git-describe[1]; empty string for undescribable commits. The `describe` string may be followed by a colon and one or more comma-separated options. + -- -tags=<bool-value>;; +`tags=<bool-value>`;; Instead of only considering annotated tags, consider lightweight tags as well; see the corresponding option in linkgit:git-describe[1] for details. -abbrev=<number>;; - Use at least <number> hexadecimal digits; see the corresponding +`abbrev=<number>`;; + Use at least _<number>_ hexadecimal digits; see the corresponding option in linkgit:git-describe[1] for details. -match=<pattern>;; - Only consider tags matching the given `glob(7)` pattern, - excluding the "refs/tags/" prefix; see the corresponding option +`match=<pattern>`;; + Only consider tags matching the `glob`(7) _<pattern>_, + excluding the `refs/tags/` prefix; see the corresponding option in linkgit:git-describe[1] for details. -exclude=<pattern>;; - Do not consider tags matching the given `glob(7)` pattern, - excluding the "refs/tags/" prefix; see the corresponding option +`exclude=<pattern>`;; + Do not consider tags matching the `glob`(7) _<pattern>_, + excluding the `refs/tags/` prefix; see the corresponding option in linkgit:git-describe[1] for details. -- @@ -357,7 +282,7 @@ variable (see linkgit:gitmailmap[5]). The raw data in an object is `raw`. -raw:size:: +`raw:size`:: The raw data size of the object. Note that `--format=%(raw)` can not be used with `--python`, `--shell`, `--tcl`, @@ -367,10 +292,10 @@ variable type. The message in a commit or a tag object is `contents`, from which `contents:<part>` can be used to extract various parts out of: -contents:size:: +`contents:size`:: The size in bytes of the commit or tag message. -contents:subject:: +`contents:subject`:: The first paragraph of the message, which typically is a single line, is taken as the "subject" of the commit or the tag message. @@ -378,19 +303,19 @@ contents:subject:: obtain same results. `:sanitize` can be appended to `subject` for subject line suitable for filename. -contents:body:: +`contents:body`:: The remainder of the commit or the tag message that follows the "subject". -contents:signature:: +`contents:signature`:: The optional GPG signature of the tag. -contents:lines=N:: - The first `N` lines of the message. +`contents:lines=<n>`:: + The first _<n>_ lines of the message. Additionally, the trailers as interpreted by linkgit:git-interpret-trailers[1] -are obtained as `trailers[:options]` (or by using the historical alias -`contents:trailers[:options]`). For valid [:option] values see `trailers` +are obtained as `trailers[:<option>,...]` (or by using the historical alias +`contents:trailers[:<option>,...]`). For valid _<option>_ values see `trailers` section of linkgit:git-log[1]. For sorting purposes, fields with numeric values sort in numeric order @@ -410,8 +335,8 @@ option to linkgit:git-rev-list[1] takes). If this formatting is provided in a `--sort` key, references will be sorted according to the byte-value of the formatted string rather than the numeric value of the underlying timestamp. -Some atoms like %(align) and %(if) always require a matching %(end). -We call them "opening atoms" and sometimes denote them as %($open). +Some atoms like `%(align)` and `%(if)` always require a matching `%(end)`. +We call them "opening atoms" and sometimes denote them as `%($open)`. When a scripting language specific quoting is in effect, everything between a top-level opening atom and its matching %(end) is evaluated @@ -429,7 +354,7 @@ An example directly producing formatted text. Show the most recent #!/bin/sh git for-each-ref --count=3 --sort='-*authordate' \ ---format='From: %(*authorname) %(*authoremail) +`--format='From: %(*authorname) %(*authoremail) Subject: %(*subject) Date: %(*authordate) Ref: %(*refname) @@ -440,7 +365,8 @@ 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: +demonstrating the use of `--shell`. List the prefixes of all heads: + ------------ #!/bin/sh @@ -455,6 +381,7 @@ done A bit more elaborate report on tags, demonstrating that the format may be an entire script: + ------------ #!/bin/sh @@ -506,7 +433,7 @@ eval "$eval" ------------ -An example to show the usage of %(if)...%(then)...%(else)...%(end). +An example to show the usage of `%(if)...%(then)...%(else)...%(end)`. This prefixes the current branch with a star. ------------ @@ -514,7 +441,7 @@ git for-each-ref --format="%(if)%(HEAD)%(then)* %(else) %(end)%(refname:short)" ------------ -An example to show the usage of %(if)...%(then)...%(end). +An example to show the usage of `%(if)...%(then)...%(end)`. This prints the authorname, if present. ------------ diff --git a/Documentation/git-format-patch.adoc b/Documentation/git-format-patch.adoc index a8b53db9a6..9a7807ca71 100644 --- a/Documentation/git-format-patch.adoc +++ b/Documentation/git-format-patch.adoc @@ -295,7 +295,8 @@ header). Note also that `git send-email` already handles this transformation for you, and this option should not be used if you are feeding the result to `git send-email`. ---[no-]force-in-body-from:: +--force-in-body-from:: +--no-force-in-body-from:: With the e-mail sender specified via the `--from` option, by default, an in-body "From:" to identify the real author of the commit is added at the top of the commit log message if @@ -314,7 +315,8 @@ feeding the result to `git send-email`. `Cc:`, and custom) headers added so far from config or command line. ---[no-]cover-letter:: +--cover-letter:: +--no-cover-letter:: In addition to the patches, generate a cover letter file containing the branch description, shortlog and the overall diffstat. You can fill in a description in the file before sending it out. @@ -379,7 +381,8 @@ configuration options in linkgit:git-notes[1] to use this workflow). The default is `--no-notes`, unless the `format.notes` configuration is set. ---[no-]signature=<signature>:: +--signature=<signature>:: +--no-signature:: Add a signature to each message produced. Per RFC 3676 the signature is separated from the body by a line with '-- ' on it. If the signature option is omitted the signature defaults to the Git version @@ -411,7 +414,8 @@ you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`. Output an all-zero hash in each patch's From header instead of the hash of the commit. ---[no-]base[=<commit>]:: +--no-base:: +--base[=<commit>]:: Record the base tree information to identify the state the patch series applies to. See the BASE TREE INFORMATION section below for details. If <commit> is "auto", a base commit is @@ -587,13 +591,19 @@ an external editor to keep Thunderbird from mangling the patches. Approach #1 (add-on) ^^^^^^^^^^^^^^^^^^^^ -Install the Toggle Word Wrap add-on that is available from -https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/ -It adds a menu entry "Enable Word Wrap" in the composer's "Options" menu +Install the Toggle Line Wrap add-on that is available from +https://addons.thunderbird.net/thunderbird/addon/toggle-line-wrap +It adds a button "Line Wrap" to the composer's toolbar that you can tick off. Now you can compose the message as you otherwise do (cut + paste, 'git format-patch' | 'git imap-send', etc), but you have to insert line breaks manually in any text that you type. +As a bonus feature, the add-on can detect patch text in the composer +and warns when line wrapping has not yet been turned off. + +The add-on requires a few tweaks of the advanced configuration +(about:config). These are listed on the download page. + Approach #2 (configuration) ^^^^^^^^^^^^^^^^^^^^^^^^^^^ Three steps: diff --git a/Documentation/git-fsck.adoc b/Documentation/git-fsck.adoc index 8f32800a83..1751f692d4 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 ----------- @@ -31,7 +31,8 @@ index file, all SHA-1 references in the `refs` namespace, and all reflogs Print out objects that exist but that aren't reachable from any of the reference nodes. ---[no-]dangling:: +--dangling:: +--no-dangling:: Print objects that exist but that are never 'directly' used (default). `--no-dangling` can be used to omit this information from the output. @@ -97,13 +98,20 @@ care about this output and want to speed it up further. compatible with linkgit:git-rev-parse[1], e.g. `HEAD@{1234567890}~25^2:src/`. ---[no-]progress:: +--progress:: +--no-progress:: Progress status is reported on the standard error stream by default when it is attached to a terminal, unless --no-progress or --verbose is specified. --progress forces progress status even if the standard error stream is not directed to a terminal. +--references:: +--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-gc.adoc b/Documentation/git-gc.adoc index 526ce01463..6fed646dd8 100644 --- a/Documentation/git-gc.adoc +++ b/Documentation/git-gc.adoc @@ -53,11 +53,13 @@ configuration options such as `gc.auto` and `gc.autoPackLimit`, all other housekeeping tasks (e.g. rerere, working trees, reflog...) will be performed as well. ---[no-]detach:: +--detach:: +--no-detach:: Run in the background if the system supports it. This option overrides the `gc.autoDetach` config. ---[no-]cruft:: +--cruft:: +--no-cruft:: When expiring unreachable objects, pack them separately into a cruft pack instead of storing them as loose objects. `--cruft` is on by default. diff --git a/Documentation/git-http-fetch.adoc b/Documentation/git-http-fetch.adoc index 4ec7c68d3b..2200f073c4 100644 --- a/Documentation/git-http-fetch.adoc +++ b/Documentation/git-http-fetch.adoc @@ -25,8 +25,11 @@ commit-id:: Either the hash or the filename under [URL]/refs/ to pull. --a, -c, -t:: +-a:: +-c:: +-t:: These options are ignored for historical reasons. + -v:: Report what is downloaded. diff --git a/Documentation/git-imap-send.adoc b/Documentation/git-imap-send.adoc index 26ccf4e433..278e5ccd36 100644 --- a/Documentation/git-imap-send.adoc +++ b/Documentation/git-imap-send.adoc @@ -9,21 +9,24 @@ git-imap-send - Send a collection of patches from stdin to an IMAP folder SYNOPSIS -------- [verse] -'git imap-send' [-v] [-q] [--[no-]curl] +'git imap-send' [-v] [-q] [--[no-]curl] [(--folder|-f) <folder>] +'git imap-send' --list DESCRIPTION ----------- -This command uploads a mailbox generated with 'git format-patch' +This command uploads a mailbox generated with `git format-patch` into an IMAP drafts folder. This allows patches to be sent as other email is when using mail clients that cannot read mailbox files directly. The command also works with any general mailbox -in which emails have the fields "From", "Date", and "Subject" in +in which emails have the fields `From`, `Date`, and `Subject` in that order. Typical usage is something like: -git format-patch --signoff --stdout --attach origin | git imap-send +------ +$ git format-patch --signoff --stdout --attach origin | git imap-send +------ OPTIONS @@ -37,6 +40,11 @@ OPTIONS --quiet:: Be quiet. +-f <folder>:: +--folder=<folder>:: + Specify the folder in which the emails have to saved. + For example: `--folder=[Gmail]/Drafts` or `-f INBOX/Drafts`. + --curl:: Use libcurl to communicate with the IMAP server, unless tunneling into it. Ignored if Git was built without the USE_CURL_FOR_IMAP_SEND @@ -47,6 +55,8 @@ OPTIONS using libcurl. Ignored if Git was built with the NO_OPENSSL option set. +--list:: + Run the IMAP LIST command to output a list of all the folders present. CONFIGURATION ------------- @@ -58,6 +68,34 @@ include::includes/cmd-config-section-rest.adoc[] include::config/imap.adoc[] +GETTING A LIST OF AVAILABLE FOLDERS +----------------------------------- + +In order to send an email to a specific folder, you need to know the correct name of +intended folder in your mailbox. The names like "Junk", "Trash" etc. displayed by +various email clients need not be the actual names of the folders stored in the mail +server of your email provider. + +In order to get the correct folder name to be used with `git imap-send`, you can run +`git imap-send --list`. This will display a list of valid folder names. An example +of such an output when run on a Gmail account is: + +......................... +* LIST (\HasNoChildren) "/" "INBOX" +* LIST (\HasChildren \Noselect) "/" "[Gmail]" +* LIST (\All \HasNoChildren) "/" "[Gmail]/All Mail" +* LIST (\Drafts \HasNoChildren) "/" "[Gmail]/Drafts" +* LIST (\HasNoChildren \Important) "/" "[Gmail]/Important" +* LIST (\HasNoChildren \Sent) "/" "[Gmail]/Sent Mail" +* LIST (\HasNoChildren \Junk) "/" "[Gmail]/Spam" +* LIST (\Flagged \HasNoChildren) "/" "[Gmail]/Starred" +* LIST (\HasNoChildren \Trash) "/" "[Gmail]/Trash" +......................... + +Here, you can observe that the correct name for the "Junk" folder is `[Gmail]/Spam` +and for the "Trash" folder is `[Gmail]/Trash`. Similar logic can be used to determine +other folders as well. + EXAMPLES -------- Using tunnel mode: @@ -102,20 +140,56 @@ Using Gmail's IMAP interface: --------- [imap] - folder = "[Gmail]/Drafts" - host = imaps://imap.gmail.com - user = user@gmail.com - port = 993 + folder = "[Gmail]/Drafts" + host = imaps://imap.gmail.com + user = user@gmail.com + port = 993 --------- +Gmail does not allow using your regular password for `git imap-send`. +If you have multi-factor authentication set up on your Gmail account, you +can generate an app-specific password for use with `git imap-send`. +Visit https://security.google.com/settings/security/apppasswords to create +it. Alternatively, use OAuth2.0 authentication as described below. + [NOTE] You might need to instead use: `folder = "[Google Mail]/Drafts"` if you get an error -that the "Folder doesn't exist". +that the "Folder doesn't exist". You can also run `git imap-send --list` to get a +list of available folders. [NOTE] If your Gmail account is set to another language than English, the name of the "Drafts" folder will be localized. +If you want to use OAuth2.0 based authentication, you can specify +`OAUTHBEARER` or `XOAUTH2` mechanism in your config. It is more secure +than using app-specific passwords, and also does not enforce the need of +having multi-factor authentication. You will have to use an OAuth2.0 +access token in place of your password when using this authentication. + +--------- +[imap] + folder = "[Gmail]/Drafts" + host = imaps://imap.gmail.com + user = user@gmail.com + port = 993 + authmethod = OAUTHBEARER +--------- + +Using Outlook's IMAP interface: + +Unlike Gmail, Outlook only supports OAuth2.0 based authentication. Also, it +supports only `XOAUTH2` as the mechanism. + +--------- +[imap] + folder = "Drafts" + host = imaps://outlook.office365.com + user = user@outlook.com + port = 993 + authmethod = XOAUTH2 +--------- + Once the commits are ready to be sent, run the following command: $ git format-patch --cover-letter -M --stdout origin/master | git imap-send @@ -124,6 +198,10 @@ Just make sure to disable line wrapping in the email client (Gmail's web interface will wrap lines no matter what, so you need to use a real IMAP client). +In case you are using OAuth2.0 authentication, it is easier to use credential +helpers to generate tokens. Credential helpers suggested in +linkgit:git-send-email[1] can be used for `git imap-send` as well. + CAUTION ------- It is still your responsibility to make sure that the email message diff --git a/Documentation/git-index-pack.adoc b/Documentation/git-index-pack.adoc index 270056cf63..18036953c0 100644 --- a/Documentation/git-index-pack.adoc +++ b/Documentation/git-index-pack.adoc @@ -36,7 +36,8 @@ OPTIONS fails if the name of packed archive does not end with .pack). ---[no-]rev-index:: +--rev-index:: +--no-rev-index:: When this flag is provided, generate a reverse index (a `.rev` file) corresponding to the given pack. If `--verify` is given, ensure that the existing diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc index 82c8780d93..fd335fe772 100644 --- a/Documentation/git-interpret-trailers.adoc +++ b/Documentation/git-interpret-trailers.adoc @@ -142,8 +142,8 @@ OPTIONS provided with '--if-exists' overrides the `trailer.ifExists` and any applicable `trailer.<keyAlias>.ifExists` configuration variables and applies to all '--trailer' options until the next occurrence of - '--if-exists' or '--no-if-exists'. Upon encountering '--no-if-exists, clear the - effect of any previous use of '--if-exists, such that the relevant configuration + '--if-exists' or '--no-if-exists'. Upon encountering '--no-if-exists', clear the + effect of any previous use of '--if-exists', such that the relevant configuration variables are no longer overridden. Possible actions are `addIfDifferent`, `addIfDifferentNeighbor`, `add`, `replace` and `doNothing`. @@ -154,8 +154,8 @@ OPTIONS provided with '--if-missing' overrides the `trailer.ifMissing` and any applicable `trailer.<keyAlias>.ifMissing` configuration variables and applies to all '--trailer' options until the next occurrence of - '--if-missing' or '--no-if-missing'. Upon encountering '--no-if-missing, - clear the effect of any previous use of '--if-missing, such that the relevant + '--if-missing' or '--no-if-missing'. Upon encountering '--no-if-missing', + clear the effect of any previous use of '--if-missing', such that the relevant configuration variables are no longer overridden. Possible actions are `doNothing` or `add`. diff --git a/Documentation/git-log.adoc b/Documentation/git-log.adoc index ae8a7e2d63..e304739c5e 100644 --- a/Documentation/git-log.adoc +++ b/Documentation/git-log.adoc @@ -8,8 +8,8 @@ git-log - Show commit logs SYNOPSIS -------- -[verse] -'git log' [<options>] [<revision-range>] [[--] <path>...] +[synopsis] +git log [<options>] [<revision-range>] [[--] <path>...] DESCRIPTION ----------- @@ -27,28 +27,34 @@ each commit introduces are shown. OPTIONS ------- ---follow:: +`--follow`:: Continue listing the history of a file beyond renames (works only for a single file). ---no-decorate:: ---decorate[=short|full|auto|no]:: - Print out the ref names of any commits that are shown. If 'short' is - specified, the ref name prefixes 'refs/heads/', 'refs/tags/' and - 'refs/remotes/' will not be printed. If 'full' is specified, the - full ref name (including prefix) will be printed. If 'auto' is - specified, then if the output is going to a terminal, the ref names - are shown as if 'short' were given, otherwise no ref names are - shown. The option `--decorate` is short-hand for `--decorate=short`. - Default to configuration value of `log.decorate` if configured, - otherwise, `auto`. - ---decorate-refs=<pattern>:: ---decorate-refs-exclude=<pattern>:: +`--no-decorate`:: +`--decorate[=(short|full|auto|no)]`:: + Print out the ref names of any commits that are shown. Possible values + are: ++ +---- +`short`;; the ref name prefixes `refs/heads/`, `refs/tags/` and + `refs/remotes/` are not printed. +`full`;; the full ref name (including prefix) is printed. +`auto`:: if the output is going to a terminal, the ref names + are shown as if `short` were given, otherwise no ref names are + shown. +---- ++ +The option `--decorate` is short-hand for `--decorate=short`. Default to +configuration value of `log.decorate` if configured, otherwise, `auto`. + +`--decorate-refs=<pattern>`:: +`--decorate-refs-exclude=<pattern>`:: For each candidate reference, do not use it for decoration if it - matches any patterns given to `--decorate-refs-exclude` or if it - doesn't match any of the patterns given to `--decorate-refs`. The - `log.excludeDecoration` config option allows excluding refs from + matches any of the _<pattern>_ parameters given to + `--decorate-refs-exclude` or if it doesn't match any of the + _<pattern>_ parameters given to `--decorate-refs`. + The `log.excludeDecoration` config option allows excluding refs from the decorations, but an explicit `--decorate-refs` pattern will override a match in `log.excludeDecoration`. + @@ -56,51 +62,53 @@ If none of these options or config settings are given, then references are used as decoration if they match `HEAD`, `refs/heads/`, `refs/remotes/`, `refs/stash/`, or `refs/tags/`. ---clear-decorations:: +`--clear-decorations`:: When specified, this option clears all previous `--decorate-refs` or `--decorate-refs-exclude` options and relaxes the default decoration filter to include all references. This option is assumed if the config value `log.initialDecorationSet` is set to `all`. ---source:: +`--source`:: Print out the ref name given on the command line by which each commit was reached. ---[no-]mailmap:: ---[no-]use-mailmap:: +`--mailmap`:: +`--no-mailmap`:: +`--use-mailmap`:: +`--no-use-mailmap`:: Use mailmap file to map author and committer names and email addresses to canonical real names and email addresses. See linkgit:git-shortlog[1]. ---full-diff:: +`--full-diff`:: Without this flag, `git log -p <path>...` shows commits that touch the specified paths, and diffs about the same specified paths. With this, the full diff is shown for commits that touch - the specified paths; this means that "<path>..." limits only + the specified paths; this means that "`<path>...`" limits only commits, and doesn't limit diff for those commits. + Note that this affects all diff-based output types, e.g. those produced by `--stat`, etc. ---log-size:: - Include a line ``log size <number>'' in the output for each commit, - where <number> is the length of that commit's message in bytes. +`--log-size`:: + Include a line `log size <number>` in the output for each commit, + where _<number>_ is the length of that commit's message in bytes. Intended to speed up tools that read log messages from `git log` output by allowing them to allocate space in advance. include::line-range-options.adoc[] -<revision-range>:: +_<revision-range>_:: Show only commits in the specified revision range. When no - <revision-range> is specified, it defaults to `HEAD` (i.e. the + _<revision-range>_ is specified, it defaults to `HEAD` (i.e. the whole history leading to the current commit). `origin..HEAD` specifies all the commits reachable from the current commit (i.e. `HEAD`), but not from `origin`. For a complete list of - ways to spell <revision-range>, see the 'Specifying Ranges' + ways to spell _<revision-range>_, see the 'Specifying Ranges' section of linkgit:gitrevisions[7]. -[--] <path>...:: +`[--] <path>...`:: Show only commits that are enough to explain how the files that match the specified paths came to be. See 'History Simplification' below for details and other simplification @@ -145,14 +153,14 @@ EXAMPLES `git log --since="2 weeks ago" -- gitk`:: - Show the changes during the last two weeks to the file 'gitk'. + Show the changes during the last two weeks to the file `gitk`. The `--` is necessary to avoid confusion with the *branch* named - 'gitk' + `gitk` `git log --name-status release..test`:: - Show the commits that are in the "test" branch but not yet - in the "release" branch, along with the list of paths + Show the commits that are in the "`test`" branch but not yet + in the "`release`" branch, along with the list of paths each commit modifies. `git log --follow builtin/rev-list.c`:: @@ -164,7 +172,7 @@ EXAMPLES `git log --branches --not --remotes=origin`:: Shows all commits that are in any of local branches but not in - any of remote-tracking branches for 'origin' (what you have that + any of remote-tracking branches for `origin` (what you have that origin doesn't). `git log master --not --remotes=*/master`:: @@ -200,11 +208,11 @@ CONFIGURATION See linkgit:git-config[1] for core variables and linkgit:git-diff[1] for settings related to diff generation. -format.pretty:: +`format.pretty`:: Default for the `--format` option. (See 'Pretty Formats' above.) Defaults to `medium`. -i18n.logOutputEncoding:: +`i18n.logOutputEncoding`:: Encoding to use when displaying logs. (See 'Discussion' above.) Defaults to the value of `i18n.commitEncoding` if set, and UTF-8 otherwise. 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..271ab220e8 100644 --- a/Documentation/git-merge-tree.adoc +++ b/Documentation/git-merge-tree.adoc @@ -59,12 +59,19 @@ OPTIONS do not list filenames multiple times if they have multiple conflicting stages). ---[no-]messages:: +--messages:: +--no-messages:: Write any informational messages such as "Auto-merging <path>" or CONFLICT notices to the end of stdout. If unspecified, the 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..a055384ad6 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] [--compact-summary] [--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 ----------- @@ -28,8 +28,8 @@ Assume the following history exists and the current branch is `master`: ------------ - A---B---C topic - / + A---B---C topic + / D---E---F---G master ------------ @@ -38,11 +38,11 @@ Then `git merge topic` will replay the changes made on the its current commit (`C`) on top of `master`, and record the result in a new commit along with the names of the two parent commits and a log message from the user describing the changes. Before the operation, -`ORIG_HEAD` is set to the tip of the current branch (`C`). +`ORIG_HEAD` is set to the tip of the current branch (`G`). ------------ - A---B---C topic - / \ + A---B---C topic + / \ D---E---F---G---H master ------------ @@ -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..e8073bc272 100644 --- a/Documentation/git-multi-pack-index.adoc +++ b/Documentation/git-multi-pack-index.adoc @@ -25,7 +25,8 @@ OPTIONS + `<dir>` must be an alternate of the current repository. ---[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. Supported by sub-commands `write`, `verify`, `expire`, and `repack. @@ -38,10 +39,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..59edd24134 100644 --- a/Documentation/git-p4.adoc +++ b/Documentation/git-p4.adoc @@ -66,6 +66,7 @@ Clone ~~~~~ Generally, 'git p4 clone' is used to create a new Git directory from an existing p4 repository: + ------------ $ git p4 clone //depot/path/project ------------ @@ -80,6 +81,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 +91,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 +131,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 +147,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 +520,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 +550,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 b1c5aa27da..71b9682485 100644 --- a/Documentation/git-pack-objects.adoc +++ b/Documentation/git-pack-objects.adoc @@ -87,13 +87,21 @@ base-name:: reference was included in the resulting packfile. This can be useful to send new tags to native Git clients. ---stdin-packs:: +--stdin-packs[=<mode>]:: Read the basenames of packfiles (e.g., `pack-1234abcd.pack`) from the standard input, instead of object names or revision arguments. The resulting pack contains all objects listed in the included packs (those not beginning with `^`), excluding any objects listed in the excluded packs (beginning with `^`). + +When `mode` is "follow", objects from packs not listed on stdin receive +special treatment. Objects within unlisted packs will be included if +those objects are (1) reachable from the included packs, and (2) not +found in any excluded packs. This mode is useful, for example, to +resurrect once-unreachable objects found in cruft packs to generate +packs which are closed under reachability up to the boundary set by the +excluded packs. ++ Incompatible with `--revs`, or options that imply `--revs` (such as `--all`), with the exception of `--unpacked`, which is compatible. @@ -235,7 +243,8 @@ depth is 4095. Add --no-reuse-object if you want to force a uniform compression level on all data no matter the source. ---[no-]sparse:: +--sparse:: +--no-sparse:: Toggle the "sparse" algorithm to determine which objects to include in the pack, when combined with the "--revs" option. This algorithm only walks trees that appear in paths that introduce new objects. diff --git a/Documentation/git-pack-refs.adoc b/Documentation/git-pack-refs.adoc index 2dcabaf74c..42b90051e6 100644 --- a/Documentation/git-pack-refs.adoc +++ b/Documentation/git-pack-refs.adoc @@ -66,7 +66,10 @@ Pack refs as needed depending on the current state of the ref database. The behavior depends on the ref format used by the repository and may change in the future. + - - "files": No special handling for `--auto` has been implemented. + - "files": Loose references are packed into the `packed-refs` file + based on the ratio of loose references to the size of the + `packed-refs` file. The bigger the `packed-refs` file, the more loose + references need to exist before we repack. + - "reftable": Tables are compacted such that they form a geometric sequence. For two tables N and N+1, where N+1 is newer, this @@ -88,10 +91,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-pull.adoc b/Documentation/git-pull.adoc index 3f4ecc4730..48e924a10a 100644 --- a/Documentation/git-pull.adoc +++ b/Documentation/git-pull.adoc @@ -87,7 +87,8 @@ OPTIONS --verbose:: Pass --verbose to git-fetch and git-merge. ---[no-]recurse-submodules[=(yes|on-demand|no)]:: +--recurse-submodules[=(yes|on-demand|no)]:: +--no-recurse-submodules:: This option controls if new commits of populated submodules should be fetched, and if the working trees of active submodules should be updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc index d1978650d6..5f5408e2c0 100644 --- a/Documentation/git-push.adoc +++ b/Documentation/git-push.adoc @@ -197,7 +197,8 @@ already exists on the remote side. with configuration variable `push.followTags`. For more information, see `push.followTags` in linkgit:git-config[1]. ---[no-]signed:: +--signed:: +--no-signed:: --signed=(true|false|if-asked):: GPG-sign the push request to update refs on the receiving side, to allow it to be checked by the hooks and/or be @@ -208,7 +209,8 @@ already exists on the remote side. will also fail if the actual call to `gpg --sign` fails. See linkgit:git-receive-pack[1] for the details on the receiving end. ---[no-]atomic:: +--atomic:: +--no-atomic:: Use an atomic transaction on the remote side if available. Either all refs are updated, or on error, no refs are updated. If the server does not support atomic pushes the push will fail. @@ -232,7 +234,8 @@ already exists on the remote side. repository over ssh, and you do not have the program in a directory on the default $PATH. ---[no-]force-with-lease:: +--force-with-lease:: +--no-force-with-lease:: --force-with-lease=<refname>:: --force-with-lease=<refname>:<expect>:: Usually, "git push" refuses to update a remote ref that is @@ -350,7 +353,8 @@ one branch, use a `+` in front of the refspec to push (e.g `git push origin +master` to force a push to the `master` branch). See the `<refspec>...` section above for details. ---[no-]force-if-includes:: +--force-if-includes:: +--no-force-if-includes:: Force an update only if the tip of the remote-tracking ref has been integrated locally. + @@ -377,7 +381,8 @@ Specifying `--no-force-if-includes` disables this behavior. linkgit:git-pull[1] and other commands. For more information, see `branch.<name>.merge` in linkgit:git-config[1]. ---[no-]thin:: +--thin:: +--no-thin:: These options are passed to linkgit:git-send-pack[1]. A thin transfer significantly reduces the amount of sent data when the sender and receiver share many of the same objects in common. The default is @@ -419,7 +424,8 @@ When using 'on-demand' or 'only', if a submodule has a "push.recurseSubmodules={on-demand,only}" or "submodule.recurse" configuration, further recursion will occur. In this case, "only" is treated as "on-demand". ---[no-]verify:: +--verify:: +--no-verify:: Toggle the pre-push hook (see linkgit:githooks[5]). The default is --verify, giving the hook a chance to prevent the push. With --no-verify, the hook is bypassed completely. diff --git a/Documentation/git-range-diff.adoc b/Documentation/git-range-diff.adoc index db0e4279b5..b5e85d37f1 100644 --- a/Documentation/git-range-diff.adoc +++ b/Documentation/git-range-diff.adoc @@ -96,7 +96,8 @@ diff. --remerge-diff:: Convenience option, equivalent to `--diff-merges=remerge`. ---[no-]notes[=<ref>]:: +--notes[=<ref>]:: +--no-notes:: This flag is passed to the `git log` program (see linkgit:git-log[1]) that generates the patches. diff --git a/Documentation/git-read-tree.adoc b/Documentation/git-read-tree.adoc index 1c48c28996..1c04bba2b7 100644 --- a/Documentation/git-read-tree.adoc +++ b/Documentation/git-read-tree.adoc @@ -100,7 +100,8 @@ OPTIONS directories the index file and index output file are located in. ---[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 by calling read-tree recursively, also setting the submodules' HEAD to be diff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc index 153cb69a4f..005caf6164 100644 --- a/Documentation/git-rebase.adoc +++ b/Documentation/git-rebase.adoc @@ -16,49 +16,12 @@ SYNOPSIS DESCRIPTION ----------- -If `<branch>` is specified, `git rebase` will perform an automatic -`git switch <branch>` before doing anything else. Otherwise -it remains on the current branch. +Transplant a series of commits onto a different starting point. +You can also use `git rebase` to reorder or combine commits: see INTERACTIVE +MODE below for how to do that. -If `<upstream>` is not specified, the upstream configured in -`branch.<name>.remote` and `branch.<name>.merge` options will be used (see -linkgit:git-config[1] for details) and the `--fork-point` option is -assumed. If you are currently not on any branch or if the current -branch does not have a configured upstream, the rebase will abort. - -All changes made by commits in the current branch but that are not -in `<upstream>` are saved to a temporary area. This is the same set -of commits that would be shown by `git log <upstream>..HEAD`; or by -`git log 'fork_point'..HEAD`, if `--fork-point` is active (see the -description on `--fork-point` below); or by `git log HEAD`, if the -`--root` option is specified. - -The current branch is reset to `<upstream>` or `<newbase>` if the -`--onto` option was supplied. This has the exact same effect as -`git reset --hard <upstream>` (or `<newbase>`). `ORIG_HEAD` is set -to point at the tip of the branch before the reset. - -[NOTE] -`ORIG_HEAD` is not guaranteed to still point to the previous branch tip -at the end of the rebase if other commands that write that pseudo-ref -(e.g. `git reset`) are used during the rebase. The previous branch tip, -however, is accessible using the reflog of the current branch -(i.e. `@{1}`, see linkgit:gitrevisions[7]). - -The commits that were previously saved into the temporary area are -then reapplied to the current branch, one by one, in order. Note that -any commits in `HEAD` which introduce the same textual changes as a commit -in `HEAD..<upstream>` are omitted (i.e., a patch already accepted upstream -with a different commit message or timestamp will be skipped). - -It is possible that a merge failure will prevent this process from being -completely automatic. You will have to resolve any such merge failure -and run `git rebase --continue`. Another option is to bypass the commit -that caused the merge failure with `git rebase --skip`. To check out the -original `<branch>` and remove the `.git/rebase-apply` working files, use -the command `git rebase --abort` instead. - -Assume the following history exists and the current branch is "topic": +For example, imagine that you have been working on the `topic` branch in this +history, and you want to "catch up" to the work done on the `master` branch. ------------ A---B---C topic @@ -66,13 +29,11 @@ Assume the following history exists and the current branch is "topic": D---E---F---G master ------------ -From this point, the result of either of the following commands: - - - git rebase master - git rebase master topic - -would be: +You want to transplant the commits you made on `topic` since it diverged from +`master` (i.e. A, B, and C), on top of the current `master`. You can do this +by running `git rebase master` while the `topic` branch is checked out. If you +want to rebase `topic` while on another branch, `git rebase master topic` is a +shortcut for `git checkout topic && git rebase master`. ------------ A'--B'--C' topic @@ -80,30 +41,56 @@ would be: D---E---F---G master ------------ -*NOTE:* The latter form is just a short-hand of `git checkout topic` -followed by `git rebase master`. When rebase exits `topic` will -remain the checked-out branch. -If the upstream branch already contains a change you have made (e.g., -because you mailed a patch which was applied upstream), then that commit -will be skipped and warnings will be issued (if the 'merge' backend is -used). For example, running `git rebase master` on the following -history (in which `A'` and `A` introduce the same set of changes, but -have different committer information): +If there is a merge conflict during this process, `git rebase` will stop at the +first problematic commit and leave conflict markers. If this happens, you can do +one of these things: ------------- - A---B---C topic - / - D---E---A'---F master ------------- +1. Resolve the conflict. You can use `git diff` to find the markers (<<<<<<) + and make edits to resolve the conflict. For each file you edit, you need to + tell Git that the conflict has been resolved. You can mark the conflict as + resolved with `git add <filename>`. After resolving all of the conflicts, + you can continue the rebasing process with -will result in: + git rebase --continue ------------- - B'---C' topic - / - D---E---A'---F master ------------- +2. Stop the `git rebase` and return your branch to its original state with + + git rebase --abort + +3. Skip the commit that caused the merge conflict with + + git rebase --skip + +If you don't specify an `<upstream>` to rebase onto, the upstream configured in +`branch.<name>.remote` and `branch.<name>.merge` options will be used (see +linkgit:git-config[1] for details) and the `--fork-point` option is +assumed. If you are currently not on any branch or if the current +branch does not have a configured upstream, the rebase will abort. + +Here is a simplified description of what `git rebase <upstream>` does: + +1. Make a list of all commits on your current branch since it branched + off from `<upstream>` that do not have an equivalent commit in + `<upstream>`. +2. Check out `<upstream>` with the equivalent of + `git checkout --detach <upstream>`. +3. Replay the commits, one by one, in order. This is similar to running + `git cherry-pick <commit>` for each commit. See REBASING MERGES for how merges + are handled. +4. Update your branch to point to the final commit with the equivalent + of `git checkout -B <branch>`. + +[NOTE] +When starting the rebase, `ORIG_HEAD` is set to point to the commit at the tip +of the to-be-rebased branch. However, `ORIG_HEAD` is not guaranteed to still +point to that commit at the end of the rebase if other commands that change +`ORIG_HEAD` (like `git reset`) are used during the rebase. The previous branch +tip, however, is accessible using the reflog of the current branch (i.e. `@{1}`, +see linkgit:gitrevisions[7]. + +TRANSPLANTING A TOPIC BRANCH WITH --ONTO +---------------------------------------- Here is how you would transplant a topic branch based on one branch to another, to pretend that you forked the topic branch @@ -186,28 +173,6 @@ This is useful if F and G were flawed in some way, or should not be part of topicA. Note that the argument to `--onto` and the `<upstream>` parameter can be any valid commit-ish. -In case of conflict, `git rebase` will stop at the first problematic commit -and leave conflict markers in the tree. You can use `git diff` to locate -the markers (<<<<<<) and make edits to resolve the conflict. For each -file you edit, you need to tell Git that the conflict has been resolved, -typically this would be done with - - - git add <filename> - - -After resolving the conflict manually and updating the index with the -desired resolution, you can continue the rebasing process with - - - git rebase --continue - - -Alternatively, you can undo the 'git rebase' with - - - git rebase --abort - MODE OPTIONS ------------ @@ -253,6 +218,8 @@ 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. +See TRANSPLANTING A TOPIC BRANCH WITH --ONTO above for examples. + --keep-base:: Set the starting point at which to create the new commits to the merge base of `<upstream>` and `<branch>`. Running @@ -687,7 +654,7 @@ In addition, the following pairs of options are incompatible: * --fork-point and --root BEHAVIORAL DIFFERENCES ------------------------ +---------------------- `git rebase` has two primary backends: 'apply' and 'merge'. (The 'apply' backend used to be known as the 'am' backend, but the name led to @@ -1107,10 +1074,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 +1114,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..38af0c977a 100644 --- a/Documentation/git-reflog.adoc +++ b/Documentation/git-reflog.adoc @@ -8,15 +8,17 @@ git-reflog - Manage reflog information SYNOPSIS -------- -[verse] -'git reflog' [show] [<log-options>] [<ref>] -'git reflog list' -'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>] +[synopsis] +git reflog [show] [<log-options>] [<ref>] +git reflog list +git reflog exists <ref> +git reflog write <ref> <old-oid> <new-oid> <message> +git reflog delete [--rewrite] [--updateref] + [--dry-run | -n] [--verbose] <ref>@{<specifier>}... +git reflog drop [--all [--single-worktree] | <refs>...] +git reflog expire [--expire=<time>] [--expire-unreachable=<time>] [--rewrite] [--updateref] [--stale-fix] [--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...] -'git reflog delete' [--rewrite] [--updateref] - [--dry-run | -n] [--verbose] <ref>@{<specifier>}... -'git reflog exists' <ref> DESCRIPTION ----------- @@ -42,21 +44,31 @@ actions, and in addition the `HEAD` reflog records branch switching. The "list" subcommand lists all refs which have a corresponding reflog. +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 +not. + +The "write" subcommand writes a single entry to the reflog of a given +reference. This new entry is appended to the reflog and will thus become +the most recent entry. The reference name must be fully qualified. Both the old +and new object IDs must not be abbreviated and must point to existing objects. +The reflog message gets normalized. + +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 "expire" subcommand prunes older reflog entries. Entries older than `expire` time, or entries older than `expire-unreachable` time 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 "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 -not. - OPTIONS ------- @@ -66,18 +78,37 @@ Options for `show` `git reflog show` accepts any of the options accepted by `git log`. +Options for `delete` +~~~~~~~~~~~~~~~~~~~~ + +`git reflog delete` accepts options `--updateref`, `--rewrite`, `-n`, +`--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. + + Options for `expire` ~~~~~~~~~~~~~~~~~~~~ ---all:: +`--all`:: Process the reflogs of all references. ---single-worktree:: +`--single-worktree`:: By default when `--all` is specified, reflogs from all working trees are processed. This option limits the processing to reflogs from the current working tree only. ---expire=<time>:: +`--expire=<time>`:: Prune entries older than the specified time. If this option is not specified, the expiration time is taken from the configuration setting `gc.reflogExpire`, which in turn @@ -85,7 +116,7 @@ Options for `expire` of their age; `--expire=never` turns off pruning of reachable entries (but see `--expire-unreachable`). ---expire-unreachable=<time>:: +`--expire-unreachable=<time>`:: Prune entries older than `<time>` that are not reachable from the current tip of the branch. If this option is not specified, the expiration time is taken from the configuration @@ -95,17 +126,17 @@ Options for `expire` turns off early pruning of unreachable entries (but see `--expire`). ---updateref:: +`--updateref`:: Update the reference to the value of the top reflog entry (i.e. <ref>@\{0\}) if the previous top entry was pruned. (This option is ignored for symbolic references.) ---rewrite:: +`--rewrite`:: If a reflog entry's predecessor is pruned, adjust its "old" SHA-1 to be equal to the "new" SHA-1 field of the entry that now precedes it. ---stale-fix:: +`--stale-fix`:: Prune any reflog entries that point to "broken commits". A broken commit is a commit that is not reachable from any of the reference tips and that refers, directly or indirectly, to @@ -116,23 +147,15 @@ has the same cost as 'git prune'. It is primarily intended to fix corruption caused by garbage collecting using older versions of Git, which didn't protect objects referred to by reflogs. --n:: ---dry-run:: +`-n`:: +`--dry-run`:: Do not actually prune any entries; just show what would have been pruned. ---verbose:: +`--verbose`:: Print extra information on screen. -Options for `delete` -~~~~~~~~~~~~~~~~~~~~ - -`git reflog delete` accepts options `--updateref`, `--rewrite`, `-n`, -`--dry-run`, and `--verbose`, with the same meanings as when they are -used with `expire`. - - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc index 4d6dc994f9..d462953fb5 100644 --- a/Documentation/git-refs.adoc +++ b/Documentation/git-refs.adoc @@ -11,6 +11,13 @@ SYNOPSIS [synopsis] git refs migrate --ref-format=<format> [--no-reflog] [--dry-run] git refs verify [--strict] [--verbose] +git refs list [--count=<count>] [--shell|--perl|--python|--tcl] + [(--sort=<key>)...] [--format=<format>] + [--include-root-refs] [--points-at=<object>] + [--merged[=<object>]] [--no-merged[=<object>]] + [--contains[=<object>]] [--no-contains[=<object>]] + [(--exclude=<pattern>)...] [--start-after=<marker>] + [ --stdin | (<pattern>...)] DESCRIPTION ----------- @@ -20,43 +27,52 @@ This command provides low-level access to refs. COMMANDS -------- -migrate:: +`migrate`:: Migrate ref store between different formats. -verify:: +`verify`:: Verify reference database consistency. +list:: + List references in the repository with support for filtering, + formatting, and sorting. This subcommand is an alias for + linkgit:git-for-each-ref[1] and offers identical functionality. + OPTIONS ------- -The following options are specific to 'git refs migrate': +The following options are specific to `git refs migrate`: ---ref-format=<format>:: +`--ref-format=<format>`:: The ref format to migrate the ref store to. Can be one of: + include::ref-storage-format.adoc[] ---dry-run:: +`--dry-run`:: Perform the migration, but do not modify the repository. The migrated refs will be written into a separate directory that can be inspected separately. The name of the directory will be reported on stdout. This can be used to double check that the migration works as expected before performing the actual migration. ---reflog:: ---no-reflog:: +`--reflog`:: +`--no-reflog`:: Choose between migrating the reflog data to the new backend, and discarding them. The default is "--reflog", to migrate. -The following options are specific to 'git refs verify': +The following options are specific to `git refs verify`: ---strict:: +`--strict`:: Enable stricter error checking. This will cause warnings to be reported as errors. See linkgit:git-fsck[1]. ---verbose:: +`--verbose`:: When verifying the reference database consistency, be chatty. +The following options are specific to 'git refs list': + +include::for-each-ref-options.adoc[] + KNOWN LIMITATIONS ----------------- diff --git a/Documentation/git-repack.adoc b/Documentation/git-repack.adoc index aa1bc081e5..d12c4985f6 100644 --- a/Documentation/git-repack.adoc +++ b/Documentation/git-repack.adoc @@ -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 diff --git a/Documentation/git-repo.adoc b/Documentation/git-repo.adoc new file mode 100644 index 0000000000..2870828d93 --- /dev/null +++ b/Documentation/git-repo.adoc @@ -0,0 +1,84 @@ +git-repo(1) +=========== + +NAME +---- +git-repo - Retrieve information about the repository + +SYNOPSIS +-------- +[synopsis] +git repo info [--format=(keyvalue|nul)] [<key>...] + +DESCRIPTION +----------- +Retrieve information about the repository. + +THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE. + +COMMANDS +-------- +`info [--format=(keyvalue|nul)] [<key>...]`:: + Retrieve metadata-related information about the current repository. Only + the requested data will be returned based on their keys (see "INFO KEYS" + section below). ++ +The values are returned in the same order in which their respective keys were +requested. ++ +The output format can be chosen through the flag `--format`. Two formats are +supported: ++ +`keyvalue`::: + output key-value pairs one per line using the `=` character as + the delimiter between the key and the value. Values containing "unusual" + characters are quoted as explained for the configuration variable + `core.quotePath` (see linkgit:git-config[1]). This is the default. + +`nul`::: + similar to `keyvalue`, but using a newline character as the delimiter + between the key and the value and using a NUL character after each value. + This format is better suited for being parsed by another applications than + `keyvalue`. Unlike in the `keyvalue` format, the values are never quoted. + +INFO KEYS +--------- +In order to obtain a set of values from `git repo info`, you should provide +the keys that identify them. Here's a list of the available keys and the +values that they return: + +`layout.bare`:: + `true` if this is a bare repository, otherwise `false`. + +`layout.shallow`:: + `true` if this is a shallow repository, otherwise `false`. + +`references.format`:: + The reference storage format. The valid values are: ++ +include::ref-storage-format.adoc[] + +EXAMPLES +-------- + +* Retrieves the reference format of the current repository: ++ +------------ +git repo info references.format +------------ ++ + +* Retrieves whether the current repository is bare and whether it is shallow +using the `nul` format: ++ +------------ +git repo info --format=nul layout.bare layout.shallow +------------ + +SEE ALSO +-------- +linkgit:git-rev-parse[1] + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc index 79ad5643ee..3b9ba9aee9 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,34 @@ 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 +`--recurse-submodules`:: +`--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 +105,33 @@ 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). -\--:: +include::diff-context-options.adoc[] + +`--`:: 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 +351,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 +461,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 +470,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..961eef0137 100644 --- a/Documentation/git-restore.adoc +++ b/Documentation/git-restore.adoc @@ -28,8 +28,6 @@ otherwise from the index. Use `--source` to restore from a different commit. See "Reset, restore and revert" in linkgit:git[1] for the differences between the three commands. -THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE. - OPTIONS ------- `-s <tree>`:: @@ -51,9 +49,8 @@ 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. + +include::diff-context-options.adoc[] `-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..11b1ab1a07 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,33 @@ 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. +--outlook-id-fix:: +--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 +146,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 +179,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 +190,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 +224,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 +239,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 +261,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,23 +270,25 @@ 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 - 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 - `sendemail.smtpSSLCertPath` configuration variable, if set, or the - backing SSL library's compiled-in default otherwise (which should - be the best choice on most platforms). + by `c_rehash`, or a single file containing one or more PEM format + certificates concatenated together: see the description of the + `-CAfile` _<file>_ and the `-CApath` _<dir>_ options of + https://docs.openssl.org/master/man1/openssl-verify/ + [OpenSSL's verify(1) manual page] for more information on these). + Set it to an empty string to disable certificate verification. + Defaults to the value of the `sendemail.smtpSSLCertPath` configuration + variable, if set, or the backing SSL library's compiled-in default + otherwise (which should be the best choice on most platforms). --smtp-user=<user>:: Username for SMTP-AUTH. Default is the value of `sendemail.smtpUser`; @@ -285,18 +301,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 +321,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 +330,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,16 +344,17 @@ 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. --no-header-cmd:: Disable any header command in use. ---[no-]chain-reply-to:: +--chain-reply-to:: +--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 +362,86 @@ 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. +--signed-off-by-cc:: +--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`. ---[no-]cc-cover:: - If this is set, emails found in Cc: headers in the first patch of +--cc-cover:: +--no-cc-cover:: + 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 +--to-cover:: +--no-to-cover:: + 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. +--suppress-from:: +--no-suppress-from:: + 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 +--thread:: +--no-thread:: + 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:: +--mailmap:: +--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,32 +452,34 @@ 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. ---[no-]format-patch:: +--format-patch:: +--no-format-patch:: 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:: +--validate:: +--no-validate:: Perform sanity checks on patches. Currently, validation means the following: + @@ -461,7 +487,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 +506,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 +522,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 +537,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,16 +591,81 @@ 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) + + - https://github.com/AdityaGarg8/git-credential-email[git-credential-aol] + (cross platform, dedicated helper for authenticating AOL accounts) + +You can also see linkgit:gitcredentials[7] for more OAuth based authentication +helpers. + +Proton Mail does not provide an SMTP server to send emails. If you are a paid +customer of Proton Mail, you can use +https://proton.me/mail/bridge[Proton Mail Bridge] +officially provided by Proton Mail to create a local SMTP server for sending +emails. For both free and paid users, community maintained projects like +https://github.com/AdityaGarg8/git-credential-email[git-protonmail] can be +used. 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]. + +Exploiting the `sendmailCmd` option of `git send-email` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Apart from sending emails via an SMTP server, `git send-email` can also send +emails through any application that supports sendmail-like commands. You can +read documentation of `--sendmail-cmd=<command>` above for more information. +This ability can be very useful if you want to use another application as an +SMTP client for `git send-email`, or if your email provider uses proprietary +APIs instead of SMTP to send emails. + +As an example, lets see how to configure https://marlam.de/msmtp/[msmtp], a +popular SMTP client found in many Linux distributions. Edit `~/.gitconfig` +to instruct `git-send-email` to use it for sending emails. + +---- +[sendemail] + sendmailCmd = /usr/bin/msmtp # Change this to the path where msmtp is installed +---- + +Links of a few such community maintained helpers are: + + - https://marlam.de/msmtp/[msmtp] + (popular SMTP client with many features, available for Linux and macOS) + + - https://github.com/AdityaGarg8/git-credential-email[git-protonmail] + (cross platform client that can send emails using the ProtonMail API) + + - https://github.com/AdityaGarg8/git-credential-email[git-msgraph] + (cross platform client that can send emails using the Microsoft Graph API) SEE ALSO -------- diff --git a/Documentation/git-send-pack.adoc b/Documentation/git-send-pack.adoc index b9e73f2e77..811193f16c 100644 --- a/Documentation/git-send-pack.adoc +++ b/Documentation/git-send-pack.adoc @@ -71,7 +71,8 @@ be in a separate packet, and the list must end with a flush packet. fails to update then the entire push will fail without changing any refs. ---[no-]signed:: +--signed:: +--no-signed:: --signed=(true|false|if-asked):: GPG-sign the push request to update refs on the receiving side, to allow it to be checked by the hooks and/or be diff --git a/Documentation/git-stash.adoc b/Documentation/git-stash.adoc index 1a5177f498..e2300a19a2 100644 --- a/Documentation/git-stash.adoc +++ b/Documentation/git-stash.adoc @@ -23,6 +23,8 @@ SYNOPSIS 'git stash' clear 'git stash' create [<message>] 'git stash' store [(-m | --message) <message>] [-q | --quiet] <commit> +'git stash' export (--print | --to-ref <ref>) [<stash>...] +'git stash' import <commit> DESCRIPTION ----------- @@ -154,6 +156,18 @@ store:: reflog. This is intended to be useful for scripts. It is probably not the command you want to use; see "push" above. +export ( --print | --to-ref <ref> ) [<stash>...]:: + + Export the specified stashes, or all of them if none are specified, to + a chain of commits which can be transferred using the normal fetch and + push mechanisms, then imported using the `import` subcommand. + +import <commit>:: + + Import the specified stashes from the specified commit, which must have been + created by `export`, and add them to the list of stashes. To replace the + existing stashes, use `clear` first. + OPTIONS ------- -a:: @@ -208,6 +222,8 @@ to learn how to operate the `--patch` mode. The `--patch` option implies `--keep-index`. You can use `--no-keep-index` to override this. +include::diff-context-options.adoc[] + -S:: --staged:: This option is only valid for `push` and `save` commands. @@ -242,6 +258,19 @@ literally (including newlines and quotes). + Quiet, suppress feedback messages. +--print:: + This option is only valid for the `export` command. ++ +Create the chain of commits representing the exported stashes without +storing it anywhere in the ref namespace and print the object ID to +standard output. This is designed for scripts. + +--to-ref:: + This option is only valid for the `export` command. ++ +Create the chain of commits representing the exported stashes and store +it to the specified ref. + \--:: This option is only valid for `push` command. + @@ -259,7 +288,7 @@ For more details, see the 'pathspec' entry in linkgit:gitglossary[7]. <stash>:: This option is only valid for `apply`, `branch`, `drop`, `pop`, - `show` commands. + `show`, and `export` commands. + A reference of the form `stash@{<revision>}`. When no `<stash>` is given, the latest stash is assumed (that is, `stash@{0}`). 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-submodule.adoc b/Documentation/git-submodule.adoc index 87d8e0f0c5..95beaee561 100644 --- a/Documentation/git-submodule.adoc +++ b/Documentation/git-submodule.adoc @@ -307,6 +307,13 @@ OPTIONS --force:: This option is only valid for add, deinit and update commands. When running add, allow adding an otherwise ignored submodule path. + This option is also used to bypass a check that the submodule's name + is not already in use. By default, 'git submodule add' will fail if + the proposed name (which is derived from the path) is already registered + for another submodule in the repository. Using '--force' allows the command + to proceed by automatically generating a unique name by appending a number + to the conflicting name (e.g., if a submodule named 'child' exists, it will + try 'child1', and so on). When running deinit the submodule working trees will be removed even if they contain local changes. When running update (only effective with the checkout procedure), @@ -435,7 +442,8 @@ options carefully. clone with a history truncated to the specified number of revisions. See linkgit:git-clone[1] ---[no-]recommend-shallow:: +--recommend-shallow:: +--no-recommend-shallow:: This option is only valid for the update command. The initial clone of a submodule will use the recommended `submodule.<name>.shallow` as provided by the `.gitmodules` file @@ -447,7 +455,8 @@ options carefully. Clone new submodules in parallel with as many jobs. Defaults to the `submodule.fetchJobs` option. ---[no-]single-branch:: +--single-branch:: +--no-single-branch:: This option is only valid for the update command. Clone only one branch during update: HEAD or one specified by --branch. diff --git a/Documentation/git-svn.adoc b/Documentation/git-svn.adoc index bcf7d84a87..c26c12bab3 100644 --- a/Documentation/git-svn.adoc +++ b/Documentation/git-svn.adoc @@ -1012,9 +1012,11 @@ branch. If you do merge, note the following rule: 'git svn dcommit' will attempt to commit on top of the SVN commit named in + ------------------------------------------------------------------------ git log --grep=^git-svn-id: --first-parent -1 ------------------------------------------------------------------------ + You 'must' therefore ensure that the most recent commit of the branch you want to dcommit to is the 'first' parent of the merge. Chaos will ensue otherwise, especially if the first parent is an older commit on diff --git a/Documentation/git-switch.adoc b/Documentation/git-switch.adoc index f55315c51e..87707e9265 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 ----------- @@ -29,37 +29,35 @@ Switching branches does not require a clean index and working tree however if the operation leads to loss of local changes, unless told otherwise with `--discard-changes` or `--merge`. -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 +65,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 +99,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 +110,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 +136,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 +169,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 +237,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 +249,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-index.adoc b/Documentation/git-update-index.adoc index 7128aed540..9bea9fab9a 100644 --- a/Documentation/git-update-index.adoc +++ b/Documentation/git-update-index.adoc @@ -86,7 +86,8 @@ OPTIONS --chmod=(+|-)x:: Set the execute permissions on the updated files. ---[no-]assume-unchanged:: +--assume-unchanged:: +--no-assume-unchanged:: When this flag is specified, the object names recorded for the paths are not updated. Instead, this option sets/unsets the "assume unchanged" bit for the @@ -108,18 +109,21 @@ you will need to handle the situation manually. Like `--refresh`, but checks stat information unconditionally, without regard to the "assume unchanged" setting. ---[no-]skip-worktree:: +--skip-worktree:: +--no-skip-worktree:: When one of these flags is specified, the object names recorded for the paths are not updated. Instead, these options set and unset the "skip-worktree" bit for the paths. See section "Skip-worktree bit" below for more information. ---[no-]ignore-skip-worktree-entries:: +--ignore-skip-worktree-entries:: +--no-ignore-skip-worktree-entries:: Do not remove skip-worktree (AKA "index-only") entries even when the `--remove` option was specified. ---[no-]fsmonitor-valid:: +--fsmonitor-valid:: +--no-fsmonitor-valid:: When one of these flags is specified, the object names recorded for the paths are not updated. Instead, these options set and unset the "fsmonitor valid" bit for the paths. See 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-upload-pack.adoc b/Documentation/git-upload-pack.adoc index 516d1639d9..9167a321d0 100644 --- a/Documentation/git-upload-pack.adoc +++ b/Documentation/git-upload-pack.adoc @@ -25,7 +25,8 @@ repository. For push operations, see 'git send-pack'. OPTIONS ------- ---[no-]strict:: +--strict:: +--no-strict:: Do not try <directory>/.git/ if <directory> is not a Git directory. --timeout=<n>:: 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-whatchanged.adoc b/Documentation/git-whatchanged.adoc index 8e55e0bb1e..d21484026f 100644 --- a/Documentation/git-whatchanged.adoc +++ b/Documentation/git-whatchanged.adoc @@ -8,8 +8,14 @@ git-whatchanged - Show logs with differences each commit introduces SYNOPSIS -------- -[verse] -'git whatchanged' <option>... +[synopsis] +git whatchanged <option>... + +WARNING +------- +`git whatchanged` has been deprecated and is scheduled for removal in +a future version of Git, as it is merely `git log` with different +default; `whatchanged` is not even shorter to type than `log --raw`. DESCRIPTION ----------- diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc index 8340b7f028..389e669ac0 100644 --- a/Documentation/git-worktree.adoc +++ b/Documentation/git-worktree.adoc @@ -200,13 +200,15 @@ To remove a locked worktree, specify `--force` twice. With `add`, detach `HEAD` in the new worktree. See "DETACHED HEAD" in linkgit:git-checkout[1]. ---[no-]checkout:: +--checkout:: +--no-checkout:: By default, `add` checks out `<commit-ish>`, however, `--no-checkout` can be used to suppress checkout in order to make customizations, such as configuring sparse-checkout. See "Sparse checkout" in linkgit:git-read-tree[1]. ---[no-]guess-remote:: +--guess-remote:: +--no-guess-remote:: With `worktree add <path>`, without `<commit-ish>`, instead of creating a new branch from `HEAD`, if there exists a tracking branch in exactly one remote matching the basename of `<path>`, @@ -216,7 +218,8 @@ To remove a locked worktree, specify `--force` twice. This can also be set up as the default behaviour by using the `worktree.guessRemote` config option. ---[no-]relative-paths:: +--relative-paths:: +--no-relative-paths:: Link worktrees using relative paths or absolute paths (default). Overrides the `worktree.useRelativePaths` config option, see linkgit:git-config[1]. @@ -224,7 +227,8 @@ This can also be set up as the default behaviour by using the With `repair`, the linking files will be updated if there's an absolute/relative mismatch, even if the links are correct. ---[no-]track:: +--track:: +--no-track:: When creating a new branch, if `<commit-ish>` is a branch, mark it as "upstream" from the new branch. This is the default if `<commit-ish>` is a remote-tracking branch. See 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/git.adoc b/Documentation/git.adoc index 743b7b00e4..03e9e69d25 100644 --- a/Documentation/git.adoc +++ b/Documentation/git.adoc @@ -684,7 +684,7 @@ other `GIT_PROGRESS_DELAY`:: A number controlling how many seconds to delay before showing - optional progress indicators. Defaults to 2. + optional progress indicators. Defaults to 1. `GIT_EDITOR`:: This environment variable overrides `$EDITOR` and `$VISUAL`. 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/gitk.adoc b/Documentation/gitk.adoc index 58ce40ddb1..5b34dcd077 100644 --- a/Documentation/gitk.adoc +++ b/Documentation/gitk.adoc @@ -163,16 +163,16 @@ used by default. If '$XDG_CONFIG_HOME' is not set it defaults to History ------- -Gitk was the first graphical repository browser. It's written in -tcl/tk. +Gitk was the first graphical repository browser, written by +Paul Mackerras in Tcl/Tk. 'gitk' is actually maintained as an independent project, but stable versions are distributed as part of the Git suite for the convenience of end users. -gitk-git/ comes from Paul Mackerras's gitk project: +`gitk-git/` comes from Johannes Sixt's gitk project: - git://ozlabs.org/~paulus/gitk + https://github.com/j6t/gitk SEE ALSO -------- 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-http.adoc b/Documentation/gitprotocol-http.adoc index ec40a550cc..d024010414 100644 --- a/Documentation/gitprotocol-http.adoc +++ b/Documentation/gitprotocol-http.adoc @@ -318,7 +318,7 @@ Extra Parameter. Smart Service git-upload-pack ------------------------------- +----------------------------- This service reads from the repository pointed to by `$GIT_URL`. Clients MUST first perform ref discovery with 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/gitremote-helpers.adoc b/Documentation/gitremote-helpers.adoc index d0be008e5e..39cdece16e 100644 --- a/Documentation/gitremote-helpers.adoc +++ b/Documentation/gitremote-helpers.adoc @@ -498,7 +498,7 @@ set by Git if the remote helper has the 'option' capability. ask for the tag specifically. Some helpers may be able to use this option to avoid a second network connection. -'option dry-run' {'true'|'false'}: +'option dry-run' {'true'|'false'}:: If true, pretend the operation completed successfully, but don't actually change any repository data. For most helpers this only applies to the 'push', if supported. diff --git a/Documentation/gitsubmodules.adoc b/Documentation/gitsubmodules.adoc index f7b5a25a0c..2082296199 100644 --- a/Documentation/gitsubmodules.adoc +++ b/Documentation/gitsubmodules.adoc @@ -8,6 +8,7 @@ gitsubmodules - Mounting one repository inside another SYNOPSIS -------- .gitmodules, $GIT_DIR/config + ------------------ git submodule git <command> --recurse-submodules @@ -240,7 +241,7 @@ Workflow for a third party library Workflow for an artificially split repo --------------------------------------- +--------------------------------------- # Enable recursion for relevant commands, such that # regular commands recurse into submodules by default 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..64bebb811c 100644 --- a/Documentation/gitweb.conf.adoc +++ b/Documentation/gitweb.conf.adoc @@ -178,7 +178,7 @@ $export_ok:: Show repository only if this file exists (in repository). Only effective if this variable evaluates to true. Can be set when building gitweb by setting `GITWEB_EXPORT_OK`. This path is - relative to `GIT_DIR`. git-daemon[1] uses 'git-daemon-export-ok', + relative to `GIT_DIR`. linkgit:git-daemon[1] uses 'git-daemon-export-ok', unless started with `--export-all`. By default this variable is not set, which means that this feature is turned off. @@ -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/glossary-content.adoc b/Documentation/glossary-content.adoc index 575c18f776..e423e4765b 100644 --- a/Documentation/glossary-content.adoc +++ b/Documentation/glossary-content.adoc @@ -418,9 +418,8 @@ full pathname may have special meaning: - A leading "`**`" followed by a slash means match in all directories. For example, "`**/foo`" matches file or directory - "`foo`" anywhere, the same as pattern "`foo`". "`**/foo/bar`" - matches file or directory "`bar`" anywhere that is directly - under directory "`foo`". + "`foo`" anywhere. "`**/foo/bar`" matches file or directory "`bar`" + anywhere that is directly under directory "`foo`". - A trailing "`/**`" matches everything inside. For example, "`abc/**`" matches all files inside directory "abc", relative 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/line-range-format.adoc b/Documentation/line-range-format.adoc index 9b51e9fb66..3cc2a14544 100644 --- a/Documentation/line-range-format.adoc +++ b/Documentation/line-range-format.adoc @@ -1,30 +1,30 @@ -'<start>' and '<end>' can take one of these forms: +_<start>_ and _<end>_ can take one of these forms: -- number +- _<number>_ + -If '<start>' or '<end>' is a number, it specifies an +If _<start>_ or _<end>_ is a number, it specifies an absolute line number (lines count from 1). + -- `/regex/` +- `/<regex>/` + This form will use the first line matching the given -POSIX regex. If '<start>' is a regex, it will search from the end of +POSIX _<regex>_. If _<start>_ is a regex, it will search from the end of the previous `-L` range, if any, otherwise from the start of file. -If '<start>' is `^/regex/`, it will search from the start of file. -If '<end>' is a regex, it will search -starting at the line given by '<start>'. +If _<start>_ is `^/<regex>/`, it will search from the start of file. +If _<end>_ is a regex, it will search starting at the line given by +_<start>_. + -- +offset or -offset +- `+<offset>` or `-<offset>` + -This is only valid for '<end>' and will specify a number -of lines before or after the line given by '<start>'. +This is only valid for _<end>_ and will specify a number +of lines before or after the line given by _<start>_. + -If `:<funcname>` is given in place of '<start>' and '<end>', it is a +If `:<funcname>` is given in place of _<start>_ and _<end>_, it is a regular expression that denotes the range from the first funcname line -that matches '<funcname>', up to the next funcname line. `:<funcname>` +that matches _<funcname>_, up to the next funcname line. `:<funcname>` searches from the end of the previous `-L` range, if any, otherwise from the start of file. `^:<funcname>` searches from the start of file. The function names are determined in the same way as `git diff` diff --git a/Documentation/line-range-options.adoc b/Documentation/line-range-options.adoc index f275df3b69..c44ba05320 100644 --- a/Documentation/line-range-options.adoc +++ b/Documentation/line-range-options.adoc @@ -1,12 +1,12 @@ --L<start>,<end>:<file>:: --L:<funcname>:<file>:: +`-L<start>,<end>:<file>`:: +`-L:<funcname>:<file>`:: - Trace the evolution of the line range given by '<start>,<end>', - or by the function name regex '<funcname>', within the '<file>'. You may + Trace the evolution of the line range given by `<start>,<end>`, + or by the function name regex _<funcname>_, within the _<file>_. You may not give any pathspec limiters. This is currently limited to a walk starting from a single revision, i.e., you may only give zero or one positive revision arguments, and - '<start>' and '<end>' (or '<funcname>') must exist in the starting revision. + _<start>_ and _<end>_ (or _<funcname>_) must exist in the starting revision. You can specify this option more than once. Implies `--patch`. Patch output can be suppressed using `--no-patch`, but other diff formats (namely `--raw`, `--numstat`, `--shortstat`, `--dirstat`, `--summary`, diff --git a/Documentation/lint-delimited-sections.perl b/Documentation/lint-delimited-sections.perl new file mode 100755 index 0000000000..140b852e5d --- /dev/null +++ b/Documentation/lint-delimited-sections.perl @@ -0,0 +1,48 @@ +#!/usr/bin/perl + +use strict; +use warnings; + +my $exit_code = 0; +sub report { + my ($msg) = @_; + print STDERR "$ARGV:$.: $msg\n"; + $exit_code = 1; +} + +my $line_length = 0; +my $in_section = 0; +my $section_header = ""; + + +while (my $line = <>) { + if (($line =~ /^\+?$/) || + ($line =~ /^\[.*\]$/) || + ($line =~ /^ifdef::/)) { + $line_length = 0; + } elsif ($line =~ /^[^-.]/) { + $line_length = length($line); + } elsif (($line =~ /^-{3,}$/) || ($line =~ /^\.{3,}$/)) { + if ($in_section) { + if ($line eq $section_header) { + $in_section = 0; + } + next; + } + if ($line_length == 0) { + $in_section = 1; + $section_header = $line; + next; + } + if (($line_length != 0) && (length($line) != $line_length)) { + report("section delimiter not preceded by an empty line"); + } + $line_length = 0; + } +} + +if ($in_section) { + report("section not finished"); +} + +exit $exit_code; diff --git a/Documentation/lint-documentation-style.perl b/Documentation/lint-documentation-style.perl new file mode 100755 index 0000000000..d7ab732293 --- /dev/null +++ b/Documentation/lint-documentation-style.perl @@ -0,0 +1,33 @@ +#!/usr/bin/perl + +use strict; +use warnings; + +my $exit_code = 0; +sub report { + my ($line, $msg) = @_; + chomp $line; + print STDERR "$ARGV:$.: '$line' $msg\n"; + $exit_code = 1; +} + +my $synopsis_style = 0; + +while (my $line = <>) { + if ($line =~ /^[ \t]*`?[-a-z0-9.]+`?(, `?[-a-z0-9.]+`?)+(::|;;)$/) { + + report($line, "multiple parameters in a definition list item"); + } + if ($line =~ /^`?--\[no-\][a-z0-9-]+.*(::|;;)$/) { + report($line, "definition list item with a `--[no-]` parameter"); + } + if ($line =~ /^\[synopsis\]$/) { + $synopsis_style = 1; + } + if (($line =~ /^(-[-a-z].*|<[-a-z0-9]+>(\.{3})?)(::|;;)$/) && ($synopsis_style)) { + report($line, "synopsis style and definition list item not backquoted"); + } +} + + +exit $exit_code; diff --git a/Documentation/lint-gitlink.perl b/Documentation/lint-gitlink.perl index aea564dad7..f183a18df2 100755 --- a/Documentation/lint-gitlink.perl +++ b/Documentation/lint-gitlink.perl @@ -41,6 +41,13 @@ die "BUG: No list of valid linkgit:* files given" unless @ARGV; @ARGV = $to_check; while (<>) { my $line = $_; + while ($line =~ m/(.{,8})((git[-a-z]+|scalar)\[(\d)*\])/g) { + my $pos = pos $line; + my ($macro, $target, $page, $section) = ($1, $2, $3, $4); + if ( $macro ne "linkgit:" && $macro !~ "ifn?def::" && $macro ne "endif::" ) { + report($pos, $line, $target, "linkgit: macro expected"); + } + } while ($line =~ m/linkgit:((.*?)\[(\d)\])/g) { my $pos = pos $line; my ($target, $page, $section) = ($1, $2, $3); diff --git a/Documentation/merge-options.adoc b/Documentation/merge-options.adoc index 0022185201..9d433265b2 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,43 @@ 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:: +`--compact-summary`:: + Show a compact-summary at the end of the merge. + +`--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 +126,17 @@ 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:: +`--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 +144,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 +169,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 +192,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 +201,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..b4ab83a510 100644 --- a/Documentation/mergetools/vimdiff.adoc +++ b/Documentation/mergetools/vimdiff.adoc @@ -3,6 +3,7 @@ Description When specifying `--tool=vimdiff` in `git mergetool` Git will open Vim with a 4 windows layout distributed in the following way: + .... ------------------------------------------ | | | | @@ -56,6 +57,7 @@ needed in this case. The next layout definition is equivalent: + -- If, for some reason, we are not interested in the `BASE` buffer. + .... ------------------------------------------ | | | | @@ -72,6 +74,7 @@ If, for some reason, we are not interested in the `BASE` buffer. Only the `MERGED` buffer will be shown. Note, however, that all the other ones are still loaded in vim, and you can access them with the "buffers" command. + .... ------------------------------------------ | | @@ -86,8 +89,9 @@ 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. + .... ------------------------------------------ | | | @@ -106,6 +110,7 @@ save after resolving the conflicts. Three tabs will open: the first one is a copy of the default layout, while the other two only show the differences between (`BASE` and `LOCAL`) and (`BASE` and `REMOTE`) respectively. + .... ------------------------------------------ | <TAB #1> | TAB #2 | TAB #3 | | @@ -119,6 +124,7 @@ the other two only show the differences between (`BASE` and `LOCAL`) and | | ------------------------------------------ .... + .... ------------------------------------------ | TAB #1 | <TAB #2> | TAB #3 | | @@ -132,6 +138,7 @@ the other two only show the differences between (`BASE` and `LOCAL`) and | | | ------------------------------------------ .... + .... ------------------------------------------ | TAB #1 | TAB #2 | <TAB #3> | | @@ -151,6 +158,7 @@ the other two only show the differences between (`BASE` and `LOCAL`) and -- Same as the previous example, but adds a fourth tab with the same information as the first tab, with a different layout. + .... --------------------------------------------- | TAB #1 | TAB #2 | TAB #3 | <TAB #4> | @@ -183,13 +191,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..41f43e0336 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, @@ -116,6 +116,7 @@ manpages = { 'git-repack.adoc' : 1, 'git-replace.adoc' : 1, 'git-replay.adoc' : 1, + 'git-repo.adoc' : 1, 'git-request-pull.adoc' : 1, 'git-rerere.adoc' : 1, 'git-reset.adoc' : 1, @@ -158,7 +159,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 +205,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 +226,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 +251,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 +298,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 +317,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 +336,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 ) @@ -347,8 +376,7 @@ foreach manpage, category : manpages output: fs.stem(manpage) + '.xml', ) - manpage_path = fs.stem(manpage) + '.' + category.to_string() - manpage_target = custom_target( + custom_target( command: [ xmlto, '-m', '@INPUT0@', @@ -364,7 +392,7 @@ foreach manpage, category : manpages 'manpage-normal.xsl', 'manpage-bold-literal.xsl', ], - output: manpage_path, + output: fs.stem(manpage) + '.' + category.to_string(), install: true, install_dir: get_option('mandir') / 'man' + category.to_string(), ) @@ -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/pretty-formats.adoc b/Documentation/pretty-formats.adoc index 07475de8c3..618ddc4a0c 100644 --- a/Documentation/pretty-formats.adoc +++ b/Documentation/pretty-formats.adoc @@ -2,11 +2,11 @@ PRETTY FORMATS -------------- If the commit is a merge, and if the pretty-format -is not 'oneline', 'email' or 'raw', an additional line is -inserted before the 'Author:' line. This line begins with +is not `oneline`, `email` or `raw`, an additional line is +inserted before the `Author:` line. This line begins with "Merge: " and the hashes of ancestral commits are printed, separated by spaces. Note that the listed commits may not -necessarily be the list of the *direct* parent commits if you +necessarily be the list of the 'direct' parent commits if you have limited your view of history: for example, if you are only interested in changes related to a certain directory or file. @@ -14,24 +14,24 @@ file. There are several built-in formats, and you can define additional formats by setting a pretty.<name> config option to either another format name, or a -'format:' string, as described below (see +`format:` string, as described below (see linkgit:git-config[1]). Here are the details of the built-in formats: -* 'oneline' +* `oneline` <hash> <title-line> + This is designed to be as compact as possible. -* 'short' +* `short` commit <hash> Author: <author> <title-line> -* 'medium' +* `medium` commit <hash> Author: <author> @@ -41,7 +41,7 @@ This is designed to be as compact as possible. <full-commit-message> -* 'full' +* `full` commit <hash> Author: <author> @@ -51,7 +51,7 @@ This is designed to be as compact as possible. <full-commit-message> -* 'fuller' +* `fuller` commit <hash> Author: <author> @@ -63,18 +63,18 @@ This is designed to be as compact as possible. <full-commit-message> -* 'reference' +* `reference` <abbrev-hash> (<title-line>, <short-author-date>) + This format is used to refer to another commit in a commit message and -is the same as `--pretty='format:%C(auto)%h (%s, %ad)'`. By default, +is the same as ++--pretty=\'format:%C(auto)%h (%s, %ad)'++. By default, the date is formatted with `--date=short` unless another `--date` option is explicitly specified. As with any `format:` with format placeholders, its output is not affected by other options like `--decorate` and `--walk-reflogs`. -* 'email' +* `email` From <hash> <date> From: <author> @@ -83,30 +83,30 @@ placeholders, its output is not affected by other options like <full-commit-message> -* 'mboxrd' +* `mboxrd` + -Like 'email', but lines in the commit message starting with "From " +Like `email`, but lines in the commit message starting with "From " (preceded by zero or more ">") are quoted with ">" so they aren't confused as starting a new commit. -* 'raw' +* `raw` + -The 'raw' format shows the entire commit exactly as +The `raw` format shows the entire commit exactly as stored in the commit object. Notably, the hashes are -displayed in full, regardless of whether --abbrev or ---no-abbrev are used, and 'parents' information show the +displayed in full, regardless of whether `--abbrev` or +`--no-abbrev` are used, and 'parents' information show the true parent commits, without taking grafts or history simplification into account. Note that this format affects the way commits are displayed, but not the way the diff is shown e.g. with `git log --raw`. To get full object names in a raw diff format, use `--no-abbrev`. -* 'format:<format-string>' +* `format:<format-string>` + -The 'format:<format-string>' format allows you to specify which information +The `format:<format-string>` format allows you to specify which information you want to show. It works a little bit like printf format, -with the notable exception that you get a newline with '%n' -instead of '\n'. +with the notable exception that you get a newline with `%n` +instead of `\n`. + E.g, 'format:"The author of %h was %an, %ar%nThe title was >>%s<<%n"' would show something like this: @@ -120,158 +120,161 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff input.<< The placeholders are: - Placeholders that expand to a single literal character: -'%n':: newline -'%%':: a raw '%' -'%x00':: '%x' followed by two hexadecimal digits is replaced with a +++%n++:: newline +++%%++:: a raw ++%++ +++%x00++:: ++%x++ followed by two hexadecimal digits is replaced with a byte with the hexadecimal digits' value (we will call this "literal formatting code" in the rest of this document). - Placeholders that affect formatting of later placeholders: -'%Cred':: switch color to red -'%Cgreen':: switch color to green -'%Cblue':: switch color to blue -'%Creset':: reset color -'%C(...)':: color specification, as described under Values in the +++%Cred++:: switch color to red +++%Cgreen++:: switch color to green +++%Cblue++:: switch color to blue +++%Creset++:: reset color +++%C(++_<spec>_++)++:: color specification, as described under Values in the "CONFIGURATION FILE" section of linkgit:git-config[1]. By default, colors are shown only when enabled for log output (by `color.diff`, `color.ui`, or `--color`, and respecting the `auto` settings of the former if we are going to a - terminal). `%C(auto,...)` is accepted as a historical - synonym for the default (e.g., `%C(auto,red)`). Specifying - `%C(always,...)` will show the colors even when color is + terminal). ++%C(auto,++_<spec>_++)++ is accepted as a historical + synonym for the default (e.g., ++%C(auto,red)++). Specifying + ++%C(always,++_<spec>_++)++ will show the colors even when color is not otherwise enabled (though consider just using - `--color=always` to enable color for the whole output, + `--color=always` to enable color for the whole output, including this format and anything else git might color). - `auto` alone (i.e. `%C(auto)`) will turn on auto coloring + `auto` alone (i.e. ++%C(auto)++) will turn on auto coloring on the next placeholders until the color is switched again. -'%m':: left (`<`), right (`>`) or boundary (`-`) mark -'%w([<w>[,<i1>[,<i2>]]])':: switch line wrapping, like the -w option of +++%m++:: left (`<`), right (`>`) or boundary (`-`) mark +++%w(++`[<w>[,<i1>[,<i2>]]]`++)++:: switch line wrapping, like the `-w` option of linkgit:git-shortlog[1]. -'%<( <N> [,trunc|ltrunc|mtrunc])':: make the next placeholder take at +++%<(++`<n>[,(trunc|ltrunc|mtrunc)]`++)++:: make the next placeholder take at least N column widths, padding spaces on the right if necessary. Optionally - truncate (with ellipsis '..') at the left (ltrunc) `..ft`, + truncate (with ellipsis `..`) at the left (ltrunc) `..ft`, the middle (mtrunc) `mi..le`, or the end (trunc) `rig..`, if the output is longer than - N columns. + _<n>_ columns. Note 1: that truncating - only works correctly with N >= 2. - Note 2: spaces around the N and M (see below) + only works correctly with _<n>_ >= 2. + Note 2: spaces around the _<n>_ and _<m>_ (see below) values are optional. Note 3: Emojis and other wide characters will take two display columns, which may over-run column boundaries. Note 4: decomposed character combining marks may be misplaced at padding boundaries. -'%<|( <M> )':: make the next placeholder take at least until Mth +++%<|(++_<m>_ ++)++:: make the next placeholder take at least until _<m>_ th display column, padding spaces on the right if necessary. - Use negative M values for column positions measured + Use negative _<m>_ values for column positions measured from the right hand edge of the terminal window. -'%>( <N> )', '%>|( <M> )':: similar to '%<( <N> )', '%<|( <M> )' respectively, +++%>(++_<n>_++)++:: +++%>|(++_<m>_++)++:: similar to ++%<(++_<n>_++)++, ++%<|(++_<m>_++)++ respectively, but padding spaces on the left -'%>>( <N> )', '%>>|( <M> )':: similar to '%>( <N> )', '%>|( <M> )' +++%>>(++_<n>_++)++:: +++%>>|(++_<m>_++)++:: similar to ++%>(++_<n>_++)++, ++%>|(++_<m>_++)++ respectively, except that if the next placeholder takes more spaces than given and there are spaces on its left, use those spaces -'%><( <N> )', '%><|( <M> )':: similar to '%<( <N> )', '%<|( <M> )' +++%><(++_<n>_++)++:: +++%><|(++_<m>_++)++:: similar to ++%<(++_<n>_++)++, ++%<|(++_<m>_++)++ respectively, but padding both sides (i.e. the text is centered) - Placeholders that expand to information extracted from the commit: -'%H':: commit hash -'%h':: abbreviated commit hash -'%T':: tree hash -'%t':: abbreviated tree hash -'%P':: parent hashes -'%p':: abbreviated parent hashes -'%an':: author name -'%aN':: author name (respecting .mailmap, see linkgit:git-shortlog[1] ++%H+:: commit hash ++%h+:: abbreviated commit hash ++%T+:: tree hash ++%t+:: abbreviated tree hash ++%P+:: parent hashes ++%p+:: abbreviated parent hashes ++%an+:: author name ++%aN+:: author name (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) -'%ae':: author email -'%aE':: author email (respecting .mailmap, see linkgit:git-shortlog[1] ++%ae+:: author email ++%aE+:: author email (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) -'%al':: author email local-part (the part before the '@' sign) -'%aL':: author local-part (see '%al') respecting .mailmap, see ++%al+:: author email local-part (the part before the `@` sign) ++%aL+:: author local-part (see +%al+) respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) -'%ad':: author date (format respects --date= option) -'%aD':: author date, RFC2822 style -'%ar':: author date, relative -'%at':: author date, UNIX timestamp -'%ai':: author date, ISO 8601-like format -'%aI':: author date, strict ISO 8601 format -'%as':: author date, short format (`YYYY-MM-DD`) -'%ah':: author date, human style (like the `--date=human` option of ++%ad+:: author date (format respects --date= option) ++%aD+:: author date, RFC2822 style ++%ar+:: author date, relative ++%at+:: author date, UNIX timestamp ++%ai+:: author date, ISO 8601-like format ++%aI+:: author date, strict ISO 8601 format ++%as+:: author date, short format (`YYYY-MM-DD`) ++%ah+:: author date, human style (like the `--date=human` option of linkgit:git-rev-list[1]) -'%cn':: committer name -'%cN':: committer name (respecting .mailmap, see ++%cn+:: committer name ++%cN+:: committer name (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) -'%ce':: committer email -'%cE':: committer email (respecting .mailmap, see ++%ce+:: committer email ++%cE+:: committer email (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) -'%cl':: committer email local-part (the part before the '@' sign) -'%cL':: committer local-part (see '%cl') respecting .mailmap, see ++%cl+:: committer email local-part (the part before the `@` sign) ++%cL+:: committer local-part (see +%cl+) respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) -'%cd':: committer date (format respects --date= option) -'%cD':: committer date, RFC2822 style -'%cr':: committer date, relative -'%ct':: committer date, UNIX timestamp -'%ci':: committer date, ISO 8601-like format -'%cI':: committer date, strict ISO 8601 format -'%cs':: committer date, short format (`YYYY-MM-DD`) -'%ch':: committer date, human style (like the `--date=human` option of ++%cd+:: committer date (format respects --date= option) ++%cD+:: committer date, RFC2822 style ++%cr+:: committer date, relative ++%ct+:: committer date, UNIX timestamp ++%ci+:: committer date, ISO 8601-like format ++%cI+:: committer date, strict ISO 8601 format ++%cs+:: committer date, short format (`YYYY-MM-DD`) ++%ch+:: committer date, human style (like the `--date=human` option of linkgit:git-rev-list[1]) -'%d':: ref names, like the --decorate option of linkgit:git-log[1] -'%D':: ref names without the " (", ")" wrapping. -'%(decorate[:<options>])':: ++%d+:: ref names, like the --decorate option of linkgit:git-log[1] ++%D+:: ref names without the " (", ")" wrapping. +++%(decorate++`[:<option>,...]`++)++:: ref names with custom decorations. The `decorate` string may be followed by a colon and zero or more comma-separated options. Option values may contain literal formatting codes. These must be used for commas (`%x2C`) and closing parentheses (`%x29`), due to their role in the option syntax. + -** 'prefix=<value>': Shown before the list of ref names. Defaults to "{nbsp}`(`". -** 'suffix=<value>': Shown after the list of ref names. Defaults to "`)`". -** 'separator=<value>': Shown between ref names. Defaults to "`,`{nbsp}". -** 'pointer=<value>': Shown between HEAD and the branch it points to, if any. - Defaults to "{nbsp}`->`{nbsp}". -** 'tag=<value>': Shown before tag names. Defaults to "`tag:`{nbsp}". +** `prefix=<value>`: Shown before the list of ref names. Defaults to "{nbsp}++(++". +** `suffix=<value>`: Shown after the list of ref names. Defaults to "+)+". +** `separator=<value>`: Shown between ref names. Defaults to "+,+{nbsp}". +** `pointer=<value>`: Shown between HEAD and the branch it points to, if any. + Defaults to "{nbsp}++->++{nbsp}". +** `tag=<value>`: Shown before tag names. Defaults to "`tag:`{nbsp}". + For example, to produce decorations with no wrapping or tag annotations, and spaces as separators: + -`%(decorate:prefix=,suffix=,tag=,separator= )` +++%(decorate:prefix=,suffix=,tag=,separator= )++ -'%(describe[:<options>])':: +++%(describe++`[:<option>,...]`++)++:: human-readable name, like linkgit:git-describe[1]; empty string for undescribable commits. The `describe` string may be followed by a colon and zero or more comma-separated options. Descriptions can be inconsistent when tags are added or removed at the same time. + -** 'tags[=<bool-value>]': Instead of only considering annotated tags, +** `tags[=<bool-value>]`: Instead of only considering annotated tags, consider lightweight tags as well. -** 'abbrev=<number>': Instead of using the default number of hexadecimal digits +** `abbrev=<number>`: Instead of using the default number of hexadecimal digits (which will vary according to the number of objects in the repository with a default of 7) of the abbreviated object name, use <number> digits, or as many digits as needed to form a unique object name. -** 'match=<pattern>': Only consider tags matching the given - `glob(7)` pattern, excluding the "refs/tags/" prefix. -** 'exclude=<pattern>': Do not consider tags matching the given - `glob(7)` pattern, excluding the "refs/tags/" prefix. +** `match=<pattern>`: Only consider tags matching the given + `glob(7)` _<pattern>_, excluding the `refs/tags/` prefix. +** `exclude=<pattern>`: Do not consider tags matching the given + `glob(7)` _<pattern>_, excluding the `refs/tags/` prefix. -'%S':: ref name given on the command line by which the commit was reached ++%S+:: ref name given on the command line by which the commit was reached (like `git log --source`), only works with `git log` -'%e':: encoding -'%s':: subject -'%f':: sanitized subject line, suitable for a filename -'%b':: body -'%B':: raw body (unwrapped subject and body) ++%e+:: encoding ++%s+:: subject ++%f+:: sanitized subject line, suitable for a filename ++%b+:: body ++%B+:: raw body (unwrapped subject and body) ifndef::git-rev-list[] -'%N':: commit notes ++%N+:: commit notes endif::git-rev-list[] -'%GG':: raw verification message from GPG for a signed commit -'%G?':: show "G" for a good (valid) signature, ++%GG+:: raw verification message from GPG for a signed commit ++%G?+:: show "G" for a good (valid) signature, "B" for a bad signature, "U" for a good signature with unknown validity, "X" for a good signature that has expired, @@ -279,86 +282,86 @@ endif::git-rev-list[] "R" for a good signature made by a revoked key, "E" if the signature cannot be checked (e.g. missing key) and "N" for no signature -'%GS':: show the name of the signer for a signed commit -'%GK':: show the key used to sign a signed commit -'%GF':: show the fingerprint of the key used to sign a signed commit -'%GP':: show the fingerprint of the primary key whose subkey was used ++%GS+:: show the name of the signer for a signed commit ++%GK+:: show the key used to sign a signed commit ++%GF+:: show the fingerprint of the key used to sign a signed commit ++%GP+:: show the fingerprint of the primary key whose subkey was used to sign a signed commit -'%GT':: show the trust level for the key used to sign a signed commit -'%gD':: reflog selector, e.g., `refs/stash@{1}` or `refs/stash@{2 ++%GT+:: show the trust level for the key used to sign a signed commit ++%gD+:: reflog selector, e.g., `refs/stash@{1}` or `refs/stash@{2 minutes ago}`; the format follows the rules described for the `-g` option. The portion before the `@` is the refname as given on the command line (so `git log -g refs/heads/master` would yield `refs/heads/master@{0}`). -'%gd':: shortened reflog selector; same as `%gD`, but the refname ++%gd+:: shortened reflog selector; same as `%gD`, but the refname portion is shortened for human readability (so `refs/heads/master` becomes just `master`). -'%gn':: reflog identity name -'%gN':: reflog identity name (respecting .mailmap, see ++%gn+:: reflog identity name ++%gN+:: reflog identity name (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) -'%ge':: reflog identity email -'%gE':: reflog identity email (respecting .mailmap, see ++%ge+:: reflog identity email ++%gE+:: reflog identity email (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) -'%gs':: reflog subject -'%(trailers[:<options>])':: ++%gs+:: reflog subject +++%(trailers++`[:<option>,...]`++)++:: display the trailers of the body as interpreted by linkgit:git-interpret-trailers[1]. The `trailers` string may be followed by a colon and zero or more comma-separated options. If any option is provided multiple times, the last occurrence wins. + -** 'key=<key>': only show trailers with specified <key>. Matching is done +** `key=<key>`: only show trailers with specified <key>. Matching is done case-insensitively and trailing colon is optional. If option is given multiple times trailer lines matching any of the keys are shown. This option automatically enables the `only` option so that non-trailer lines in the trailer block are hidden. If that is not desired it can be disabled with `only=false`. E.g., - `%(trailers:key=Reviewed-by)` shows trailer lines with key + +%(trailers:key=Reviewed-by)+ shows trailer lines with key `Reviewed-by`. -** 'only[=<bool>]': select whether non-trailer lines from the trailer +** `only[=<bool>]`: select whether non-trailer lines from the trailer block should be included. -** 'separator=<sep>': specify the separator inserted between trailer +** `separator=<sep>`: specify the separator inserted between trailer lines. Defaults to a line feed character. The string <sep> may contain the literal formatting codes described above. To use comma as separator one must use `%x2C` as it would otherwise be parsed as - next option. E.g., `%(trailers:key=Ticket,separator=%x2C )` + next option. E.g., +%(trailers:key=Ticket,separator=%x2C )+ shows all trailer lines whose key is "Ticket" separated by a comma and a space. -** 'unfold[=<bool>]': make it behave as if interpret-trailer's `--unfold` +** `unfold[=<bool>]`: make it behave as if interpret-trailer's `--unfold` option was given. E.g., - `%(trailers:only,unfold=true)` unfolds and shows all trailer lines. -** 'keyonly[=<bool>]': only show the key part of the trailer. -** 'valueonly[=<bool>]': only show the value part of the trailer. -** 'key_value_separator=<sep>': specify the separator inserted between + +%(trailers:only,unfold=true)+ unfolds and shows all trailer lines. +** `keyonly[=<bool>]`: only show the key part of the trailer. +** `valueonly[=<bool>]`: only show the value part of the trailer. +** `key_value_separator=<sep>`: specify the separator inserted between the key and value of each trailer. Defaults to ": ". Otherwise it - shares the same semantics as 'separator=<sep>' above. + shares the same semantics as `separator=<sep>` above. NOTE: Some placeholders may depend on other options given to the -revision traversal engine. For example, the `%g*` reflog options will +revision traversal engine. For example, the +%g*+ reflog options will insert an empty string unless we are traversing reflog entries (e.g., by -`git log -g`). The `%d` and `%D` placeholders will use the "short" +`git log -g`). The +%d+ and +%D+ placeholders will use the "short" decoration format if `--decorate` was not already provided on the command line. The boolean options accept an optional value `[=<bool-value>]`. The -values taken by `--type=bool` git-config[1], like `yes` and `off`, +values taken by `--type=bool` linkgit:git-config[1], like `yes` and `off`, are all accepted. Giving a boolean option without `=<value>` is equivalent to giving it with `=true`. -If you add a `+` (plus sign) after '%' of a placeholder, a line-feed +If you add a `+` (plus sign) after +%+ of a placeholder, a line-feed is inserted immediately before the expansion if and only if the placeholder expands to a non-empty string. -If you add a `-` (minus sign) after '%' of a placeholder, all consecutive +If you add a `-` (minus sign) after +%+ of a placeholder, all consecutive line-feeds immediately preceding the expansion are deleted if and only if the placeholder expands to an empty string. -If you add a ` ` (space) after '%' of a placeholder, a space +If you add a `' '` (space) after +%+ of a placeholder, a space is inserted immediately before the expansion if and only if the placeholder expands to a non-empty string. -* 'tformat:' +* `tformat:` + -The 'tformat:' format works exactly like 'format:', except that it +The `tformat:` format works exactly like `format:`, except that it provides "terminator" semantics instead of "separator" semantics. In other words, each commit has the message terminator character (usually a newline) appended, rather than a separator placed between entries. @@ -378,7 +381,7 @@ $ git log -2 --pretty=tformat:%h 4da45bef \ 7134973 --------------------- + -In addition, any unrecognized string that has a `%` in it is interpreted +In addition, any unrecognized string that has a +%+ in it is interpreted as if it has `tformat:` in front of it. For example, these two are equivalent: + diff --git a/Documentation/pretty-options.adoc b/Documentation/pretty-options.adoc index 23888cd612..8aac51dbe7 100644 --- a/Documentation/pretty-options.adoc +++ b/Documentation/pretty-options.adoc @@ -1,38 +1,38 @@ ---pretty[=<format>]:: ---format=<format>:: +`--pretty[=<format>]`:: +`--format=<format>`:: Pretty-print the contents of the commit logs in a given format, - where '<format>' can be one of 'oneline', 'short', 'medium', - 'full', 'fuller', 'reference', 'email', 'raw', 'format:<string>' - and 'tformat:<string>'. When '<format>' is none of the above, - and has '%placeholder' in it, it acts as if - '--pretty=tformat:<format>' were given. + where '<format>' can be one of `oneline`, `short`, `medium`, + `full`, `fuller`, `reference`, `email`, `raw`, `format:<string>` + and `tformat:<string>`. When _<format>_ is none of the above, + and has `%<placeholder>` in it, it acts as if + `--pretty=tformat:<format>` were given. + See the "PRETTY FORMATS" section for some additional details for each -format. When '=<format>' part is omitted, it defaults to 'medium'. +format. When `=<format>` part is omitted, it defaults to `medium`. + -Note: you can specify the default pretty format in the repository +NOTE: you can specify the default pretty format in the repository configuration (see linkgit:git-config[1]). ---abbrev-commit:: +`--abbrev-commit`:: Instead of showing the full 40-byte hexadecimal commit object name, show a prefix that names the object uniquely. - "--abbrev=<n>" (which also modifies diff output, if it is displayed) + `--abbrev=<n>` (which also modifies diff output, if it is displayed) option can be used to specify the minimum length of the prefix. + -This should make "--pretty=oneline" a whole lot more readable for +This should make `--pretty=oneline` a whole lot more readable for people using 80-column terminals. ---no-abbrev-commit:: +`--no-abbrev-commit`:: Show the full 40-byte hexadecimal commit object name. This negates `--abbrev-commit`, either explicit or implied by other options such - as "--oneline". It also overrides the `log.abbrevCommit` variable. + as `--oneline`. It also overrides the `log.abbrevCommit` variable. ---oneline:: - This is a shorthand for "--pretty=oneline --abbrev-commit" +`--oneline`:: + This is a shorthand for `--pretty=oneline --abbrev-commit` used together. ---encoding=<encoding>:: +`--encoding=<encoding>`:: Commit objects record the character encoding used for the log message in their encoding header; this option can be used to tell the command to re-code the commit log message in the encoding @@ -44,25 +44,30 @@ people using 80-column terminals. to convert the commit, we will quietly output the original object verbatim. ---expand-tabs=<n>:: ---expand-tabs:: ---no-expand-tabs:: +`--expand-tabs=<n>`:: +`--expand-tabs`:: +`--no-expand-tabs`:: Perform a tab expansion (replace each tab with enough spaces - to fill to the next display column that is a multiple of '<n>') + to fill to the next display column that is a multiple of _<n>_) in the log message before showing it in the output. `--expand-tabs` is a short-hand for `--expand-tabs=8`, and `--no-expand-tabs` is a short-hand for `--expand-tabs=0`, which disables tab expansion. + By default, tabs are expanded in pretty formats that indent the log -message by 4 spaces (i.e. 'medium', which is the default, 'full', -and 'fuller'). +message by 4 spaces (i.e. `medium`, which is the default, `full`, +and `fuller`). ifndef::git-rev-list[] ---notes[=<ref>]:: +`--notes[=<ref>]`:: Show the notes (see linkgit:git-notes[1]) that annotate the commit, when showing the commit log message. This is the default +ifndef::with-breaking-changes[] for `git log`, `git show` and `git whatchanged` commands when +endif::with-breaking-changes[] +ifdef::with-breaking-changes[] + for `git log` and `git show` commands when +endif::with-breaking-changes[] there is no `--pretty`, `--format`, or `--oneline` option given on the command line. + @@ -75,28 +80,29 @@ to display. The ref can specify the full refname when it begins with `refs/notes/`; when it begins with `notes/`, `refs/` and otherwise `refs/notes/` is prefixed to form the full name of the ref. + -Multiple --notes options can be combined to control which notes are -being displayed. Examples: "--notes=foo" will show only notes from -"refs/notes/foo"; "--notes=foo --notes" will show both notes from +Multiple `--notes` options can be combined to control which notes are +being displayed. Examples: "`--notes=foo`" will show only notes from +`refs/notes/foo`; "`--notes=foo --notes`" will show both notes from "refs/notes/foo" and from the default notes ref(s). ---no-notes:: +`--no-notes`:: Do not show notes. This negates the above `--notes` option, by resetting the list of notes refs from which notes are shown. Options are parsed in the order given on the command line, so e.g. - "--notes --notes=foo --no-notes --notes=bar" will only show notes - from "refs/notes/bar". + "`--notes --notes=foo --no-notes --notes=bar`" will only show notes + from `refs/notes/bar`. ---show-notes-by-default:: +`--show-notes-by-default`:: Show the default notes unless options for displaying specific notes are given. ---show-notes[=<ref>]:: ---[no-]standard-notes:: - These options are deprecated. Use the above --notes/--no-notes +`--show-notes[=<ref>]`:: +`--standard-notes`:: +`--no-standard-notes`:: + These options are deprecated. Use the above `--notes`/`--no-notes` options instead. endif::git-rev-list[] ---show-signature:: +`--show-signature`:: Check the validity of a signed commit object by passing the signature to `gpg --verify` and show the output. 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-description.adoc b/Documentation/rev-list-description.adoc index a9efa7fa27..82c680e570 100644 --- a/Documentation/rev-list-description.adoc +++ b/Documentation/rev-list-description.adoc @@ -26,8 +26,8 @@ endif::git-log[] means "list all the commits which are reachable from 'foo' or 'bar', but not from 'baz'". -A special notation "'<commit1>'..'<commit2>'" can be used as a -short-hand for "^'<commit1>' '<commit2>'". For example, either of +A special notation "`<commit1>..<commit2>`" can be used as a +short-hand for "`^<commit1> <commit2>`". For example, either of the following may be used interchangeably: ifdef::git-rev-list[] @@ -43,7 +43,7 @@ $ git log HEAD ^origin ----------------------------------------------------------------------- endif::git-log[] -Another special notation is "'<commit1>'...'<commit2>'" which is useful +Another special notation is "`<commit1>...<commit2>`" which is useful for merges. The resulting set of commits is the symmetric difference between the two operands. The following two commands are equivalent: diff --git a/Documentation/rev-list-options.adoc b/Documentation/rev-list-options.adoc index 785c0786e0..d9665d82c8 100644 --- a/Documentation/rev-list-options.adoc +++ b/Documentation/rev-list-options.adoc @@ -6,60 +6,60 @@ special notations explained in the description, additional commit limiting may be applied. Using more options generally further limits the output (e.g. -`--since=<date1>` limits to commits newer than `<date1>`, and using it +`--since=<date1>` limits to commits newer than _<date1>_, and using it with `--grep=<pattern>` further limits to commits whose log message -has a line that matches `<pattern>`), unless otherwise noted. +has a line that matches _<pattern>_), unless otherwise noted. Note that these are applied before commit ordering and formatting options, such as `--reverse`. --<number>:: --n <number>:: ---max-count=<number>:: - Limit the number of commits to output. +`-<number>`:: +`-n <number>`:: +`--max-count=<number>`:: + Limit the output to _<number>_ commits. ---skip=<number>:: - Skip 'number' commits before starting to show the commit output. +`--skip=<number>`:: + Skip _<number>_ commits before starting to show the commit output. ---since=<date>:: ---after=<date>:: - Show commits more recent than a specific date. +`--since=<date>`:: +`--after=<date>`:: + Show commits more recent than _<date>_. ---since-as-filter=<date>:: - Show all commits more recent than a specific date. This visits +`--since-as-filter=<date>`:: + Show all commits more recent than _<date>_. This visits all commits in the range, rather than stopping at the first commit which - is older than a specific date. + is older than _<date>_. ---until=<date>:: ---before=<date>:: - Show commits older than a specific date. +`--until=<date>`:: +`--before=<date>`:: + Show commits older than _<date>_. ifdef::git-rev-list[] ---max-age=<timestamp>:: ---min-age=<timestamp>:: +`--max-age=<timestamp>`:: +`--min-age=<timestamp>`:: Limit the commits output to specified time range. endif::git-rev-list[] ---author=<pattern>:: ---committer=<pattern>:: +`--author=<pattern>`:: +`--committer=<pattern>`:: Limit the commits output to ones with author/committer - header lines that match the specified pattern (regular - expression). With more than one `--author=<pattern>`, - commits whose author matches any of the given patterns are + header lines that match the _<pattern>_ regular + expression. With more than one `--author=<pattern>`, + commits whose author matches any of the _<pattern>_ are chosen (similarly for multiple `--committer=<pattern>`). ---grep-reflog=<pattern>:: +`--grep-reflog=<pattern>`:: Limit the commits output to ones with reflog entries that - match the specified pattern (regular expression). With + match the _<pattern>_ regular expression. With more than one `--grep-reflog`, commits whose reflog message matches any of the given patterns are chosen. It is an error to use this option unless `--walk-reflogs` is in use. ---grep=<pattern>:: +`--grep=<pattern>`:: Limit the commits output to ones with a log message that - matches the specified pattern (regular expression). With + matches the _<pattern>_ regular expression. With more than one `--grep=<pattern>`, commits whose message - matches any of the given patterns are chosen (but see + matches any of the _<pattern>_ are chosen (but see `--all-match`). ifndef::git-rev-list[] + @@ -67,35 +67,35 @@ When `--notes` is in effect, the message from the notes is matched as if it were part of the log message. endif::git-rev-list[] ---all-match:: +`--all-match`:: Limit the commits output to ones that match all given `--grep`, instead of ones that match at least one. ---invert-grep:: +`--invert-grep`:: Limit the commits output to ones with a log message that do not - match the pattern specified with `--grep=<pattern>`. + match the _<pattern>_ specified with `--grep=<pattern>`. --i:: ---regexp-ignore-case:: +`-i`:: +`--regexp-ignore-case`:: Match the regular expression limiting patterns without regard to letter case. ---basic-regexp:: +`--basic-regexp`:: Consider the limiting patterns to be basic regular expressions; this is the default. --E:: ---extended-regexp:: +`-E`:: +`--extended-regexp`:: Consider the limiting patterns to be extended regular expressions instead of the default basic regular expressions. --F:: ---fixed-strings:: +`-F`:: +`--fixed-strings`:: Consider the limiting patterns to be fixed strings (don't interpret pattern as a regular expression). --P:: ---perl-regexp:: +`-P`:: +`--perl-regexp`:: Consider the limiting patterns to be Perl-compatible regular expressions. + @@ -103,20 +103,20 @@ Support for these types of regular expressions is an optional compile-time dependency. If Git wasn't compiled with support for them providing this option will cause it to die. ---remove-empty:: +`--remove-empty`:: Stop when a given path disappears from the tree. ---merges:: +`--merges`:: Print only merge commits. This is exactly the same as `--min-parents=2`. ---no-merges:: +`--no-merges`:: Do not print commits with more than one parent. This is exactly the same as `--max-parents=1`. ---min-parents=<number>:: ---max-parents=<number>:: ---no-min-parents:: ---no-max-parents:: +`--min-parents=<number>`:: +`--max-parents=<number>`:: +`--no-min-parents`:: +`--no-max-parents`:: Show only commits which have at least (or at most) that many parent commits. In particular, `--max-parents=1` is the same as `--no-merges`, `--min-parents=2` is the same as `--merges`. `--max-parents=0` @@ -126,7 +126,7 @@ providing this option will cause it to die. again. Equivalent forms are `--min-parents=0` (any commit has 0 or more parents) and `--max-parents=-1` (negative numbers denote no upper limit). ---first-parent:: +`--first-parent`:: When finding commits to include, follow only the first parent commit upon seeing a merge commit. This option can give a better overview when viewing the evolution of @@ -141,14 +141,14 @@ This option also changes default diff format for merge commits to `first-parent`, see `--diff-merges=first-parent` for details. endif::git-log[] ---exclude-first-parent-only:: +`--exclude-first-parent-only`:: When finding commits to exclude (with a '{caret}'), follow only the first parent commit upon seeing a merge commit. This can be used to find the set of changes in a topic branch from the point where it diverged from the remote branch, given that arbitrary merges can be valid topic branch changes. ---not:: +`--not`:: Reverses the meaning of the '{caret}' prefix (or lack thereof) for all following revision specifiers, up to the next `--not`. When used on the command line before --stdin, the revisions passed @@ -156,37 +156,37 @@ endif::git-log[] via standard input, the revisions passed on the command line will not be affected by it. ---all:: +`--all`:: Pretend as if all the refs in `refs/`, along with `HEAD`, are - listed on the command line as '<commit>'. + listed on the command line as _<commit>_. ---branches[=<pattern>]:: +`--branches[=<pattern>]`:: Pretend as if all the refs in `refs/heads` are listed - on the command line as '<commit>'. If '<pattern>' is given, limit - branches to ones matching given shell glob. If pattern lacks '?', + on the command line as _<commit>_. If _<pattern>_ is given, limit + branches to ones matching given shell glob. If _<pattern>_ lacks '?', '{asterisk}', or '[', '/{asterisk}' at the end is implied. ---tags[=<pattern>]:: +`--tags[=<pattern>]`:: Pretend as if all the refs in `refs/tags` are listed - on the command line as '<commit>'. If '<pattern>' is given, limit + on the command line as _<commit>_. If _<pattern>_ is given, limit tags to ones matching given shell glob. If pattern lacks '?', '{asterisk}', or '[', '/{asterisk}' at the end is implied. ---remotes[=<pattern>]:: +`--remotes[=<pattern>]`:: Pretend as if all the refs in `refs/remotes` are listed - on the command line as '<commit>'. If '<pattern>' is given, limit + on the command line as _<commit>_. If _<pattern>_ is given, limit remote-tracking branches to ones matching given shell glob. If pattern lacks '?', '{asterisk}', or '[', '/{asterisk}' at the end is implied. ---glob=<glob-pattern>:: - Pretend as if all the refs matching shell glob '<glob-pattern>' - are listed on the command line as '<commit>'. Leading 'refs/', +`--glob=<glob-pattern>`:: + Pretend as if all the refs matching shell glob _<glob-pattern>_ + are listed on the command line as _<commit>_. Leading 'refs/', is automatically prepended if missing. If pattern lacks '?', '{asterisk}', or '[', '/{asterisk}' at the end is implied. ---exclude=<glob-pattern>:: +`--exclude=<glob-pattern>`:: - Do not include refs matching '<glob-pattern>' that the next `--all`, + Do not include refs matching _<glob-pattern>_ that the next `--all`, `--branches`, `--tags`, `--remotes`, or `--glob` would otherwise consider. Repetitions of this option accumulate exclusion patterns up to the next `--all`, `--branches`, `--tags`, `--remotes`, or @@ -199,7 +199,7 @@ respectively, and they must begin with `refs/` when applied to `--glob` or `--all`. If a trailing '/{asterisk}' is intended, it must be given explicitly. ---exclude-hidden=[fetch|receive|uploadpack]:: +`--exclude-hidden=(fetch|receive|uploadpack)`:: Do not include refs that would be hidden by `git-fetch`, `git-receive-pack` or `git-upload-pack` by consulting the appropriate `fetch.hideRefs`, `receive.hideRefs` or `uploadpack.hideRefs` @@ -207,11 +207,11 @@ explicitly. linkgit:git-config[1]). This option affects the next pseudo-ref option `--all` or `--glob` and is cleared after processing them. ---reflog:: +`--reflog`:: Pretend as if all objects mentioned by reflogs are listed on the - command line as `<commit>`. + command line as _<commit>_. ---alternate-refs:: +`--alternate-refs`:: Pretend as if all objects mentioned as ref tips of alternate repositories were listed on the command line. An alternate repository is any repository whose object directory is specified @@ -219,7 +219,7 @@ explicitly. be modified by `core.alternateRefsCommand`, etc. See linkgit:git-config[1]. ---single-worktree:: +`--single-worktree`:: By default, all working trees will be examined by the following options when there are more than one (see linkgit:git-worktree[1]): `--all`, `--reflog` and @@ -227,19 +227,19 @@ explicitly. This option forces them to examine the current working tree only. ---ignore-missing:: +`--ignore-missing`:: Upon seeing an invalid object name in the input, pretend as if the bad input was not given. ifndef::git-rev-list[] ---bisect:: +`--bisect`:: Pretend as if the bad bisection ref `refs/bisect/bad` was listed and as if it was followed by `--not` and the good bisection refs `refs/bisect/good-*` on the command line. endif::git-rev-list[] ---stdin:: +`--stdin`:: In addition to getting arguments from the command line, read them from standard input as well. This accepts commits and pseudo-options like `--all` and `--glob=`. When a `--` separator @@ -249,15 +249,15 @@ endif::git-rev-list[] influence any subsequent command line arguments. ifdef::git-rev-list[] ---quiet:: +`--quiet`:: Don't print anything to standard output. This form is primarily meant to allow the caller to test the exit status to see if a range of objects is fully connected (or not). It is faster than redirecting stdout to `/dev/null` as the output does not have to be formatted. ---disk-usage:: ---disk-usage=human:: +`--disk-usage`:: +`--disk-usage=human`:: Suppress normal output; instead, print the sum of the bytes used for on-disk storage by the selected commits or objects. This is equivalent to piping the output into `git cat-file @@ -269,11 +269,11 @@ ifdef::git-rev-list[] in human-readable string(e.g. 12.24 Kib, 3.50 Mib). endif::git-rev-list[] ---cherry-mark:: +`--cherry-mark`:: Like `--cherry-pick` (see below) but mark equivalent commits with `=` rather than omitting them, and inequivalent ones with `+`. ---cherry-pick:: +`--cherry-pick`:: Omit any commit that introduces the same change as another commit on the ``other side'' when the set of commits are limited with symmetric difference. @@ -286,8 +286,8 @@ cherry-picked from the other branch (for example, ``3rd on b'' may be cherry-picked from branch A). With this option, such pairs of commits are excluded from the output. ---left-only:: ---right-only:: +`--left-only`:: +`--right-only`:: List only commits on the respective side of a symmetric difference, i.e. only those which would be marked `<` resp. `>` by `--left-right`. @@ -298,20 +298,20 @@ commits from `B` which are in `A` or are patch-equivalent to a commit in More precisely, `--cherry-pick --right-only --no-merges` gives the exact list. ---cherry:: +`--cherry`:: A synonym for `--right-only --cherry-mark --no-merges`; useful to limit the output to the commits on our side and mark those that have been applied to the other side of a forked history with `git log --cherry upstream...mybranch`, similar to `git cherry upstream mybranch`. --g:: ---walk-reflogs:: +`-g`:: +`--walk-reflogs`:: Instead of walking the commit ancestry chain, walk reflog entries from the most recent one to older ones. When this option is used you cannot specify commits to - exclude (that is, '{caret}commit', 'commit1..commit2', - and 'commit1\...commit2' notations cannot be used). + exclude (that is, `^<commit>`, `<commit1>..<commit2>`, + and `<commit1>...<commit2>` notations cannot be used). + With `--pretty` format other than `oneline` and `reference` (for obvious reasons), this causes the output to have two extra lines of information @@ -340,27 +340,51 @@ See also linkgit:git-reflog[1]. + Under `--pretty=reference`, this information will not be shown at all. ---merge:: +`--merge`:: Show commits touching conflicted paths in the range `HEAD...<other>`, where `<other>` is the first existing pseudoref in `MERGE_HEAD`, `CHERRY_PICK_HEAD`, `REVERT_HEAD` or `REBASE_HEAD`. Only works when the index has unmerged entries. This option can be used to show relevant commits when resolving conflicts from a 3-way merge. ---boundary:: +`--boundary`:: Output excluded boundary commits. Boundary commits are prefixed with `-`. ifdef::git-rev-list[] ---use-bitmap-index:: +`--use-bitmap-index`:: Try to speed up the traversal using the pack bitmap index (if one is available). Note that when traversing with `--objects`, trees and blobs will not have their associated path printed. ---progress=<header>:: +`--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 @@ -373,62 +397,63 @@ is how to do it, as there are various strategies to simplify the history. The following options select the commits to be shown: -<paths>:: +`<paths>`:: Commits modifying the given <paths> are selected. ---simplify-by-decoration:: +`--simplify-by-decoration`:: Commits that are referred by some branch or tag are selected. Note that extra commits can be shown to give a meaningful history. The following options affect the way the simplification is performed: -Default mode:: +`Default mode`:: Simplifies the history to the simplest history explaining the final state of the tree. Simplest because it prunes some side branches if the end result is the same (i.e. merging branches with the same content) ---show-pulls:: +`--show-pulls`:: Include all commits from the default mode, but also any merge commits that are not TREESAME to the first parent but are TREESAME to a later parent. This mode is helpful for showing the merge commits that "first introduced" a change to a branch. ---full-history:: +`--full-history`:: Same as the default mode, but does not prune some history. ---dense:: +`--dense`:: Only the selected commits are shown, plus some to have a meaningful history. ---sparse:: +`--sparse`:: All commits in the simplified history are shown. ---simplify-merges:: +`--simplify-merges`:: Additional option to `--full-history` to remove some needless merges from the resulting history, as there are no selected commits contributing to this merge. ---ancestry-path[=<commit>]:: - When given a range of commits to display (e.g. 'commit1..commit2' - or 'commit2 {caret}commit1'), and a commit <commit> in that range, +`--ancestry-path[=<commit>]`:: + When given a range of commits to display (e.g. `<commit1>..<commit2>` + or `<commit2> ^<commit1>`), and a commit _<commit>_ in that range, only display commits in that range - that are ancestors of <commit>, descendants of <commit>, or - <commit> itself. If no commit is specified, use 'commit1' (the - excluded part of the range) as <commit>. Can be passed multiple + that are ancestors of _<commit>_, descendants of _<commit>_, or + _<commit>_ itself. If no commit is specified, use _<commit1>_ (the + excluded part of the range) as _<commit>_. Can be passed multiple times; if so, a commit is included if it is any of the commits given or if it is an ancestor or descendant of one of them. A more detailed explanation follows. -Suppose you specified `foo` as the <paths>. We shall call commits +Suppose you specified `foo` as the _<paths>_. We shall call commits that modify `foo` !TREESAME, and the rest TREESAME. (In a diff 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,26 +461,27 @@ 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: * `I` is the initial commit, in which `foo` exists with contents - ``asdf'', and a file `quux` exists with contents ``quux''. Initial + `asdf`, and a file `quux` exists with contents `quux`. Initial commits are compared to an empty tree, so `I` is !TREESAME. -* In `A`, `foo` contains just ``foo''. +* In `A`, `foo` contains just `foo`. * `B` contains the same change as `A`. Its merge `M` is trivial and hence TREESAME to all parents. -* `C` does not change `foo`, but its merge `N` changes it to ``foobar'', +* `C` does not change `foo`, but its merge `N` changes it to `foobar`, so it is not TREESAME to any parent. -* `D` sets `foo` to ``baz''. Its merge `O` combines the strings from - `N` and `D` to ``foobarbaz''; i.e., it is not TREESAME to any parent. +* `D` sets `foo` to `baz`. Its merge `O` combines the strings from + `N` and `D` to `foobarbaz`; i.e., it is not TREESAME to any parent. -* `E` changes `quux` to ``xyzzy'', and its merge `P` combines the - strings to ``quux xyzzy''. `P` is TREESAME to `O`, but not to `E`. +* `E` changes `quux` to `xyzzy`, and its merge `P` combines the + strings to `quux xyzzy`. `P` is TREESAME to `O`, but not to `E`. * `X` is an independent root commit that added a new file `side`, and `Y` modified it. `Y` is TREESAME to `X`. Its merge `Q` added `side` to `P`, and @@ -491,7 +517,7 @@ Parent/child relations are only visible with `--parents`, but that does not affect the commits selected in default mode, so we have shown the parent lines. ---full-history without parent rewriting:: +`--full-history` without parent rewriting:: This mode differs from the default in one point: always follow all parents of a merge, even if it is TREESAME to one of them. Even if more than one side of the merge has commits that are @@ -510,7 +536,7 @@ Note that without parent rewriting, it is not really possible to talk about the parent/child relationships between the commits, so we show them disconnected. ---full-history with parent rewriting:: +`--full-history` with parent rewriting:: Ordinary commits are only included if they are !TREESAME (though this can be changed, see `--sparse` below). + @@ -534,18 +560,18 @@ rewritten to contain `E`'s parent `I`. The same happened for `C` and In addition to the above settings, you can change whether TREESAME affects inclusion: ---dense:: +`--dense`:: Commits that are walked are included if they are not TREESAME to any parent. ---sparse:: +`--sparse`:: All commits that are walked are included. + Note that without `--full-history`, this still simplifies merges: if one of the parents is TREESAME, we follow only that one, so the other sides of the merge are never walked. ---simplify-merges:: +`--simplify-merges`:: First, build a history graph in the same way that `--full-history` with parent rewriting does (see above). + @@ -592,9 +618,9 @@ Note the major differences in `N`, `P`, and `Q` over `--full-history`: There is another simplification mode available: ---ancestry-path[=<commit>]:: +`--ancestry-path[=<commit>]`:: Limit the displayed commits to those which are an ancestor of - <commit>, or which are a descendant of <commit>, or are <commit> + _<commit>_, or which are a descendant of _<commit>_, or are _<commit>_ itself. + As an example use case, consider the following commit history: @@ -610,15 +636,15 @@ As an example use case, consider the following commit history: A regular 'D..M' computes the set of commits that are ancestors of `M`, but excludes the ones that are ancestors of `D`. This is useful to see what happened to the history leading to `M` since `D`, in the sense -that ``what does `M` have that did not exist in `D`''. The result in this +that "what does `M` have that did not exist in `D`". The result in this example would be all the commits, except `A` and `B` (and `D` itself, of course). + When we want to find out what commits in `M` are contaminated with the bug introduced by `D` and need fixing, however, we might want to view -only the subset of 'D..M' that are actually descendants of `D`, i.e. +only the subset of `D..M` that are actually descendants of `D`, i.e. excluding `C` and `K`. This is exactly what the `--ancestry-path` -option does. Applied to the 'D..M' range, it results in: +option does. Applied to the `D..M` range, it results in: + ----------------------------------------------------------------------- E-------F @@ -629,7 +655,7 @@ option does. Applied to the 'D..M' range, it results in: ----------------------------------------------------------------------- + We can also use `--ancestry-path=D` instead of `--ancestry-path` which -means the same thing when applied to the 'D..M' range but is just more +means the same thing when applied to the `D..M` range but is just more explicit. + If we instead are interested in a given topic within this range, and all @@ -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 ----------------------------------------------------------------------- @@ -744,7 +770,7 @@ into the important branch. This commit may have information about why the change `X` came to override the changes from `A` and `B` in its commit message. ---show-pulls:: +`--show-pulls`:: In addition to the commits shown in the default history, show each merge commit that is not TREESAME to its first parent but is TREESAME to a later parent. @@ -793,7 +819,7 @@ ifdef::git-rev-list[] Bisection Helpers ~~~~~~~~~~~~~~~~~ ---bisect:: +`--bisect`:: Limit output to the one commit object which is roughly halfway between included and excluded commits. Note that the bad bisection ref `refs/bisect/bad` is added to the included commits (if it @@ -817,7 +843,7 @@ introduces a regression is thus reduced to a binary search: repeatedly generate and test new 'midpoint's until the commit chain is of length one. ---bisect-vars:: +`--bisect-vars`:: This calculates the same as `--bisect`, except that refs in `refs/bisect/` are not used, and except that this outputs text ready to be eval'ed by the shell. These lines will assign the @@ -829,7 +855,7 @@ one. `bisect_bad`, and the number of commits we are bisecting right now to `bisect_all`. ---bisect-all:: +`--bisect-all`:: This outputs all the commit objects between the included and excluded commits, ordered by their distance to the included and excluded commits. Refs in `refs/bisect/` are not used. The farthest @@ -852,15 +878,15 @@ Commit Ordering By default, the commits are shown in reverse chronological order. ---date-order:: +`--date-order`:: Show no parents before all of its children are shown, but otherwise show commits in the commit timestamp order. ---author-date-order:: +`--author-date-order`:: Show no parents before all of its children are shown, but otherwise show commits in the author timestamp order. ---topo-order:: +`--topo-order`:: Show no parents before all of its children are shown, and avoid showing commits on multiple lines of history intermixed. @@ -884,8 +910,8 @@ With `--topo-order`, they would show 8 6 5 3 7 4 2 1 (or 8 7 4 2 6 5 avoid showing the commits from two parallel development track mixed together. ---reverse:: - Output the commits chosen to be shown (see Commit Limiting +`--reverse`:: + Output the commits chosen to be shown (see 'Commit Limiting' section above) in reverse order. Cannot be combined with `--walk-reflogs`. endif::git-shortlog[] @@ -897,39 +923,39 @@ Object Traversal These options are mostly targeted for packing of Git repositories. ifdef::git-rev-list[] ---objects:: +`--objects`:: Print the object IDs of any object referenced by the listed - commits. `--objects foo ^bar` thus means ``send me + commits. `--objects foo ^bar` thus means "send me all object IDs which I need to download if I have the commit - object _bar_ but not _foo_''. See also `--object-names` below. + object `bar` but not `foo`". See also `--object-names` below. ---in-commit-order:: +`--in-commit-order`:: Print tree and blob ids in order of the commits. The tree and blob ids are printed after they are first referenced by a commit. ---objects-edge:: +`--objects-edge`:: Similar to `--objects`, but also print the IDs of excluded - commits prefixed with a ``-'' character. This is used by + commits prefixed with a "`-`" character. This is used by linkgit:git-pack-objects[1] to build a ``thin'' pack, which records objects in deltified form based on objects contained in these excluded commits to reduce network traffic. ---objects-edge-aggressive:: +`--objects-edge-aggressive`:: Similar to `--objects-edge`, but it tries harder to find excluded commits at the cost of increased time. This is used instead of `--objects-edge` to build ``thin'' packs for shallow repositories. ---indexed-objects:: +`--indexed-objects`:: Pretend as if all trees and blobs used by the index are listed on the command line. Note that you probably want to use `--objects`, too. ---unpacked:: +`--unpacked`:: Only useful with `--objects`; print the object IDs that are not in packs. ---object-names:: +`--object-names`:: Only useful with `--objects`; print the names of the object IDs that are found. This is the default behavior. Note that the "name" of each object is ambiguous, and mostly intended as a @@ -938,52 +964,52 @@ ifdef::git-rev-list[] to remove newlines; and if an object would appear multiple times with different names, only one name is shown. ---no-object-names:: +`--no-object-names`:: Only useful with `--objects`; does not print the names of the object IDs that are found. This inverts `--object-names`. This flag allows the output to be more easily parsed by commands such as linkgit:git-cat-file[1]. ---filter=<filter-spec>:: +`--filter=<filter-spec>`:: Only useful with one of the `--objects*`; omits objects (usually - blobs) from the list of printed objects. The '<filter-spec>' + blobs) from the list of printed objects. The _<filter-spec>_ may be one of the following: + -The form '--filter=blob:none' omits all blobs. +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' +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 +The form `--filter=object:type=(tag|commit|tree|blob)` omits all objects which are not of the requested type. + -The form '--filter=sparse:oid=<blob-ish>' uses a sparse-checkout -specification contained in the blob (or blob-expression) '<blob-ish>' +The form `--filter=sparse:oid=<blob-ish>` uses a sparse-checkout +specification contained in the blob (or blob-expression) _<blob-ish>_ to omit blobs that would not be required for a sparse checkout on the requested refs. + -The form '--filter=tree:<depth>' omits all blobs and trees whose depth -from the root tree is >= <depth> (minimum depth if an object is located -at multiple depths in the commits traversed). <depth>=0 will not include +The form `--filter=tree:<depth>` omits all blobs and trees whose depth +from the root tree is >= _<depth>_ (minimum depth if an object is located +at multiple depths in the commits traversed). _<depth>_=0 will not include any trees or blobs unless included explicitly in the command-line (or -standard input when --stdin is used). <depth>=1 will include only the +standard input when `--stdin` is used). _<depth>_=1 will include only the tree and blobs which are referenced directly by a commit reachable from -<commit> or an explicitly-given object. <depth>=2 is like <depth>=1 +_<commit>_ or an explicitly-given object. _<depth>_=2 is like <depth>=1 while also including trees and blobs one more level removed from an explicitly-given commit or tree. + -Note that the form '--filter=sparse:path=<path>' that wants to read +Note that the form `--filter=sparse:path=<path>` that wants to read from an arbitrary path on the filesystem has been dropped for security reasons. + -Multiple '--filter=' flags can be specified to combine filters. Only +Multiple `--filter=` flags can be specified to combine filters. Only objects which are accepted by every filter are included. + -The form '--filter=combine:<filter1>+<filter2>+...<filterN>' can also be +The form `--filter=combine:<filter1>+<filter2>+...<filterN>` can also be used to combined several filters, but this is harder than just repeating -the '--filter' flag and is usually not necessary. Filters are joined by +the `--filter` flag and is usually not necessary. Filters are joined by '{plus}' and individual filters are %-encoded (i.e. URL-encoded). Besides the '{plus}' and '%' characters, the following characters are reserved and also must be encoded: `~!@#$^&*()[]{}\;",<>?`+'`+ @@ -991,52 +1017,52 @@ as well as all characters with ASCII code <= `0x20`, which includes space and newline. + Other arbitrary characters can also be encoded. For instance, -'combine:tree:3+blob:none' and 'combine:tree%3A3+blob%3Anone' are +`combine:tree:3+blob:none` and `combine:tree%3A3+blob%3Anone` are equivalent. ---no-filter:: +`--no-filter`:: Turn off any previous `--filter=` argument. ---filter-provided-objects:: +`--filter-provided-objects`:: Filter the list of explicitly provided objects, which would otherwise always be printed even if they did not match any of the filters. Only useful with `--filter=`. ---filter-print-omitted:: +`--filter-print-omitted`:: Only useful with `--filter=`; prints a list of the objects omitted by the filter. Object IDs are prefixed with a ``~'' character. ---missing=<missing-action>:: +`--missing=<missing-action>`:: A debug option to help with future "partial clone" development. This option specifies how missing objects are handled. + -The form '--missing=error' requests that rev-list stop with an error if +The form `--missing=error` requests that rev-list stop with an error if a missing object is encountered. This is the default action. + -The form '--missing=allow-any' will allow object traversal to continue +The form `--missing=allow-any` will allow object traversal to continue if a missing object is encountered. Missing objects will silently be omitted from the results. + -The form '--missing=allow-promisor' is like 'allow-any', but will only +The form `--missing=allow-promisor` is like `allow-any`, but will only allow object traversal to continue for EXPECTED promisor missing objects. Unexpected missing objects will raise an error. + -The form '--missing=print' is like 'allow-any', but will also print a +The form `--missing=print` is like `allow-any`, but will also print a list of the missing objects. Object IDs are prefixed with a ``?'' character. + -The form '--missing=print-info' is like 'print', but will also print additional +The form `--missing=print-info` is like `print`, but will also print additional information about the missing object inferred from its containing object. The information is all printed on the same line with the missing object ID in the form: `?<oid> [<token>=<value>]...`. The `<token>=<value>` pairs containing -additional information are separated from each other by a SP. The value is -encoded in a token specific fashion, but SP or LF contained in value are always +additional information are separated from each other by a _SP_. The value is +encoded in a token specific fashion, but _SP_ or _LF_ contained in value are always expected to be represented in such a way that the resulting encoded value does not have either of these two problematic bytes. Each `<token>=<value>` may be one of the following: + -- * The `path=<path>` shows the path of the missing object inferred from a - containing object. A path containing SP or special characters is enclosed in + containing object. A path containing _SP_ or special characters is enclosed in double-quotes in the C style as needed. + * The `type=<type>` shows the type of the missing object inferred from a @@ -1047,7 +1073,7 @@ If some tips passed to the traversal are missing, they will be considered as missing too, and the traversal will ignore them. In case we cannot get their Object ID though, an error will be raised. ---exclude-promisor-objects:: +`--exclude-promisor-objects`:: (For internal use only.) Prefilter object traversal at promisor boundary. This is used with partial clone. This is stronger than `--missing=allow-promisor` because it limits the @@ -1055,7 +1081,7 @@ we cannot get their Object ID though, an error will be raised. objects. endif::git-rev-list[] ---no-walk[=(sorted|unsorted)]:: +`--no-walk[=(sorted|unsorted)]`:: Only show the given commits, but do not traverse their ancestors. This has no effect if a range is specified. If the argument `unsorted` is given, the commits are shown in the order they were @@ -1064,7 +1090,7 @@ endif::git-rev-list[] by commit time. Cannot be combined with `--graph`. ---do-walk:: +`--do-walk`:: Overrides a previous `--no-walk`. endif::git-shortlog[] @@ -1074,16 +1100,21 @@ Commit Formatting ifdef::git-rev-list[] Using these options, linkgit:git-rev-list[1] will act similar to the -more specialized family of commit log tools: linkgit:git-log[1], -linkgit:git-show[1], and linkgit:git-whatchanged[1] +more specialized family of commit log tools: +ifndef::with-breaking-changes[] +linkgit:git-log[1], linkgit:git-show[1], and linkgit:git-whatchanged[1]. +endif::with-breaking-changes[] +ifdef::with-breaking-changes[] +linkgit:git-log[1] and linkgit:git-show[1]. +endif::with-breaking-changes[] endif::git-rev-list[] include::pretty-options.adoc[] ---relative-date:: +`--relative-date`:: Synonym for `--date=relative`. ---date=<format>:: +`--date=<format>`:: Only takes effect for dates shown in human-readable format, such as when using `--pretty`. `log.date` config variable sets a default value for the log command's `--date` option. By default, dates @@ -1133,12 +1164,12 @@ omitted. 1970). As with `--raw`, this is always in UTC and therefore `-local` has no effect. -`--date=format:...` feeds the format `...` to your system `strftime`, -except for %s, %z, and %Z, which are handled internally. +`--date=format:<format>` feeds the _<format>_ to your system `strftime`, +except for `%s`, `%z`, and `%Z`, which are handled internally. Use `--date=format:%c` to show the date in your system locale's -preferred format. See the `strftime` manual for a complete list of +preferred format. See the `strftime`(3) manual for a complete list of format placeholders. When using `-local`, the correct syntax is -`--date=format-local:...`. +`--date=format-local:<format>`. `--date=default` is the default format, and is based on ctime(3) output. It shows a single line with three-letter day of the week, @@ -1148,33 +1179,33 @@ the local time zone is used, e.g. `Thu Jan 1 00:00:00 1970 +0000`. -- ifdef::git-rev-list[] ---header:: +`--header`:: Print the contents of the commit in raw-format; each record is separated with a NUL character. ---no-commit-header:: +`--no-commit-header`:: Suppress the header line containing "commit" and the object ID printed before the specified format. This has no effect on the built-in formats; only custom formats are affected. ---commit-header:: +`--commit-header`:: Overrides a previous `--no-commit-header`. endif::git-rev-list[] ---parents:: +`--parents`:: Print also the parents of the commit (in the form "commit parent..."). Also enables parent rewriting, see 'History Simplification' above. ---children:: +`--children`:: Print also the children of the commit (in the form "commit child..."). Also enables parent rewriting, see 'History Simplification' above. ifdef::git-rev-list[] ---timestamp:: +`--timestamp`:: Print the raw commit timestamp. endif::git-rev-list[] ---left-right:: +`--left-right`:: Mark which side of a symmetric difference a commit is reachable from. Commits from the left side are prefixed with `<` and those from the right with `>`. If combined with `--boundary`, those @@ -1203,7 +1234,7 @@ you would get an output like this: -xxxxxxx... 1st on a ----------------------------------------------------------------------- ---graph:: +`--graph`:: Draw a text-based graphical representation of the commit history on the left hand side of the output. This may cause extra lines to be printed in between commits, in order for the graph history @@ -1215,15 +1246,15 @@ This enables parent rewriting, see 'History Simplification' above. This implies the `--topo-order` option by default, but the `--date-order` option may also be specified. ---show-linear-break[=<barrier>]:: - When --graph is not used, all history branches are flattened +`--show-linear-break[=<barrier>]`:: + When `--graph` is not used, all history branches are flattened which can make it hard to see that the two consecutive commits do not belong to a linear branch. This option puts a barrier - in between them in that case. If `<barrier>` is specified, it + in between them in that case. If _<barrier>_ is specified, it is the string that will be shown instead of the default one. ifdef::git-rev-list[] ---count:: +`--count`:: Print a number stating how many commits would have been listed, and suppress all other output. When used together with `--left-right`, instead print the counts for left and diff --git a/Documentation/scalar.adoc b/Documentation/scalar.adoc index 7e4259c674..f81b2832f8 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> @@ -71,7 +71,8 @@ HEAD[:<directory>]`. Instead of checking out the branch pointed to by the cloned repository's HEAD, check out the `<name>` branch instead. ---[no-]single-branch:: +--single-branch:: +--no-single-branch:: Clone only the history leading to the tip of a single branch, either specified by the `--branch` option or the primary branch remote's `HEAD` points at. @@ -81,22 +82,31 @@ remote-tracking branch for the branch this option was used for the initial cloning. If the HEAD at the remote did not point at any branch when `--single-branch` clone was made, no remote-tracking branch is created. ---[no-]src:: +--src:: +--no-src:: By default, `scalar clone` places the cloned repository within a `<entlistment>/src` directory. Use `--no-src` to place the cloned repository directly in the `<enlistment>` directory. ---[no-]tags:: +--tags:: +--no-tags:: By default, `scalar clone` will fetch the tag objects advertised by the remote and future `git fetch` commands will do the same. Use `--no-tags` to avoid fetching tags in `scalar clone` and to configure the repository to avoid fetching tags in the future. To fetch tags after cloning with `--no-tags`, run `git fetch --tags`. ---[no-]full-clone:: +--full-clone:: +--no-full-clone:: A sparse-checkout is initialized by default. This behavior can be turned off via `--full-clone`. +--maintenance:: +--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 +127,13 @@ 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. +--maintenance:: +--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 +166,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 34c905eb9c..a67de1b143 100644 --- a/Documentation/technical/api-path-walk.adoc +++ b/Documentation/technical/api-path-walk.adoc @@ -39,7 +39,10 @@ It is also important that you do not specify the `--objects` flag for the the objects will be walked in a separate way based on those starting commits. -`commits`, `blobs`, `trees`, `tags`:: +`commits`:: +`blobs`:: +`trees`:: +`tags`:: By default, these members are enabled and signal that the path-walk API should call the `path_fn` on objects of these types. Specialized applications could disable some options to make it simpler to walk 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/long-running-process-protocol.adoc b/Documentation/technical/long-running-process-protocol.adoc index 6f33654b42..39bd89d467 100644 --- a/Documentation/technical/long-running-process-protocol.adoc +++ b/Documentation/technical/long-running-process-protocol.adoc @@ -24,6 +24,7 @@ After the version negotiation Git sends a list of all capabilities that it supports and a flush packet. Git expects to read a list of desired capabilities, which must be a subset of the supported capabilities list, and a flush packet as response: + ------------------------ packet: git> git-filter-client packet: git> version=2 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 d968659354..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. @@ -442,7 +440,7 @@ understanding these differences can be beneficial. * blame (only matters when one or more -C flags are passed) * and annotate * log - * whatchanged + * whatchanged (may not exist anymore) * ls-files * diff-index * diff-tree diff --git a/Documentation/user-manual.adoc b/Documentation/user-manual.adoc index d2b478ad23..7696987117 100644 --- a/Documentation/user-manual.adoc +++ b/Documentation/user-manual.adoc @@ -4240,7 +4240,7 @@ command `git`. The source side of a builtin is - an entry in `BUILTIN_OBJECTS` in the `Makefile`. Sometimes, more than one builtin is contained in one source file. For -example, `cmd_whatchanged()` and `cmd_log()` both reside in `builtin/log.c`, +example, `cmd_show()` and `cmd_log()` both reside in `builtin/log.c`, since they share quite a bit of code. In that case, the commands which are _not_ named like the `.c` file in which they live have to be listed in `BUILT_INS` in the `Makefile`. @@ -4270,7 +4270,7 @@ So, look into `builtin/cat-file.c`, search for `cmd_cat_file()` and look what it does. ------------------------------------------------------------------ - git_config(git_default_config); + repo_config(the_repository, git_default_config); if (argc != 3) usage("git cat-file [-t|-s|-e|-p|<type>] <sha1>"); if (get_sha1(argv[2], sha1)) @@ -4301,11 +4301,11 @@ Now, for the meat: ----------------------------------------------------------------------------- case 0: - buf = read_object_with_reference(sha1, argv[1], &size, NULL); + buf = odb_read_object_peeled(r->objects, sha1, argv[1], &size, NULL); ----------------------------------------------------------------------------- This is how you read a blob (actually, not only a blob, but any type of -object). To know how the function `read_object_with_reference()` actually +object). To know how the function `odb_read_object_peeled()` actually works, find the source code for it (something like `git grep read_object_with | grep ":[a-z]"` in the Git repository), and read the source. |