Commit Graph

76 Commits

Author SHA1 Message Date
Philippe Blain
e29678bb7c git-cherry-pick.txt: do not use 'ORIG_HEAD' in example
Commit 67ac1e1d57 (cherry-pick/revert: add support for
-X/--strategy-option, 2010-12-10) added an example to the documentation
of 'git cherry-pick'. This example mentions how to abort a failed
cherry-pick and retry with an additional merge strategy option.

The command used in the example to abort the cherry-pick is 'git reset
--merge ORIG_HEAD', but cherry-pick does not write 'ORIG_HEAD' before
starting its operation. So this command would checkout a commit
unrelated to what was at HEAD when the user invoked cherry-pick.

Use 'git cherry-pick --abort' instead.

Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
Acked-by: Phillip Wood <phillip.wood@dunelm.org.uk>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2023-01-13 09:55:45 -08:00
Junio C Hamano
0dbc715ae0 doc: consolidate --rerere-autoupdate description
The `--rerere-autoupdate` option is shared across 5 commands, and
are described the same way because it works exactly the same way in
these commands.

Create a separate file and include it from the help pages for these
commands, so that we can improve the description at one place to
improve all of them at once, and keep them in sync.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-08-03 13:47:11 -07:00
Jean-Noël Avila
49cbad0edd doc: express grammar placeholders between angle brackets
This discerns user inputs from verbatim options in the synopsis.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-11-09 09:39:11 -08:00
Bradley M. Kuhn
3abd4a67d9 Documentation: stylistically normalize references to Signed-off-by:
Ted reported an old typo in the git-commit.txt and merge-options.txt.
Namely, the phrase "Signed-off-by line" was used without either a
definite nor indefinite article.

Upon examination, it seems that the documentation (including items in
Documentation/, but also option help strings) have been quite
inconsistent on usage when referring to `Signed-off-by`.

First, very few places used a definite or indefinite article with the
phrase "Signed-off-by line", but that was the initial typo that led
to this investigation.  So, normalize using either an indefinite or
definite article consistently.

The original phrasing, in Commit 3f971fc425 (Documentation updates,
2005-08-14), is "Add Signed-off-by line".  Commit 6f855371a5 (Add
--signoff, --check, and long option-names. 2005-12-09) switched to
using "Add `Signed-off-by:` line", but didn't normalize the former
commit to match.  Later commits seem to have cut and pasted from one
or the other, which is likely how the usage became so inconsistent.

Junio stated on the git mailing list in
<xmqqy2k1dfoh.fsf@gitster.c.googlers.com> a preference to leave off
the colon.  Thus, prefer `Signed-off-by` (with backticks) for the
documentation files and Signed-off-by (without backticks) for option
help strings.

Additionally, Junio argued that "trailer" is now the standard term to
refer to `Signed-off-by`, saying that "becomes plenty clear that we
are not talking about any random line in the log message".  As such,
prefer "trailer" over "line" anywhere the former word fits.

However, leave alone those few places in documentation that use
Signed-off-by to refer to the process (rather than the specific
trailer), or in places where mail headers are generally discussed in
comparison with Signed-off-by.

Reported-by: "Theodore Y. Ts'o" <tytso@mit.edu>
Signed-off-by: Bradley M. Kuhn <bkuhn@sfconservancy.org>
Acked-by: Taylor Blau <me@ttaylorr.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-10-20 11:57:40 -07:00
Đoàn Trần Công Danh
cf0ad4d199 cherry-pick/revert: honour --no-gpg-sign in all case
{cherry-pick,revert} --edit hasn't honoured --no-gpg-sign yet.

Pass this option down to git-commit to honour it.

Signed-off-by: Đoàn Trần Công Danh <congdanhqx@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-04-03 11:37:22 -07:00
Rohit Ashiwal
de81ca3f36 cherry-pick/revert: add --skip option
git am or rebase have a --skip flag to skip the current commit if the
user wishes to do so. During a cherry-pick or revert a user could
likewise skip a commit, but needs to use 'git reset' (or in the case
of conflicts 'git reset --merge'), followed by 'git (cherry-pick |
revert) --continue' to skip the commit. This is more annoying and
sometimes confusing on the users' part. Add a `--skip` option to make
skipping commits easier for the user and to make the commands more
consistent.

