10.3 Refreshing Buffers

All commands that create a new Magit buffer or change what is being displayed in an existing buffer do so by calling magit-mode-setup. Among other things, that function sets the buffer local values of default-directory (to the top-level of the repository), magit-refresh-function, and magit-refresh-args.

Buffers are refreshed by calling the function that is the local value of magit-refresh-function (a function named magit-*-refresh-buffer, where * may be something like diff) with the value of magit-refresh-args as arguments.

Macro: magit-mode-setup buffer switch-func mode refresh-func &optional refresh-args

This function displays and selects BUFFER, turns on MODE, and refreshes a first time.

This function displays and optionally selects BUFFER by calling magit-mode-display-buffer with BUFFER, MODE and SWITCH-FUNC as arguments. Then it sets the local value of magit-refresh-function to REFRESH-FUNC and that of magit-refresh-args to REFRESH-ARGS. Finally it creates the buffer content by calling REFRESH-FUNC with REFRESH-ARGS as arguments.

All arguments are evaluated before switching to BUFFER.

Function: magit-mode-display-buffer buffer mode &optional switch-function

This function display BUFFER in some window and select it. BUFFER may be a buffer or a string, the name of a buffer. The buffer is returned.

Unless BUFFER is already displayed in the selected frame, store the previous window configuration as a buffer local value, so that it can later be restored by magit-mode-bury-buffer.

The buffer is displayed and selected using SWITCH-FUNCTION. If that is nil then pop-to-buffer is used if the current buffer’s major mode derives from magit-mode. Otherwise switch-to-buffer is used.

Variable: magit-refresh-function

The value of this buffer-local variable is the function used to refresh the current buffer. It is called with magit-refresh-args as arguments.

Variable: magit-refresh-args

The list of arguments used by magit-refresh-function to refresh the current buffer. magit-refresh-function is called with these arguments.

The value is usually set using magit-mode-setup, but in some cases it’s also useful to provide commands which can change the value. For example, the magit-diff-refresh-popup can be used to change any of the arguments used to display the diff, without having to specify again which differences should be shown. magit-diff-more-context, magit-diff-less-context, and magit-diff-default-context change just the -U<N> argument. In both case this is done by changing the value of this variable and then calling this magit-refresh-function.