git-rebase: Clarify usage statement and copy it into the actual documentation.
I found a paper thin man page for git-rebase, but was quite happy to see something much more useful in the usage statement of the script when I went there to find out how this thing worked. Here it is cleaned up slightly and expanded a bit into the actual documentation. Signed-off-by: Carl Worth <cworth@cworth.org> Signed-off-by: Junio C Hamano <junkio@cox.net>
Carl Worth committed
Feb 21, 2006 at 17:10 UTC
69a60af5d0a84c4a7af907eba87f42dd6fb3c6e1
2 files changed
+56
-12
Documentation/git-rebase.txt
+42
-2
@@ -7,14 +7,54 @@ git-rebase - Rebase local commits to new upstream head.
7
8
SYNOPSIS
9
--------
10
-'git-rebase' <upstream> [<head>]
10
+'git-rebase' [--onto <newbase>] <upstream> [<branch>]
11
12
DESCRIPTION
13
-----------
14
-Rebases local commits to the new head of the upstream tree.
14
+git-rebase applies to <upstream> (or optionally to <newbase>) commits
15
+from <branch> that do not appear in <upstream>. When <branch> is not
16
+specified it defaults to the current branch (HEAD).
17
+
18
+When git-rebase is complete, <branch> will be updated to point to the
19
+newly created line of commit objects, so the previous line will not be
20
+accessible unless there are other references to it already.
21
+
22
+Assume the following history exists and the current branch is "topic":
23
+
24
+ A---B---C topic
25
+ /
26
+ D---E---F---G master
27
+
28
+From this point, the result of the following commands:
29
+
30
+ git-rebase master
31
+ git-rebase master topic
32
+
33
+would be:
34
+
35
+ A'--B'--C' topic
36
+ /
37
+ D---E---F---G master
38
+
39
+While, starting from the same point, the result of the following
40
+commands:
41
+
42
+ git-rebase --onto master~1 master
43
+ git-rebase --onto master~1 master topic
44
+
45
+would be:
46
+
47
+ A'--B'--C' topic
48
+ /
49
+ D---E---F---G master
50
51
OPTIONS
52
-------
53
+<newbase>::
54
+ Starting point at which to create the new commits. If the
55
+ --onto option is not specified, the starting point is
56
+ <upstream>.
57
+
58
<upstream>::
59
Upstream branch to compare against.
60
git-rebase.sh
+14
-10
@@ -4,24 +4,28 @@
4
#
5
6
USAGE='[--onto <newbase>] <upstream> [<branch>]'
7
-LONG_USAGE='If <branch> is specified, switch to that branch first. Then,
8
-extract commits in the current branch that are not in <upstream>,
9
-and reconstruct the current on top of <upstream>, discarding the original
10
-development history. If --onto <newbase> is specified, the history is
11
-reconstructed on top of <newbase>, instead of <upstream>. For example,
12
-while on "topic" branch:
7
+LONG_USAGE='git-rebase applies to <upstream> (or optionally to <newbase>) commits
8
+from <branch> that do not appear in <upstream>. When <branch> is not
9
+specified it defaults to the current branch (HEAD).
10
+
11
+When git-rebase is complete, <branch> will be updated to point to the
12
+newly created line of commit objects, so the previous line will not be
13
+accessible unless there are other references to it already.
14
+
15
+Assuming the following history:
16
17
A---B---C topic
18
/
19
D---E---F---G master
20
18
- $ '"$0"' --onto master~1 master topic
21
+The result of the following command:
22
20
-would rewrite the history to look like this:
23
+ git-rebase --onto master~1 master topic
24
25
+ would be:
26
23
- A'\''--B'\''--C'\'' topic
24
- /
27
+ A'\''--B'\''--C'\'' topic
28
+ /
29
D---E---F---G master
30
'
31