We did not document that many commands take unique prefix
abbreviations of long options (e.g. "--option" may be the only flag
that the command accepts that begin with "--opt", in which case you
can give "--opt") anywhere easy to find for new people.
* jc/maint-abbrev-option-cli:
gitcli: describe abbreviation of long options
It was unclear what "--topo-order" was really about in the
documentation. It is not just about "children before parent", but
also about "don't mix lineages".
* jc/maint-rev-list-topo-doc:
rev-list docs: clarify --topo-order description
In earlier days, "imitate the style in the neibouring code" was
sufficient to keep the coherent style, but over time some parts of
the codebase have drifted enough to make it ineffective.
* hv/coding-guidelines:
Documentation/CodingGuidelines: spell out more shell guidelines
Our documentation used to assume having files in .git/refs/*
directories was the only to have branches and tags, but that is not
true for quite some time.
* jc/tag-doc:
Documentation: do not mention .git/refs/* directories
Currently, it will only do a checkout if the sha1 registered in the containing
repository doesn't match the HEAD of the submodule, regardless of whether the
submodule is dirty. As discussed on the mailing list, the '--force' flag is a
strong indicator that the state of the submodule is suspect, and should be reset
to HEAD.
Signed-off-by: Stefan Zager <szager@google.com>
Acked-by: Jens Lehmann <Jens.Lehmann@web.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
One fictitious command "proxy-command" is enclosed inside a double
quote pair, while another fictitious command "default-proxy" is not
in the example, but the quoting does not change anything in the pair
of examples. Remove the quotes to avoid unnecessary confusion.
Noticed by Michael Haggerty.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The "--add" option is required to add a new value to a multivalued
configuration entry.
Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Letting the "--rebase" option squat on the short-and-sweet single
letter option "-r" was an unintended accident and was not even
documented, but the short option seems to be already used in the
wild. Let's document it so that other options that begin with "r"
would not be tempted to steal it.
Signed-off-by: Miklos Vajna <vmiklos@suse.cz>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
It was unclear what "--topo-order" was really about in the
documentation. It is not just about "children before parent", but
also about "don't mix lineages".
Reword the description for both "--date-order" and "--topo-order",
and add an illustration to it.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
In earlier days, "imitate the style in the neibouring code" was
sufficient to keep the coherent style, but over time some parts of
the codebase have drifted enough to make it ineffective.
Spell some of the guidelines out.
Signed-off-by: Heiko Voigt <hvoigt@hvoigt.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
When asciidoc converts a listing block like:
----------------------
$ git log --merge
----------------------
it marks it to be displayed in a monospace font. This works
fine when generating HTML output. However, when generating
docbook output, we override the expansion of a listingblock
to work around bugs in some versions of the docbook
toolchain. Our override did not mark the listingblock with
the "monospaced" class.
The main output that uses docbook as an intermediate format
is the manpages. We didn't notice any issue there because
the monospaced class seems to be ignored when generating
roff from the docbook manpages.
However, when generating texinfo to make info pages, docbook
does respect this class. The resulting texinfo output
properly uses "@example" blocks to display the listing in
this case. Besides possibly looking prettier in some texinfo
backends, one important effect is that the monospace font
suppresses texinfo's expansion of "--" and "---" into
en-dashes and em-dashes. With the current code, the example
above ends up looking like "git log -merge", which is
confusing and wrong.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
- (glossary) the quotes around the Wikipedia URL prevented its
linkification in frontends that support it; remove them
- (manual) newer version (SHA-1) == following, older == preceding, not
the other way around
- trivial typo and wording fixes
Signed-off-by: Štěpán Němec <stepnem@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
It is an implementation detail that a new tag is created by adding a
file in the .git/refs/tags directory. The only thing the user needs
to know is that a "git tag" creates a ref in the refs/tags namespace,
and without "-f", it does not overwrite an existing tag.
Inspired by a report from 乙酸鋰 <ch3cooli@gmail.com>; I think I
caught all the existing mention in Documentation/ directory in the
tip of 1.7.9.X maintenance track, but we may have added new ones
since then.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
"$GIT_DIR/COMMIT_EDITMSG" file that is used to hold the commit log
message user edits was not documented.
* jk/maint-commit-document-editmsg:
commit: document the temporary commit message file
"git commit-tree" learned a more natural "-p <parent> <tree>" order
of arguments long time ago, but recently forgot it by mistake.
* kk/maint-commit-tree:
Revert "git-commit-tree(1): update synopsis"
commit-tree: resurrect command line parsing updates
When "git am" failed, old timers knew to check .git/rebase-apply/patch
to see what went wrong, but we never told the users about it.
* pg/maint-1.7.9-am-where-is-patch:
am: indicate where a failed patch is to be found
We instead failed with an undocumented exit status 255.
Also define a "catch-all" status and document it.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
It was a bit hard to learn how <rev>^@, <rev>^! and various other
forms of range specifiers are used, because they were discussed
mostly in the prose part of the documentation, unlike various forms
of extended SHA-1 expressions that are listed in an enumerated list.
Also add a few more examples showing use of <rev>, <rev>..<rev> and
<rev>^! forms, stolen from a patch by Max Horn.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
We do not document COMMIT_EDITMSG at all, but users may want
to know about it for two reasons:
1. They may want to tell their editor to configure itself
for formatting a commit message.
2. If a commit is aborted by an error, the user may want
to recover the commit message they typed.
Let's put a note in git-commit(1).
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This way we do not have to risk the list of tools going out of sync
between the implementation and the documentation.
In the same spirit as bf73fc2 (difftool: print list of valid tools
with '--tool-help', 2012-03-29), trim the list of merge backends in
the documentation. We do not want to have a complete list of valid
tools; we only want a list to help people guess what kind of things
the tools do to be specified there, and refer them to --tool-help
for a complete list.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
If "git am" fails to apply something, the end user may need to know
where to find the patch that failed to apply, so that the user can
do other things (e.g. trying "GNU patch" on it, running "diffstat"
to see what it tried to change, etc.) The input to "am" may have
contained more than one patch, or the message may have been MIME
encoded, and knowing what the user fed to "am" does not help very
much for this purpose.
Also introduce advice.amworkdir configuration to allow people who
learned where to look to squelch this message.
Signed-off-by: Paul Gortmaker <paul.gortmaker@windriver.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The documentation for "git cherry-pick A B..C" was misleading.
* cn/cherry-pick-range-docs:
git-cherry-pick.txt: clarify the use of revision range notation
Documentation: --no-walk is no-op if range is specified
Formerly, the documentation for <refname> would occasionally say
<name> instead of <refname>. Now it uniformly uses <refname>.
Signed-off-by: Max Horn <max@quendi.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Commit fe77b41 introduced a new attribute to let the linkgit macro
create cross-directory HTML references from the technical/ and howto/
subdirectories back to the main documentation. We define that attribute
to "../" on the command-line when building inside those subdirectories,
and otherwise leave it unset under the assumption that it would default
to being blank. Instead, asciidoc omits the link entirely, leading to
broken documentation. Fix this by defining git-relative-html-prefix to
blank in asciidoc.conf (and an instance on the command-line, when
present, will override it).
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Even with many new kinds of options, the command still takes the
single <tree> as the first argument.
Probably we would want to update the command to allow it to take
<tree>-ish at the end for consistency.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
