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 <mhagger@alum.mit.edu> Reviewed-by: Stefan Beller <sbeller@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Michael Haggerty committed
Mar 3, 2015 at 12:43 UTC
fe2a18165c97d3e0937bb99fda449e1f64e5c867
2 files changed
+88
-64
Documentation/git-reflog.txt
+85
-58
@@ -17,85 +17,112 @@ The command takes various subcommands, and different options
17
depending on the subcommand:
18
19
[verse]
20
-'git reflog expire' [--dry-run] [--stale-fix] [--verbose]
21
- [--expire=<time>] [--expire-unreachable=<time>] [--all] <refs>...
22
-'git reflog delete' ref@\{specifier\}...
20
'git reflog' ['show'] [log-options] [<ref>]
21
+'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>]
22
+ [--rewrite] [--updateref] [--stale-fix]
23
+ [--dry-run] [--verbose] [--all | <refs>...]
24
+'git reflog delete' [--rewrite] [--updateref]
25
+ [--dry-run] [--verbose] ref@\{specifier\}...
26
+
27
+Reference logs, or "reflogs", record when the tips of branches and
28
+other references were updated in the local repository. Reflogs are
29
+useful in various Git commands, to specify the old value of a
30
+reference. For example, `HEAD@{2}` means "where HEAD used to be two
31
+moves ago", `master@{one.week.ago}` means "where master used to point
32
+to one week ago in this local repository", and so on. See
33
+linkgit:gitrevisions[7] for more details.
34
+
35
+This command manages the information recorded in the reflogs.
36
+
37
+The "show" subcommand (which is also the default, in the absence of
38
+any subcommands) shows the log of the reference provided in the
39
+command-line (or `HEAD`, by default). The reflog covers all recent
40
+actions, and in addition the `HEAD` reflog records branch switching.
41
+`git reflog show` is an alias for `git log -g --abbrev-commit
42
+--pretty=oneline`; see linkgit:git-log[1] for more information.
43
+
44
+The "expire" subcommand prunes older reflog entries. Entries older
45
+than `expire` time, or entries older than `expire-unreachable` time
46
+and not reachable from the current tip, are removed from the reflog.
47
+This is typically not used directly by end users -- instead, see
48
+linkgit:git-gc[1].
49
+
50
+The "delete" subcommand deletes single entries from the reflog. Its
51
+argument must be an _exact_ entry (e.g. "`git reflog delete
52
+master@{2}`"). This subcommand is also typically not used directly by
53
+end users.
54
25
-Reflog is a mechanism to record when the tip of branches are
26
-updated. This command is to manage the information recorded in it.
55
28
-The subcommand "expire" is used to prune older reflog entries.
29
-Entries older than `expire` time, or entries older than
30
-`expire-unreachable` time and not reachable from the current
31
-tip, are removed from the reflog. This is typically not used
32
-directly by the end users -- instead, see linkgit:git-gc[1].
33
-
34
-The subcommand "show" (which is also the default, in the absence of any
35
-subcommands) will take all the normal log options, and show the log of
36
-the reference provided in the command-line (or `HEAD`, by default).
37
-The reflog will cover all recent actions (HEAD reflog records branch switching
38
-as well). It is an alias for `git log -g --abbrev-commit --pretty=oneline`;
39
-see linkgit:git-log[1].
56
+OPTIONS
57
+-------
58
41
-The reflog is useful in various Git commands, to specify the old value
42
-of a reference. For example, `HEAD@{2}` means "where HEAD used to be
43
-two moves ago", `master@{one.week.ago}` means "where master used to
44
-point to one week ago", and so on. See linkgit:gitrevisions[7] for
45
-more details.
59
+Options for `show`
60
+~~~~~~~~~~~~~~~~~~
61
47
-To delete single entries from the reflog, use the subcommand "delete"
48
-and specify the _exact_ entry (e.g. "`git reflog delete master@{2}`").
62
+`git reflog show` accepts any of the options accepted by `git log`.
63
64
51
-OPTIONS
52
--------
65
+Options for `expire`
66
+~~~~~~~~~~~~~~~~~~~~
67
54
---stale-fix::
55
- This revamps the logic -- the definition of "broken commit"
56
- becomes: a commit that is not reachable from any of the refs and
57
- there is a missing object among the commit, tree, or blob
58
- objects reachable from it that is not reachable from any of the
59
- refs.
60
-+
61
-This computation involves traversing all the reachable objects, i.e. it
62
-has the same cost as 'git prune'. Fortunately, once this is run, we
63
-should not have to ever worry about missing objects, because the current
64
-prune and pack-objects know about reflogs and protect objects referred by
65
-them.
68
+--all::
69
+ Process the reflogs of all references.
70
71
--expire=<time>::
68
- Entries older than this time are pruned. Without the
69
- option it is taken from configuration `gc.reflogExpire`,
70
- which in turn defaults to 90 days. --expire=all prunes
71
- entries regardless of their age; --expire=never turns off
72
- pruning of reachable entries (but see --expire-unreachable).
72
+ Prune entries older than the specified time. If this option is
73
+ not specified, the expiration time is taken from the
74
+ configuration setting `gc.reflogExpire`, which in turn
75
+ defaults to 90 days. `--expire=all` prunes entries regardless
76
+ of their age; `--expire=never` turns off pruning of reachable
77
+ entries (but see `--expire-unreachable`).
78
79
--expire-unreachable=<time>::
75
- Entries older than this time and not reachable from
76
- the current tip of the branch are pruned. Without the
77
- option it is taken from configuration
78
- `gc.reflogExpireUnreachable`, which in turn defaults to
79
- 30 days. --expire-unreachable=all prunes unreachable
80
- entries regardless of their age; --expire-unreachable=never
80
+ Prune entries older than `<time>` that are not reachable from
81
+ the current tip of the branch. If this option is not
82
+ specified, the expiration time is taken from the configuration
83
+ setting `gc.reflogExpireUnreachable`, which in turn defaults
84
+ to 30 days. `--expire-unreachable=all` prunes unreachable
85
+ entries regardless of their age; `--expire-unreachable=never`
86
turns off early pruning of unreachable entries (but see
82
- --expire).
83
-
84
---all::
85
- Instead of listing <refs> explicitly, prune all refs.
87
+ `--expire`).
88
89
--updateref::
88
- Update the ref with the sha1 of the top reflog entry (i.e.
89
- <ref>@\{0\}) after expiring or deleting.
90
+ Update the reference to the value of the top reflog entry (i.e.
91
+ <ref>@\{0\}) if the previous top entry was pruned.
92
93
--rewrite::
92
- While expiring or deleting, adjust each reflog entry to ensure
93
- that the `old` sha1 field points to the `new` sha1 field of the
94
- previous entry.
94
+ If a reflog entry's predecessor is pruned, adjust its "old"
95
+ SHA-1 to be equal to the "new" SHA-1 field of the entry that
96
+ now precedes it.
97
+
98
+--stale-fix::
99
+ Prune any reflog entries that point to "broken commits". A
100
+ broken commit is a commit that is not reachable from any of
101
+ the reference tips and that refers, directly or indirectly, to
102
+ a missing commit, tree, or blob object.
103
++
104
+This computation involves traversing all the reachable objects, i.e. it
105
+has the same cost as 'git prune'. It is primarily intended to fix
106
+corruption caused by garbage collecting using older versions of Git,
107
+which didn't protect objects referred to by reflogs.
108
+
109
+-n::
110
+--dry-run::
111
+ Do not actually prune any entries; just show what would have
112
+ been pruned.
113
114
--verbose::
115
Print extra information on screen.
116
117
+
118
+Options for `delete`
119
+~~~~~~~~~~~~~~~~~~~~
120
+
121
+`git reflog delete` accepts options `--updateref`, `--rewrite`, `-n`,
122
+`--dry-run`, and `--verbose`, with the same meanings as when they are
123
+used with `expire`.
124
+
125
+
126
GIT
127
---
128
Part of the linkgit:git[1] suite
builtin/reflog.c
+3
-6
@@ -8,14 +8,11 @@
8
#include "revision.h"
9
#include "reachable.h"
10
11
-/*
12
- * reflog expire
13
- */
14
-
11
+/* NEEDSWORK: switch to using parse_options */
12
static const char reflog_expire_usage[] =
16
-"git reflog expire [--verbose] [--dry-run] [--stale-fix] [--expire=<time>] [--expire-unreachable=<time>] [--all] <refs>...";
13
+"git reflog expire [--expire=<time>] [--expire-unreachable=<time>] [--rewrite] [--updateref] [--stale-fix] [--dry-run | -n] [--verbose] [--all] <refs>...";
14
static const char reflog_delete_usage[] =
18
-"git reflog delete [--verbose] [--dry-run] [--rewrite] [--updateref] <refs>...";
15
+"git reflog delete [--rewrite] [--updateref] [--dry-run | -n] [--verbose] <refs>...";
16
17
static unsigned long default_reflog_expire;
18
static unsigned long default_reflog_expire_unreachable;