summaryrefslogtreecommitdiff
path: root/Documentation
AgeCommit message (Collapse)AuthorFilesLines
2021-08-02Git 2.33-rc0Libravatar Junio C Hamano1-0/+17
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-08-02Merge branch 'fc/pull-no-rebase-merges-theirs-into-ours'Libravatar Junio C Hamano1-1/+1
Documentation fix for "git pull --rebase=no". * fc/pull-no-rebase-merges-theirs-into-ours: doc: pull: fix rebase=false documentation
2021-08-02Merge branch 'jk/config-env-doc'Libravatar Junio C Hamano1-11/+17
Documentation around GIT_CONFIG has been updated. * jk/config-env-doc: doc/git-config: simplify "override" advice for FILES section doc/git-config: clarify GIT_CONFIG environment variable doc/git-config: explain --file instead of referring to GIT_CONFIG
2021-08-02Merge branch 'pb/submodule-recurse-doc'Libravatar Junio C Hamano1-2/+3
Doc update. * pb/submodule-recurse-doc: doc: clarify description of 'submodule.recurse'
2021-07-28The seventh batchLibravatar Junio C Hamano1-0/+43
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-07-28Merge branch 'en/rename-limits-doc'Libravatar Junio C Hamano3-12/+21
Documentation on "git diff -l<n>" and diff.renameLimit have been updated, and the defaults for these limits have been raised. * en/rename-limits-doc: rename: bump limit defaults yet again diffcore-rename: treat a rename_limit of 0 as unlimited doc: clarify documentation for rename/copy limits diff: correct warning message when renameLimit exceeded
2021-07-28Merge branch 'ds/gender-neutral-doc-guidelines'Libravatar Junio C Hamano1-0/+45
A guideline for gender neutral documentation has been added. * ds/gender-neutral-doc-guidelines: CodingGuidelines: recommend gender-neutral description
2021-07-28Merge branch 'dl/diff-merge-base'Libravatar Junio C Hamano1-3/+7
"git diff --merge-base" documentation has been updated. * dl/diff-merge-base: git-diff: fix missing --merge-base docs
2021-07-28Merge branch 'sm/worktree-add-lock'Libravatar Junio C Hamano1-2/+2
"git worktree add --lock" learned to record why the worktree is locked with a custom message. * sm/worktree-add-lock: worktree: teach `add` to accept --reason <string> with --lock worktree: mark lock strings with `_()` for translation t2400: clean up '"add" worktree with lock' test
2021-07-22The sixth batchLibravatar Junio C Hamano1-0/+10
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-07-22Merge branch 'bc/rev-list-without-commit-line'Libravatar Junio C Hamano1-0/+8
"git rev-list" learns to omit the "commit <object-name>" header lines from the output with the `--no-commit-header` option. * bc/rev-list-without-commit-line: rev-list: add option for --pretty=format without header
2021-07-22Merge branch 'ab/gitignore-discovery-doc'Libravatar Junio C Hamano1-6/+5
Doc update. * ab/gitignore-discovery-doc: docs: .gitignore parsing is to the top of the repo
2021-07-22Merge branch 'ab/send-email-optim'Libravatar Junio C Hamano1-3/+0
"git send-email" optimization. * ab/send-email-optim: perl: nano-optimize by replacing Cwd::cwd() with Cwd::getcwd() send-email: move trivial config handling to Perl perl: lazily load some common Git.pm setup code send-email: lazily load modules for a big speedup send-email: get rid of indirect object syntax send-email: use function syntax instead of barewords send-email: lazily shell out to "git var" send-email: lazily load config for a big speedup send-email: copy "config_regxp" into git-send-email.perl send-email: refactor sendemail.smtpencryption config parsing send-email: remove non-working support for "sendemail.smtpssl" send-email tests: test for boolean variables without a value send-email tests: support GIT_TEST_PERL_FATAL_WARNINGS=true
2021-07-22Merge branch 'jk/typofix'Libravatar Junio C Hamano1-1/+1
Typofix. * jk/typofix: doc/rev-list-options: fix duplicate word typo
2021-07-21doc: pull: fix rebase=false documentationLibravatar Felipe Contreras1-1/+1
"git pull --rebase=false" means we merge their history into ours, but it has been described the other way around. Cc: Stephen Haberman <stephen@exigencecorp.com> Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> [jc: updated the log message] Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-07-20doc: clarify description of 'submodule.recurse'Libravatar Philippe Blain1-2/+3
The doc for 'submodule.recurse' starts with "Specifies if commands recurse into submodles by default". This is not exactly true of all commands that have a '--recurse-submodules' option. For example, 'git pull --recurse-submodules' does not run 'git pull' in each submodule, but rather runs 'git submodule update --recursive' so that the submodule working trees after the pull matches the commits recorded in the superproject. Clarify that by just saying that it enables '--recurse-submodules'. Note that the way this setting interacts with 'fetch.recurseSubmodules' and 'push.recurseSubmodules', which can have other values than true or false, is already documented since 4da9e99e6e (doc: be more precise on (fetch|push).recurseSubmodules, 2020-04-06). Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-07-20doc/git-config: simplify "override" advice for FILES sectionLibravatar Jeff King1-5/+4
At the end of the FILES section, we indicate that you can override the regular lookup rules with --global, etc. But: - we're missing the --local option - we point to GIT_CONFIG instead of --file, but the latter has much better documentation - we're vague about how the overrides work; the actual option descriptions are much better here So let's just mention the names and point people back to the OPTIONS section. We could perhaps even delete this paragraph entirely, but the presence of the names may give people reading FILES a clue about where to look for more information. Signed-off-by: Jeff King <peff@peff.net> Reviewed-by: Taylor Blau <me@ttaylorr.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-07-20doc/git-config: clarify GIT_CONFIG environment variableLibravatar Jeff King1-5/+6
The scope and utility of the GIT_CONFIG variable was drastically reduced by dc87183189 (Only use GIT_CONFIG in "git config", not other programs, 2008-06-30). But the documentation in git-config(1) predates that, which makes it rather misleading. These days it is really just another way to say "--file". So let's say that, and explicitly make it clear that it does not impact other Git commands (like GIT_CONFIG_SYSTEM, etc, would). I also bumped it to the bottom of the list of variables, and warned people off of using it. We don't have any plans for deprecation at this point, but there's little point in encouraging people to use it by putting it at the top of the list. Signed-off-by: Jeff King <peff@peff.net> Reviewed-by: Taylor Blau <me@ttaylorr.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-07-20doc/git-config: explain --file instead of referring to GIT_CONFIGLibravatar Jeff King1-1/+7
The explanation for the --file option only refers to GIT_CONFIG. This redirection to an environment variable is confusing, but doubly so because the description of GIT_CONFIG is out of date. Let's describe --file from scratch, detailing both the reading and writing behavior as we do for other similar options like --system, etc. Signed-off-by: Jeff King <peff@peff.net> Reviewed-by: Taylor Blau <me@ttaylorr.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-07-16The fifth batchLibravatar Junio C Hamano1-0/+29
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-07-16Merge branch 'ds/gender-neutral-doc'Libravatar Junio C Hamano3-6/+5
Update the documentation not to assume users are of certain gender and adds to guidelines to do so. * ds/gender-neutral-doc: *: fix typos comments: avoid using the gender of our users doc: avoid using the gender of other people
2021-07-16Merge branch 'ab/fetch-negotiate-segv-fix'Libravatar Junio C Hamano2-3/+13
Code recently added to support common ancestry negotiation during "git push" did not sanity check its arguments carefully enough. * ab/fetch-negotiate-segv-fix: fetch: fix segfault in --negotiate-only without --negotiation-tip=* fetch: document the --negotiate-only option send-pack.c: move "no refs in common" abort earlier
2021-07-16CodingGuidelines: recommend gender-neutral descriptionLibravatar Junio C Hamano1-0/+45
Technical writing seeks to convey information with minimal friction. One way that a reader can experience friction is if they encounter a description of "a user" that is later simplified using a gendered pronoun. If the reader does not consider that pronoun to apply to them, then they can experience cognitive dissonance that removes focus from the information. Give some basic tips to guide us avoid unnecessary uses of gendered description. Using a gendered pronoun is appropriate when referring to a specific person. There are acceptable existing uses of gendered pronouns within the Git codebase, such as: * References to real people (e.g. Linus Torvalds, "the Git maintainer"). Do not misgender real people. If there is any doubt to the gender of a person, then avoid using pronouns. * References to fictional people with clear genders (e.g. Alice and Bob). * Sample text used in test cases (e.g t3702, t6432). * The official text of the GPL license contains uses of "he or she", but using singular "they" (or modifying the text in some other way) is not within the scope of the Git project. * Literal email messages in Documentation/howto/ should not be edited for grammatical concerns such as this, unless we update the entire document to fit the standard documentation format. If such an effort is taken on, then the authorship would change and no longer refer to the exact mail message. * External projects consumed in contrib/ should not deviate solely for style reasons. Recommended edits should be contributed to those projects directly. Other cases within the Git project were cleaned up by the previous changes. Co-authored-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Derrick Stolee <dstolee@microsoft.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-07-15rename: bump limit defaults yet againLibravatar Elijah Newren2-2/+2
These were last bumped in commit 92c57e5c1d29 (bump rename limit defaults (again), 2011-02-19), and were bumped both because processors had gotten faster, and because people were getting ugly merges that caused problems and reporting it to the mailing list (suggesting that folks were willing to spend more time waiting). Since that time: * Linus has continued recommending kernel folks to set diff.renameLimit=0 (maps to 32767, currently) * Folks with repositories with lots of renames were happy to set merge.renameLimit above 32767, once the code supported that, to get correct cherry-picks * Processors have gotten faster * It has been discovered that the timing methodology used last time probably used too large example files. The last point is probably worth explaining a bit more: * The "average" file size used appears to have been average blob size in the linux kernel history at the time (probably v2.6.25 or something close to it). * Since bigger files are modified more frequently, such a computation weights towards larger files. * Larger files may be more likely to be modified over time, but are not more likely to be renamed -- the mean and median blob size within a tree are a bit higher than the mean and median of blob sizes in the history leading up to that version for the linux kernel. * The mean blob size in v2.6.25 was half the average blob size in history leading to that point * The median blob size in v2.6.25 was about 40% of the mean blob size in v2.6.25. * Since the mean blob size is more than double the median blob size, any file as big as the mean will not be compared to any files of median size or less (because they'd be more than 50% dissimilar). * Since it is the number of files compared that provides the O(n^2) behavior, median-sized files should matter more than mean-sized ones. The combined effect of the above is that the file size used in past calculations was likely about 5x too large. Combine that with a CPU performance improvement of ~30%, and we can increase the limits by a factor of sqrt(5/(1-.3)) = 2.67, while keeping the original stated time limits. Keeping the same approximate time limit probably makes sense for diff.renameLimit (there is no progress feedback in e.g. git log -p), but the experience above suggests merge.renameLimit could be extended significantly. In fact, it probably would make sense to have an unlimited default setting for merge.renameLimit, but that would likely need to be coupled with changes to how progress is displayed. (See https://lore.kernel.org/git/YOx+Ok%2FEYvLqRMzJ@coredump.intra.peff.net/ for details in that area.) For now, let's just bump the approximate time limit from 10s to 1m. (Note: We do not want to use actual time limits, because getting results that depend on how loaded your system is that day feels bad, and because we don't discover that we won't get all the renames until after we've put in a lot of work rather than just upfront telling the user there are too many files involved.) Using the original time limit of 2s for diff.renameLimit, and bumping merge.renameLimit from 10s to 60s, I found the following timings using the simple script at the end of this commit message (on an AWS c5.xlarge which reports as "Intel(R) Xeon(R) Platinum 8124M CPU @ 3.00GHz"): N Timing 1300 1.995s 7100 59.973s So let's round down to nice even numbers and bump the limits from 400->1000, and from 1000->7000. Here is the measure_rename_perf script (adapted from https://lore.kernel.org/git/20080211113516.GB6344@coredump.intra.peff.net/ in particular to avoid triggering the linear handling from basename-guided rename detection): #!/bin/bash n=$1; shift rm -rf repo mkdir repo && cd repo git init -q -b main mkdata() { mkdir $1 for i in `seq 1 $2`; do (sed "s/^/$i /" <../sample echo tag: $1 ) >$1/$i done } mkdata initial $n git add . git commit -q -m initial mkdata new $n git add . cd new for i in *; do git mv $i $i.renamed; done cd .. git rm -q -rf initial git commit -q -m new time git diff-tree -M -l0 --summary HEAD^ HEAD Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-07-15diffcore-rename: treat a rename_limit of 0 as unlimitedLibravatar Elijah Newren1-0/+1
In commit 89973554b52c (diffcore-rename: make diff-tree -l0 mean -l<large>, 2017-11-29), -l0 was given a special magical "large" value, but one which was not large enough for some uses (as can be seen from commit 9f7e4bfa3b6d (diff: remove silent clamp of renameLimit, 2017-11-13). Make 0 (or a negative value) be treated as unlimited instead and update the documentation to mention this. Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-07-15doc: clarify documentation for rename/copy limitsLibravatar Elijah Newren3-12/+20
A few places in the docs implied that rename/copy detection is always quadratic or that all (unpaired) files were involved in the quadratic portion of rename/copy detection. The following two commits each introduced an exception to this: 9027f53cb505 (Do linear-time/space rename logic for exact renames, 2007-10-25) bd24aa2f97a0 (diffcore-rename: guide inexact rename detection based on basenames, 2021-02-14) (As a side note, for copy detection, the basename guided inexact rename detection is turned off and the exact renames will only result in sources (without the dests) being removed from the set of files used in quadratic detection. So, for copy detection, the documentation was closer to correct.) Avoid implying that all files involved in rename/copy detection are subject to the full quadratic algorithm. While at it, also note the default values for all these settings. Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-07-15worktree: teach `add` to accept --reason <string> with --lockLibravatar Stephen Manz1-2/+2
The default reason stored in the lock file, "added with --lock", is unlikely to be what the user would have given in a separate `git worktree lock` command. Allowing `--reason` to be specified along with `--lock` when adding a working tree gives the user control over the reason for locking without needing a second command. Signed-off-by: Stephen Manz <smanz@alum.mit.edu> Reviewed-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-07-13The fourth batchLibravatar Junio C Hamano1-0/+26
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-07-13Merge branch 'bk/doc-commit-typofix'Libravatar Junio C Hamano1-1/+1
Doc typo/grammo-fix. * bk/doc-commit-typofix: Documentation: fix typo in the --patch option of the commit command
2021-07-13Merge branch 'fc/push-simple-updates'Libravatar Junio C Hamano1-7/+6
Some code and doc clarification around "git push". * fc/push-simple-updates: doc: push: explain default=simple correctly push: remove unused code in setup_push_upstream() push: simplify setup_push_simple() push: reorganize setup_push_simple() push: copy code to setup_push_simple() push: hedge code of default=simple push: rename !triangular to same_remote
2021-07-13doc/rev-list-options: fix duplicate word typoLibravatar Jeff King1-1/+1
Reported-by: Jason Hatton <jhatton@globalfinishing.com> Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-07-12git-diff: fix missing --merge-base docsLibravatar Denton Liu1-3/+7
When `git diff --merge-base` was introduced at around Git 2.30, the documentation included a few errors. In the example given for `git diff --cached --merge-base`, the `--cached` flag was omitted for the `--merge-base` example. Add the missing flag. In the `git diff <commit>` case, we failed to mention that `--merge-base` is an available option. Give the usage of `--merge-base` as an option there. Finally, there are two errors in the usage of `git diff`. Firstly, we do not mention `--merge-base` in the `git diff --cached` case. Mention it so that it's consistent with the documentation. Secondly, we put the `[--merge-base]` in between `<commit>` and `[<commit>...]`. Move the `[--merge-base]` so that it's beside `[<options>]` which is a more logical grouping. Signed-off-by: Denton Liu <liu.denton@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-07-12rev-list: add option for --pretty=format without headerLibravatar brian m. carlson1-0/+8
In general, we encourage users to use plumbing commands, like git rev-list, over porcelain commands, like git log, when scripting. However, git rev-list has one glaring problem that prevents it from being used in certain cases: when --pretty is used with a custom format, it always prints out a line containing "commit" and the object ID. This makes it unsuitable for many scripting needs, and forces users to use git log instead. While we can't change this behavior for backwards compatibility, we can add an option to suppress this behavior, so let's do so, and call it "--no-commit-header". Additionally, add the corresponding positive option to switch it back on. Note that this option doesn't affect the built-in formats, only custom formats. This is exactly the same behavior as users already have from git log and is what most users will be used to. Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-07-08The third batchLibravatar Junio C Hamano1-0/+77
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-07-08Merge branch 'dd/document-log-decorate-default'Libravatar Junio C Hamano1-1/+3
Doc clean-up. * dd/document-log-decorate-default: doc/log: correct default for --decorate
2021-07-08Merge branch 'ar/doc-libera-chat-in-my-first-contrib'Libravatar Junio C Hamano1-2/+2
Update MyFirst document. * ar/doc-libera-chat-in-my-first-contrib: MyFirstContribution: link #git-devel to Libera Chat
2021-07-08Merge branch 'jk/doc-max-pack-size'Libravatar Junio C Hamano3-10/+23
Doc update. * jk/doc-max-pack-size: doc: warn people against --max-pack-size
2021-07-08Merge branch 'ar/more-typofix'Libravatar Junio C Hamano2-2/+2
Typofixes. * ar/more-typofix: git-worktree.txt: fix typo in example path t: fix typos in test messages blame: correct name of config option in docs
2021-07-08Merge branch 'ar/typofix'Libravatar Junio C Hamano6-7/+7
Typofixes. * ar/typofix: *: fix typos which duplicate a word
2021-07-08Merge branch 'fc/doc-default-to-upstream-config'Libravatar Junio C Hamano1-1/+1
Doc clean-up. * fc/doc-default-to-upstream-config: doc: merge: mention default of defaulttoupstream
2021-07-08Merge branch 'js/trace2-discard-event-docfix'Libravatar Junio C Hamano1-2/+2
Docfix. * js/trace2-discard-event-docfix: docs: fix api-trace2 doc for "too_many_files" event
2021-07-08Merge branch 'tk/partial-clone-repack-doc'Libravatar Junio C Hamano1-5/+1
Docfix. * tk/partial-clone-repack-doc: Remove warning that repack only works on non-promisor packfiles
2021-07-06docs: .gitignore parsing is to the top of the repoLibravatar Andrew Berry1-6/+5
The current documentation reads as if .gitignore files will be parsed in every parent directory, and not until they reach a repository boundary. This clarifies the current behaviour. As well, this corrects 'toplevel' to 'top-level', matching usage for 'top-level domain'. Signed-off-by: Andrew Berry <andrew@furrypaws.ca> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-06-30fetch: document the --negotiate-only optionLibravatar Ævar Arnfjörð Bjarmason2-3/+13
There was no documentation for the --negotiate-only option added in 9c1e657a8fd (fetch: teach independent negotiation (no packfile), 2021-05-04), only documentation for the related push.negotiation option added in the following commit in 477673d6f39 (send-pack: support push negotiation, 2021-05-04). Let's document it, and update the cross-linking I'd added between --negotiation-tip=* and 'fetch.negotiationAlgorithm' in 526608284a7 (fetch doc: cross-link two new negotiation options, 2018-08-01). I think it would be better to say "in common with the remote" here than "...the server", but the documentation for --negotiation-tip=* above this talks about "the server", so let's continue doing that in this related option. See 3390e42adb3 (fetch-pack: support negotiation tip whitelist, 2018-07-02) for that documentation. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-06-28Documentation: fix typo in the --patch option of the commit commandLibravatar Beshr Kayali1-1/+1
Typofix (chose -> choose) in the documentation of the patch option under the commit command. Signed-off-by: Beshr Kayali <me@beshr.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-06-28git-worktree.txt: fix typo in example pathLibravatar Andrei Rybak1-1/+1
Signed-off-by: Andrei Rybak <rybak.a.v@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-06-28blame: correct name of config option in docsLibravatar Andrei Rybak1-1/+1
As can be seen in files "Documentation/blame-options.txt" and "builtin/blame.c", the name of this configuration option is "blame.markUnblamableLines". Signed-off-by: Andrei Rybak <rybak.a.v@gmail.com> Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-06-16doc: avoid using the gender of other peopleLibravatar Felipe Contreras3-6/+5
Using gendered pronouns for an anonymous person applies a gender where none is known and further excludes readers who do not use gendered pronouns. Avoid such examples in the documentation by using "they" or passive voice to avoid the need for a pronoun. Inspired-by: Derrick Stolee <dstolee@microsoft.com> Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Derrick Stolee <dstolee@microsoft.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-06-14The second batchLibravatar Junio C Hamano1-2/+48
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-06-14Merge branch 'fc/doc-build-cleanup'Libravatar Junio C Hamano1-48/+29
Preparatory build procedure clean-up for documentation. * fc/doc-build-cleanup: doc: avoid using rm directly doc: simplify Makefile using .DELETE_ON_ERROR doc: remove unnecessary rm instances doc: improve asciidoc dependencies doc: refactor common asciidoc dependencies