In the next commit, we will change the advice messages hence finishing
the process of teaching revert and cherry-pick "how to skip commits".

Signed-off-by: Rohit Ashiwal <rohit.ashiwal265@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-07-02 12:08:08 -07:00
Denton Liu
1a2b985fb3 cherry-pick/revert: add scissors line on merge conflict
Fix a bug where the scissors line is placed after the Conflicts:
section, in the case where a merge conflict occurs and
commit.cleanup = scissors.

Helped-by: Phillip Wood <phillip.wood@dunelm.org.uk>
Signed-off-by: Denton Liu <liu.denton@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-04-19 12:05:36 +09:00
Phillip Wood
aba4954cb0 am/cherry-pick/rebase/revert: document --rerere-autoupdate
This option was missing from the man pages of these commands.

Signed-off-by: Phillip Wood <phillip.wood@dunelm.org.uk>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-03-18 10:24:56 +09:00
Jean-Noël Avila
ba170517be doc: tidy asciidoc style
This mainly refers to enforcing indentation on additional lines of
items of lists.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-01-23 11:37:29 -08:00
Junio C Hamano
ce18123cec Merge branch 'mm/doc-tt'
More mark-up updates to typeset strings that are expected to
literally typed by the end user in fixed-width font.

* mm/doc-tt:
  doc: typeset HEAD and variants as literal
  CodingGuidelines: formatting HEAD in documentation
  doc: typeset long options with argument as literal
  doc: typeset '--' as literal
  doc: typeset long command-line options as literal
  doc: typeset short command-line options as literal
  Documentation/git-mv.txt: fix whitespace indentation
2016-07-13 11:24:14 -07:00
Matthieu Moy
bcf9626a71 doc: typeset long command-line options as literal
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>
2016-06-28 08:36:45 -07:00
Junio C Hamano
1df2d6e8df Merge branch 'pa/cherry-pick-doc-typo'
"git cherry-pick --help" had three instances of word "behavior",
one of which was spelled "behaviour", which is updated to match the
other two.

* pa/cherry-pick-doc-typo:
  git-cherry-pick.txt: correct a small typo
2016-06-03 14:38:02 -07:00
Pablo Santiago Blum de Aguiar
cd82b7a0f7 git-cherry-pick.txt: correct a small typo
Most of the document mentions `behavior` instead of the British
variation, `behaviour`. This change makes it consistent.

Signed-off-by: Pablo Santiago Blum de Aguiar <scorphus@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-05-29 17:32:12 -07:00
David A. Wheeler
b2c150d3aa Expand documentation describing --signoff
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>
2016-01-05 13:42:39 -08:00
Matthieu Moy
2b594bf90d Documentation: explain optional arguments better
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>
2015-09-21 10:48:23 -07:00
Matthieu Moy
340f2c5e63 Documentation: use 'keyid' consistently, not 'key-id'
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>
2015-09-21 10:48:17 -07:00
Jeff King
f907282faf cherry-pick: fix docs describing handling of empty commits
Commit b27cfb0 (git-cherry-pick: Add keep-redundant-commits
option, 2012-04-20), added the --keep-redundant-commits
option, and switched the default behavior (without that
option) to silently ignore empty commits. Later, the second
half of that commit was reverted in ac2b0e8 (cherry-pick:
regression fix for empty commits, 2012-05-29), but the
documentation added for --keep-redundant-commits was never
updated to match. Let's do so now.

Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-03-30 21:49:51 -07:00
Junio C Hamano
e703d7118c parse-options: multi-word argh should use dash to separate words
"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>
2014-03-24 10:43:34 -07:00
Nicolas Vigier
3253553e12 cherry-pick, revert: add the --gpg-sign option
Signed-off-by: Nicolas Vigier <boklm@mars-attacks.org>
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-01-27 15:15:52 -08:00
Junio C Hamano
831287d37c Merge branch 'cw/cherry-pick-allow-empty-message'
"git cherry-pick" by default stops when it sees a commit without any
log message.  The "--allow-empty-message" option can be used to
silently proceed.

