@matheusbsbs / matheus-bagliano / commits / 69a60af5d0
Fork 0

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