4.2.3 Section Hooks

Which sections are inserted into certain buffers is controlled with hooks. This includes the status and the refs buffers. For other buffers, e.g. log and diff buffers, this is not possible. The command magit-describe-section can be used to see which hook (if any) was responsible for inserting the section at point.

For buffers whose sections can be customized by the user, a hook variable called magit-TYPE-sections-hook exists. This hook should be changed using magit-add-section-hook. Avoid using add-hooks or the Custom interface.

The various available section hook variables are described later in this manual along with the appropriate "section inserter functions".

Function: magit-add-section-hook hook function &optional at append local

Add the function FUNCTION to the value of section hook HOOK.

Add FUNCTION at the beginning of the hook list unless optional APPEND is non-nil, in which case FUNCTION is added at the end. If FUNCTION already is a member then move it to the new location.

If optional AT is non-nil and a member of the hook list, then add FUNCTION next to that instead. Add before or after AT, or replace AT with FUNCTION depending on APPEND. If APPEND is the symbol replace, then replace AT with FUNCTION. For any other non-nil value place FUNCTION right after AT. If nil, then place FUNCTION right before AT. If FUNCTION already is a member of the list but AT is not, then leave FUNCTION where ever it already is.

If optional LOCAL is non-nil, then modify the hook’s buffer-local value rather than its global value. This makes the hook local by copying the default value. That copy is then modified.

HOOK should be a symbol. If HOOK is void, it is first set to nil. HOOK’s value must not be a single hook function. FUNCTION should be a function that takes no arguments and inserts one or multiple sections at point, moving point forward. FUNCTION may choose not to insert its section(s), when doing so would not make sense. It should not be abused for other side-effects.

To remove a function from a section hook, use remove-hook.