Next: Section Hooks, Previous: Section Movement, Up: Sections [Contents][Index]
Magit provides many commands for changing the visibility of sections, but all you need to get started are the next two.
magit-section-toggle) ¶Toggle the visibility of the body of the current section.
magit-section-cycle) ¶magit-section-cycle)Cycle the visibility of current section and its children.
If this command is invoked using C-<tab> and that is globally bound
to tab-next, then this command pivots to behave like that command,
and you must instead use C-c TAB to cycle section visibility.
If you would like to keep using C-<tab> to cycle section visibility
but also want to use tab-bar-mode, then you have to prevent that mode
from using this key and instead bind another key to tab-next. Because
tab-bar-mode does not use a mode map but instead manipulates the
global map, this involves advising tab-bar--define-keys.
magit-section-cycle-diffs) ¶Cycle the visibility of diff-related sections in the current buffer.
magit-section-cycle-global) ¶Cycle the visibility of all sections in the current buffer.
magit-section-show-level-1) ¶magit-section-show-level-2)magit-section-show-level-3)magit-section-show-level-4)Show sections surrounding the current section up to level N.
magit-section-show-level-1-all) ¶magit-section-show-level-2-all)magit-section-show-level-3-all)magit-section-show-level-4-all)Show all sections up to level N.
Some functions, which are used to implement the above commands, are also exposed as commands themselves. By default no keys are bound to these commands, as they are generally perceived to be much less useful. But your mileage may vary.
Show the body of the current section.
Hide the body of the current section.
Recursively show headings of children of the current section. Only show the headings. Previously shown text-only bodies are hidden.
Recursively show the bodies of children of the current section. With a prefix argument show children down to the level of the current section, and hide deeper children.
Recursively hide the bodies of children of the current section.
Toggle visibility of bodies of children of the current section.
When a buffer is first created then some sections are shown expanded
while others are not. This is hard coded. When a buffer is refreshed
then the previous visibility is preserved. The initial visibility of
certain sections can also be overwritten using the hook
magit-section-set-visibility-hook.
This options can be used to override the initial visibility of sections. In the future it will also be used to define the defaults, but currently a section’s default is still hardcoded.
The value is an alist. Each element maps a section type or lineage
to the initial visibility state for such sections. The state has to
be one of show or hide, or a function that returns one of these
symbols. A function is called with the section as the only argument.
Use the command magit-describe-section-briefly to determine a
section’s lineage or type. The vector in the output is the section
lineage and the type is the first element of that vector. Wildcards
can be used, see magit-section-match.
This option controls for which sections the previous visibility state should be restored if a section disappears and later appears again. The value is a boolean or a list of section types. If t, then the visibility of all sections is cached. Otherwise this is only done for sections whose type matches one of the listed types.
This requires that the function magit-section-cached-visibility is
a member of magit-section-set-visibility-hook.
This hook is run when first creating a buffer and also when refreshing an existing buffer, and is used to determine the visibility of the section currently being inserted.
Each function is called with one argument, the section being
inserted. It should return hide or show, or to leave the visibility
undefined nil. If no function decides on the visibility and the
buffer is being refreshed, then the visibility is preserved; or if
the buffer is being created, then the hard coded default is used.
Usually this should only be used to set the initial visibility but
not during refreshes. If magit-insert-section--oldroot is non-nil,
then the buffer is being refreshed and these functions should
immediately return nil.
This option controls whether and how to indicate that a section can be expanded/collapsed.
If nil, then no visibility indicators are shown. Otherwise the value has to have one of these two forms:
(EXPANDABLE-BITMAP . COLLAPSIBLE-BITMAP)
Both values have to be variables whose values are fringe bitmaps. In this case every section that can be expanded or collapsed gets an indicator in the left fringe.
To provide extra padding around the indicator, set
left-fringe-width in magit-mode-hook, e.g.:
(add-hook 'magit-mode-hook (lambda ()
(setq left-fringe-width 20)))
(STRING . BOOLEAN)
In this case STRING (usually an ellipsis) is shown at the end of the heading of every collapsed section. Expanded sections get no indicator. The cdr controls whether the appearance of these ellipsis take section highlighting into account. Doing so might potentially have an impact on performance, while not doing so is kinda ugly.
Next: Section Hooks, Previous: Section Movement, Up: Sections [Contents][Index]