Next: , Up: Editing Commit Messages   [Contents][Index]


Using the Revision Stack

C-c C-w (magit-pop-revision-stack)

This command inserts a representation of a revision into the current buffer. It can be used inside buffers used to write commit messages but also in other buffers such as buffers used to edit emails or ChangeLog files.

By default this command pops the revision which was last added to the magit-revision-stack and inserts it into the current buffer according to magit-pop-revision-stack-format. Revisions can be put on the stack using magit-copy-section-value and magit-copy-buffer-revision.

If the stack is empty or with a prefix argument it instead reads a revision in the minibuffer. By using the minibuffer history this allows selecting an item which was popped earlier or to insert an arbitrary reference or revision without first pushing it onto the stack.

When reading the revision from the minibuffer, then it might not be possible to guess the correct repository. When this command is called inside a repository (e.g., while composing a commit message), then that repository is used. Otherwise (e.g., while composing an email) then the repository recorded for the top element of the stack is used (even though we insert another revision). If not called inside a repository and with an empty stack, or with two prefix arguments, then read the repository in the minibuffer too.

User Option: magit-pop-revision-stack-format

This option controls how the command magit-pop-revision-stack inserts a revision into the current buffer.

The entries on the stack have the format (HASH TOPLEVEL) and this option has the format (POINT-FORMAT EOB-FORMAT INDEX-REGEXP), all of which may be nil or a string (though either one of EOB-FORMAT or POINT-FORMAT should be a string, and if INDEX-REGEXP is non-nil, then the two formats should be too).

First INDEX-REGEXP is used to find the previously inserted entry, by searching backward from point. The first submatch must match the index number. That number is incremented by one, and becomes the index number of the entry to be inserted. If you don’t want to number the inserted revisions, then use nil for INDEX-REGEXP.

If INDEX-REGEXP is non-nil then both POINT-FORMAT and EOB-FORMAT should contain \"%N\", which is replaced with the number that was determined in the previous step.

Both formats, if non-nil and after removing %N, are then expanded using git show --format=FORMAT ... inside TOPLEVEL.

The expansion of POINT-FORMAT is inserted at point, and the expansion of EOB-FORMAT is inserted at the end of the buffer (if the buffer ends with a comment, then it is inserted right before that).


Next: Commit Pseudo Headers, Up: Editing Commit Messages   [Contents][Index]