{"thread":{"id":"3428","subject":"[PATCH] git-rebase: Clarify usage statement and copy it into the actual documentation.","startedAt":"2006-02-22T01:10:12Z","lastAt":"2006-02-22T01:10:12Z","messageCount":1,"participants":["Carl Worth"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"16549","messageId":"87mzgkryff.wl%cworth@cworth.org","threadId":"3428","inReplyTo":null,"subject":"[PATCH] git-rebase: Clarify usage statement and copy it into the actual documentation.","fromName":"Carl Worth","fromEmail":"cworth@cworth.org","sentAt":"2006-02-22T01:10:12Z","receivedAt":"2006-02-22T01:10:12Z","isPatch":true,"sender":{"key":"cworth@cworth.org","avatar":"https://gravatar.com/avatar/3746dc28cde609bdbd7f939058356e7e2bbd16d21e32274df0725eb3d998bc5b?d=mp&s=160"},"body":"I found a paper thin man page for git-rebase, but was quite happy to\nsee something much more useful in the usage statement of the script\nwhen I went there to find out how this thing worked. Here it is\ncleaned up slightly and expanded a bit into the actual documentation.\n\nSigned-off-by: Carl Worth <cworth@cworth.org>\n\n---\n\n Drat. I just realized I've been neglecting the Signed-off-by: line in\n my last few patches. Junio, if you'd like me to re-send those with\n that fixed, just let me know.\n\n Documentation/git-rebase.txt |   44 ++++++++++++++++++++++++++++++++++++++++--\n git-rebase.sh                |   24 +++++++++++++----------\n 2 files changed, 56 insertions(+), 12 deletions(-)\n\nf78b6a97afd562d2cf2d30488892ff893dd81a3b\ndiff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\nindex 16c158f..f037d12 100644\n--- a/Documentation/git-rebase.txt\n+++ b/Documentation/git-rebase.txt\n@@ -7,14 +7,54 @@ git-rebase - Rebase local commits to new\n \n SYNOPSIS\n --------\n-'git-rebase' <upstream> [<head>]\n+'git-rebase' [--onto <newbase>] <upstream> [<branch>]\n \n DESCRIPTION\n -----------\n-Rebases local commits to the new head of the upstream tree.\n+git-rebase applies to <upstream> (or optionally to <newbase>) commits\n+from <branch> that do not appear in <upstream>. When <branch> is not\n+specified it defaults to the current branch (HEAD).\n+\n+When git-rebase is complete, <branch> will be updated to point to the\n+newly created line of commit objects, so the previous line will not be\n+accessible unless there are other references to it already.\n+\n+Assume the following history exists and the current branch is \"topic\":\n+\n+          A---B---C topic\n+         /\n+    D---E---F---G master\n+\n+From this point, the result of the following commands:\n+\n+    git-rebase master\n+    git-rebase master topic\n+\n+would be:\n+\n+                  A'--B'--C' topic\n+                 /\n+    D---E---F---G master\n+\n+While, starting from the same point, the result of the following\n+commands:\n+\n+    git-rebase --onto master~1 master\n+    git-rebase --onto master~1 master topic\n+\n+would be:\n+\n+              A'--B'--C' topic\n+             /\n+    D---E---F---G master\n \n OPTIONS\n -------\n+<newbase>::\n+\tStarting point at which to create the new commits. If the\n+\t--onto option is not specified, the starting point is\n+\t<upstream>.\n+\n <upstream>::\n \tUpstream branch to compare against.\n \ndiff --git a/git-rebase.sh b/git-rebase.sh\nindex 21c3d83..211bf68 100755\n--- a/git-rebase.sh\n+++ b/git-rebase.sh\n@@ -4,24 +4,28 @@\n #\n \n USAGE='[--onto <newbase>] <upstream> [<branch>]'\n-LONG_USAGE='If <branch> is specified, switch to that branch first.  Then,\n-extract commits in the current branch that are not in <upstream>,\n-and reconstruct the current on top of <upstream>, discarding the original\n-development history.  If --onto <newbase> is specified, the history is\n-reconstructed on top of <newbase>, instead of <upstream>.  For example,\n-while on \"topic\" branch:\n+LONG_USAGE='git-rebase applies to <upstream> (or optionally to <newbase>) commits\n+from <branch> that do not appear in <upstream>. When <branch> is not\n+specified it defaults to the current branch (HEAD).\n+\n+When git-rebase is complete, <branch> will be updated to point to the\n+newly created line of commit objects, so the previous line will not be\n+accessible unless there are other references to it already.\n+\n+Assuming the following history:\n \n           A---B---C topic\n          /\n     D---E---F---G master\n \n-\t$ '\"$0\"' --onto master~1 master topic\n+The result of the following command:\n \n-would rewrite the history to look like this:\n+    git-rebase --onto master~1 master topic\n \n+  would be:\n \n-\t      A'\\''--B'\\''--C'\\'' topic\n-\t     /\n+              A'\\''--B'\\''--C'\\'' topic\n+             /\n     D---E---F---G master\n '\n \n-- \n1.2.2.g0a5f5-dirty\n\n"}]}