* cw/cherry-pick-allow-empty-message:
  cherry-pick: add --allow-empty-message option
2012-09-03 15:53:37 -07:00
Chris Webb
4bee958479 cherry-pick: add --allow-empty-message option
Scripts such as "git rebase -i" cannot currently cherry-pick commits
which have an empty commit message, as git cherry-pick calls git
commit without the --allow-empty-message option.

Add an --allow-empty-message option to git cherry-pick which is passed
through to git commit, so this behaviour can be overridden.

Signed-off-by: Chris Webb <chris@arachsys.com>
Reviewed-by: Neil Horman <nhorman@tuxdriver.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-08-06 09:59:53 -07:00
Junio C Hamano
a913b56fcb Merge branch 'cn/cherry-pick-range-docs'
The command line argument of "git cherry-pick maint master..next" is
just an ordinary revision range, which is unintuitive and at least
deserves documentation.

* 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
2012-06-25 11:25:38 -07:00
Carlos Martín Nieto
b98878edef git-cherry-pick.txt: clarify the use of revision range notation
When given a set of commits, cherry-pick will apply the changes for
all of them. Specifying a simple range will also work as expected.

This can lead the user to think that

    git cherry-pick A B..C

may apply A and then B..C, but that is not what happens.

Instead the revs are given to a single invocation of rev-list, which
will consider A and C as positive revs and B as a negative one.  The
commit A will not be used if it is an ancestor of B.

Add a note about this and add an example with this particular
syntax, which has shown up on the list a few times.

Signed-off-by: Carlos Martín Nieto <cmn@elego.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-06-15 10:56:13 -07:00
Junio C Hamano
d274fc093c Merge branch 'jk/doc-asciidoc-inline-literal'
Our documentation was written for an ancient version of AsciiDoc,
making the source not very readable.

By Jeff King
* jk/doc-asciidoc-inline-literal:
  docs: stop using asciidoc no-inline-literal
2012-05-02 13:51:45 -07:00
Jeff King
6cf378f0cb docs: stop using asciidoc no-inline-literal
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>
2012-04-26 13:19:06 -07:00
Neil Horman
b27cfb0d8d git-cherry-pick: Add keep-redundant-commits option
The git-cherry-pick --allow-empty command by default only preserves empty
commits that were originally empty, i.e only those commits for which
<commit>^{tree} and <commit>^^{tree} are equal.  By default commits which are
non-empty, but were made empty by the inclusion of a prior commit on the current
history are filtered out.  This option allows us to override that behavior and
include redundant commits as empty commits in the change history.

Note that this patch changes the default behavior of git cherry-pick slightly.
Prior to this patch all commits in a cherry-pick sequence were applied and git
commit was run.  The implication here was that, if a commit was redundant, and
the commit did not trigger the fast forward logic, the git commit operation, and
therefore the git cherry-pick operation would fail, displaying the cherry pick
advice (i.e. run git commit --allow-empty).  With this patch however, such
redundant commits are automatically skipped without stopping, unless
--keep-redundant-commits is specified, in which case, they are automatically
applied as empty commits.

Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-04-24 14:52:12 -07:00
Neil Horman
df478b744c git-cherry-pick: add allow-empty option
git cherry-pick fails when picking a non-ff commit that is empty.  The advice
given with the failure is that a git-commit --allow-empty should be issued to
explicitly add the empty commit during the cherry pick.  This option allows a
user to specify before hand that they want to keep the empty commit.  This
eliminates the need to issue both a cherry pick and a commit operation.

Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-04-11 13:46:08 -07:00
Jonathan Nieder
539047c19e revert: introduce --abort to cancel a failed cherry-pick
After running some ill-advised command like "git cherry-pick
HEAD..linux-next", the bewildered novice may want to return to more
familiar territory.  Introduce a "git cherry-pick --abort" command
that rolls back the entire cherry-pick sequence and places the
repository back on solid ground.

