From: Carl Worth <cworth@cworth.org>
To: Junio C Hamano <junkio@cox.net>
Cc: git@vger.kernel.org
Subject: [PATCH] git-rebase: Clarify usage statement and copy it into the actual documentation.
Date: Tue, 21 Feb 2006 17:10:12 -0800 [thread overview]
Message-ID: <87mzgkryff.wl%cworth@cworth.org> (raw)
[-- Attachment #1: Type: text/plain, Size: 3818 bytes --]
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>
---
Drat. I just realized I've been neglecting the Signed-off-by: line in
my last few patches. Junio, if you'd like me to re-send those with
that fixed, just let me know.
Documentation/git-rebase.txt | 44 ++++++++++++++++++++++++++++++++++++++++--
git-rebase.sh | 24 +++++++++++++----------
2 files changed, 56 insertions(+), 12 deletions(-)
f78b6a97afd562d2cf2d30488892ff893dd81a3b
diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index 16c158f..f037d12 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -7,14 +7,54 @@ git-rebase - Rebase local commits to new
SYNOPSIS
--------
-'git-rebase' <upstream> [<head>]
+'git-rebase' [--onto <newbase>] <upstream> [<branch>]
DESCRIPTION
-----------
-Rebases local commits to the new head of the upstream tree.
+git-rebase applies to <upstream> (or optionally to <newbase>) commits
+from <branch> that do not appear in <upstream>. When <branch> is not
+specified it defaults to the current branch (HEAD).
+
+When git-rebase is complete, <branch> will be updated to point to the
+newly created line of commit objects, so the previous line will not be
+accessible unless there are other references to it already.
+
+Assume the following history exists and the current branch is "topic":
+
+ A---B---C topic
+ /
+ D---E---F---G master
+
+From this point, the result of the following commands:
+
+ git-rebase master
+ git-rebase master topic
+
+would be:
+
+ A'--B'--C' topic
+ /
+ D---E---F---G master
+
+While, starting from the same point, the result of the following
+commands:
+
+ git-rebase --onto master~1 master
+ git-rebase --onto master~1 master topic
+
+would be:
+
+ A'--B'--C' topic
+ /
+ D---E---F---G master
OPTIONS
-------
+<newbase>::
+ Starting point at which to create the new commits. If the
+ --onto option is not specified, the starting point is
+ <upstream>.
+
<upstream>::
Upstream branch to compare against.
diff --git a/git-rebase.sh b/git-rebase.sh
index 21c3d83..211bf68 100755
--- a/git-rebase.sh
+++ b/git-rebase.sh
@@ -4,24 +4,28 @@
#
USAGE='[--onto <newbase>] <upstream> [<branch>]'
-LONG_USAGE='If <branch> is specified, switch to that branch first. Then,
-extract commits in the current branch that are not in <upstream>,
-and reconstruct the current on top of <upstream>, discarding the original
-development history. If --onto <newbase> is specified, the history is
-reconstructed on top of <newbase>, instead of <upstream>. For example,
-while on "topic" branch:
+LONG_USAGE='git-rebase applies to <upstream> (or optionally to <newbase>) commits
+from <branch> that do not appear in <upstream>. When <branch> is not
+specified it defaults to the current branch (HEAD).
+
+When git-rebase is complete, <branch> will be updated to point to the
+newly created line of commit objects, so the previous line will not be
+accessible unless there are other references to it already.
+
+Assuming the following history:
A---B---C topic
/
D---E---F---G master
- $ '"$0"' --onto master~1 master topic
+The result of the following command:
-would rewrite the history to look like this:
+ git-rebase --onto master~1 master topic
+ would be:
- A'\''--B'\''--C'\'' topic
- /
+ A'\''--B'\''--C'\'' topic
+ /
D---E---F---G master
'
--
1.2.2.g0a5f5-dirty
[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]
reply other threads:[~2006-02-22 1:11 UTC|newest]
Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87mzgkryff.wl%cworth@cworth.org \
--to=cworth@cworth.org \
--cc=git@vger.kernel.org \
--cc=junkio@cox.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).