summaryrefslogtreecommitdiff
path: root/Documentation
AgeCommit message (Collapse)AuthorFilesLines
2020-03-17Merge branch 'jc/doc-single-h-is-for-help' into maintLibravatar Junio C Hamano2-1/+8
Both "git ls-remote -h" and "git grep -h" give short usage help, like any other Git subcommand, but it is not unreasonable to expect that the former would behave the same as "git ls-remote --head" (there is no other sensible behaviour for the latter). The documentation has been updated in an attempt to clarify this. * jc/doc-single-h-is-for-help: Documentation: clarify that `-h` alone stands for `help`
2020-03-17Merge branch 'en/check-ignore' into maintLibravatar Junio C Hamano1-3/+9
"git check-ignore" did not work when the given path is explicitly marked as not ignored with a negative entry in the .gitignore file. * en/check-ignore: check-ignore: fix documentation and implementation to match
2020-03-17Merge branch 'jk/push-option-doc-markup-fix' into maintLibravatar Junio C Hamano1-2/+2
Doc markup fix. * jk/push-option-doc-markup-fix: doc/config/push: use longer "--" line for preformatted example
2020-03-17Merge branch 'jk/doc-diff-parallel' into maintLibravatar Junio C Hamano1-1/+1
Update to doc-diff. * jk/doc-diff-parallel: doc-diff: use single-colon rule in rendering Makefile
2020-02-27Documentation: clarify that `-h` alone stands for `help`Libravatar Junio C Hamano2-1/+8
We seem to be getting new users who get confused every 20 months or so with this "-h consistently wants to give help, but the commands to which `-h` may feel like a good short-form option want it to mean something else." compromise. Let's make sure that the readers know that `git cmd -h` (with no other arguments) is a way to get usage text, even for commands like ls-remote and grep. Also extend the description that is already in gitcli.txt, as it is clear that users still get confused with the current text. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-02-18check-ignore: fix documentation and implementation to matchLibravatar Elijah Newren1-3/+9
check-ignore has two different modes, and neither of these modes has an implementation that matches the documentation. These modes differ in whether they just print paths or whether they also print the final pattern matched by the path. The fix is different for both modes, so I'll discuss both separately. === First (default) mode === The first mode is documented as: For each pathname given via the command-line or from a file via --stdin, check whether the file is excluded by .gitignore (or other input files to the exclude mechanism) and output the path if it is excluded. However, it fails to do this because it did not account for negated patterns. Commands other than check-ignore verify exclusion rules via calling ... -> treat_one_path() -> is_excluded() -> last_matching_pattern() while check-ignore has a call path of the form: ... -> check_ignore() -> last_matching_pattern() The fact that the latter does not include the call to is_excluded() means that it is susceptible to to messing up negated patterns (since that is the only significant thing is_excluded() adds over last_matching_pattern()). Unfortunately, we can't make it just call is_excluded(), because the same codepath is used by the verbose mode which needs to know the matched pattern in question. This brings us to... === Second (verbose) mode === The second mode, known as verbose mode, references the first in the documentation and says: Also output details about the matching pattern (if any) for each given pathname. For precedence rules within and between exclude sources, see gitignore(5). The "Also" means it will print patterns that match the exclude rules as noted for the first mode, and also print which pattern matches. Unless more information is printed than just pathname and pattern (which is not done), this definition is somewhat ill-defined and perhaps even self-contradictory for negated patterns: A path which matches a negated exclude pattern is NOT excluded and thus shouldn't be printed by the former logic, while it certainly does match one of the explicit patterns and thus should be printed by the latter logic. === Resolution == Since the second mode exists to find out which pattern matches given paths, and showing the user a pattern that begins with a '!' is sufficient for them to figure out whether the pattern is excluded, the existing behavior is desirable -- we just need to update the documentation to match the implementation (i.e. it is about printing which pattern is matched by paths, not about showing which paths are excluded). For the first or default mode, users just want to know whether a pattern is excluded. As such, the existing documentation is desirable; change the implementation to match the documented behavior. Finally, also adjust a few tests in t0008 that were caught up by this discrepancy in how negated paths were handled. Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-02-18doc-diff: use single-colon rule in rendering MakefileLibravatar Jeff King1-1/+1
When rendering the troff manpages to text via "man", we create an ad-hoc Makefile and feed it to "make". The purpose here is two-fold: - reuse results from a prior interrupted render of the same tree - use make's -j option to build in parallel But the second part doesn't seem to work (at least with my version of GNU make, 4.2.1). It just runs one render at a time. We use a double-colon "all" rule for each file, like: all:: foo foo: ...actual render recipe... all:: bar bar: ...actual render recipe... ...and so on... And it's this double-colon that seems to inhibit the parallelism. We can just switch to a regular single-colon rule. Even though we do have multiple rules for "all" here, we don't have any recipe to execute for "all" (we only care about triggering its dependencies), so the distinction is irrelevant. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-02-18doc/config/push: use longer "--" line for preformatted exampleLibravatar Jeff King1-2/+2
The example for the push.pushOption config tries to create a preformatted section, but uses only two dashes in its "--" line. In AsciiDoc this is an "open block", with no type; the lines end up jumbled because they're formatted as paragraphs. We need four or more dashes to make it a "listing block" that will respect the linebreaks. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-02-16Git 2.25.1Libravatar Junio C Hamano1-0/+55
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-02-14Merge branch 'jb/multi-pack-index-docfix' into maintLibravatar Junio C Hamano1-2/+3
Doc fix. * jb/multi-pack-index-docfix: pack-format: correct multi-pack-index description
2020-02-14Merge branch 'ma/diff-doc-clarify-regexp-example' into maintLibravatar Junio C Hamano1-4/+4
Doc clarification. * ma/diff-doc-clarify-regexp-example: diff-options.txt: avoid "regex" overload in example
2020-02-14Merge branch 'ms/doc-bundle-format' into maintLibravatar Junio C Hamano1-0/+48
Technical details of the bundle format has been documented. I think this is in a good enough shape. * ms/doc-bundle-format: doc: describe Git bundle format
2020-02-14Merge branch 'ma/filter-branch-doc-caret' into maintLibravatar Junio C Hamano1-3/+3
Doc mark-up updates. * ma/filter-branch-doc-caret: git-filter-branch.txt: wrap "maths" notation in backticks
2020-02-14Merge branch 'km/submodule-doc-use-sm-path' into maintLibravatar Junio C Hamano1-1/+1
Docfix. * km/submodule-doc-use-sm-path: submodule foreach: replace $path with $sm_path in example
2020-02-14Merge branch 'pb/do-not-recurse-grep-no-index' into maintLibravatar Junio C Hamano1-1/+2
"git grep --no-index" should not get affected by the contents of the .gitmodules file but when "--recurse-submodules" is given or the "submodule.recurse" variable is set, it did. Now these settings are ignored in the "--no-index" mode. * pb/do-not-recurse-grep-no-index: grep: ignore --recurse-submodules if --no-index is given
2020-02-14Merge branch 'bc/misconception-doc' into maintLibravatar Junio C Hamano2-0/+24
Doc updates. * bc/misconception-doc: docs: mention when increasing http.postBuffer is valuable doc: dissuade users from trying to ignore tracked files
2020-02-14Merge branch 'bc/author-committer-doc' into maintLibravatar Junio C Hamano4-27/+69
Clarify documentation on committer/author identities. * bc/author-committer-doc: doc: provide guidance on user.name format docs: expand on possible and recommended user config options doc: move author and committer information to git-commit(1)
2020-02-14Merge branch 'ds/refmap-doc' into maintLibravatar Junio C Hamano1-1/+4
"git fetch --refmap=" option has got a better documentation. * ds/refmap-doc: fetch: document and test --refmap=""
2020-02-14Merge branch 'bc/actualmente' into maintLibravatar Junio C Hamano1-2/+2
Doc grammo fix. * bc/actualmente: docs: use "currently" for the present time
2020-02-14Merge branch 'hw/tutorial-favor-switch-over-checkout' into maintLibravatar Junio C Hamano1-1/+1
Complete an update to tutorial that encourages "git switch" over "git checkout" that was done only half-way. * hw/tutorial-favor-switch-over-checkout: doc/gitcore-tutorial: fix prose to match example command
2020-02-10pack-format: correct multi-pack-index descriptionLibravatar Johannes Berg1-2/+3
The description of the multi-pack-index contains a small bug, if all offsets are < 2^32 then there will be no LOFF chunk, not only if they're all < 2^31 (since the highest bit is only needed as the "LOFF-escape" when that's actually needed.) Correct this, and clarify that in that case only offsets up to 2^31-1 can be stored in the OOFF chunk. Signed-off-by: Johannes Berg <johannes@sipsolutions.net> Acked-by: Derrick Stolee <dstolee@microsoft.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-02-09diff-options.txt: avoid "regex" overload in exampleLibravatar Martin Ågren1-4/+4
When we exemplify the difference between `-G` and `-S` (using `--pickaxe-regex`), we do so using an example diff and git-diff invocation involving "regexec", "regexp", "regmatch", ... The example is correct, but we can make it easier to untangle by avoiding writing "regex.*" unless it's really needed to make our point. Use some made-up, non-regexy words instead. Reported-by: Adam Dinwoodie <adam@dinwoodie.org> Signed-off-by: Martin Ågren <martin.agren@gmail.com> Reviewed-by: Taylor Blau <me@ttaylorr.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-02-07doc: describe Git bundle formatLibravatar Masaya Suzuki1-0/+48
The bundle format was not documented. Describe the format with ABNF and explain the meaning of each part. Signed-off-by: Masaya Suzuki <masayasuzuki@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-02-04git-filter-branch.txt: wrap "maths" notation in backticksLibravatar Martin Ågren1-3/+3
In this paragraph, we have a few instances of the '^' character, which we give as "\^". This renders well with AsciiDoc ("^"), but Asciidoctor renders it literally as "\^". Dropping the backslashes renders fine with Asciidoctor, but not AsciiDoc... An earlier version of this patch used "{caret}" instead of "^", which avoided these escaping problems. The rendering was still so-so, though -- these expressions end up set as normal text, similarly to when one provides, e.g., computer code in the middle of running text, without properly marking it with `backticks` to be monospaced. As noted by Jeff King, this suggests actually wrapping these expressions in backticks, setting them in monospace. The lone "5" could be left as is or wrapped as `5`. Spell it out as "five" instead -- this generally looks better anyway for small numbers in the middle of text like this. Suggested-by: Jeff King <peff@peff.net> Signed-off-by: Martin Ågren <martin.agren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-01-31submodule foreach: replace $path with $sm_path in exampleLibravatar Kyle Meyer1-1/+1
f0fd0dc5c5 (submodule foreach: document '$sm_path' instead of '$path', 2018-05-08) updated the documentation to advise callers to favor $sm_path over the deprecated synonym $path. However, the example in that section still uses $path. Update it to use $sm_path. Signed-off-by: Kyle Meyer <kyle@kyleam.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-01-30grep: ignore --recurse-submodules if --no-index is givenLibravatar Philippe Blain1-1/+2
Since grep learned to recurse into submodules in 0281e487fd (grep: optionally recurse into submodules, 2016-12-16), using --recurse-submodules along with --no-index makes Git die(). This is unfortunate because if submodule.recurse is set in a user's ~/.gitconfig, invoking `git grep --no-index` either inside or outside a Git repository results in fatal: option not supported with --recurse-submodules Let's allow using these options together, so that setting submodule.recurse globally does not prevent using `git grep --no-index`. Using `--recurse-submodules` should not have any effect if `--no-index` is used inside a repository, as Git will recurse into the checked out submodule directories just like into regular directories. Helped-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-01-22docs: mention when increasing http.postBuffer is valuableLibravatar brian m. carlson1-0/+8
Users in a wide variety of situations find themselves with HTTP push problems. Oftentimes these issues are due to antivirus software, filtering proxies, or other man-in-the-middle situations; other times, they are due to simple unreliability of the network. However, a common solution to HTTP push problems found online is to increase http.postBuffer. This works for none of the aforementioned situations and is only useful in a small, highly restricted number of cases: essentially, when the connection does not properly support HTTP/1.1. Document when raising this value is appropriate and what it actually does, and discourage people from using it as a general solution for push problems, since it is not effective there. Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-01-22doc: dissuade users from trying to ignore tracked filesLibravatar brian m. carlson1-0/+16
It is quite common for users to want to ignore the changes to a file that Git tracks. Common scenarios for this case are IDE settings and configuration files, which should generally not be tracked and possibly generated from tracked files using a templating mechanism. However, users learn about the assume-unchanged and skip-worktree bits and try to use them to do this anyway. This is problematic, because when these bits are set, many operations behave as the user expects, but they usually do not help when git checkout needs to replace a file. There is no sensible behavior in this case, because sometimes the data is precious, such as certain configuration files, and sometimes it is irrelevant data that the user would be happy to discard. Since this is not a supported configuration and users are prone to misuse the existing features for unintended purposes, causing general sadness and confusion, let's document the existing behavior and the pitfalls in the documentation for git update-index so that users know they should explore alternate solutions. In addition, let's provide a recommended solution to dealing with the common case of configuration files, since there are well-known approaches used successfully in many environments. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-01-22doc: provide guidance on user.name formatLibravatar brian m. carlson2-1/+12
It's a frequent misconception that the user.name variable controls authentication in some way, and as a result, beginning users frequently attempt to change it when they're having authentication troubles. Document that the convention is that this variable represents some form of a human's personal name, although that is not required. In addition, address concerns about whether Unicode is supported. Use the term "personal name" as this is likely to draw the intended contrast, be applicable across cultures which may have different naming conventions, and be easily understandable to people who do not speak English as their first language. Indicate that "some form" is conventionally used, as people may use a nickname or preferred name instead of a full legal name. Point users who may be confused about authentication to an appropriate configuration option instead. Provide a shortened form of this information in the configuration option description. Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-01-22docs: expand on possible and recommended user config optionsLibravatar brian m. carlson1-0/+7
In the section on setting author and committer information, we omit the author.* and committer.* variables, so mention them for completeness. In addition, guide users to the typical case: simply setting user.name and user.email, which are recommended if one does not need complex configuration. Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-01-22doc: move author and committer information to git-commit(1)Libravatar brian m. carlson4-27/+51
While at one time it made perfect sense to store information about configuring author and committer information in the documentation for git commit-tree, in modern Git that operation is seldom used. Most users will use git commit and expect to find comprehensive documentation about its use in the manual page for that command. Considering that there is significant confusion about how one is to use the user.name and user.email variables, let's put as much documentation as possible into an obvious place where users will be more likely to find it. In addition, expand the environment variables section to describe their use more fully. Even though we now describe all of the options there and in the configuration settings documentation, preserve the existing text in git-commit.txt so that people can easily reason about the ordering of the various options they can use. Explain the use of the author.* and committer.* options as well. Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-01-21docs: use "currently" for the present timeLibravatar brian m. carlson1-2/+2
In many languages, the adverb with the root "actual" means "at the present time." However, this usage is considered dated or even archaic in English, and for referring to events occurring at the present time, we usually prefer "currently" or "presently". "Actually" is commonly used in modern English only for the meaning of "in fact" or to express a contrast with what is expected. Since the documentation refers to the available options at the present time (that is, at the time of writing) instead of drawing a contrast, let's switch to "currently," which both is commonly used and sounds less formal than "presently." Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-01-21fetch: document and test --refmap=""Libravatar Derrick Stolee1-1/+4
To prevent long blocking time during a 'git fetch' call, a user may want to set up a schedule for background 'git fetch' processes. However, these runs will update the refs/remotes branches due to the default refspec set in the config when Git adds a remote. Hence the user will not notice when remote refs are updated during their foreground fetches. In fact, they may _want_ those refs to stay put so they can work with the refs from their last foreground fetch call. This can be accomplished by overriding the configured refspec using '--refmap=' along with a custom refspec: git fetch --refmap='' <remote> +refs/heads/*:refs/hidden/<remote>/* to populate a custom ref space and download a pack of the new reachable objects. This kind of call allows a few things to happen: 1. We download a new pack if refs have updated. 2. Since the refs/hidden branches exist, GC will not remove the newly-downloaded data. 3. With fetch.writeCommitGraph enabled, the refs/hidden refs are used to update the commit-graph file. To avoid the refs/hidden directory from filling without bound, the --prune option can be included. When providing a refspec like this, the --prune option does not delete remote refs and instead only deletes refs in the target refspace. Update the documentation to clarify how '--refmap=""' works and create tests to guarantee this behavior remains in the future. Signed-off-by: Derrick Stolee <dstolee@microsoft.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-01-12Revert "Merge branch 'ra/rebase-i-more-options'"Libravatar Junio C Hamano2-24/+6
This reverts commit 5d9324e0f4210bb7d52bcb79efe3935703083f72, reversing changes made to c58ae96fc4bb11916b62a96940bb70bb85ea5992. The topic turns out to be too buggy for real use. cf. <f2fe7437-8a48-3315-4d3f-8d51fe4bb8f1@gmail.com>
2020-01-10Merge branch 'ma/config-advice-markup-fix'Libravatar Junio C Hamano1-1/+1
Documentation markup fix. * ma/config-advice-markup-fix: config/advice.txt: fix description list separator
2020-01-08config/advice.txt: fix description list separatorLibravatar Martin Ågren1-1/+1
The whole submoduleAlternateErrorStrategyDie item is interpreted as being part of the supporting content of the preceding item. This is because we don't give a double-colon "::" for the separator, but just a single colon, ":". Let's fix that. There are a few other matches for [^:]:\s*$ in Documentation/config, but I didn't spot any similar bugs among them. Signed-off-by: Martin Ågren <martin.agren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-01-08Git 2.25-rc2Libravatar Junio C Hamano1-0/+4
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-01-08Merge branch 'tm/doc-submodule-absorb-fix'Libravatar Junio C Hamano1-1/+1
Typofix. * tm/doc-submodule-absorb-fix: doc: submodule: fix typo for command absorbgitdirs
2020-01-08Merge branch 'pm/am-in-body-header-doc-update'Libravatar Junio C Hamano1-2/+2
Doc update. * pm/am-in-body-header-doc-update: am: document that Date: can appear as an in-body header
2020-01-08Merge branch 'jb/doc-multi-pack-idx-fix'Libravatar Junio C Hamano1-1/+1
Typofix. * jb/doc-multi-pack-idx-fix: multi-pack-index: correct configuration in documentation
2020-01-08doc/gitcore-tutorial: fix prose to match example commandLibravatar Heba Waly1-1/+1
In 328c6cb853 (doc: promote "git switch", 2019-03-29), an example was changed to use "git switch" rather than "git checkout" but an instance of "git checkout" in the explanatory text preceding the example was overlooked. Fix this oversight. Signed-off-by: Heba Waly <heba.waly@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-01-06The final batch before -rc2Libravatar Junio C Hamano1-2/+18
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-01-06Merge branch 'ds/sparse-cone'Libravatar Junio C Hamano1-1/+1
Code cleanup. * ds/sparse-cone: Documentation/git-sparse-checkout.txt: fix a typo sparse-checkout: use extern for global variables
2020-01-06Merge branch 'ds/sparse-list-in-cone-mode'Libravatar Junio C Hamano1-1/+20
"git sparse-checkout list" subcommand learned to give its output in a more concise form when the "cone" mode is in effect. * ds/sparse-list-in-cone-mode: sparse-checkout: document interactions with submodules sparse-checkout: list directories in cone mode
2020-01-06Merge branch 'pb/clarify-line-log-doc'Libravatar Junio C Hamano2-4/+12
Doc update. * pb/clarify-line-log-doc: doc: log, gitk: line-log arguments must exist in starting revision doc: log, gitk: document accepted line-log diff formats
2020-01-06doc: submodule: fix typo for command absorbgitdirsLibravatar Thomas Menzel1-1/+1
The sentence wants to talk about the superproject's possesive, not plural form. Signed-off-by: Thomas Menzel <dev@tomsit.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-01-04am: document that Date: can appear as an in-body headerLibravatar Paul Menzel1-2/+2
Similar to "From:" and "Subject:" already mentioned in the documentation, "Date:" can also appear as an in-body header to override the value in the e-mail headers. Document it. Signed-off-by: Paul Menzel <pmenzel@molgen.mpg.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-01-04multi-pack-index: correct configuration in documentationLibravatar Johannes Berg1-1/+1
It's core.multiPackIndex, not pack.multiIndex. Signed-off-by: Johannes Berg <johannes@sipsolutions.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-01-04Documentation/git-sparse-checkout.txt: fix a typoLibravatar Taylor Blau1-1/+1
This typo was introduced in 94c0956b60 (sparse-checkout: create builtin with 'list' subcommand, 2019-11-21). Signed-off-by: Taylor Blau <me@ttaylorr.com> Acked-by: Derrick Stolee <dstolee@microsoft.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-01-02Git 2.25-rc1Libravatar Junio C Hamano1-0/+13
Signed-off-by: Junio C Hamano <gitster@pobox.com>