Just like "git merge --abort", this internally uses "git reset
--merge", so local changes not involved in the conflict resolution are
preserved.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-11-22 18:16:59 -08:00
Jonathan Nieder
f80a87262a revert: rename --reset option to --quit
The option to "git cherry-pick" and "git revert" to discard the
sequencer state introduced by v1.7.8-rc0~141^2~6 (revert: Introduce
--reset to remove sequencer state, 2011-08-04) has a confusing name.
Change it now, while we still have the time.

The new name for "cherry-pick, please get out of my way, since I've
long forgotten about the sequence of commits I was cherry-picking when
you wrote that old .git/sequencer directory" is --quit.  Mnemonic:
this is analagous to quiting a program the user is no longer using ---
we just want to get out of the multiple-command cherry-pick procedure
and not to reset HEAD or rewind any other old state.

The "--reset" option is kept as a synonym to minimize the impact.  We
might consider dropping it for simplicity in a separate patch, though.

Adjust documentation and tests to use the newly preferred name (--quit)
instead of --reset.  While at it, let's clarify the short descriptions
of these operations in "-h" output.

Before:

	--reset		forget the current operation
	--continue	continue the current operation

After:

	--quit		end revert or cherry-pick sequence
	--continue	resume revert or cherry-pick sequence

Noticed-by: Phil Hord <phil.hord@gmail.com>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-11-22 13:30:35 -08:00
Junio C Hamano
cd4093b603 Merge branch 'rr/revert-cherry-pick-continue'
* rr/revert-cherry-pick-continue:
  builtin/revert.c: make commit_list_append() static
  revert: Propagate errors upwards from do_pick_commit
  revert: Introduce --continue to continue the operation
  revert: Don't implicitly stomp pending sequencer operation
  revert: Remove sequencer state when no commits are pending
  reset: Make reset remove the sequencer state
  revert: Introduce --reset to remove sequencer state
  revert: Make pick_commits functionally act on a commit list
  revert: Save command-line options for continuing operation
  revert: Save data for continuing after conflict resolution
  revert: Don't create invalid replay_opts in parse_args
  revert: Separate cmdline parsing from functional code
  revert: Introduce struct to keep command-line options
  revert: Eliminate global "commit" variable
  revert: Rename no_replay to record_origin
  revert: Don't check lone argument in get_encoding
  revert: Simplify and inline add_message_to_msg
  config: Introduce functions to write non-standard file
  advice: Introduce error_resolve_conflict
2011-10-05 12:36:19 -07:00
Ramkumar Ramachandra
5a5d80f4ca revert: Introduce --continue to continue the operation
Introduce a new "git cherry-pick --continue" command which uses the
information in ".git/sequencer" to continue a cherry-pick that stopped
because of a conflict or other error.  It works by dropping the first
instruction from .git/sequencer/todo and performing the remaining
cherry-picks listed there, with options (think "-s" and "-X") from the
initial command listed in ".git/sequencer/opts".

So now you can do:

  $ git cherry-pick -Xpatience foo..bar
  ... description conflict in commit moo ...
  $ git cherry-pick --continue
  error: 'cherry-pick' is not possible because you have unmerged files.
  fatal: failed to resume cherry-pick
  $ echo resolved >conflictingfile
  $ git add conflictingfile && git commit
  $ git cherry-pick --continue; # resumes with the commit after "moo"

During the "git commit" stage, CHERRY_PICK_HEAD will aid by providing
the commit message from the conflicting "moo" commit.  Note that the
cherry-pick mechanism has no control at this stage, so the user is
free to violate anything that was specified during the first
cherry-pick invocation.  For example, if "-x" was specified during the
first cherry-pick invocation, the user is free to edit out the message
during commit time.  Note that the "--signoff" option specified at
cherry-pick invocation time is not reflected in the commit message
provided by CHERRY_PICK_HEAD; the user must take care to add
"--signoff" during the "git commit" invocation.

