diff --git a/.gitattributes b/.gitattributes index 1048ea7eb68b8e..a727d7ab9bdcb1 100644 --- a/.gitattributes +++ b/.gitattributes @@ -14,6 +14,7 @@ CODE_OF_CONDUCT.md -whitespace /mergetools/* text eol=lf /t/oid-info/* text eol=lf /Documentation/git-merge.adoc conflict-marker-size=32 +/Documentation/git-merge-file.adoc conflict-marker-size=32 /Documentation/gitk.adoc conflict-marker-size=32 /Documentation/user-manual.adoc conflict-marker-size=32 /t/t????-*.sh conflict-marker-size=32 diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index b104a97347f2c1..14e598bac16818 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -268,7 +268,7 @@ jobs: run: pip install meson ninja - name: Setup shell: pwsh - run: meson setup build -Dperl=disabled -Dcredential_helpers=wincred + run: meson setup build --vsenv -Dbuildtype=release -Dperl=disabled -Dcredential_helpers=wincred - name: Compile shell: pwsh run: meson compile -C build @@ -352,6 +352,7 @@ jobs: if: needs.ci-config.outputs.enabled == 'yes' env: CC: clang + CI_JOB_IMAGE: ubuntu-latest runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 @@ -410,12 +411,27 @@ jobs: jobname: ${{matrix.vector.jobname}} CC: ${{matrix.vector.cc}} CI_JOB_IMAGE: ${{matrix.vector.image}} + CUSTOM_PATH: /custom runs-on: ubuntu-latest container: ${{matrix.vector.image}} steps: - name: prepare libc6 for actions if: matrix.vector.jobname == 'linux32' run: apt -q update && apt -q -y install libc6-amd64 lib64stdc++6 + - name: install git in container + run: | + if command -v git + then + : # nothing to do + elif command -v apk + then + apk add --update git + elif command -v dnf + then + dnf -yq update && dnf -yq install git + else + apt-get -q update && apt-get -q -y install git + fi - uses: actions/checkout@v4 - run: ci/install-dependencies.sh - run: useradd builder --create-home @@ -435,6 +451,7 @@ jobs: if: needs.ci-config.outputs.enabled == 'yes' env: jobname: StaticAnalysis + CI_JOB_IMAGE: ubuntu-22.04 runs-on: ubuntu-22.04 concurrency: group: static-analysis-${{ github.ref }} @@ -449,6 +466,7 @@ jobs: if: needs.ci-config.outputs.enabled == 'yes' env: jobname: sparse + CI_JOB_IMAGE: ubuntu-22.04 runs-on: ubuntu-22.04 concurrency: group: sparse-${{ github.ref }} @@ -467,6 +485,7 @@ jobs: cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} env: jobname: Documentation + CI_JOB_IMAGE: ubuntu-latest runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 diff --git a/.github/workflows/monitor-components.yml b/.github/workflows/monitor-components.yml index 495425c0e53c2d..65d212ba194699 100644 --- a/.github/workflows/monitor-components.yml +++ b/.github/workflows/monitor-components.yml @@ -68,6 +68,9 @@ jobs: title-pattern: ^libgcrypt-[0-9\.]*$ - label: gpg feed: https://github.com/gpg/gnupg/releases.atom + # As per https://gnupg.org/download/index.html#sec-1-1, the stable + # versions are the one with an even minor version number. + title-pattern: ^gnupg-\d+\.\d*[02468]\. - label: mintty feed: https://github.com/mintty/mintty/releases.atom - label: 7-zip diff --git a/.gitignore b/.gitignore index c7301ec6944e5c..a58ffc8d1a73d3 100644 --- a/.gitignore +++ b/.gitignore @@ -55,6 +55,7 @@ /git-diff /git-diff-files /git-diff-index +/git-diff-pairs /git-diff-tree /git-difftool /git-difftool--helper diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 2805cdeecb6a54..bb6d5b976cdc36 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -164,7 +164,7 @@ build:msvc-meson: extends: .msvc-meson stage: build script: - - meson setup build -Dperl=disabled -Dbackend_max_links=1 -Dcredential_helpers=wincred + - meson setup build --vsenv -Dperl=disabled -Dbackend_max_links=1 -Dcredential_helpers=wincred - meson compile -C build artifacts: paths: @@ -173,7 +173,6 @@ build:msvc-meson: test:msvc-meson: extends: .msvc-meson stage: test - when: manual timeout: 6h needs: - job: "build:msvc-meson" diff --git a/Documentation/BreakingChanges.adoc b/Documentation/BreakingChanges.adoc index bdfad29d8a9e3d..61bdd586b9edb2 100644 --- a/Documentation/BreakingChanges.adoc +++ b/Documentation/BreakingChanges.adoc @@ -178,6 +178,12 @@ 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. + + == 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 a0e7041c54b497..c1046abfb7d10b 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -861,6 +861,9 @@ Markup: __ __ +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 diff --git a/Documentation/Makefile b/Documentation/Makefile index 671267a8ac7af6..b109d25e9c804d 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -109,6 +109,7 @@ SP_ARTICLES += howto/coordinate-embargoed-releases API_DOCS = $(patsubst %.adoc,%,$(filter-out technical/api-index-skel.adoc technical/api-index.adoc, $(wildcard technical/api-*.adoc))) SP_ARTICLES += $(API_DOCS) +TECH_DOCS += BreakingChanges TECH_DOCS += DecisionMaking TECH_DOCS += ReviewingGuidelines TECH_DOCS += MyFirstContribution @@ -316,8 +317,8 @@ cmds_txt = cmds-ancillaryinterrogators.adoc \ $(cmds_txt): cmd-list.made -cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT) - $(QUIET_GEN)$(PERL_PATH) ./cmd-list.perl .. . $(cmds_txt) && \ +cmd-list.made: cmd-list.sh ../command-list.txt $(MAN1_TXT) + $(QUIET_GEN)$(SHELL_PATH) ./cmd-list.sh .. . $(cmds_txt) && \ date >$@ mergetools-%.adoc: generate-mergetool-list.sh ../git-mergetool--lib.sh $(wildcard ../mergetools/*) @@ -397,9 +398,9 @@ user-manual.html: user-manual.xml $(XSLT) git.info: user-manual.texi $(QUIET_MAKEINFO)$(MAKEINFO) --no-split -o $@ user-manual.texi -user-manual.texi: user-manual.xml +user-manual.texi: user-manual.xml fix-texi.sh $(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout >$@+ && \ - $(PERL_PATH) fix-texi.perl <$@+ >$@ && \ + $(SHELL_PATH) fix-texi.sh <$@+ >$@ && \ $(RM) $@+ user-manual.pdf: user-manual.xml @@ -509,7 +510,7 @@ 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 >tmp-meson-diff/actual.adoc && \ if ! cmp tmp-meson-diff/meson.adoc tmp-meson-diff/actual.adoc; then \ echo "Meson man pages differ from actual man pages:"; \ diff -u tmp-meson-diff/meson.adoc tmp-meson-diff/actual.adoc; \ diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc index afcf4b46c11ab2..aca7212cfe2a42 100644 --- a/Documentation/MyFirstContribution.adoc +++ b/Documentation/MyFirstContribution.adoc @@ -40,14 +40,6 @@ the list by sending an email to The https://lore.kernel.org/git[archive] of this mailing list is available to view in a browser. -==== https://groups.google.com/forum/#!forum/git-mentoring[git-mentoring@googlegroups.com] - -This mailing list is targeted to new contributors and was created as a place to -post questions and receive answers outside of the public eye of the main list. -Veteran contributors who are especially interested in helping mentor newcomers -are present on the list. In order to avoid search indexers, group membership is -required to view messages; anyone can join and no approval is required. - ==== https://web.libera.chat/#git-devel[#git-devel] on Libera Chat This IRC channel is for conversations between Git contributors. If someone is @@ -150,15 +142,31 @@ command in `builtin/psuh.c`. Create that file, and within it, write the entry point for your command in a function matching the style and signature: ---- -int cmd_psuh(int argc, const char **argv, const char *prefix) +int cmd_psuh(int argc UNUSED, const char **argv UNUSED, + const char *prefix UNUSED, struct repository *repo UNUSED) ---- +A few things to note: + +* A subcommand implementation takes its command line arguments + in `int argc` + `const char **argv`, like `main()` would. + +* It also takes two extra parameters, `prefix` and `repo`. What + they mean will not be discussed until much later. + +* Because this first example will not use any of the parameters, + your compiler will give warnings on unused parameters. As the + list of these four parameters is mandated by the API to add + new built-in commands, you cannot omit them. Instead, you add + `UNUSED` to each of them to tell the compiler that you *know* + you are not (yet) using it. + We'll also need to add the declaration of psuh; open up `builtin.h`, find the declaration for `cmd_pull`, and add a new line for `psuh` immediately before it, in order to keep the declarations alphabetically sorted: ---- -int cmd_psuh(int argc, const char **argv, const char *prefix); +int cmd_psuh(int argc, const char **argv, const char *prefix, struct repository *repo); ---- Be sure to `#include "builtin.h"` in your `psuh.c`. You'll also need to @@ -174,7 +182,8 @@ Throughout the tutorial, we will mark strings for translation as necessary; you should also do so when writing your user-facing commands in the future. ---- -int cmd_psuh(int argc, const char **argv, const char *prefix) +int cmd_psuh(int argc UNUSED, const char **argv UNUSED, + const char *prefix UNUSED, struct repository *repo UNUSED) { printf(_("Pony saying hello goes here.\n")); return 0; @@ -287,8 +296,9 @@ on the reference implementation linked at the top of this document. It's probably useful to do at least something besides printing out a string. Let's start by having a look at everything we get. -Modify your `cmd_psuh` implementation to dump the args you're passed, keeping -existing `printf()` calls in place: +Modify your `cmd_psuh` implementation to dump the args you're passed, +keeping existing `printf()` calls in place; because the args are now +used, remove the `UNUSED` macro from them: ---- int i; @@ -312,7 +322,8 @@ on the command line, including the name of our command. (If `prefix` is empty for you, try `cd Documentation/ && ../bin-wrappers/git psuh`). That's not so helpful. So what other context can we get? -Add a line to `#include "config.h"`. Then, add the following bits to the +Add a line to `#include "config.h"` and `#include "repository.h"`. +Then, add the following bits to the function body: function body: ---- @@ -320,18 +331,18 @@ function body: ... - git_config(git_default_config, NULL); - if (git_config_get_string_tmp("user.name", &cfg_name) > 0) + repo_config(repo, git_default_config, NULL); + if (repo_config_get_string_tmp(repo, "user.name", &cfg_name)) printf(_("No name is found in config\n")); else printf(_("Your name: %s\n"), cfg_name); ---- -`git_config()` will grab the configuration from config files known to Git and -apply standard precedence rules. `git_config_get_string_tmp()` will look up +`repo_config()` will grab the configuration from config files known to Git and +apply standard precedence rules. `repo_config_get_string_tmp()` will look up a specific key ("user.name") and give you the value. There are a number of single-key lookup functions like this one; you can see them all (and more info -about how to use `git_config()`) in `Documentation/technical/api-config.adoc`. +about how to use `repo_config()`) in `Documentation/technical/api-config.adoc`. You should see that the name printed matches the one you see when you run: @@ -364,9 +375,10 @@ status_init_config(&s, git_status_config); ---- But as we drill down, we can find that `status_init_config()` wraps a call -to `git_config()`. Let's modify the code we wrote in the previous commit. +to `repo_config()`. Let's modify the code we wrote in the previous commit. Be sure to include the header to allow you to use `struct wt_status`: + ---- #include "wt-status.h" ---- @@ -379,8 +391,8 @@ prepare it, and print its contents: ... - wt_status_prepare(the_repository, &status); - git_config(git_default_config, &status); + wt_status_prepare(repo, &status); + repo_config(repo, git_default_config, &status); ... diff --git a/Documentation/MyFirstObjectWalk.adoc b/Documentation/MyFirstObjectWalk.adoc index d6e9dfdbbe232e..bfe8f5f5611209 100644 --- a/Documentation/MyFirstObjectWalk.adoc +++ b/Documentation/MyFirstObjectWalk.adoc @@ -287,6 +287,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 +296,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. ==== diff --git a/Documentation/RelNotes/2.50.0.adoc b/Documentation/RelNotes/2.50.0.adoc new file mode 100644 index 00000000000000..c6c34d1a1d60eb --- /dev/null +++ b/Documentation/RelNotes/2.50.0.adoc @@ -0,0 +1,389 @@ +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 all-or-none + 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 "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. + + +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. + + * 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 in the + 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. + + +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 []" with only the configured fetch refspec + should be the only thing to update refs/remotes//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/nulll + (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. + (merge 436a42215e js/windows-arm64 later to maint). + * 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 develper 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). + + * 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). diff --git a/Documentation/ToolsForGit.adoc b/Documentation/ToolsForGit.adoc index ae7690b45d08b3..a842c1332797fb 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 f2aef6cb79f47c..9d9139306e6f75 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'\1', re.sub(r'([\[\s|()>]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1\2', re.sub(r'(\.\.\.?)([^\]$.])', r'\1\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'\1', re.sub(r'([\[\s|()>]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@\\\*\/_^\$]+\.?)+|,)',r'\1\2', re.sub(r'(\.\.\.?)([^\]$.])', r'\1\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= {target}{0?({0})} [literal-inlinemacro] -{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'\1', re.sub(r'([\[\s|()>]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1\2', re.sub(r'(\.\.\.?)([^\]$.])', r'\1\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'\1', re.sub(r'([\[\s|()>]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,\\\*\/_^\$]+\.?)+)',r'\1\2', re.sub(r'(\.\.\.?)([^\]$.])', r'\1\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!…\\(\\]\\|$\\)!\\0!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.]\\+\\|…\\)!\\1\\2!g;s!<[-a-zA-Z0-9.]\\+>!\\0!g'" +synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!\\0!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1\\2!g;s!<[-a-zA-Z0-9.]\\+>!\\0!g'" endif::doctype-manpage[] endif::backend-docbook[] ifdef::backend-xhtml11[] [paradef-default] -synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!\\0!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.]\\+\\|…\\)!\\1\\2!g;s!<[-a-zA-Z0-9.]\\+>!\\0!g'" +synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!\\0!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1\\2!g;s!<[-a-zA-Z0-9.]\\+>!\\0!g'" endif::backend-xhtml11[] diff --git a/Documentation/asciidoctor-extensions.rb.in b/Documentation/asciidoctor-extensions.rb.in index 2494f17a514d9d..8b7b1613496748 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 %() elsif type == :monospaced - node.text.gsub(/(\.\.\.?)([^\]$.])/, '\1\2') - .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1\2') + node.text.gsub(/(\.\.\.?)([^\]$\.])/, '\1\2') + .gsub(/^\.\.\.?$/, '\0') + .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@/_^\$\\\*]+\.{0,2})+|,)}, '\1\2') .gsub(/(<[-a-zA-Z0-9.]+>)/, '\1') 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(/(\.\.\.?)([^\]$.])/, '\1\2') - .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1\2') + .gsub(/^\.\.\.?$/, '\0') + .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,/_^\$\\\*]+\.{0,2})+)}, '\1\2') .gsub(/(<[-a-zA-Z0-9.]+>)/, '\1') else diff --git a/Documentation/blame-options.adoc b/Documentation/blame-options.adoc index aa77406d4ef335..19ea1872388ffe 100644 --- a/Documentation/blame-options.adoc +++ b/Documentation/blame-options.adoc @@ -125,7 +125,8 @@ take effect. another commit will be marked with a `?` in the blame output. If the `blame.markUnblamableLines` config option is set, then those lines touched by an ignored commit that we could not attribute to another revision are - marked with a '*'. + marked with a '*'. In the porcelain modes, we print 'ignored' and + 'unblamable' on a newline respectively. --ignore-revs-file :: 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 0a0c1b3f611450..00000000000000 --- 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 () { - 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 () { - last if /^### command list/; -} - -my %cmds = (); -for (sort ) { - 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 00000000000000..077def3b721490 --- /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 432b9cd2c0e667..e35ea7ac640d64 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..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..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=" option provided, the + linkgit:git-branch[1]. Without the `--sort=` 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..remote:: - When on branch , it tells 'git fetch' and 'git push' +`branch..remote`:: + When on branch __, 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..remote:: Additionally, `.` (a period) is the current local repository (a dot-repository), see `branch..merge`'s final note below. -branch..pushRemote:: - When on branch , it overrides `branch..remote` for +`branch..pushRemote`:: + When on branch __, it overrides `branch..remote` for pushing. It also overrides `remote.pushDefault` for pushing - from branch . When you pull from one place (e.g. your + from branch __. 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..merge:: - Defines, together with branch..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 , it tells 'git fetch' the default - refspec to be marked for merging in FETCH_HEAD. The value is +`branch..merge`:: + Defines, together with `branch..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 __, 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..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..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 from + If you wish to setup `git pull` so that it merges into from another branch in the local repository, you can point branch..merge to the desired branch, and use the relative path - setting `.` (a period) for branch..remote. + setting `.` (a period) for `branch..remote`. -branch..mergeOptions:: - Sets default options for merging into branch . The syntax and +`branch..mergeOptions`:: + Sets default options for merging into branch __. 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..rebase:: - When true, rebase the branch on top of the fetched branch, +`branch..rebase`:: + When true, rebase the branch __ 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..description:: +`branch..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/core.adoc b/Documentation/config/core.adoc index 5771e10274de8a..1412cebd77a7f5 100644 --- a/Documentation/config/core.adoc +++ b/Documentation/config/core.adoc @@ -512,6 +512,11 @@ centrally configure your Git hooks instead of configuring them on a per-repository basis, or as a more flexible and centralized alternative to having an `init.templateDir` where you've changed default hooks. ++ +You can also disable all hooks entirely by setting `core.hooksPath` +to `/dev/null`. This is usually only advisable for expert users and +on a per-command basis using configuration parameters of the form +`git -c core.hooksPath=/dev/null ...`. core.editor:: Commands such as `commit` and `tag` that let you edit diff --git a/Documentation/config/http.adoc b/Documentation/config/http.adoc index 484a6b574473e7..dedfe63322019d 100644 --- a/Documentation/config/http.adoc +++ b/Documentation/config/http.adoc @@ -303,6 +303,24 @@ http.lowSpeedLimit, http.lowSpeedTime:: Can be overridden by the `GIT_HTTP_LOW_SPEED_LIMIT` and `GIT_HTTP_LOW_SPEED_TIME` environment variables. +http.keepAliveIdle:: + Specifies how long in seconds to wait on an idle connection + before sending TCP keepalive probes (if supported by the OS). If + unset, curl's default value is used. Can be overridden by the + `GIT_HTTP_KEEPALIVE_IDLE` environment variable. + +http.keepAliveInterval:: + Specifies how long in seconds to wait between TCP keepalive + probes (if supported by the OS). If unset, curl's default value + is used. Can be overridden by the `GIT_HTTP_KEEPALIVE_INTERVAL` + environment variable. + +http.keepAliveCount:: + Specifies how many TCP keepalive probes to send before giving up + and terminating the connection (if supported by the OS). If + unset, curl's default value is used. Can be overridden by the + `GIT_HTTP_KEEPALIVE_COUNT` environment variable. + http.noEPSV:: A boolean which disables using of EPSV ftp command by curl. This can be helpful with some "poor" ftp servers which don't diff --git a/Documentation/config/maintenance.adoc b/Documentation/config/maintenance.adoc index 72a9d6cf816928..2f719342183322 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/promisor.adoc b/Documentation/config/promisor.adoc index 9192acfd243097..2638b01f8308a1 100644 --- a/Documentation/config/promisor.adoc +++ b/Documentation/config/promisor.adoc @@ -26,5 +26,5 @@ promisor.acceptFromServer:: server will be accepted. By accepting a promisor remote, the client agrees that the server might omit objects that are lazily fetchable from this promisor remote from its responses - to "fetch" and "clone" requests from the client. See - linkgit:gitprotocol-v2[5]. + to "fetch" and "clone" requests from the client. Name and URL + comparisons are case sensitive. See linkgit:gitprotocol-v2[5]. diff --git a/Documentation/config/remote.adoc b/Documentation/config/remote.adoc index 25fe219d103cc4..91e46f66f5dd1c 100644 --- a/Documentation/config/remote.adoc +++ b/Documentation/config/remote.adoc @@ -108,7 +108,8 @@ the values inherited from a lower priority configuration files (e.g. `$HOME/.gitconfig`). remote..followRemoteHEAD:: - How linkgit:git-fetch[1] should handle updates to `remotes//HEAD`. + How linkgit:git-fetch[1] should handle updates to `remotes//HEAD` + when fetching using the configured refspecs of a remote. The default value is "create", which will create `remotes//HEAD` if it exists on the remote, but not locally; this will not touch an already existing local reference. Setting it to "warn" will print diff --git a/Documentation/fix-texi.perl b/Documentation/fix-texi.perl deleted file mode 100755 index ff7d78f620a35f..00000000000000 --- 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 00000000000000..bc300f7b0f170c --- /dev/null +++ b/Documentation/fix-texi.sh @@ -0,0 +1,21 @@ +#!/bin/sh + +awk ' + /^@setfilename/{ + print "@setfilename git.info" + next + } + /^@direntry/{ + direntry=1 + print "@dircategory Development" + print "@direntry" + print "* Git: (git). A fast distributed revision control system" + print "@end direntry" + next + } + /^@end direntry/{ + direntry=0 + next + } + !direntry +' diff --git a/Documentation/fsck-msgids.adoc b/Documentation/fsck-msgids.adoc index b14bc44ca4791f..0ba4f9a27e4c73 100644 --- a/Documentation/fsck-msgids.adoc +++ b/Documentation/fsck-msgids.adoc @@ -16,6 +16,13 @@ `badObjectSha1`:: (ERROR) An object has a bad sha1. +`badPackedRefEntry`:: + (ERROR) The "packed-refs" file contains an invalid entry. + +`badPackedRefHeader`:: + (ERROR) The "packed-refs" file contains an invalid + header. + `badParentSha1`:: (ERROR) A commit object has a bad parent sha1. @@ -52,6 +59,12 @@ `emptyName`:: (WARN) A path contains an empty name. +`emptyPackedRefsFile`:: + (INFO) "packed-refs" file is empty. Report to the + git@vger.kernel.org mailing list if you see this error. As only + very early versions of Git would create such an empty + "packed_refs" file, we might tighten this rule in the future. + `extraHeaderEntry`:: (IGNORE) Extra headers found after `tagger`. @@ -176,6 +189,13 @@ `nullSha1`:: (WARN) Tree contains entries pointing to a null sha1. +`packedRefEntryNotTerminated`:: + (ERROR) The "packed-refs" file contains an entry that is + not terminated by a newline. + +`packedRefUnsorted`:: + (ERROR) The "packed-refs" file is not sorted. + `refMissingNewline`:: (INFO) A loose ref that does not end with newline(LF). As valid implementations of Git never created such a loose ref diff --git a/Documentation/git-bisect.adoc b/Documentation/git-bisect.adoc index 82f944dc03dffc..58dbb74a15760c 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 f75ed4479021cb..e438d286258826 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 7a073a36d6dbf0..c0afddc424d610 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[=] | --no-color] [--show-current] - [-v [--abbrev= | --no-abbrev]] - [--column[=] | --no-column] [--sort=] - [--merged []] [--no-merged []] - [--contains []] [--no-contains []] - [--points-at ] [--format=] - [(-r | --remotes) | (-a | --all)] - [--list] [...] -'git branch' [--track[=(direct|inherit)] | --no-track] [-f] - [--recurse-submodules] [] -'git branch' (--set-upstream-to= | -u ) [] -'git branch' --unset-upstream [] -'git branch' (-m | -M) [] -'git branch' (-c | -C) [] -'git branch' (-d | -D) [-r] ... -'git branch' --edit-description [] +[synopsis] +git branch [--color[=] | --no-color] [--show-current] + [-v [--abbrev= | --no-abbrev]] + [--column[=] | --no-column] [--sort=] + [--merged []] [--no-merged []] + [--contains []] [--no-contains []] + [--points-at ] [--format=] + [(-r|--remotes) | (-a|--all)] + [--list] [...] +git branch [--track[=(direct|inherit)] | --no-track] [-f] + [--recurse-submodules] [] +git branch (--set-upstream-to=|-u ) [] +git branch --unset-upstream [] +git branch (-m|-M) [] +git branch (-c|-C) [] +git branch (-d|-D) [-r] ... +git branch --edit-description [] 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 +branches not merged into the named commit will be listed. If the __ 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 -which points to the current `HEAD`, or if given. As a -special case, for , 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 __ +which points to the current `HEAD`, or __ if given. As a +special case, for __, you may use `...` as a +shortcut for the merge base of __ and __ if there is exactly +one merge base. You can leave out at most one of __ and __, +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 " to switch to the +working tree to it; use `git switch ` 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..remote` and `branch..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, will be renamed to . -If had a corresponding reflog, it is renamed to match -, and a reflog entry is created to remember the branch -renaming. If exists, -M must be used to force the rename +With a `-m` or `-M` option, __ will be renamed to __. +If __ had a corresponding reflog, it is renamed to match +__, and a reflog entry is created to remember the branch +renaming. If __ 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, `` will be deleted. You may +With a `-d` or `-D` option, __ 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 "@\{yesterday}". + based sha1 expressions such as `@{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 to , even if exists - already. Without `-f`, 'git branch' refuses to change an existing branch. +`-f`:: +`--force`:: + Reset __ to __, even if __ 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 []', even with '-f', -refuses to change an existing branch `` that is checked out +Note that `git branch -f []`, even with `-f`, +refuses to change an existing branch __ 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[=]:: +`--color[=]`:: 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[=]:: ---no-column:: +`--column[=]`:: +`--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=`:: + Sort based on __. Prefix `-` to sort in descending + order of the value. You may use the `--sort=` 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 `...`, 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 `). 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=:: +`--abbrev=`:: In the verbose listing that show the commit object name, - show the shortest prefix that is at least '' hexdigits + show the shortest prefix that is at least __ 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..remote` and `branch..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 __ 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..remote` and `branch..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 will be created +When used in branch creation, a new branch __ will be created in the superproject and all of the submodules in the superproject's -. In submodules, the branch will point to the submodule -commit in the superproject's but the branch's tracking +__. In submodules, the branch will point to the submodule +commit in the superproject's __ 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 :: ---set-upstream-to=:: - Set up 's tracking information so is - considered 's upstream branch. If no +`-u `:: +`--set-upstream-to=`:: + Set up __'s tracking information so __ is + considered __'s upstream branch. If no __ is specified, then it defaults to the current branch. ---unset-upstream:: - Remove the upstream information for . If no branch +`--unset-upstream`:: + Remove the upstream information for __. 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 []:: - Only list branches which contain the specified commit (HEAD +`--contains []`:: + Only list branches which contain __ (`HEAD` if not specified). Implies `--list`. ---no-contains []:: - Only list branches which don't contain the specified commit - (HEAD if not specified). Implies `--list`. +`--no-contains []`:: + Only list branches which don't contain __ + (`HEAD` if not specified). Implies `--list`. ---merged []:: - Only list branches whose tips are reachable from the - specified commit (HEAD if not specified). Implies `--list`. +`--merged []`:: + Only list branches whose tips are reachable from + __ (`HEAD` if not specified). Implies `--list`. ---no-merged []:: - Only list branches whose tips are not reachable from the - specified commit (HEAD if not specified). Implies `--list`. +`--no-merged []`:: + Only list branches whose tips are not reachable from + __ (`HEAD` if not specified). Implies `--list`. -:: +`--points-at `:: + Only list branches of __. + +`--format `:: + A string that interpolates `%(fieldname)` from a branch ref being shown + and the object it points at. __ is the same as + that of linkgit:git-for-each-ref[1]. + +__:: 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. -:: +__:: 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. -:: +__:: The name of an existing branch. If this option is omitted, the name of the current branch will be used instead. -:: +__:: The new name for an existing branch. The same restrictions as for - apply. - ---sort=:: - Sort based on the key given. Prefix `-` to sort in descending - order of the value. You may use the --sort= 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 :: - Only list branches of the given object. - ---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]. + __ 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 '/' <1> $ git for-each-ref 'refs/remotes//' <2> ------------ + -<1> Using `-a` would conflate with any local branches you happen to - have been prefixed with the same pattern. +<1> Using `-a` would conflate __ with any local branches you happen to + have been prefixed with the same __ 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 ` is used to find all branches which will need - special attention if were to be rebased or amended, since those - branches contain the specified . + special attention if __ were to be rebased or amended, since those + branches contain the specified __. - `--no-contains ` is the inverse of that, i.e. branches that don't - contain the specified . + contain the specified __. - `--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 d5890ae3686f6b..cde79ad242bb77 100644 --- a/Documentation/git-cat-file.adoc +++ b/Documentation/git-cat-file.adoc @@ -9,8 +9,7 @@ SYNOPSIS -------- [verse] 'git cat-file' -'git cat-file' (-e | -p) -'git cat-file' (-t | -s) [--allow-unknown-type] +'git cat-file' (-e | -p | -t | -s) 'git cat-file' (--textconv | --filters) [: | --path= ] 'git cat-file' (--batch | --batch-check | --batch-command) [--batch-all-objects] @@ -81,6 +80,25 @@ OPTIONS end-of-line conversion, etc). In this case, `` has to be of the form `:`, or `:`. +--filter=:: +--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 '' may be one of the following: ++ +The form '--filter=blob:none' omits all blobs. ++ +The form '--filter=blob:limit=[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=:: For use with `--textconv` or `--filters`, to allow specifying an object name and a path separately, e.g. when it is difficult to figure out @@ -183,9 +201,6 @@ flush:: only once, even if it is stored multiple times in the repository. ---allow-unknown-type:: - Allow `-s` or `-t` to query broken/corrupt objects of unknown type. - --follow-symlinks:: With `--batch` or `--batch-check`, follow symlinks inside the repository when requesting objects with extended SHA-1 @@ -322,10 +337,10 @@ of `%(objectsize)` bytes), followed by a newline. For example, `--batch` without a custom format would produce: ------------- +----------- SP SP LF LF ------------- +----------- Whereas `--batch-check='%(objectname) %(objecttype)'` would produce: @@ -340,6 +355,13 @@ the repository, then `cat-file` will ignore any custom format and print: 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: + +------------ + 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: ------------ diff --git a/Documentation/git-check-attr.adoc b/Documentation/git-check-attr.adoc index cb5a6c8f335e12..503b6446574d18 100644 --- a/Documentation/git-check-attr.adoc +++ b/Documentation/git-check-attr.adoc @@ -76,6 +76,7 @@ EXAMPLES -------- In the examples, the following '.gitattributes' file is used: + --------------- *.java diff=java -crlf myAttr NoMyAttr.java !myAttr @@ -83,12 +84,14 @@ README caveat=unspecified --------------- * Listing a single attribute: ++ --------------- $ git check-attr diff org/example/MyClass.java org/example/MyClass.java: diff: java --------------- * Listing multiple attributes for a file: ++ --------------- $ git check-attr crlf diff myAttr -- org/example/MyClass.java org/example/MyClass.java: crlf: unset @@ -97,6 +100,7 @@ org/example/MyClass.java: myAttr: set --------------- * Listing all attributes for a file: ++ --------------- $ git check-attr --all -- org/example/MyClass.java org/example/MyClass.java: diff: java @@ -104,6 +108,7 @@ org/example/MyClass.java: myAttr: set --------------- * Listing an attribute for multiple files: ++ --------------- $ git check-attr myAttr -- org/example/MyClass.java org/example/NoMyAttr.java org/example/MyClass.java: myAttr: set @@ -111,6 +116,7 @@ org/example/NoMyAttr.java: myAttr: unspecified --------------- * Not all values are equally unambiguous: ++ --------------- $ git check-attr caveat README README: caveat: unspecified diff --git a/Documentation/git-column.adoc b/Documentation/git-column.adoc index 85fb87c94a4445..5a4f2b6fde9f27 100644 --- a/Documentation/git-column.adoc +++ b/Documentation/git-column.adoc @@ -50,6 +50,7 @@ EXAMPLES -------- Format data by columns: ++ ------------ $ seq 1 24 | git column --mode=column --padding=5 1 4 7 10 13 16 19 22 @@ -58,6 +59,7 @@ $ seq 1 24 | git column --mode=column --padding=5 ------------ Format data by rows: ++ ------------ $ seq 1 21 | git column --mode=row --padding=5 1 2 3 4 5 6 7 @@ -66,6 +68,7 @@ $ seq 1 21 | git column --mode=row --padding=5 ------------ List some tags in a table with unequal column widths: ++ ------------ $ git tag --list 'v2.4.*' --column=row,dense v2.4.0 v2.4.0-rc0 v2.4.0-rc1 v2.4.0-rc2 v2.4.0-rc3 diff --git a/Documentation/git-cvsserver.adoc b/Documentation/git-cvsserver.adoc index 4c475efeab976a..fe822f571d0bea 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 ------ + 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 ------ + 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 ede7b935d64947..99389f038894c4 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=] [--init-timeout=] [--max-connections=] - [--strict-paths] [--base-path=] [--base-path-relaxed] - [--user-path | --user-path=] - [--interpolated-path=] - [--reuseaddr] [--detach] [--pid-file=] - [--enable=] [--disable=] - [--allow-override=] [--forbid-override=] - [--access-hook=] [--[no-]informative-errors] - [--inetd | - [--listen=] [--port=] - [--user= [--group=]]] - [--log-destination=(stderr|syslog|none)] - [...] +[synopsis] +git daemon [--verbose] [--syslog] [--export-all] + [--timeout=] [--init-timeout=] [--max-connections=] + [--strict-paths] [--base-path=] [--base-path-relaxed] + [--user-path | --user-path=] + [--interpolated-path=] + [--reuseaddr] [--detach] [--pid-file=] + [--enable=] [--disable=] + [--allow-override=] [--forbid-override=] + [--access-hook=] [--[no-]informative-errors] + [--inetd | + [--listen=] [--port=] + [--user= [--group=]]] + [--log-destination=(stderr|syslog|none)] + [...] 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=:: +`--base-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=:: +`--interpolated-path=`:: 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=:: +`--listen=`:: 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= is also not supported and - --listen must be given an IPv4 address. + is not supported, then `--listen=` is also not supported + and `--listen` must be given an IPv4 address. Can be given more than once. Incompatible with `--inetd` option. ---port=:: +`--port=`:: Listen on an alternative port. Incompatible with `--inetd` option. ---init-timeout=:: +`--init-timeout=`:: 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=:: +`--timeout=`:: 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=:: +`--max-connections=`:: Maximum number of concurrent clients, defaults to 32. Set it to zero for no limit. ---syslog:: +`--syslog`:: Short for `--log-destination=syslog`. ---log-destination=:: +`--log-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 must be one of: + The __ 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=:: +`--user-path`:: +`--user-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 `/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=:: - Save the process id in 'file'. Ignored when the daemon +`--pid-file=`:: + Save the process id in __. Ignored when the daemon is run under `--inetd`. ---user=:: ---group=:: +`--user=`:: +`--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 `` before starting the daemon, and make sure any -Git configuration files in that directory are readable by ``. +directory of __ before starting the daemon, and make sure any +Git configuration files in that directory are readable by __. ---enable=:: ---disable=:: +`--enable=`:: +`--disable=`:: 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=:: ---forbid-override=:: +`--allow-override=`:: +`--forbid-override=`:: 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=:: +`--access-hook=`:: Every time a client connects, first run an external command specified by the 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. -:: +__:: 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 00000000000000..f99fcd1ead2479 --- /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 [] + +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-fast-export.adoc b/Documentation/git-fast-export.adoc index 752e4b9b01d7d8..413a5274969b6c 100644 --- a/Documentation/git-fast-export.adoc +++ b/Documentation/git-fast-export.adoc @@ -27,17 +27,33 @@ OPTIONS Insert 'progress' statements every 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 'abort'. ++ +Earlier versions this command that did not have '--signed-commits' +behaved as if '--signed-commits=strip'. As an escape hatch for users +of tools that call 'git fast-export' but do not yet support +'--signed-commits', you may set the environment variable +'FAST_EXPORT_SIGNED_COMMITS_NOABORT=1' in order to change the default +from 'abort' to 'warn-strip'. --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 58a2eaa51a8034..7b107f5e8e9da5 100644 --- a/Documentation/git-fast-import.adoc +++ b/Documentation/git-fast-import.adoc @@ -431,13 +431,22 @@ and control the current import process. More detailed discussion Create or update a branch with a new commit, recording one logical change to the project. +//// +Yes, it's intentional that the 'gpgsig' line doesn't have a trailing +`LF`; the definition of `data` has a byte-count prefix, so it +doesn't need an `LF` to act as a terminator (and `data` also already +includes an optional trailing `LF?` just in case you want to include +one). +//// + .... 'commit' SP LF mark? original-oid? ('author' (SP )? SP LT GT SP LF)? 'committer' (SP )? SP LT GT SP LF - ('encoding' SP )? + ('gpgsig' SP LF data)? + ('encoding' SP LF)? data ('from' SP LF)? ('merge' SP LF)* @@ -505,6 +514,15 @@ that was selected by the --date-format= command-line option. See ``Date Formats'' above for the set of supported formats, and their syntax. +`gpgsig` +^^^^^^^^ + +The optional `gpgsig` command is used to include a PGP/GPG signature +that signs the commit data. + +Here specifies which hashing algorithm is used for this +signature, either `sha1` or `sha256`. + `encoding` ^^^^^^^^^^ The optional `encoding` command indicates the encoding of the commit diff --git a/Documentation/git-for-each-ref.adoc b/Documentation/git-for-each-ref.adoc index ffb97e62c2d94e..5ef89fc0fe3c9d 100644 --- a/Documentation/git-for-each-ref.adoc +++ b/Documentation/git-for-each-ref.adoc @@ -441,6 +441,7 @@ Ref: %(*refname) A simple example showing the use of shell eval on the output, demonstrating the use of --shell. List the prefixes of all heads: + ------------ #!/bin/sh @@ -455,6 +456,7 @@ done A bit more elaborate report on tags, demonstrating that the format may be an entire script: + ------------ #!/bin/sh diff --git a/Documentation/git-fsck.adoc b/Documentation/git-fsck.adoc index 8f32800a835fe8..11203ba925c717 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] [...] + [--[no-]name-objects] [--[no-]references] [...] DESCRIPTION ----------- @@ -104,6 +104,11 @@ care about this output and want to speed it up further. progress status even if the standard error stream is not directed to a terminal. +--[no-]references:: + Control whether to check the references database consistency + via 'git refs verify'. See linkgit:git-refs[1] for details. + The default is to check the references database. + CONFIGURATION ------------- diff --git a/Documentation/git-maintenance.adoc b/Documentation/git-maintenance.adoc index 0450d74aff1ea2..931f3e02e85fe4 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 + linkit:git-worktree[1] for more information. + OPTIONS ------- --auto:: diff --git a/Documentation/git-merge-tree.adoc b/Documentation/git-merge-tree.adoc index cf0578f9b5e86d..f824eea61f1e06 100644 --- a/Documentation/git-merge-tree.adoc +++ b/Documentation/git-merge-tree.adoc @@ -65,6 +65,12 @@ OPTIONS default is to include these messages if there are merge conflicts, and to omit them otherwise. +--quiet:: + Disable all output from the program. Useful when you are only + interested in the exit status. Allows merge-tree to exit + early when it finds a conflict, and allows it to avoid writing + most objects created by merges. + --allow-unrelated-histories:: merge-tree will by default error out if the two branches specified share no common history. This flag can be given to override that diff --git a/Documentation/git-mv.adoc b/Documentation/git-mv.adoc index dc1bf61534106a..f707e998f77325 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' [] ... + +[synopsis] +git mv [-v] [-f] [-n] [-k] +git mv [-v] [-f] [-n] [-k] ... DESCRIPTION ----------- Move or rename a file, directory, or symlink. - git mv [-v] [-f] [-n] [-k] - git mv [-v] [-f] [-n] [-k] ... - -In the first form, it renames , which must exist and be either -a file, symlink or directory, to . -In the second form, the last argument has to be an existing +In the first form, it renames __, which must exist and be either +a file, symlink or directory, to __. +In the second form, __ 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 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..path setting in -the linkgit:gitmodules[5] file and stage that file (unless -n is used). +It also will attempt to update the `submodule..path` setting in +the linkgit:gitmodules[5] file and stage that file (unless `-n` is used). BUGS ---- diff --git a/Documentation/git-p4.adoc b/Documentation/git-p4.adoc index de5ee6748e3588..f97b786bf98a21 100644 --- a/Documentation/git-p4.adoc +++ b/Documentation/git-p4.adoc @@ -80,6 +80,7 @@ This: To reproduce the entire p4 history in Git, use the '@all' modifier on the depot path: + ------------ $ git p4 clone //depot/path/project@all ------------ @@ -89,19 +90,23 @@ Sync ~~~~ As development continues in the p4 repository, those changes can be included in the Git repository using: + ------------ $ git p4 sync ------------ + This command finds new changes in p4 and imports them as Git commits. P4 repositories can be added to an existing Git repository using 'git p4 sync' too: + ------------ $ mkdir repo-git $ cd repo-git $ git init $ git p4 sync //path/in/your/perforce/depot ------------ + This imports the specified depot into 'refs/remotes/p4/master' in an existing Git repository. The `--branch` option can be used to specify a different branch to @@ -125,6 +130,7 @@ and merge them with local uncommitted changes. Often, the p4 repository is the ultimate location for all code, thus a rebase workflow makes sense. This command does 'git p4 sync' followed by 'git rebase' to move local commits on top of updated p4 changes. + ------------ $ git p4 rebase ------------ @@ -140,16 +146,19 @@ will be created and populated if it does not already exist. To submit all changes that are in the current Git branch but not in the 'p4/master' branch, use: + ------------ $ git p4 submit ------------ To specify a branch other than the current one, use: + ------------ $ git p4 submit topicbranch ------------ To specify a single commit or a range of commits, use: + ------------ $ git p4 submit --commit $ git p4 submit --commit @@ -510,20 +519,24 @@ when cloning or syncing to have 'git p4' automatically find subdirectories in p4, and to generate these as branches in Git. For example, if the P4 repository structure is: + ---- //depot/main/... //depot/branch1/... ---- And "p4 branch -o branch1" shows a View line that looks like: + ---- //depot/main/... //depot/branch1/... ---- Then this 'git p4 clone' command: + ---- git p4 clone --detect-branches //depot@all ---- + produces a separate branch in 'refs/remotes/p4/' for //depot/main, called 'master', and one for //depot/branch1 called 'depot/branch1'. @@ -536,6 +549,7 @@ simple p4 branch specification, where the "source" and "destination" are the path elements in the p4 repository. The example above relied on the presence of the p4 branch. Without p4 branches, the same result will occur with: + ---- git init depot cd depot diff --git a/Documentation/git-pack-refs.adoc b/Documentation/git-pack-refs.adoc index 2dcabaf74cefb4..652c5497715a0f 100644 --- a/Documentation/git-pack-refs.adoc +++ b/Documentation/git-pack-refs.adoc @@ -88,10 +88,10 @@ Do not pack refs matching the given `glob(7)` pattern. Repetitions of this optio accumulate exclusion patterns. Use `--no-exclude` to clear and reset the list of patterns. If a ref is already packed, including it with `--exclude` will not unpack it. - ++ When used with `--all`, pack only loose refs which do not match any of the provided `--exclude` patterns. - ++ When used with `--include`, refs provided to `--include`, minus refs that are provided to `--exclude` will be packed. diff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc index 153cb69a4f810e..956d3048f5a618 100644 --- a/Documentation/git-rebase.adoc +++ b/Documentation/git-rebase.adoc @@ -1107,10 +1107,12 @@ In that case, the fix is easy because 'git rebase' knows to skip changes that are already present in the new upstream (unless `--reapply-cherry-picks` is given). So if you say (assuming you're on 'topic') + ------------ $ git rebase subsystem ------------ you will end up with the fixed history + ------------ o---o---o---o---o---o---o---o master \ @@ -1145,6 +1147,7 @@ of the old 'subsystem', for example: You can then transplant the old `subsystem..topic` to the new tip by saying (for the reflog case, and assuming you are on 'topic' already): + ------------ $ git rebase --onto subsystem subsystem@{1} ------------ diff --git a/Documentation/git-receive-pack.adoc b/Documentation/git-receive-pack.adoc index 20aca92073d8c9..0956086d6117d3 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 a929c52982ff76..412f06b8fec57a 100644 --- a/Documentation/git-reflog.adoc +++ b/Documentation/git-reflog.adoc @@ -16,6 +16,7 @@ SYNOPSIS [--dry-run | -n] [--verbose] [--all [--single-worktree] | ...] 'git reflog delete' [--rewrite] [--updateref] [--dry-run | -n] [--verbose] @{}... +'git reflog drop' [--all [--single-worktree] | ...] 'git reflog exists' DESCRIPTION @@ -48,10 +49,14 @@ and not reachable from the current tip, are removed from the reflog. This is typically not used directly by end users -- instead, see linkgit:git-gc[1]. -The "delete" subcommand deletes single entries from the reflog. Its -argument must be an _exact_ entry (e.g. "`git reflog delete -master@{2}`"). This subcommand is also typically not used directly by -end users. +The "delete" subcommand deletes single entries from the reflog, but +not the reflog itself. Its argument must be an _exact_ entry (e.g. "`git +reflog delete master@{2}`"). This subcommand is also typically not used +directly by end users. + +The "drop" subcommand completely removes the reflog for the specified +references. This is in contrast to "expire" and "delete", both of which +can be used to delete reflog entries, but not the reflog itself. The "exists" subcommand checks whether a ref has a reflog. It exits with zero status if the reflog exists, and non-zero status if it does @@ -132,6 +137,16 @@ Options for `delete` `--dry-run`, and `--verbose`, with the same meanings as when they are used with `expire`. +Options for `drop` +~~~~~~~~~~~~~~~~~~ + +--all:: + Drop the reflogs of all references from all worktrees. + +--single-worktree:: + By default when `--all` is specified, reflogs from all working + trees are dropped. This option limits the processing to reflogs + from the current working tree only. GIT --- diff --git a/Documentation/git-repack.adoc b/Documentation/git-repack.adoc index 2199eb3b94f2ec..33e3e7a4535b4a 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=:: - Repack cruft objects into packs as large as `` bytes before - creating new packs. As long as there are enough cruft packs - smaller than ``, 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 - `` will not be modified. When the new cruft pack is larger - than `` bytes, it will be split into multiple packs, all of - which are guaranteed to be at most `` 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=:: + When generating cruft packs without pruning, only repack + existing cruft packs whose size is strictly less than ``, + where `` 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 `` 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=:: Write a cruft pack containing pruned objects (if any) to the diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc index 94fed757630f51..e5c96128d78f93 100644 --- a/Documentation/git-reset.adoc +++ b/Documentation/git-reset.adoc @@ -7,24 +7,24 @@ git-reset - Reset current HEAD to the specified state SYNOPSIS -------- -[verse] -'git reset' [-q] [] [--] ... -'git reset' [-q] [--pathspec-from-file= [--pathspec-file-nul]] [] -'git reset' (--patch | -p) [] [--] [...] -'git reset' [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [] -DEPRECATED: 'git reset' [-q] [--stdin [-z]] [] +[synopsis] +git reset [-q] [] [--] ... +git reset [-q] [--pathspec-from-file= [--pathspec-file-nul]] [] +git reset (--patch | -p) [] [--] [...] +git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [] +DEPRECATED: git reset [-q] [--stdin [-z]] [] DESCRIPTION ----------- -In the first three forms, copy entries from `` to the index. -In the last form, set the current branch head (`HEAD`) to ``, +In the first three forms, copy entries from __ to the index. +In the last form, set the current branch head (`HEAD`) to __, optionally modifying index and working tree to match. -The ``/`` defaults to `HEAD` in all forms. +The __/__ defaults to `HEAD` in all forms. -'git reset' [-q] [] [--] ...:: -'git reset' [-q] [--pathspec-from-file= [--pathspec-file-nul]] []:: +`git reset [-q] [] [--] ...`:: +`git reset [-q] [--pathspec-from-file= [--pathspec-file-nul]] []`:: These forms reset the index entries for all paths that match the - `` to their state at ``. (It does not affect + __ to their state at __. (It does not affect the working tree or the current branch.) + This means that `git reset ` is the opposite of `git add @@ -38,30 +38,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) [] [--] [...]:: +`git reset (--patch | -p) [] [--] [...]`:: Interactively select hunks in the difference between the index - and `` (defaults to `HEAD`). The chosen hunks are applied + and __ (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' [] []:: - This form resets the current branch head to `` and - possibly updates the index (resetting it to the tree of ``) and - the working tree depending on ``. Before the operation, `ORIG_HEAD` - is set to the tip of the current branch. If `` is omitted, - defaults to `--mixed`. The `` must be one of the following: +`git reset [] []`:: + This form resets the current branch head to __ and + possibly updates the index (resetting it to the tree of __) and + the working tree depending on __. Before the operation, `ORIG_HEAD` + is set to the tip of the current branch. If __ is omitted, + defaults to `--mixed`. The __ 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 ``, just like all modes do). This leaves + resets the head to __, 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. @@ -69,33 +69,33 @@ section of linkgit:git-add[1] to learn how to operate the `--patch` mode. If `-N` is specified, removed paths are marked as intent-to-add (see linkgit:git-add[1]). ---hard:: +`--hard`:: Resets the index and working tree. Any changes to tracked files in the - working tree since `` are discarded. Any untracked files or + working tree since __ 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 `` and `HEAD`, but keeps those which are + different between __ 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 `` and the index has + If a file that is different between __ and the index has unstaged changes, reset is aborted. + In other words, `--merge` does something like a `git read-tree -u -m `, but carries forward unmerged index entries. ---keep:: +`--keep`:: Resets index entries and updates files in the working tree that are - different between `` and `HEAD`. - If a file that is different between `` and `HEAD` has local + different between __ and `HEAD`. + If a file that is different between __ and `HEAD` has local changes, reset is aborted. ---[no-]recurse-submodules:: - When the working tree is updated, using --recurse-submodules will +`--[no-]recurse-submodules`:: + When the working tree is updated, using `--recurse-submodules` will also recursively reset the working tree of all active submodules according to the commit recorded in the superproject, also setting - the submodules' HEAD to be detached at that commit. + the submodules' `HEAD` to be detached at that commit. -- See "Reset, restore and revert" in linkgit:git[1] for the differences @@ -105,31 +105,31 @@ between the three commands. OPTIONS ------- --q:: ---quiet:: +`-q`:: +`--quiet`:: Be quiet, only report errors. ---refresh:: ---no-refresh:: +`--refresh`:: +`--no-refresh`:: Refresh the index after a mixed reset. Enabled by default. ---pathspec-from-file=:: - Pathspec is passed in `` instead of commandline args. If - `` is exactly `-` then standard input is used. Pathspec - elements are separated by LF or CR/LF. Pathspec elements can be +`--pathspec-from-file=`:: + Pathspec is passed in __ instead of commandline args. If + __ is exactly `-` then standard input is used. Pathspec + elements are separated by _LF_ or _CR_/_LF_. Pathspec elements can be quoted as explained for the configuration variable `core.quotePath` (see linkgit:git-config[1]). See also `--pathspec-file-nul` and global `--literal-pathspecs`. ---pathspec-file-nul:: +`--pathspec-file-nul`:: Only meaningful with `--pathspec-from-file`. Pathspec elements are - separated with NUL character and all other characters are taken + separated with _NUL_ character and all other characters are taken literally (including newlines and quotes). -\--:: +`--`:: Do not interpret any more arguments as options. -...:: +`...`:: Limits the paths affected by the operation. + For more details, see the 'pathspec' entry in linkgit:gitglossary[7]. @@ -359,7 +359,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` @@ -469,7 +469,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 @@ -478,7 +478,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 751f01b4418b5b..877b7772e66735 100644 --- a/Documentation/git-restore.adoc +++ b/Documentation/git-restore.adoc @@ -51,9 +51,6 @@ leave out at most one of ___ and __, in which case it defaults to restore source and the restore location. See the "Interactive Mode" section of linkgit:git-add[1] to learn how to operate the `--patch` mode. -+ -Note that `--patch` can accept no pathspec and will prompt to restore -all modified paths. `-W`:: `--worktree`:: diff --git a/Documentation/git-rm.adoc b/Documentation/git-rm.adoc index 363a26934f54e0..b5ead867963b50 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= [--pathspec-file-nul]] - [--] [...] +[synopsis] +git rm [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch] + [--quiet] [--pathspec-from-file= [--pathspec-file-nul]] + [--] [...] DESCRIPTION ----------- @@ -30,7 +30,7 @@ sparse-checkouts are in use (see linkgit:git-sparse-checkout[1]), OPTIONS ------- -...:: +`...`:: 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 __ 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=:: - Pathspec is passed in `` instead of commandline args. If - `` is exactly `-` then standard input is used. Pathspec - elements are separated by LF or CR/LF. Pathspec elements can be +`--pathspec-from-file=`:: + Pathspec is passed in __ instead of args. If + __ 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. section +the submodule's history. If it exists the `submodule.` 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 7f223db42dd313..26fda63c2fc1ff 100644 --- a/Documentation/git-send-email.adoc +++ b/Documentation/git-send-email.adoc @@ -115,6 +115,19 @@ illustration below where `[PATCH v2 0/3]` is in reply to `[PATCH 0/2]`: Only necessary if --compose is also set. If --compose is not set, this will be prompted for. +--[no-]outlook-id-fix:: + Microsoft Outlook SMTP servers discard the Message-ID sent via email and + assign a new random Message-ID, thus breaking threads. ++ +With `--outlook-id-fix`, 'git send-email' uses a mechanism specific to +Outlook servers to learn the Message-ID the server assigned to fix the +threading. Use it only when you know that the server reports the +rewritten Message-ID the same way as Outlook servers do. ++ +Without this option specified, the fix is done by default when talking +to 'smtp.office365.com' or 'smtp-mail.outlook.com'. Use +`--no-outlook-id-fix` to disable even when talking to these two servers. + --subject=:: Specify the initial subject of the email thread. Only necessary if --compose is also set. If --compose @@ -496,12 +509,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] @@ -515,6 +528,41 @@ 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 https://security.google.com/settings/security/apppasswords to create it. +You can also use OAuth2.0 authentication with Gmail. `OAUTHBEARER` and +`XOAUTH2` are common methods 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 +---- + +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 method. + +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,9 +571,25 @@ 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 for Gmail and Outlook +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) + +You can also see linkgit:gitcredentials[7] for more OAuth based authentication +helpers. Note: the following core Perl modules that may be installed with your distribution of Perl are required: diff --git a/Documentation/git-update-ref.adoc b/Documentation/git-update-ref.adoc index 9e6935d38d031b..9310ce97683209 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 ] [--no-deref] (-d [] | [--create-reflog] [] | --stdin [-z]) +[synopsis] +git update-ref [-m ] [--no-deref] -d [] +git update-ref [-m ] [--no-deref] [--create-reflog] [] +git update-ref [-m ] [--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 ( | ) SP ( | ) SP LF + Quote fields containing whitespace as if they were strings in C source code; i.e., surrounded by double-quotes and with backslash escapes. Use 40 "0" characters or the empty string to specify a zero value. To diff --git a/Documentation/git-var.adoc b/Documentation/git-var.adoc index 0680568dfda732..b606c2d649979f 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 | ) +[synopsis] +git var (-l | ) 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 aee4c40eac4666..ff5b8b97ef37dd 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] ... +[synopsis] +git verify-commit [-v | --verbose] [--raw] ... 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. -...:: - 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 d7e886918aa7af..b0462d8db3935f 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] [--] .idx... +[synopsis] +git verify-pack [-v | --verbose] [-s | --stat-only] [--] .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 ------- -.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 81d50ecc4c6879..b3721a86f49e31 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=] [--raw] ... +[synopsis] +git verify-tag [-v | --verbose] [--format=] [--raw] ... 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. -...:: - 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 80fa7754a6d70a..9462043a142838 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: