summaryrefslogtreecommitdiff
path: root/Documentation/gitcli.txt
AgeCommit message (Collapse)AuthorFilesLines
2020-03-11Merge branch 'jc/doc-single-h-is-for-help'Libravatar Junio C Hamano1-0/+5
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-02-27Documentation: clarify that `-h` alone stands for `help`Libravatar Junio C Hamano1-0/+5
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>
2019-12-06Merge branch 'dl/lore-is-the-archive'Libravatar Junio C Hamano1-2/+2
Publicize lore.kernel.org mailing list archive and use URLs pointing into it to refer to notable messages in the documentation. * dl/lore-is-the-archive: doc: replace LKML link with lore.kernel.org RelNotes: replace Gmane with real Message-IDs doc: replace MARC links with lore.kernel.org
2019-12-04doc: replace MARC links with lore.kernel.orgLibravatar Denton Liu1-2/+2
Since we're now recommending lore.kernel.org, replace marc.info links with lore.kernel.org. Although MARC has been around for a long time, nothing lasts forever (see Gmane). Since MARC uses opaque message identifiers, switching to lore.kernel.org should be a strict improvement since, even if lore.kernel.org goes down, the Message-ID will allow future readers to look up the referenced messages on any other archive. We leave behind one reference to MARC in the README.md since it's a perfectly fine mail archive for personal reading, just not for linking messages for the future. Signed-off-by: Denton Liu <liu.denton@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-08-06gitcli: document --end-of-optionsLibravatar Jeff King1-0/+6
Now that --end-of-options is available for any users of setup_revisions() or parse_options(), which should be effectively everywhere, we can guide people to use it for all their disambiguating needs. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-05-07doc: promote "git restore"Libravatar Nguyễn Thái Ngọc Duy1-2/+2
The new command "git restore" (together with "git switch") are added to avoid the confusion of one-command-do-all "git checkout" for new users. They are also helpful to avoid ambiguous context. For these reasons, promote it everywhere possible. This includes documentation, suggestions/advice from other commands. One nice thing about git-restore is the ability to restore "everything", so it can be used in "git status" advice instead of both "git checkout" and "git reset". The three commands suggested by "git status" are add, rm and restore. "git checkout" is also removed from "git help" (i.e. it's no longer considered a commonly used command) Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-05-07checkout: split part of it to new command 'restore'Libravatar Nguyễn Thái Ngọc Duy1-0/+12
Previously the switching branch business of 'git checkout' becomes a new command 'switch'. This adds the restore command for the checking out paths path. Similar to git-switch, a new man page is added to describe what the command will become. The implementation will be updated shortly to match the man page. A couple main differences from 'git checkout <paths>': - 'restore' by default will only update worktree. This matters more when --source is specified ('checkout <tree> <paths>' updates both worktree and index). - 'restore --staged' can be used to restore the index. This command overlaps with 'git reset <paths>'. - both worktree and index could also be restored at the same time (from a tree) when both --staged and --worktree are specified. This overlaps with 'git checkout <tree> <paths>' - default source for restoring worktree and index is the index and HEAD respectively. A different (tree) source could be specified as with --source (*). - when both index and worktree are restored, --source must be specified since the default source for these two individual targets are different (**) - --no-overlay is enabled by default, if an entry is missing in the source, restoring means deleting the entry (*) I originally went with --from instead of --source. I still think --from is a better name. The short option -f however is already taken by force. And I do think short option is good to have, e.g. to write -s@ or -s@^ instead of --source=HEAD. (**) If you sit down and think about it, moving worktree's source from the index to HEAD makes sense, but nobody is really thinking it through when they type the commands. Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-05-25Use proper syntax for replaceables in command docsLibravatar Robert P. J. Day1-2/+2
The standard for command documentation synopses appears to be: [...] means optional <...> means replaceable [<...>] means both optional and replaceable So fix a number of doc pages that use incorrect variations of the above. Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-06-18stash: update documentation to use 'stash entry'Libravatar Liam Beguin1-1/+1
Most of the time, a 'stash entry' is called a 'stash'. Lets try to make this more consistent and use 'stash entry' instead. Signed-off-by: Liam Beguin <liambeguin@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-05-21Documentation: use "command-line" when used as a compound adjective, and fix ↵Libravatar Jason St. John1-4/+4
other minor grammatical issues Signed-off-by: Jason St. John <jstjohn@purdue.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-02-07Merge branch 'ow/manpages-typofix'Libravatar Junio C Hamano1-1/+1
Various typofixes, all looked correct. * ow/manpages-typofix: Documentation: fix typos in man pages
2014-02-05Documentation: fix typos in man pagesLibravatar Øystein Walle1-1/+1
Signed-off-by: Øystein Walle <oystwa@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-12-17Merge branch 'jj/doc-markup-gitcli' into maintLibravatar Junio C Hamano1-5/+5
* jj/doc-markup-gitcli: Documentation/gitcli.txt: fix double quotes
2013-12-05Merge branch 'nv/parseopt-opt-arg'Libravatar Junio C Hamano1-3/+3
Enhance "rev-parse --parseopt" mode to help parsing options with an optional parameter. * nv/parseopt-opt-arg: rev-parse --parseopt: add the --stuck-long mode Use the word 'stuck' instead of 'sticked'
2013-12-03Merge branch 'jj/doc-markup-gitcli'Libravatar Junio C Hamano1-5/+5
* jj/doc-markup-gitcli: Documentation/gitcli.txt: fix double quotes
2013-11-20Documentation/gitcli.txt: fix double quotesLibravatar Jason St. John1-5/+5
Replace double quotes around literal examples with backticks Signed-off-by: Jason St. John <jstjohn@purdue.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-10-31Use the word 'stuck' instead of 'sticked'Libravatar Nicolas Vigier1-3/+3
The past participle of 'stick' is 'stuck'. Signed-off-by: Nicolas Vigier <boklm@mars-attacks.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-10-23Merge branch 'po/dot-url'Libravatar Junio C Hamano1-0/+4
Explain how '.' can be used to refer to the "current repository" in the documentation. * po/dot-url: doc/cli: make "dot repository" an independent bullet point config doc: update dot-repository notes doc: command line interface (cli) dot-repository dwimmery
2013-10-15doc/cli: make "dot repository" an independent bullet pointLibravatar Philip Oakley1-4/+4
The way to spell the current repository with a '.' dot is independent from how the pathspec allows globs expanded by Git. Make them two separate bullet items in the enumeration. Signed-off-by: Philip Oakley <philipoakley@iee.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-09-13doc: command line interface (cli) dot-repository dwimmeryLibravatar Philip Oakley1-0/+4
The Git cli will accept dot '.' (period) as the relative path to the current repository. Explain this action. Signed-off-by: Philip Oakley <philipoakley@iee.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-09-04use 'commit-ish' instead of 'committish'Libravatar Richard Hansen1-1/+1
Replace 'committish' in documentation and comments with 'commit-ish' to match gitglossary(7) and to be consistent with 'tree-ish'. The only remaining instances of 'committish' are: * variable, function, and macro names * "(also committish)" in the definition of commit-ish in gitglossary[7] Signed-off-by: Richard Hansen <rhansen@bbn.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-03-19Merge branch 'gp/avoid-explicit-mention-of-dot-git-refs'Libravatar Junio C Hamano1-4/+5
* gp/avoid-explicit-mention-of-dot-git-refs: Fix ".git/refs" stragglers
2013-02-24Fix ".git/refs" stragglersLibravatar Greg Price1-4/+5
A couple of references still survive to .git/refs as a tree of all refs. Fix one in docs, one in a -h message, one in a -h message quoted in docs. Signed-off-by: Greg Price <price@mit.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-01Documentation: the name of the system is 'Git', not 'git'Libravatar Thomas Ackermann1-7/+7
Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-10-04gitcli: parse-options lets you omit tail of long optionsLibravatar Junio C Hamano1-1/+11
Describe the behaviour, but do warn people against taking it too literally and expect an abbreviation valid today will stay valid forever. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-09-14Merge branch 'jc/maint-checkout-fileglob-doc' into maint-1.7.11Libravatar Junio C Hamano1-1/+18
* jc/maint-checkout-fileglob-doc: gitcli: contrast wildcard given to shell and to git gitcli: formatting fix Document file-glob for "git checkout -- '*.c'"
2012-09-10gitcli: contrast wildcard given to shell and to gitLibravatar Junio C Hamano1-0/+17
People who are not used to working with shell may intellectually understand how the command line argument is massaged by the shell but still have a hard time visualizing the difference between letting the shell expand fileglobs and having Git see the fileglob to use as a pathspec. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-09-10gitcli: formatting fixLibravatar Junio C Hamano1-1/+1
The paragraph to encourage use of "--" in scripts belongs to the bullet point that describes the behaviour for a command line without the explicit "--" disambiguation; it is not a supporting explanation for the entire bulletted list, and it is wrong to make it a separate paragraph outside the list. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-08-16gitcli: describe abbreviation of long optionsLibravatar Junio C Hamano1-0/+8
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-04-26docs: stop using asciidoc no-inline-literalLibravatar Jeff King1-6/+6
In asciidoc 7, backticks like `foo` produced a typographic effect, but did not otherwise affect the syntax. In asciidoc 8, backticks introduce an "inline literal" inside which markup is not interpreted. To keep compatibility with existing documents, asciidoc 8 has a "no-inline-literal" attribute to keep the old behavior. We enabled this so that the documentation could be built on either version. It has been several years now, and asciidoc 7 is no longer in wide use. We can now decide whether or not we want inline literals on their own merits, which are: 1. The source is much easier to read when the literal contains punctuation. You can use `master~1` instead of `master{tilde}1`. 2. They are less error-prone. Because of point (1), we tend to make mistakes and forget the extra layer of quoting. This patch removes the no-inline-literal attribute from the Makefile and converts every use of backticks in the documentation to an inline literal (they must be cleaned up, or the example above would literally show "{tilde}" in the output). Problematic sites were found by grepping for '`.*[{\\]' and examined and fixed manually. The results were then verified by comparing the output of "html2text" on the set of generated html pages. Doing so revealed that in addition to making the source more readable, this patch fixes several formatting bugs: - HTML rendering used the ellipsis character instead of literal "..." in code examples (like "git log A...B") - some code examples used the right-arrow character instead of '->' because they failed to quote - api-config.txt did not quote tilde, and the resulting HTML contained a bogus snippet like: <tt><sub></tt> foo <tt></sub>bar</tt> which caused some parsers to choke and omit whole sections of the page. - git-commit.txt confused ``foo`` (backticks inside a literal) with ``foo'' (matched double-quotes) - mentions of `A U Thor <author@example.com>` used to erroneously auto-generate a mailto footnote for author@example.com - the description of --word-diff=plain incorrectly showed the output as "[-removed-] and {added}", not "{+added+}". - using "prime" notation like: commit `C` and its replacement `C'` confused asciidoc into thinking that everything between the first backtick and the final apostrophe were meant to be inside matched quotes - asciidoc got confused by the escaping of some of our asterisks. In particular, `credential.\*` and `credential.<url>.\*` properly escaped the asterisk in the first case, but literally passed through the backslash in the second case. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-03-11doc: drop author/documentation sections from most pagesLibravatar Jeff King1-4/+0
The point of these sections is generally to: 1. Give credit where it is due. 2. Give the reader an idea of where to ask questions or file bug reports. But they don't do a good job of either case. For (1), they are out of date and incomplete. A much more accurate answer can be gotten through shortlog or blame. For (2), the correct contact point is generally git@vger, and even if you wanted to cc the contact point, the out-of-date and incomplete fields mean you're likely sending to somebody useless. So let's drop the fields entirely from all manpages except git(1) itself. We already point people to the mailing list for bug reports there, and we can update the Authors section to give credit to the major contributors and point to shortlog and blame for more information. Each page has a "This is part of git" footer, so people can follow that to the main git manpage.
2009-09-22Update "describe" documentation to match realityLibravatar Thiago Farina1-1/+1
A sample "git describe -h" did not match what the program actually says. Signed-off-by: Thiago Farina <tfransosi@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-17Documentation: remove extra quoting/emphasis around literal textsLibravatar Chris Johnsen1-12/+12
If literal text (asciidoc `...`) can be rendered in a differently from normal text for each output format (man, HTML), then we do not need extra quotes or other wrapping around inline literal text segments. config.txt Change '`...`' to `...`. In asciidoc, the single quotes provide emphasis, literal text should be distintive enough. Change "`...`" to `...`. These double quotes do not work if present in the described config value, so drop them. git-checkout.txt Change "`...`" to `...` or `"..."`. All instances are command line argument examples. One "`-`" becomes `-`. Two others are involve curly braces, so move the double quotes inside the literal region to indicate that they might need to be quoted on the command line of certain shells (tcsh). git-merge.txt Change "`...`" to `...`. All instances are used to describe merge conflict markers. The quotes should are not important. git-rev-parse.txt Change "`...`" to `...`. All instances are around command line arguments where no in-shell quoting should be necessary. gitcli.txt Change `"..."` to `...`. All instances are around command line examples or single command arguments. They do not semanticly belong inside the literal text, and they are not needed outside it. glossary-content.txt user-manual.txt Change "`...`" to `...`. All instances were around command lines. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-01gitcli: Document meaning of --cached and --indexLibravatar Nanako Shiraishi1-1/+37
We saw this explanation repeated on the mailing list a few times. Even though the description of individual options to particular commands are explained in their manual pages, the reason behind choosing which is which has not been clearly explained in any of the documentation. Signed-off-by: Nanako Shiraishi <nanako3@lavabit.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-06-27Document the double-dash "rev -- path" disambiguatorLibravatar Junio C Hamano1-4/+33
This is a very well established command line convention that old residents of the git mailing list knew by heart and nobody even thought about documenting it explicitly, which was not very nice. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-06-06documentation: move git(7) to git(1)Libravatar Christian Couder1-1/+1
As the "git" man page describes the "git" command at the end-user level, it seems better to move it to man section 1. Signed-off-by: Christian Couder <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-05-04Documentation: rename "hooks.txt" to "githooks.txt" and make it a man pageLibravatar Christian Couder1-1/+1
Also now "gitcli(5)" becomes "gitcli(7)". Signed-off-by: Christian Couder <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-01-07Documentation: typofixLibravatar Ralf Wildenhues1-1/+1
Signed-off-by: Ralf Wildenhues <Ralf.Wildenhues@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-01-06Documentation: rename gitlink macro to linkgitLibravatar Dan McGee1-1/+1
Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-22parse-options: Add a gitcli(5) man page.Libravatar Pierre Habouzit1-0/+113
This page should hold every information about the git ways to parse command lines, and best practices to be used for scripting. Signed-off-by: Pierre Habouzit <madcoder@debian.org>