Helped-by: Christian Couder <chriscool@tuxfamily.org>
Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-08-08 09:28:24 -07:00
Jeff King
5d2fc9135a docs: put listed example commands in backticks
Many examples of git command invocation are given in asciidoc listing
blocks, which makes them monospaced and avoids further interpretation of
special characters.  Some manpages make a list of examples, like:

  git foo::
    Run git foo.

  git foo -q::
    Use the "-q" option.

to quickly show many variants. However, they can sometimes be hard to
read, because they are shown in a proportional-width font (so, for
example, seeing the difference between "-- foo" and "--foo" can be
difficult).

This patch puts all such examples into backticks, which gives the
equivalent formatting to a listing block (i.e., monospaced and without
character interpretation).

As a bonus, this also fixes an example in the git-push manpage, in which
"git push origin :::" was accidentally considered a newly-indented list,
and not a list item with "git push origin :" in it.

Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-08-04 15:49:13 -07:00
Ramkumar Ramachandra
26ae337be1 revert: Introduce --reset to remove sequencer state
To explicitly remove the sequencer state for a fresh cherry-pick or
revert invocation, introduce a new subcommand called "--reset" to
remove the sequencer state.

Take the opportunity to publicly expose the sequencer paths, and a
generic function called "remove_sequencer_state" that various git
programs can use to remove the sequencer state in a uniform manner;
"git reset" uses it later in this series.  Introducing this public API
is also in line with our long-term goal of eventually factoring out
functions from revert.c into a generic commit sequencer.

Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-08-04 15:41:21 -07:00
Martin von Zweigbergk
7791a1d9b9 Documentation: use [verse] for SYNOPSIS sections
The SYNOPSIS sections of most commands that span several lines already
use [verse] to retain line breaks. Most commands that don't span
several lines seem not to use [verse]. In the HTML output, [verse]
does not only preserve line breaks, but also makes the section
indented, which causes a slight inconsistency between commands that
use [verse] and those that don't. Use [verse] in all SYNOPSIS sections
for consistency.

Also remove the blank lines from git-fetch.txt and git-rebase.txt to
align with the other man pages. In the case of git-rebase.txt, which
already uses [verse], the blank line makes the [verse] not apply to
the last line, so removing the blank line also makes the formatting
within the document more consistent.

While at it, add single quotes to 'git cvsimport' for consistency with
other commands.

Signed-off-by: Martin von Zweigbergk <martin.von.zweigbergk@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-07-06 14:26:26 -07:00
Junio C Hamano
3340f60483 Merge branch 'ss/cherry-pick-x-doc'
* ss/cherry-pick-x-doc:
  doc: Clarify that "cherry-pick -x" does not use "git notes"
2011-05-04 15:51:35 -07:00
Sebastian Schuberth
bea7d16e8b doc: Clarify that "cherry-pick -x" does not use "git notes"
The documentation for "cherry-pick -x" could be misread in the way that a
"git notes" object is attached to the new commit, which is not the case.

Signed-off-by: Sebastian Schuberth <sschuberth@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-04-15 13:53:00 -07:00
Jeff King
48bb914ed6 doc: drop author/documentation sections from most pages
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.
2011-03-11 10:59:16 -05:00
Junio C Hamano
66ecd2d053 Merge branch 'js/cherry-pick-usability'
* js/cherry-pick-usability:
  Teach commit about CHERRY_PICK_HEAD
  bash: teach __git_ps1 about CHERRY_PICK_HEAD
  Introduce CHERRY_PICK_HEAD
  t3507: introduce pristine-detach helper
2011-03-09 15:56:17 -08:00
Jay Soffian
d7e5c0cbfb Introduce CHERRY_PICK_HEAD
When a cherry-pick conflicts git advises:

 $ git commit -c <original commit id>

to preserve the original commit message and authorship. Instead, let's
record the original commit id in CHERRY_PICK_HEAD and advise:

  $ git commit -c CHERRY_PICK_HEAD

