diff --git a/magit.texi b/magit.texi index fcb9f632..013faba6 100644 --- a/magit.texi +++ b/magit.texi @@ -39,6 +39,7 @@ as an extension to Emacs. * Branching:: * Merging:: * Rebasing:: +* Rewriting:: * Pushing and Pulling:: @end menu @@ -324,6 +325,67 @@ Of course, you can initiate a rebase in any number of ways, by configuring @code{git pull} to rebase instead of merge, for example. Such a rebase can be finished with @kbd{R} as well. +@node Rewriting +@chapter Rewriting + +As hinted at earlier, you can rewrite your commit history. For +example, you can reset he current head to an earlier commit with +@kbd{x}. This leaves the working tree unchanged, and the status +buffer will show all the changes that has been made since that new +value of the current head. You can commit these changes again, +possibly splitting them into multiple commits as you go along. + +Amending your last commit is common special case of rewriting history +like this. + +Another common way to rewrite history is to reset the head to an +earlier commit, and then to cherry pick the discarded commits by +cherry picking them in a different order. You could pick them from +the reflog, for example. + +Magit has special support for rewriting that can simplify the book +keeping. These support commands all start with teh @kbd{r} prefix +key. + +Typing @kbd{r s} will start a rewrite operation. You will be prompted +for a @emph{base} commit, and all commits between the current head and +this commit are put in a list of @emph{Pending commits} (including the +base commit). The current head will then be reset to the parent of +the base commit. + +You would then typically use @kbd{a} and @kbd{A} to cherry pick +commits from the list of pending commits in the desired order, until +all have been applied. Magit shows which commits have been applied by +changing their marker from @code{*} to @code{.}. + +Using @kbd{A} will immediately commit the commit (as usual). If you +want to combine multiple old commits into a single new one, use +@kbd{a} to apply them all to your working tree, and then commit them +in the normal way. + +You can also use @kbd{v} to revert a commit when you have changed your +mind. This will change the @code{.} mark back to @code{*}. + +Once you are done with the rewrite, type @kbd{r t} to remove the book +keeping information from the status buffer. + +If you rather wish to start over, type @kbd{r a}. This will abort the +rewriting, resetting the current head back to the value it had before +the rewrite was started with @kbd{r s}. + +Typing @kbd{r f} will @emph{finish} the rewrite: it will apply all +unused commits one after the other, as if you would us @kbd{A} with +all of them. + +You can change the @kbd{*} and @kbd{.} marks of a pending commit +explicitly with @kbd{r *} and @kbd{r .}. + +In addition to a list of pending commits, the status buffer will show +the @emph{Pending changes}. This section shows the diff between the +original head and the current head. You can use it to review the +changes that you still need to rewrite, and you can apply hunks from +it, like from any other diff. + @node Pushing and Pulling @chapter Pushing and Pulling