diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/CodingGuidelines | 45 | ||||
| -rw-r--r-- | Documentation/RelNotes/2.33.0.txt | 60 | ||||
| -rw-r--r-- | Documentation/SubmittingPatches | 207 | ||||
| -rw-r--r-- | Documentation/config/diff.txt | 7 | ||||
| -rw-r--r-- | Documentation/config/merge.txt | 10 | ||||
| -rw-r--r-- | Documentation/config/submodule.txt | 5 | ||||
| -rw-r--r-- | Documentation/diff-options.txt | 16 | ||||
| -rw-r--r-- | Documentation/git-config.txt | 28 | ||||
| -rw-r--r-- | Documentation/git-diff.txt | 10 | ||||
| -rw-r--r-- | Documentation/git-pull.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-worktree.txt | 4 |
11 files changed, 252 insertions, 142 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index e3af089ecf..711cb9171e 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -551,6 +551,51 @@ Writing Documentation: documentation, please see the documentation-related advice in the Documentation/SubmittingPatches file). + In order to ensure the documentation is inclusive, avoid assuming + that an unspecified example person is male or female, and think + twice before using "he", "him", "she", or "her". Here are some + tips to avoid use of gendered pronouns: + + - Prefer succinctness and matter-of-factly describing functionality + in the abstract. E.g. + + --short:: Emit output in the short-format. + + and avoid something like these overly verbose alternatives: + + --short:: Use this to emit output in the short-format. + --short:: You can use this to get output in the short-format. + --short:: A user who prefers shorter output could.... + --short:: Should a person and/or program want shorter output, he + she/they/it can... + + This practice often eliminates the need to involve human actors in + your description, but it is a good practice regardless of the + avoidance of gendered pronouns. + + - When it becomes awkward to stick to this style, prefer "you" when + addressing the the hypothetical user, and possibly "we" when + discussing how the program might react to the user. E.g. + + You can use this option instead of --xyz, but we might remove + support for it in future versions. + + while keeping in mind that you can probably be less verbose, e.g. + + Use this instead of --xyz. This option might be removed in future + versions. + + - If you still need to refer to an example person that is + third-person singular, you may resort to "singular they" to avoid + "he/she/him/her", e.g. + + A contributor asks their upstream to pull from them. + + Note that this sounds ungrammatical and unnatural to those who + learned that "they" is only used for third-person plural, e.g. + those who learn English as a second language in some parts of the + world. + Every user-visible change should be reflected in the documentation. The same general rule as for code applies -- imitate the existing conventions. diff --git a/Documentation/RelNotes/2.33.0.txt b/Documentation/RelNotes/2.33.0.txt index a69531c1ef..7960c4f7ab 100644 --- a/Documentation/RelNotes/2.33.0.txt +++ b/Documentation/RelNotes/2.33.0.txt @@ -33,6 +33,9 @@ UI, Workflows & Features * "git rev-list" learns to omit the "commit <object-name>" header lines from the output with the `--no-commit-header` option. + * "git worktree add --lock" learned to record why the worktree is + locked with a custom message. + Performance, Internal Implementation, Development Support etc. @@ -62,6 +65,39 @@ Performance, Internal Implementation, Development Support etc. * GitHub Actions / CI update. (merge 0dc787a9f2 js/ci-windows-update later to maint). + * Object accesses in repositories with many alternate object store + have been optimized. + + * "git log" has been optimized not to waste cycles to load ref + decoration data that may not be needed. + + * Many "printf"-like helper functions we have have been annotated + with __attribute__() to catch placeholder/parameter mismatches. + + * Tests that cover protocol bits have been updated and helpers + used there have been consolidated. + + * The CI gained a new job to run "make sparse" check. + + * "git status" codepath learned to work with sparsely populated index + without hydrating it fully. + + * A guideline for gender neutral documentation has been added. + + * Documentation on "git diff -l<n>" and diff.renameLimit have been + updated, and the defaults for these limits have been raised. + + * The completion support used to offer alternate spelling of options + that exist only for compatibility, which has been corrected. + + * "TEST_OUTPUT_DIRECTORY=there make test" failed to work, which has + been corrected. + + * "git bundle" gained more test coverage. + + * "git read-tree" had a codepath where blobs are fetched one-by-one + from the promisor remote, which has been corrected to fetch in bulk. + Fixes since v2.32 ----------------- @@ -183,6 +219,24 @@ Fixes since v2.32 and adds to guidelines to do so. (merge 46a237f42f ds/gender-neutral-doc later to maint). + * "git commit --allow-empty-message" won't abort the operation upon + an empty message, but the hint shown in the editor said otherwise. + (merge 6f70f00b4f hj/commit-allow-empty-message later to maint). + + * The code that gives an error message in "git multi-pack-index" when + no subcommand is given tried to print a NULL pointer as a strong, + which has been corrected. + (merge 88617d11f9 tb/reverse-midx later to maint). + + * CI update. + (merge a066a90db6 js/ci-check-whitespace-updates later to maint). + + * Documentation fix for "git pull --rebase=no". + (merge d3236becec fc/pull-no-rebase-merges-theirs-into-ours later to maint). + + * A race between repacking and using pack bitmaps has been corrected. + (merge dc1daacdcc jk/check-pack-valid-before-opening-bitmap later to maint). + * Other code cleanup, docfix, build fix, etc. (merge bfe35a6165 ah/doc-describe later to maint). (merge f302c1e4aa jc/clarify-revision-range later to maint). @@ -218,3 +272,9 @@ Fixes since v2.32 (merge 5632e838f8 rs/khash-alloc-cleanup later to maint). (merge b1d87fbaf1 jk/typofix later to maint). (merge e04170697a ab/gitignore-discovery-doc later to maint). + (merge 8232a0ff48 dl/packet-read-response-end-fix later to maint). + (merge eb448631fb dl/diff-merge-base later to maint). + (merge c510928a25 hn/refs-debug-empty-prefix later to maint). + (merge ddcb189d9d tb/bitmap-type-filter-comment-fix later to maint). + (merge 878b399734 pb/submodule-recurse-doc later to maint). + (merge 734283855f jk/config-env-doc later to maint). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 3e215f4d80..e409022d93 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -74,10 +74,9 @@ the feature triggers the new behavior when it should, and to show the feature does not trigger when it shouldn't. After any code change, make sure that the entire test suite passes. -If you have an account at GitHub (and you can get one for free to work -on open source projects), you can use their Travis CI integration to -test your changes on Linux, Mac (and hopefully soon Windows). See -GitHub-Travis CI hints section for details. +Pushing to a fork of https://github.com/git/git will use their CI +integration to test your changes on Linux, Mac and Windows. See the +<<GHCI,GitHub CI>> section for details. Do not forget to update the documentation to describe the updated behavior and make sure that the resulting documentation set formats @@ -167,6 +166,85 @@ or, on an older version of Git without support for --pretty=reference: git show -s --date=short --pretty='format:%h (%s, %ad)' <commit> .... +[[sign-off]] +=== Certify your work by adding your `Signed-off-by` trailer + +To improve tracking of who did what, we ask you to certify that you +wrote the patch or have the right to pass it on under the same license +as ours, by "signing off" your patch. Without sign-off, we cannot +accept your patches. + +If (and only if) you certify the below D-C-O: + +[[dco]] +.Developer's Certificate of Origin 1.1 +____ +By making a contribution to this project, I certify that: + +a. The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +b. The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +c. The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +d. I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +____ + +you add a "Signed-off-by" trailer to your commit, that looks like +this: + +.... + Signed-off-by: Random J Developer <random@developer.example.org> +.... + +This line can be added by Git if you run the git-commit command with +the -s option. + +Notice that you can place your own `Signed-off-by` trailer when +forwarding somebody else's patch with the above rules for +D-C-O. Indeed you are encouraged to do so. Do not forget to +place an in-body "From: " line at the beginning to properly attribute +the change to its true author (see (2) above). + +This procedure originally came from the Linux kernel project, so our +rule is quite similar to theirs, but what exactly it means to sign-off +your patch differs from project to project, so it may be different +from that of the project you are accustomed to. + +[[real-name]] +Also notice that a real name is used in the `Signed-off-by` trailer. Please +don't hide your real name. + +[[commit-trailers]] +If you like, you can put extra tags at the end: + +. `Reported-by:` is used to credit someone who found the bug that + the patch attempts to fix. +. `Acked-by:` says that the person who is more familiar with the area + the patch attempts to modify liked the patch. +. `Reviewed-by:`, unlike the other tags, can only be offered by the + reviewers themselves when they are completely satisfied with the + patch after a detailed analysis. +. `Tested-by:` is used to indicate that the person applied the patch + and found it to have the desired effect. + +You can also create your own tag or use one that's in common usage +such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:". + [[git-tools]] === Generate your patch using Git tools out of your commits. @@ -302,85 +380,6 @@ Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and `Tested-by:` lines as necessary to credit people who helped your patch, and "cc:" them when sending such a final version for inclusion. -[[sign-off]] -=== Certify your work by adding your `Signed-off-by` trailer - -To improve tracking of who did what, we ask you to certify that you -wrote the patch or have the right to pass it on under the same license -as ours, by "signing off" your patch. Without sign-off, we cannot -accept your patches. - -If (and only if) you certify the below D-C-O: - -[[dco]] -.Developer's Certificate of Origin 1.1 -____ -By making a contribution to this project, I certify that: - -a. The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -b. The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -c. The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -d. I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -____ - -you add a "Signed-off-by" trailer to your commit, that looks like -this: - -.... - Signed-off-by: Random J Developer <random@developer.example.org> -.... - -This line can be added by Git if you run the git-commit command with -the -s option. - -Notice that you can place your own `Signed-off-by` trailer when -forwarding somebody else's patch with the above rules for -D-C-O. Indeed you are encouraged to do so. Do not forget to -place an in-body "From: " line at the beginning to properly attribute -the change to its true author (see (2) above). - -This procedure originally came from the Linux kernel project, so our -rule is quite similar to theirs, but what exactly it means to sign-off -your patch differs from project to project, so it may be different -from that of the project you are accustomed to. - -[[real-name]] -Also notice that a real name is used in the `Signed-off-by` trailer. Please -don't hide your real name. - -[[commit-trailers]] -If you like, you can put extra tags at the end: - -. `Reported-by:` is used to credit someone who found the bug that - the patch attempts to fix. -. `Acked-by:` says that the person who is more familiar with the area - the patch attempts to modify liked the patch. -. `Reviewed-by:`, unlike the other tags, can only be offered by the - reviewers themselves when they are completely satisfied with the - patch after a detailed analysis. -. `Tested-by:` is used to indicate that the person applied the patch - and found it to have the desired effect. - -You can also create your own tag or use one that's in common usage -such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:". - == Subsystems with dedicated maintainers Some parts of the system have dedicated maintainers with their own @@ -449,13 +448,12 @@ their trees themselves. entitled "What's cooking in git.git" and "What's in git.git" giving the status of various proposed changes. -[[travis]] -== GitHub-Travis CI hints +== GitHub CI[[GHCI]]] -With an account at GitHub (you can get one for free to work on open -source projects), you can use Travis CI to test your changes on Linux, -Mac (and hopefully soon Windows). You can find a successful example -test build here: https://travis-ci.org/git/git/builds/120473209 +With an account at GitHub, you can use GitHub CI to test your changes +on Linux, Mac and Windows. See +https://github.com/git/git/actions/workflows/main.yml for examples of +recent CI runs. Follow these steps for the initial setup: @@ -463,31 +461,18 @@ Follow these steps for the initial setup: You can find detailed instructions how to fork here: https://help.github.com/articles/fork-a-repo/ -. Open the Travis CI website: https://travis-ci.org - -. Press the "Sign in with GitHub" button. - -. Grant Travis CI permissions to access your GitHub account. - You can find more information about the required permissions here: - https://docs.travis-ci.com/user/github-oauth-scopes - -. Open your Travis CI profile page: https://travis-ci.org/profile - -. Enable Travis CI builds for your Git fork. - -After the initial setup, Travis CI will run whenever you push new changes +After the initial setup, CI will run whenever you push new changes to your fork of Git on GitHub. You can monitor the test state of all your -branches here: https://travis-ci.org/__<Your GitHub handle>__/git/branches +branches here: https://github.com/<Your GitHub handle>/git/actions/workflows/main.yml If a branch did not pass all test cases then it is marked with a red -cross. In that case you can click on the failing Travis CI job and -scroll all the way down in the log. Find the line "<-- Click here to see -detailed test output!" and click on the triangle next to the log line -number to expand the detailed test output. Here is such a failing -example: https://travis-ci.org/git/git/jobs/122676187 - -Fix the problem and push your fix to your Git fork. This will trigger -a new Travis CI build to ensure all tests pass. +cross. In that case you can click on the failing job and navigate to +"ci/run-build-and-tests.sh" and/or "ci/print-test-failures.sh". You +can also download "Artifacts" which are tarred (or zipped) archives +with test data relevant for debugging. + +Then fix the problem and push your fix to your GitHub fork. This will +trigger a new CI build to ensure all tests pass. [[mua]] == MUA specific hints diff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt index 2d3331f55c..32f84838ac 100644 --- a/Documentation/config/diff.txt +++ b/Documentation/config/diff.txt @@ -118,9 +118,10 @@ diff.orderFile:: relative to the top of the working tree. diff.renameLimit:: - The number of files to consider when performing the copy/rename - detection; equivalent to the 'git diff' option `-l`. This setting - has no effect if rename detection is turned off. + The number of files to consider in the exhaustive portion of + copy/rename detection; equivalent to the 'git diff' option + `-l`. If not set, the default value is currently 1000. This + setting has no effect if rename detection is turned off. diff.renames:: Whether and how Git detects renames. If set to "false", diff --git a/Documentation/config/merge.txt b/Documentation/config/merge.txt index 6b66c83eab..e27cc63944 100644 --- a/Documentation/config/merge.txt +++ b/Documentation/config/merge.txt @@ -33,10 +33,12 @@ merge.verifySignatures:: include::fmt-merge-msg.txt[] merge.renameLimit:: - The number of files to consider when performing rename detection - during a merge; if not specified, defaults to the value of - diff.renameLimit. This setting has no effect if rename detection - is turned off. + The number of files to consider in the exhaustive portion of + rename detection during a merge. If not specified, defaults + to the value of diff.renameLimit. If neither + merge.renameLimit nor diff.renameLimit are specified, + currently defaults to 7000. This setting has no effect if + rename detection is turned off. merge.renames:: Whether Git detects renames. If set to "false", rename detection diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt index d7a63c8c12..ee454f8126 100644 --- a/Documentation/config/submodule.txt +++ b/Documentation/config/submodule.txt @@ -58,8 +58,9 @@ submodule.active:: commands. See linkgit:gitsubmodules[7] for details. submodule.recurse:: - Specifies if commands recurse into submodules by default. This - applies to all commands that have a `--recurse-submodules` option + A boolean indicating if commands should enable the `--recurse-submodules` + option by default. + Applies to all commands that support this option (`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`, `restore` and `switch`) except `clone` and `ls-files`. Defaults to false. diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 32e6dee5ac..0aebe83205 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -588,11 +588,17 @@ When used together with `-B`, omit also the preimage in the deletion part of a delete/create pair. -l<num>:: - The `-M` and `-C` options require O(n^2) processing time where n - is the number of potential rename/copy targets. This - option prevents rename/copy detection from running if - the number of rename/copy targets exceeds the specified - number. + The `-M` and `-C` options involve some preliminary steps that + can detect subsets of renames/copies cheaply, followed by an + exhaustive fallback portion that compares all remaining + unpaired destinations to all relevant sources. (For renames, + only remaining unpaired sources are relevant; for copies, all + original sources are relevant.) For N sources and + destinations, this exhaustive check is O(N^2). This option + prevents the exhaustive portion of rename/copy detection from + running if the number of source/destination files involved + exceeds the specified number. Defaults to diff.renameLimit. + Note that a value of 0 is treated as unlimited. ifndef::git-format-patch[] --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]:: diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 5cddadafd2..2dc4bae6da 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -71,6 +71,7 @@ codes are: On success, the command returns the exit code 0. +[[OPTIONS]] OPTIONS ------- @@ -143,7 +144,13 @@ See also <<FILES>>. -f config-file:: --file config-file:: - Use the given config file instead of the one specified by GIT_CONFIG. + For writing options: write to the specified file rather than the + repository `.git/config`. ++ +For reading options: read only from the specified file rather than from all +available files. ++ +See also <<FILES>>. --blob blob:: Similar to `--file` but use the given blob instead of a file. E.g. @@ -325,21 +332,14 @@ All writing options will per default write to the repository specific configuration file. Note that this also affects options like `--replace-all` and `--unset`. *'git config' will only ever change one file at a time*. -You can override these rules either by command-line options or by environment -variables. The `--global`, `--system` and `--worktree` options will limit -the file used to the global, system-wide or per-worktree file respectively. -The `GIT_CONFIG` environment variable has a similar effect, but you -can specify any filename you want. +You can override these rules using the `--global`, `--system`, +`--local`, `--worktree`, and `--file` command-line options; see +<<OPTIONS>> above. ENVIRONMENT ----------- -GIT_CONFIG:: - Take the configuration from the given file instead of .git/config. - Using the "--global" option forces this to ~/.gitconfig. Using the - "--system" option forces this to $(prefix)/etc/gitconfig. - GIT_CONFIG_GLOBAL:: GIT_CONFIG_SYSTEM:: Take the configuration from the given files instead from global or @@ -367,6 +367,12 @@ This is useful for cases where you want to spawn multiple git commands with a common configuration but cannot depend on a configuration file, for example when writing scripts. +GIT_CONFIG:: + If no `--file` option is provided to `git config`, use the file + given by `GIT_CONFIG` as if it were provided via `--file`. This + variable has no effect on other Git commands, and is mostly for + historical compatibility; there is generally no reason to use it + instead of the `--file` option. [[EXAMPLES]] EXAMPLES diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 7f4c8a8ce7..6236c75c9b 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -51,16 +51,20 @@ files on disk. --staged is a synonym of --cached. + If --merge-base is given, instead of using <commit>, use the merge base -of <commit> and HEAD. `git diff --merge-base A` is equivalent to -`git diff $(git merge-base A HEAD)`. +of <commit> and HEAD. `git diff --cached --merge-base A` is equivalent to +`git diff --cached $(git merge-base A HEAD)`. -'git diff' [<options>] <commit> [--] [<path>...]:: +'git diff' [<options>] [--merge-base] <commit> [--] [<path>...]:: This form is to view the changes you have in your working tree relative to the named <commit>. You can use HEAD to compare it with the latest commit, or a branch name to compare with the tip of a different branch. ++ +If --merge-base is given, instead of using <commit>, use the merge base +of <commit> and HEAD. `git diff --merge-base A` is equivalent to +`git diff $(git merge-base A HEAD)`. 'git diff' [<options>] [--merge-base] <commit> <commit> [--] [<path>...]:: diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 5c3fb67c01..7f4b2d1982 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -117,7 +117,7 @@ When set to `preserve` (deprecated in favor of `merges`), rebase with the `--preserve-merges` option passed to `git rebase` so that locally created merge commits will not be flattened. + -When false, merge the current branch into the upstream branch. +When false, merge the upstream branch into the current branch. + When `interactive`, enable the interactive mode of rebase. + diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index 66e67e6cbf..8a7cbdd19c 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -9,7 +9,7 @@ git-worktree - Manage multiple working trees SYNOPSIS -------- [verse] -'git worktree add' [-f] [--detach] [--checkout] [--lock] [-b <new-branch>] <path> [<commit-ish>] +'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]] [-b <new-branch>] <path> [<commit-ish>] 'git worktree list' [--porcelain] 'git worktree lock' [--reason <string>] <worktree> 'git worktree move' <worktree> <new-path> @@ -242,7 +242,7 @@ With `list`, annotate missing working trees as prunable if they are older than `<time>`. --reason <string>:: - With `lock`, an explanation why the working tree is locked. + With `lock` or with `add --lock`, an explanation why the working tree is locked. <worktree>:: Working trees can be identified by path, either relative or |