Commit Graph

39 Commits

Author SHA1 Message Date
Ævar Arnfjörð Bjarmason 4618d2ca82 reflog doc: list real subcommands up-front
Change the "git reflog" documentation to exhaustively list the
subcommands it accepts in the SYNOPSIS, as opposed to leaving that for
a "[verse]" in the DESCRIPTION section. This documentation style was
added in cf39f54efc (git reflog show, 2007-02-08), but isn't how
other commands which take subcommands are documented.

Signed-off-by: Ævar Arnfjörð Bjarmason <>
Signed-off-by: Junio C Hamano <>
2022-10-13 09:32:58 -07:00
Ævar Arnfjörð Bjarmason b2ca7e417e doc SYNOPSIS: don't use ' for subcommands
Almost all of our documentation doesn't use "'" syntax for
subcommands, but these did, let's make them consistent with the

Signed-off-by: Ævar Arnfjörð Bjarmason <>
Signed-off-by: Junio C Hamano <>
2022-10-13 09:32:54 -07:00
Glen Choo 94955d576b Documentation/git-reflog: remove unneeded \ from \{
There are some inconsistencies with how different asciidoc environments
handle different combinations of "\{<>}", e.g. these results were
observed with asciidoc on two different environments:

  | Input     | Output (env A) | Output (env B)   | same/different |
  | \{<foo>\} | {&lt;foo&gt;}  | \{&lt;foo&gt;}^M | different      |
  | {<foo>}   | {&lt;foo&gt;}  | {&lt;foo&gt;}    | same           |
  | \{<foo>}  | {&lt;foo&gt;}  | \{&lt;foo&gt;}^M | different      |
  | \{foo\}   | {foo}          | {foo}            | same           |
  | \{\}      | {}             | \{}^M            | different      |
  | \{}       | {}             | {}               | same           |
  | {\}       | {}             | {}               | same           |

The only instance of this biting us is "@\{<specifier>\}" in
Documentation/git-reflog.txt; all other combinations of "\{<>}" (e.g. in
Documentation/revisions.txt) seem to render consistently.

Fix this inconsistent rendering by removing the unnecessary "\" in

Signed-off-by: Glen Choo <>
Signed-off-by: Junio C Hamano <>
2022-08-01 14:33:44 -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 <>
Signed-off-by: Junio C Hamano <>
2021-11-09 09:39:11 -08:00
Nguyễn Thái Ngọc Duy c9ef0d95eb reflog expire: cover reflog from all worktrees
Reported-by: Jeff King <>
Signed-off-by: Nguyễn Thái Ngọc Duy <>
Signed-off-by: Junio C Hamano <>
2018-10-22 13:32:54 +09:00
Robert P. J. Day 0ba014035a doc: add missing "-n" (dry-run) option to reflog man page
While the "git reflog" man page supports both "--dry-run" and "-n" for
a dry run, the man page mentions only the former, not the latter.

Signed-off-by: Robert P. J. Day <>
Signed-off-by: Junio C Hamano <>
2017-11-22 12:24:47 +09:00
David Turner afcb2e7a3b git-reflog: add exists command
This is necessary because alternate ref backends might store reflogs
somewhere other than .git/logs.  Code that now directly manipulates
.git/logs should instead go through git-reflog.

Signed-off-by: David Turner <>
Signed-off-by: Junio C Hamano <>
2015-07-21 14:08:14 -07:00
Michael Haggerty 5e6f003ca8 reflog_expire(): ignore --updateref for symbolic references
If we are expiring reflog entries for a symbolic reference, then how
should --updateref be handled if the newest reflog entry is expired?

Option 1: Update the referred-to reference. (This is what the current
code does.) This doesn't make sense, because the referred-to reference
has its own reflog, which hasn't been rewritten.

Option 2: Update the symbolic reference itself (as in, REF_NODEREF).
This would convert the symbolic reference into a non-symbolic
reference (e.g., detaching HEAD), which is surely not what a user
would expect.

Option 3: Error out. This is plausible, but it would make the
following usage impossible:

    git reflog expire ... --updateref --all

Option 4: Ignore --updateref for symbolic references.

We choose to implement option 4.

Note: another problem in this code will be fixed in a moment.

Signed-off-by: Michael Haggerty <>
Reviewed-by: Stefan Beller <>
Signed-off-by: Junio C Hamano <>
2015-03-05 12:35:37 -08:00
Michael Haggerty fe2a18165c reflog: improve and update documentation
Revamp the "git reflog" usage documentation in the manpage and the
command help to match the current reality and improve its clarity:

* Add documentation for some options that had been left out.

* Group the subcommands and options more logically and move more
  common subcommands/options higher.

* Improve some explanations.

Signed-off-by: Michael Haggerty <>
Reviewed-by: Stefan Beller <>
Signed-off-by: Junio C Hamano <>
2015-03-05 12:35:36 -08:00
Junio C Hamano 3e1e7624aa Merge branch 'jc/prune-all'
We used the approxidate() parser for "--expire=<timestamp>" options
of various commands, but it is better to treat --expire=all and
--expire=now a bit more specially than using the current timestamp.
Update "git gc" and "git reflog" with a new parsing function for
expiry dates.

* jc/prune-all:
  prune: introduce OPT_EXPIRY_DATE() and use it
  api-parse-options.txt: document "no-" for non-boolean options
  git-gc.txt, git-reflog.txt: document new expiry options
  date.c: add parse_expiry_date()
2013-05-29 14:23:04 -07:00
Michael Haggerty 61929404df git-gc.txt, git-reflog.txt: document new expiry options
Document the new values that can be used for expiry values where their
use makes sense:

* git reflog expire --expire=[all|never]
* git reflog expire --expire-unreachable=[all|never]
* git gc --prune=all

Other combinations aren't useful and therefore no documentation is
added (even though they are allowed):

* git gc --prune=never

  is redundant with "git gc --no-prune"

* git prune --expire=all

  is equivalent to providing no --expire option

* git prune --expire=never

  is a NOP

Signed-off-by: Michael Haggerty <>
Signed-off-by: Junio C Hamano <>
2013-04-18 09:30:15 -07:00
Thomas Ackermann 2de9b71138 Documentation: the name of the system is 'Git', not 'git'
Signed-off-by: Thomas Ackermann <>
Signed-off-by: Junio C Hamano <>
2013-02-01 13:53:33 -08: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

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

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 <>` used to
    erroneously auto-generate a mailto footnote for

  - 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

Signed-off-by: Jeff King <>
Signed-off-by: Junio C Hamano <>
2012-04-26 13:19:06 -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 <>
Signed-off-by: Junio C Hamano <>
2011-07-06 14:26:26 -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

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
Jonathan Nieder 9d83e3827f Documentation: gitrevisions is in section 7
Fix references to gitrevisions(1) in the manual pages and HTML

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 <>
Signed-off-by: Junio C Hamano <>
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 <>
Signed-off-by: Junio C Hamano <>
2010-07-05 13:39:13 -07:00
Junio C Hamano d16a5dafdc Merge branch 'maint-1.6.6' into maint
* maint-1.6.6:
  Documentation/git-clone: Transform description list into item list
  Documentation/urls: Remove spurious example markers
  Documentation/gitdiffcore: Remove misleading date in heading
  Documentation/git-reflog: Fix formatting of command lists
2010-03-21 17:00:22 -07:00
Michael J Gruber b6c7c41b17 Documentation/git-reflog: Fix formatting of command lists
A misplaced list continuation mark appears literally in the
rendered doc. Fix this by removing it.

Signed-off-by: Michael J Gruber <>
Signed-off-by: Junio C Hamano <>
2010-03-21 14:40:02 -07: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
2010-01-10 13:01:28 +01:00
Markus Heidelberg 04c8ce9c1c Documentation: fix typos, grammar, asciidoc syntax
Signed-off-by: Markus Heidelberg <>
Signed-off-by: Junio C Hamano <>
2008-12-19 19:10:46 -08:00
Junio C Hamano 59eb68aa2b Update my e-mail address
The old address is still getting mails from gitters.

Signed-off-by: Junio C Hamano <>
2008-07-21 12:14:42 -07:00
Jonathan Nieder db5d6666af manpages: use teletype font for sample command lines
I think that some of these uses of italics were meant to be
rendered in quotation marks, anyway.

Signed-off-by: Jonathan Nieder <>
Signed-off-by: Junio C Hamano <>
2008-07-05 11:24:40 -07:00
Jonathan Nieder 04c2407eaf manpages: italicize command names in synopses
To tell command names from options in a glance.

Signed-off-by: Jonathan Nieder <>
Signed-off-by: Junio C Hamano <>
2008-07-05 11:24:39 -07:00
Jonathan Nieder 467c0197fd Documentation: more "git-" versus "git " changes
With git-commands moving out of $(bindir), it is useful to make a
clearer distinction between the git subcommand 'git-whatever' and
the command you type, `git whatever <options>`.  So we use a dash
after "git" when referring to the former and not the latter.

I already sent a patch doing this same thing, but I missed some

Signed-off-by: Jonathan Nieder <>
Signed-off-by: Junio C Hamano <>
2008-07-05 11:24:39 -07:00
Christian Couder 9e1f0a85c6 documentation: move git(7) to git(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 <>
Signed-off-by: Junio C Hamano <>
2008-06-06 11:18:28 -07:00
Brandon Casey cf2756ae19 git-reflog.txt: Document new commands --updateref and --rewrite
Signed-off-by: Brandon Casey <>
Signed-off-by: Junio C Hamano <>
2008-03-03 01:20:59 -08:00
Junio C Hamano 50f3ac29cb Merge branch 'bc/reflog-fix' into js/reflog-delete
* bc/reflog-fix: (1490 commits)
  builtin-reflog.c: don't install new reflog on write failure
  hash: fix lookup_hash semantics
  gitweb: Better chopping in commit search results
  builtin-tag.c: remove cruft
  git-merge-index documentation: clarify synopsis
  send-email: fix In-Reply-To regression
  git-reset --hard and git-read-tree --reset: fix read_cache_unmerged()
  Teach git-grep --name-only as synonym for -l
  diff: fix java funcname pattern for solaris
  t3404: use configured shell instead of /bin/sh
  git_config_*: don't assume we are parsing a config file
  prefix_path: use is_absolute_path() instead of *orig == '/'
  git-clean: handle errors if removing files fails
  Clarified the meaning of git-add -u in the documentation properly configure remote even if remote's head is dangling
  git.el: Set process-environment instead of invoking env
  Documentation/git-stash: document options for git stash list
  send-email: squelch warning due to comparing undefined $_ to ""
  cvsexportcommit: be graceful when "cvs status" reorders the arguments
  Rename git-core rpm to just git and rename the meta-pacakge to git-all.


2008-02-22 22:54:37 -08:00
Dan McGee 5162e69732 Documentation: rename gitlink macro to linkgit
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.
+# Explicit so they can be nested.
 # Anchor: [[[id]]]. Bibliographic anchor.
 # 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 <>
Signed-off-by: Junio C Hamano <>
2008-01-06 18:41:44 -08:00
Matthieu Moy 97e92e2cbc Doc fix for git-reflog: mention @{...} syntax, and <ref> in synopsys.
The HEAD@{...} syntax was documented in git-rev-parse manpage, which
is hard to find by someone looking for the documentation of porcelain.
git-reflog is probably the place where one expects to find this.

While I'm there, "git revlog show whatever" was also undocumented.

Signed-off-by: Matthieu Moy <>
Signed-off-by: Junio C Hamano <>
2007-11-20 00:15:13 -08:00
Johannes Schindelin 552cecc214 Teach "git reflog" a subcommand to delete single entries
This commit implements the "delete" subcommand:

	git reflog delete master@{2}

will delete the second reflog entry of the "master" branch.

With this, it should be easy to implement "git stash pop" everybody
seems to want these days.

Signed-off-by: Johannes Schindelin <>
Signed-off-by: Shawn O. Pearce <>
2007-10-17 02:54:51 -04:00
Michele Ballabio a5d4101537 git-reflog: document --verbose
Signed-off-by: Michele Ballabio <>
Signed-off-by: Lars Hjemli <>
Signed-off-by: Shawn O. Pearce <>
2007-10-15 21:10:54 -04:00
Brian Hetro 027830755d Documentation: Correct various misspellings and typos.
Fix minor typos throughout the documentation.

Signed-off-by: Brian Hetro <>
Signed-off-by: Junio C Hamano <>
2007-08-24 18:54:37 -07:00
Shawn O. Pearce 95064cbcc8 Correct documentation of 'reflog show' to explain it shows HEAD
By default 'git reflog show' will show the reflog of 'HEAD' and not
the reflog of the current branch.  This is most likely due to the
work done a while ago as part of the detached HEAD series to allow
HEAD to have its own reflog independent of each branch's reflog.

Since 'git reflog show' is really just an obscure alias for 'git
log -g --abbrev-commit --pretty=oneline' it should behave the same
way and its documentation should match.

Signed-off-by: Shawn O. Pearce <>
Signed-off-by: Junio C Hamano <>
2007-08-19 11:38:53 -07:00
Jakub Narebski cb877cd7b6 Document git reflog --stale-fix
Document --stale-fix, used in "git reflog expire --stale-fix --all"
to remove invalid reflog entries, to fix situation after running
non reflog-aware git-prune from an older git in the presence of
reflogs (see RelNotes-1.5.0.txt).

Based on description of commit 1389d9ddaa
  "reflog expire --fix-stale"
which introduced this option.

Signed-off-by: Jakub Narebski <>
Signed-off-by: Junio C Hamano <>
2007-06-16 13:08:12 -07:00
Junio C Hamano a6080a0a44 War on whitespace
This uses "git-apply --whitespace=strip" to fix whitespace errors that have
crept in to our source files over time.  There are a few files that need
to have trailing whitespaces (most notably, test vectors).  The results
still passes the test, and build result in Documentation/ area is unchanged.

Signed-off-by: Junio C Hamano <>
2007-06-07 00:04:01 -07:00
Linus Torvalds cf39f54efc git reflog show
It makes "git reflog [show]" act as

	git log -g --pretty=oneline --abbrev-cmit

and is fairly straightforward. So you can just write

	git reflog


	git reflog show

and it will show you the reflog in a nice format.

Signed-off-by: Linus Torvalds <>
Signed-off-by: Junio C Hamano <>
2007-02-08 15:35:24 -08:00
Junio C Hamano 15261e3b33 git reflog expire: document --stale-fix option.
Signed-off-by: Junio C Hamano <>
2007-01-15 14:43:03 -08:00
Junio C Hamano 4aec56d12b git-reflog: gc.* configuration and documentation.
Signed-off-by: Junio C Hamano <>
2006-12-27 01:47:57 -08:00