--only is implied when paths are present, and required
them unless --amend. But with --allow-empty it should
be allowed as well - it is the only way to create an
empty commit in the presence of staged changes.
Signed-off-by: Andreas Krey <a.krey@gmx.de>
Reviewed-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
How pathspec is used, with and without --interactive/--patch, is
different. But this is not clear from the document. These changes hint
the user to keep reading (to option #5) instead of stopping at #2 and
assuming --patch/--interactive behaves the same way.
And since all the options listed here always mention how the index is
involved (or not) in the final commit, add that bit for #5 as well. This
"on top of the index" is implied when you head over git-add(1), but if
you just go straight to the "Interactive mode" and not read what git-add
is for, you may miss it.
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Similarly to the previous commit, use backquotes instead of
forward-quotes, for long options.
This was obtained with:
perl -pi -e "s/'(--[a-z][a-z=<>-]*)'/\`\$1\`/g" *.txt
and manual tweak to remove false positive in ascii-art (o'--o'--o' to
describe rewritten history).
Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
It was common in our documentation to surround short option names with
forward quotes, which renders as italic in HTML. Instead, use backquotes
which renders as monospace. This is one more step toward conformance to
Documentation/CodingGuidelines.
This was obtained with:
perl -pi -e "s/'(-[a-z])'/\`\$1\`/g" *.txt
Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This change configuration variables that where in italic style
to monospace font according to the guideline. It was obtained with
grep '[[:alpha:]]*\.[[:alpha:]]*::$' config.txt | \
sed -e 's/::$//' -e 's/\./\\\\./' | \
xargs -iP perl -pi -e "s/\'P\'/\`P\`/g" ./*.txt
Signed-off-by: Tom Russello <tom.russello@grenoble-inp.org>
Signed-off-by: Erwan Mathoniere <erwan.mathoniere@grenoble-inp.org>
Signed-off-by: Samuel Groot <samuel.groot@grenoble-inp.org>
Signed-off-by: Matthieu Moy <matthieu.moy@grenoble-inp.fr>
Reviewed-by: Matthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Wrap with backticks (monospaced font) unwrapped or single-quotes wrapped
(italic type) environment variables which are followed by the word
"environment". It was obtained with:
perl -pi -e "s/\'?(\\\$?[0-9A-Z\_]+)\'?(?= environment ?)/\`\1\`/g" *.txt
One of the main purposes is to stick to the CodingGuidelines as possible so
that people writting new documentation by mimicking the existing are more likely
to have it right (even if they didn't read the CodingGuidelines).
Signed-off-by: Tom Russello <tom.russello@grenoble-inp.org>
Signed-off-by: Erwan Mathoniere <erwan.mathoniere@grenoble-inp.org>
Signed-off-by: Samuel Groot <samuel.groot@grenoble-inp.org>
Signed-off-by: Matthieu Moy <matthieu.moy@grenoble-inp.fr>
Reviewed-by: Matthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Add commit.verbose configuration variable as a convenience for those
who always prefer --verbose.
Add tests to check the behavior introduced by this commit and also to
verify that behavior of status doesn't break because of this commit.
Helped-by: Junio C Hamano <gitster@pobox.com>
Helped-by: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Pranit Bauva <pranit.bauva@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Modify various document (man page) files to explain
in more detail what --signoff means.
This was inspired by https://lwn.net/Articles/669976/ where
paulj noted, "adding [the] '-s' argument to [a] git commit
doesn't really mean you have even heard of the DCO...".
Extending git's documentation will make it easier to argue
that developers understood --signoff when they use it.
Signed-off-by: David A. Wheeler <dwheeler@dwheeler.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Improve the documentation of commands taking optional arguments in two
ways:
* Documents the behavior of '-O' (for grep) and '-S' (for commands
creating commits) when used without the optional argument.
* Document the syntax of these options.
For the second point, the behavior is documented in gitcli(7), but it is
easy for users to miss, and hard for the same user to understand why e.g.
"git status -u no" does not work.
Document this explicitly in the documentation of each short option having
an optional argument: they are the most error prone since there is no '='
sign between the option and its argument.
Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
Reviewed-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The `-v` shows a unified diff in the editor to edit the commit
message to help the user to describe the change. The diff is
stripped and will not become a part of the commit message.
Add a note about this with the `-v` description and slightly modify
the description for the default `--cleanup` mode.
Signed-off-by: Fredrik Gustafsson <iveqy@iveqy.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This should improve readability. Compare "thislongname" and
"thisLongName". The following keys are left in unchanged. We can
decide what to do with them later.
- am.keepcr
- core.autocrlf .safecrlf .trustctime
- diff.dirstat .noprefix
- gitcvs.usecrlfattr
- gui.blamehistoryctx .trustmtime
- pull.twohead
- receive.autogc
- sendemail.signedoffbycc .smtpsslcertpath .suppresscc
Helped-by: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
git commit and git status in long format show the diff between HEAD
and the index when given -v. This allows previewing a commit to be made.
They also list tracked files with unstaged changes, but without a diff.
Introduce '-v -v' which shows the diff between the index and the
worktree in addition to the HEAD index diff. This allows a review of unstaged
changes which might be missing from the commit.
In the case of '-v -v', additonal header lines
Changes to be committed:
and
Changes not staged for commit:
are inserted before the diffs, which are equal to those in the status
part; the latter preceded by 50*"-" to make it stick out more.
Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
With the original phrasing, it is possible to misunderstand as if
the contents in the index for only the specified paths are made into
the new commit.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
"When you need to use space, use dash" is a strange way to say that
you must not use a space. Because it is more common for the command
line descriptions to use dashed-multi-words, you do not even want to
use spaces in these places. Rephrase the documentation to avoid
this strangeness.
Fix a few existing multi-word argument help strings, i.e.
- GPG key-ids given to -S/--gpg-sign are "key-id";
- Refs used for storing notes are "notes-ref"; and
- Expiry timestamps given to --expire are "expiry-date".
and update the corresponding documentation pages.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Since 1a72cfd (commit -v: strip diffs and submodule shortlogs from the
commit message - 2013-12-05) we have a less fragile way to cut out
"git status" at the end of a commit message but it's only enabled for
stripping submodule shortlogs.
Add new cleanup option that reuses the same mechanism for the entire
"git status" without accidentally removing lines starting with '#'.
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Document how to override commit.gpgsign configuration that is set to
true per "git commit" invocation (parse-options machinery lets us
say "--no-gpg-sign" to do so).
"git commit-tree" does not use parse-options, so manually add the
corresponding option for now.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
White-spaces, missing braces, standardize --[no-]foo.
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
-C takes a commit object, not a file.
Signed-off-by: Anders Granskogen Bjørnstad <andersgb@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The explanation for 'git commit --amend' talks about preparing a tree
object, which shouldn't be how user-facing documentation talks about
commit.
Reword it to say it works as usual, but replaces the current commit.
Signed-off-by: Carlos Martín Nieto <cmn@elego.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The text is copied from Documentation/git-tag.txt.
Signed-off-by: Christian Helmuth <christian.helmuth@genode-labs.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The default of the "cleanup" option in "git commit"
is not configurable. Users who don't want to use the
default have to pass this option on every commit since
there's no way to configure it. This commit introduces
a new config option "commit.cleanup" which can be used
to change the default of the "cleanup" option in
"git commit".
Signed-off-by: Ralf Thielow <ralf.thielow@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
In e858af6 (commit: document a couple of options) the description of the
--no-post-rewrite option was put inside the paragraph for the --amend
option. Move it down after the paragraph.
Signed-off-by: Andreas Schwab <schwab@linux-m68k.org>
Signed-off-by: Jeff King <peff@peff.net>
git commit -S, --gpg-sign was mentioned in the program's help message,
but not in the manpage.
This adds an equivalent entry for the option in the manpage.
Signed-off-by: Tom Jones <tom@oxix.org>
Signed-off-by: Jeff King <peff@peff.net>
You can currently set the output format to --short or
--porcelain. There is no --long, because we default to it
already. However, you may want to override an alias that
uses "--short" to get back to the default.
This requires a little bit of refactoring, because currently
we use STATUS_FORMAT_LONG internally to mean the same as
"the user did not specify anything". By expanding the enum
to include STATUS_FORMAT_NONE, we can distinguish between
the implicit and explicit cases. This effects these
conditions:
1. The user has asked for NUL termination. With NONE, we
currently default to turning on the porcelain mode.
With an explicit --long, we would in theory use NUL
termination with the long mode, but it does not support
it. So we can just complain and die.
2. When an output format is given to "git commit", we
default to "--dry-run". This behavior would now kick in
when "--long" is given, too.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The discussion of email subject throughout the documentation is
misleading; it indicates that the first line will always become
the subject. In fact, the subject is generally all lines up until
the first full blank line.
This patch refines that, and makes more use of the concept of a
commit title, with the title being all text up to the first blank line.
Signed-off-by: Jeremy White <jwhite@codeweavers.com>
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>
Document git commit '--branch' and '--no-post-rewrite'. Mention that
'-z' can also be spelt as '--null'.
Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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>
The description of "commit -t <file>" said the file is used "as the
initial version" of the commit message, but in the context of an SCM,
"version" is a loaded word that can needlesslyl confuse readers.
Explain the purpose of the mechanism without using "version".
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Make it clear that, when using commit --template, the message *must* be
changed or the commit will be aborted.
Helped-by: Junio C Hamano <gitster@pobox.com>
Helped-by: Ivan Heffner <iheffner@gmail.com>
Signed-off-by: Adam Monsen <haircut@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
AsciiDoc versions since 5.0.6 treat a double-dash surrounded by spaces
(outside of verbatim environments) as a request to insert an em dash.
Such versions also treat the three-character sequence "\--", when not
followed by another dash, as a request to insert two literal minus
signs. Thus from time to time there have been patches to add
backslashes to AsciiDoc markup to escape double-dashes that are meant
to be represent '--' characters used literally on the command line;
see v1.4.0-rc1~174, Fix up docs where "--" isn't displayed correctly,
2006-05-05, for example.
AsciiDoc 6.0.3 (2005-04-20) made life harder by also treating
double-dashes without surrounding whitespace as markup for an em dash,
though only when formatting for backends other than the manpages
(e.g., HTML). Many pages needed to be changed to use a backslash
before the "--" in names of command-line flags like "--add" (see
v0.99.6~37, Update tutorial, 2005-08-30).
AsciiDoc 8.3.0 (2008-11-29) refined the em-dash rule to avoid that
requirement. Double-dashes without surrounding spaces are not
rendered as em dashes any more unless bordered on both sides by
alphanumeric characters. The unescaped markup for option names (e.g.,
"--add") works fine, and many instances of this style have leaked into
Documentation/; git's HTML documentation contains many spurious em
dashes when formatted by an older toolchain. (This patch will not
change that.)
The upshot: "--" as an isolated word and in phrases like "git
web--browse" must be escaped if it is not to be rendered as an em dash
by current asciidoc. Use "\--" to avoid such misformatting in
sentences in which "--" represents a literal double-minus command line
argument that separates options and revs from pathspecs, and use
"{litdd}" in cases where the double-dash is embedded in the command
name. The latter is just for consistency with v1.7.3-rc0~13^2 (Work
around em-dash handling in newer AsciiDoc, 2010-08-23).
List of lines to fix found by grepping manpages for "(em".
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Improved-by: Junio C Hamano <gitster@pobox.com>
Improved-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The --interactive flag is already shared by git add and git commit,
share the -p and --patch flags too.
Signed-off-by: Conrad Irwin <conrad.irwin@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Change the behaviour of git commit --interactive so that when you abort
the commit (by leaving the commit message empty) the index remains
unchanged.
Hitherto an aborted commit --interactive has added the selected hunks to
the index regardless of whether the commit succeeded or not.
Signed-off-by: Conrad Irwin <conrad.irwin@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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.
Previously the user was advised to use commit -c CHERRY_PICK_HEAD after
a conflicting cherry-pick. While this would preserve the original
commit's authorship, it would sadly discard cherry-pick's carefully
crafted MERGE_MSG (which contains the list of conflicts as well as the
original commit-id in the case of cherry-pick -x).
On the other hand, if a bare 'commit' were performed, it would preserve
the MERGE_MSG while resetting the authorship.
In other words, there was no way to simultaneously take the authorship
from CHERRY_PICK_HEAD and the commit message from MERGE_MSG.
This change fixes that situation. A bare 'commit' will now take the
authorship from CHERRY_PICK_HEAD and the commit message from MERGE_MSG.
If the user wishes to reset authorship, that must now be done explicitly
via --reset-author.
A side-benefit of passing commit authorship along this way is that we
can eliminate redundant authorship parsing code from revert.c.
(Also removed an unused include from revert.c)
Signed-off-by: Jay Soffian <jaysoffian@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
All options, including -i and -o, must come before "--" which is the
end of options marker.
Reported-by: Joey Hess <joey@kitenet.net>
Signed-off-by: Jari Aalto <jari.aalto@cante.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This option makes it convenient to construct commit messages for use
with 'rebase --autosquash'. The resulting commit message will be
"squash! ..." where "..." is the subject line of the specified commit
message. This option can be used with other commit message options
such as -m, -c, -C and -F.
If an editor is invoked (as with -c or -eF or no message options) the
commit message is seeded with the correctly formatted subject line.
Example usage:
$ git commit --squash HEAD~2
$ git commit --squash HEAD~2 -m "clever comment"
$ git commit --squash HEAD~2 -F msgfile
$ git commit --squash HEAD~2 -C deadbeef
Signed-off-by: Pat Notz <patnotz@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This option makes it convenient to construct commit messages for use
with 'rebase --autosquash'. The resulting commit message will be
"fixup! ..." where "..." is the subject line of the specified commit
message.
Example usage:
$ git commit --fixup HEAD~2
Signed-off-by: Pat Notz <patnotz@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
commit --author was added by 146ea06 (git commit --author=$name: look $name up
in existing commits), but its documentation was sorely lacking compared to its
excellent commit message. This commit tries to improve the documentation.
Signed-off-by: Jay Soffian <jaysoffian@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Change git-commit(1) to accept the --allow-empty-message option
to allow a commit with an empty message. This is analogous to the
existing --allow-empty option which allows a commit that records
no changes. As these are mainly for interoperating with foreign SCM
systems, and are not meant for normal use, ensure that "git commit -h"
does not talk about them.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Ever since the "See linkgit:git-config[1]..." paragraph was added to the
description for --untracked-files (d6293d1), the paragraphs for the
following options were indented at the same level as the "See
linkgit:git-config[1]" paragraph. This problem showed up in the
manpages, but not in the HTML documentation.
While this does fix the alignment of the options following
--untracked-files in the manpage, the "See linkgit..." portion of the
description does not retain its previous indentation level in the
manpages, or HTML documentation.
Signed-off-by: Jacob Helwig <jacob.helwig@gmail.com>
Acked-by: Thomas Rast <trast@student.ethz.ch>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
A new configuration variable commit.status, and new command line
options --status, and --no-status control whether or not the git
status information is included in the commit message template
when using an editor to prepare the commit message. It does not
affect the effects of a user's commit.template settings.
Signed-off-by: James P. Howard, II <jh@jameshoward.us>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The documentation was quite inconsistent when spelling 'git cmd' if it
only refers to the program, not to some specific invocation syntax:
both 'git-cmd' and 'git cmd' spellings exist.
The current trend goes towards dashless forms, and there is precedent
in 647ac70 (git-svn.txt: stop using dash-form of commands.,
2009-07-07) to actively eliminate the dashed variants.
Replace 'git-cmd' with 'git cmd' throughout, except where git-shell,
git-cvsserver, git-upload-pack, git-receive-pack, and
git-upload-archive are concerned, because those really live in the
$PATH.
Andreas Krey