4.1.1 Switching Buffers

Function: magit-display-buffer buffer

This function is a wrapper around display-buffer and is used to display any Magit buffer. It displays BUFFER in some window and, unlike display-buffer, also selects that window, provided magit-display-buffer-noselect is nil. It also runs the hooks mentioned below.

Variable: magit-display-buffer-noselect

When this is non-nil, then magit-display-buffer only displays the buffer but forgoes also selecting the window. This variable should not be set globally, it is only intended to be let-bound, by code that automatically updates "the other window". This is used for example when the revision buffer is updated when you move inside the log buffer.

User Option: magit-display-buffer-function

The function specified here is called by magit-display-buffer with one argument, a buffer, to actually display that buffer. This function should call display-buffer with that buffer as first and a list of display actions as second argument.

Magit provides several functions, listed below, that are suitable values for this option. If you want to use different rules, then a good way of doing that is to start with a copy of one of these functions and then adjust it to your needs.

Instead of using a wrapper around display-buffer, that function itself can be used here, in which case the display actions have to be specified by adding them to display-buffer-alist instead.

To learn about display actions, see (elisp)Choosing a Window for Display.

Function: magit-display-buffer-traditional buffer

This function is the current default value of the option magit-display-buffer-function. Before that option and this function were added, the behavior was hard-coded in many places all over the code base but now all the rules are contained in this one function (except for the "noselect" special case mentioned above).

Function: magit-display-buffer-same-window-except-diff-v1

This function displays most buffers in the currently selected window. If a buffer’s mode derives from magit-diff-mode or magit-process-mode, it is displayed in another window.

Function: magit-display-buffer-fullframe-status-v1

This function fills the entire frame when displaying a status buffer. Otherwise, it behaves like magit-display-buffer-traditional.

Function: magit-display-buffer-fullframe-status-topleft-v1

This function fills the entire frame when displaying a status buffer. It behaves like magit-display-buffer-fullframe-status-v1 except that it displays buffers that derive from magit-diff-mode or magit-process-mode to the top or left of the current buffer rather than to the bottom or right. As a result, Magit buffers tend to pop up on the same side as they would if magit-display-buffer-traditional were in use.

Function: magit-display-buffer-fullcolumn-most-v1

This function displays most buffers so that they fill the entire height of the frame. However, the buffer is displayed in another window if (1) the buffer’s mode derives from magit-process-mode, or (2) the buffer’s mode derives from magit-diff-mode, provided that the mode of the current buffer derives from magit-log-mode or magit-cherry-mode.

User Option: magit-pre-display-buffer-hook

This hook is run by magit-display-buffer before displaying the buffer.

Function: magit-save-window-configuration

This function saves the current window configuration. Later when the buffer is buried, it may be restored by magit-restore-window-configuration.

User Option: magit-post-display-buffer-hook

This hook is run by magit-display-buffer after displaying the buffer.

Function: magit-maybe-set-dedicated

This function remembers if a new window had to be created to display the buffer, or whether an existing window was reused. This information is later used by magit-mode-quit-window, to determine whether the window should be deleted when its last Magit buffer is buried.