diff options
| -rw-r--r-- | Documentation/magit.org | 124 | ||||
| -rw-r--r-- | Documentation/magit.texi | 165 |
2 files changed, 289 insertions, 0 deletions
diff --git a/Documentation/magit.org b/Documentation/magit.org index ed10044..515f6f9 100644 --- a/Documentation/magit.org +++ b/Documentation/magit.org @@ -2959,6 +2959,130 @@ commands instead. - User Option: git-rebase-confirm-cancel Whether confirmation is required to cancel. +*** Rebase sequence log + +While a rebase sequence is in progress, the status buffer features a +section which lists the commits that have already been applied as well +as the commits that still have to be applied. + +The commits are split in two halves. When rebase stops at a commit, +either because the user has to deal with a conflict or explicitly +requested that rebase stops at that commit, then point is placed on +the commit that separates the two groups, i.e. on ~HEAD~. The commits +above it have not been applied yet, while it and the commits below it +have already been applied. In between these two groups or applied and +yet-to-be applied commits there sometimes is a commit which has been +dropped. + +Each commit is prefixed with a word and these words are additionally +shown in different colors to indicate the status of the commits. + +The following colors are used: + +- Yellow commits have not been applied yet. + +- Gray commits have already been applied. + +- The blue commit is the ~HEAD~ commit. + +- The green commit is the commit the rebase sequence stopped at. If + this is the same commit as ~HEAD~ (e.g. because you haven't done + anything yet after rebase stopped at the commit, then this commit is + shown in blue, not green. There can only be a green and a blue + commit at the same time, if you create one or more new commits after + rebase stops at a commit. + +- Red commits have been dropped. They are shown for reference only, + e.g. to make it easier to diff. + +Of course these colors are subject to the color-theme in use. + +The following words are used: + +- Commits prefixed with ~pick~, ~reword~, ~edit~, ~squash~, and ~fixup~ have not + been applied yet. These words have the same meaning here as they do + in the buffer used to edit the rebase sequence. See [[*Editing rebase + sequences]]. + +- The commit prefixed with ~onto~ is the commit on top of which all the + other commits are being re-applied. Like the commits that have + already been re-applied, it is reachable from ~HEAD~, but unlike those + it has not actually been re-applied during the current session - it + wasn't touched at all. + +- Commits prefixed with ~done~ have already been re-applied. Not all + commits that have already been applied are prefixed with this word, + though. + +- When a commit is prefixed with ~void~, then that indicates that Magit + knows for sure that all the changes in that commit have been applied + using several new commits. This commit is no longer reachable from + ~HEAD~ and it also isn't one of the commits that will be applied when + resuming the session. + +- When a commit is prefixed with ~join~, then that indicates that the + rebase sequence stopped at that commit due to a conflict - you now + have to join (merge) the changes, with what has already been + applied. In a sense this is the commit rebase stopped at, but while + its effect is already in the index and in the worktree (with + conflict markers), the commit itself has not actually been applied + yet (it isn't the ~HEAD~). So it is shown in yellow, like the other + commits that still have to be applied. + +- When a commit is prefixed with ~goal~, ~same~, or ~work~, then that + indicates that you reset to an earlier commit (and that this commit + therefore is no longer reachable from ~HEAD~), but that it might still + be possible to create a new commit with the exact same tree or at + least the same patch-id, without manually editing any file. Or at + the very least that there are some uncommitted remaining, which + might, or might, not originate from that commit. + + - When a commit is prefixed with ~goal~, then that indicates that it + is still be possible to create a commit with the exact same tree + (the "goal") without manually editing a file, by simply committing + the index (or, provided nothing is already staged, by staging all + unstaged changes and then committing that). This is the case when + the original tree exists in the index or worktree in untainted + form. + + - When a commit is prefixed with ~same~, then that indicates that it + is no longer possible to create a commit with the exact same tree, + but that it is still possible to create a commit with the same + patch-id. This would be the case if you created a new commit with + other changes, but the changes from the original commit still + exist in the index and/or working tree in untainted form. + + - When a commit is prefixed with ~work~, then that indicates that you + are working with the changes from that commit after resetting to + an earlier commit. There are changes in the index and/or working + tree and some of them likely originate from that commit. + +- When a commit is prefixed with ~poof~ or ~gone~, then that indicates + that you reset to an earlier commit (and that this commit therefore + is no longer reachable from ~HEAD~), and that there are no uncommitted + changes remaining which might or might not allow you to create a new + commit with the same tree or at least the same patch-id. + + - When a commit is prefixed with ~poof~, then that indicates that it + is no longer reachable from ~HEAD~ but that it has been replaced + with one or more commits, which together have the exact same + effect. + + - When a commit is prefixed with ~gone~, then that indicates that it + is no longer reachable from ~HEAD~ and that we also cannot determine + whether its changes are still in effect in one or more new + commits. They might be, but if so, then there must also be other + changes which makes it impossible to know for sure. + +Do not worry if you do not fully understand the above. That's okay, +you will acquire a good enough understanding through practice. + +For other sequence operations such as cherry-picking a similar section +is displayed, but they lack some of the features described below, due +to limitations in the git commands used to implement them. Most +importantly these sequences only support "picking" a commit but not +other actions such as "rewording", and they do not keep track of the +commits which have already been applied. ** Cherry picking diff --git a/Documentation/magit.texi b/Documentation/magit.texi index ef03b69..b2202eb 100644 --- a/Documentation/magit.texi +++ b/Documentation/magit.texi @@ -168,6 +168,7 @@ Committing Rebasing * Editing rebase sequences:: +* Rebase sequence log:: Cherry picking @@ -4029,6 +4030,7 @@ Abort the current rebase operation, restoring the original branch. @menu * Editing rebase sequences:: +* Rebase sequence log:: @end menu @node Editing rebase sequences @@ -4176,6 +4178,169 @@ Whether to show usage instructions inside the rebase buffer. Whether confirmation is required to cancel. @end defopt +@node Rebase sequence log +@subsection Rebase sequence log + +While a rebase sequence is in progress, the status buffer features a +section which lists the commits that have already been applied as well +as the commits that still have to be applied. + +The commits are split in two halves. When rebase stops at a commit, +either because the user has to deal with a conflict or explicitly +requested that rebase stops at that commit, then point is placed on +the commit that separates the two groups, i.e. on @code{HEAD}. The commits +above it have not been applied yet, while it and the commits below it +have already been applied. In between these two groups or applied and +yet-to-be applied commits there sometimes is a commit which has been +dropped. + +Each commit is prefixed with a word and these words are additionally +shown in different colors to indicate the status of the commits. + +The following colors are used: + +@itemize +@item +Yellow commits have not been applied yet. + + +@item +Gray commits have already been applied. + + +@item +The blue commit is the @code{HEAD} commit. + + +@item +The green commit is the commit the rebase sequence stopped at. If +this is the same commit as @code{HEAD} (e.g. because you haven't done +anything yet after rebase stopped at the commit, then this commit is +shown in blue, not green. There can only be a green and a blue +commit at the same time, if you create one or more new commits after +rebase stops at a commit. + + +@item +Red commits have been dropped. They are shown for reference only, +e.g. to make it easier to diff. +@end itemize + +Of course these colors are subject to the color-theme in use. + +The following words are used: + +@itemize +@item +Commits prefixed with @code{pick}, @code{reword}, @code{edit}, @code{squash}, and @code{fixup} have not +been applied yet. These words have the same meaning here as they do +in the buffer used to edit the rebase sequence. See @ref{Editing rebase sequences,Editing rebase sequences}. + + +@item +The commit prefixed with @code{onto} is the commit on top of which all the +other commits are being re-applied. Like the commits that have +already been re-applied, it is reachable from @code{HEAD}, but unlike those +it has not actually been re-applied during the current session - it +wasn't touched at all. + + +@item +Commits prefixed with @code{done} have already been re-applied. Not all +commits that have already been applied are prefixed with this word, +though. + + +@item +When a commit is prefixed with @code{void}, then that indicates that Magit +knows for sure that all the changes in that commit have been applied +using several new commits. This commit is no longer reachable from +@code{HEAD} and it also isn't one of the commits that will be applied when +resuming the session. + + +@item +When a commit is prefixed with @code{join}, then that indicates that the +rebase sequence stopped at that commit due to a conflict - you now +have to join (merge) the changes, with what has already been +applied. In a sense this is the commit rebase stopped at, but while +its effect is already in the index and in the worktree (with +conflict markers), the commit itself has not actually been applied +yet (it isn't the @code{HEAD}). So it is shown in yellow, like the other +commits that still have to be applied. + + +@item +When a commit is prefixed with @code{goal}, @code{same}, or @code{work}, then that +indicates that you reset to an earlier commit (and that this commit +therefore is no longer reachable from @code{HEAD}), but that it might still +be possible to create a new commit with the exact same tree or at +least the same patch-id, without manually editing any file. Or at +the very least that there are some uncommitted remaining, which +might, or might, not originate from that commit. + +@itemize +@item +When a commit is prefixed with @code{goal}, then that indicates that it +is still be possible to create a commit with the exact same tree +(the "goal") without manually editing a file, by simply committing +the index (or, provided nothing is already staged, by staging all +unstaged changes and then committing that). This is the case when +the original tree exists in the index or worktree in untainted +form. + + +@item +When a commit is prefixed with @code{same}, then that indicates that it +is no longer possible to create a commit with the exact same tree, +but that it is still possible to create a commit with the same +patch-id. This would be the case if you created a new commit with +other changes, but the changes from the original commit still +exist in the index and/or working tree in untainted form. + + +@item +When a commit is prefixed with @code{work}, then that indicates that you +are working with the changes from that commit after resetting to +an earlier commit. There are changes in the index and/or working +tree and some of them likely originate from that commit. +@end itemize + + +@item +When a commit is prefixed with @code{poof} or @code{gone}, then that indicates +that you reset to an earlier commit (and that this commit therefore +is no longer reachable from @code{HEAD}), and that there are no uncommitted +changes remaining which might or might not allow you to create a new +commit with the same tree or at least the same patch-id. + +@itemize +@item +When a commit is prefixed with @code{poof}, then that indicates that it +is no longer reachable from @code{HEAD} but that it has been replaced +with one or more commits, which together have the exact same +effect. + + +@item +When a commit is prefixed with @code{gone}, then that indicates that it +is no longer reachable from @code{HEAD} and that we also cannot determine +whether its changes are still in effect in one or more new +commits. They might be, but if so, then there must also be other +changes which makes it impossible to know for sure. +@end itemize +@end itemize + +Do not worry if you do not fully understand the above. That's okay, +you will acquire a good enough understanding through practice. + +For other sequence operations such as cherry-picking a similar section +is displayed, but they lack some of the features described below, due +to limitations in the git commands used to implement them. Most +importantly these sequences only support "picking" a commit but not +other actions such as "rewording", and they do not keep track of the +commits which have already been applied. + @node Cherry picking @section Cherry picking |