A later patch teaches git to handle the '-c CHERRY_PICK_HEAD' part.
Note that we record CHERRY_PICK_HEAD even in the case where there
are no conflicts so that we may use it to communicate authorship to
commit; this will then allow us to remove set_author_ident_env from
revert.c. However, we do not record CHERRY_PICK_HEAD when --no-commit
is used, as presumably the user intends to further edit the commit
and possibly even cherry-pick additional commits on top.

Tests and documentation contributed by Jonathan Nieder.

Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Jay Soffian <jaysoffian@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-02-21 22:58:02 -08:00
Jonathan Nieder
67ac1e1d57 cherry-pick/revert: add support for -X/--strategy-option
For example, this would allow cherry-picking or reverting patches from
a piece of history with a different end-of-line style, like so:

	$ git revert -Xrenormalize old-problematic-commit

Currently that is possible with manual use of merge-recursive but the
cherry-pick/revert porcelain does not expose the functionality.

While at it, document the existing support for --strategy.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-12-28 11:27:56 -08:00
Junio C Hamano
be1b055877 Documentation: Fix mark-up of lines with more than one tilde
The manual pages of cherry-pick and revert had examples with two revisions
on the same line in the examples section, that looked like this:

    git cherry-pick master~4 master~2::

Unfortunately, this is taken as a mark-up to make the part between two
tildes, "4 master", subscript.  Use {tilde} to make it explicit that we
do want ~ characters in these places (backslash does not help).

Reported-by: Sylvain Rabot <sylvain.rabot@f-secure.com>
Helped-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-12-02 11:30:35 -08:00
Jonathan Nieder
9d83e3827f Documentation: gitrevisions is in section 7
Fix references to gitrevisions(1) in the manual pages and HTML
documentation.

In practice, this will not matter much unless someone tries to use a
hard copy of the git reference manual.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-10-13 19:10:55 -07:00
Michael J Gruber
f028cdae66 Documentation: link to gitrevisions rather than git-rev-parse
Currently, whenever we need documentation for revisions and ranges, we
link to the git-rev-parse man page, i.e. a plumbing man page, which has
this along with the documentation of all rev-parse modes.

Link to the new gitrevisions man page instead in all cases except
- when the actual git-rev-parse command is referred to or
- in very technical context (git-send-pack).

Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-07-05 13:39:13 -07:00
Christian Couder
f873a273d1 revert: accept arbitrary rev-list options
This can be useful to do something like:

git rev-list --reverse master -- README | git cherry-pick -n --stdin

without using xargs.

Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-06-25 08:55:48 -07:00
Christian Couder
89d32d33ae Documentation/cherry-pick: describe passing more than one commit
And while at it, add an "EXAMPLES" section.

Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-06-02 10:10:05 -07:00
Christian Couder
ab7e63e85f Documentation: describe new cherry-pick --ff option
Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-03-06 23:58:47 -08:00
Thomas Rast
0b444cdb19 Documentation: spell 'git cmd' without dash throughout
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.
2010-01-10 13:01:28 +01:00
Bryan Drewery
37a7744ffe Fix misleading wording for git-cherry-pick
Documentation for -n implies that -x is normally
used, however this is no longer true.

Signed-off-by: Bryan Drewery <bryan@shatow.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-11-23 19:32:39 -08:00
Junio C Hamano
59eb68aa2b Update my e-mail address
The old cox.net address is still getting mails from gitters.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-21 12:14:42 -07:00
Junio C Hamano
88bbda08d7 Merge branch 'maint'
* maint:
  Start preparing 1.5.6.4 release notes
  git fetch-pack: do not complain about "no common commits" in an empty repo
  rebase-i: keep old parents when preserving merges
  t7600-merge: Use test_expect_failure to test option parsing
  Fix buffer overflow in prepare_attr_stack
  Fix buffer overflow in git diff
  Fix buffer overflow in git-grep
  git-cvsserver: fix call to nonexistant cleanupWorkDir()
  Documentation/git-cherry-pick.txt et al.: Fix misleading -n description

Conflicts:
	RelNotes
2008-07-16 17:10:28 -07:00