// A guide to using magit-section for building collapsible, hierarchical buffer UIs in Emacs.
Clojure library for spawning sub-processes and shell operations
REPL-friendly data visualization and literate programming for Clojure with Kindly convention
Pure Clojure/Script logging library with flexible configuration and powerful features
Django-inspired HTML templating system for Clojure with filters, tags, and template inheritance
Structured logging and telemetry for Clojure/Script with tracing and performance monitoring
Emacs Lisp package development standards and conventions
| name | magit-section |
| description | A guide to using magit-section for building collapsible, hierarchical buffer UIs in Emacs. |
magit-section is Emacs's premier library for creating interactive, hierarchical buffer interfaces with collapsible sections. Originally extracted from Magit, it provides the foundation for building information-dense UIs that users can navigate and explore efficiently.
magit-section enables creation of buffers with tree-like, collapsible content organized into sections. Each section can contain nested child sections, custom keybindings, associated data, and responsive highlighting.
Key Characteristics:
Version: 4.2.0+ (January 2025) Repository: https://github.com/magit/magit License: GPL-3.0+
Sections are EIEIO objects with these slots:
type - Symbol identifying section kind (e.g., file, commit, hunk)value - Associated data (filename, commit SHA, etc.)start - Buffer position where section begins (includes heading)content - Buffer position where body content startsend - Buffer position where section endshidden - Visibility state (nil=visible, non-nil=hidden)children - List of child sectionsparent - Parent section referencekeymap - Section-specific key bindingswasher - Function for deferred content generationEvery magit-section buffer requires a single root section that spans the entire buffer. Sections form a tree hierarchy with proper nesting.
Sections can be:
Primary macro for section creation:
(magit-insert-section (type value &optional hide)
[HEADING-FORM]
BODY...)
Arguments:
type - Section type (symbol or (eval FORM))value - Data to store in section's value slothide - Initial visibility (nil=visible, t=hidden)Example:
(magit-insert-section (file "README.md")
(magit-insert-heading "README.md")
(insert "File contents here\n"))
Advanced Usage:
(magit-insert-section (commit commit-sha nil)
(magit-insert-heading
(format "%s %s"
(substring commit-sha 0 7)
(magit-commit-message commit-sha)))
;; Insert commit details
(magit-insert-section (diffstat commit-sha)
(insert (magit-format-diffstat commit-sha))))
Insert section heading with optional child count:
(magit-insert-heading &rest ARGS)
Example:
(magit-insert-heading
(format "Changes (%d)" (length file-list)))
Defer section body evaluation until first expansion:
(magit-insert-section-body
;; Expensive operations here
(insert (expensive-computation)))
Use for performance when sections are initially hidden.
Abort partial section creation:
(when (null items)
(magit-cancel-section))
Removes partial section from buffer and section tree.
(magit-section-forward) ; Next sibling or parent's next
(magit-section-backward) ; Previous sibling or parent
(magit-section-up) ; Parent section
(magit-section-forward-sibling) ; Next sibling
(magit-section-backward-sibling) ; Previous sibling
Keybindings:
n - Forwardp - Backward^ - Up to parentM-n - Forward siblingM-p - Backward siblingExample Navigation Hook:
(add-hook 'magit-section-movement-hook
(lambda ()
(when (eq (oref (magit-current-section) type) 'commit)
(message "On commit: %s"
(oref (magit-current-section) value)))))
(magit-section-toggle &optional SECTION) ; Toggle current/specified
(magit-section-show SECTION) ; Expand
(magit-section-hide SECTION) ; Collapse
Keybindings:
TAB - Toggle current sectionC-c TAB / C-<tab> - Cycle visibility states<backtab> - Cycle all top-level sections(magit-section-show-children SECTION &optional DEPTH)
(magit-section-hide-children SECTION)
(magit-section-show-headings SECTION)
Example:
;; Expand section and first level of children
(magit-section-show-children (magit-current-section) 1)
(magit-section-show-level-1) ; Show only top level
(magit-section-show-level-2) ; Show two levels
(magit-section-show-level-3) ; Show three levels
(magit-section-show-level-4) ; Show four levels
Keybindings:
1 / 2 / 3 / 4 - Show levels around current sectionM-1 / M-2 / M-3 / M-4 - Show levels for entire buffer(magit-section-cycle &optional SECTION) ; Current section
(magit-section-cycle-global) ; All sections
Cycles through: collapsed → expanded → children-collapsed → collapsed
(magit-current-section) ; Section at point
(magit-section-at &optional POS) ; Section at position
Example:
(let ((section (magit-current-section)))
(message "Type: %s, Value: %s"
(oref section type)
(oref section value)))
(magit-section-ident SECTION) ; Unique identifier
(magit-section-lineage SECTION) ; List of ancestor sections
(magit-section-hidden SECTION) ; Hidden or ancestor hidden?
(magit-section-content-p SECTION) ; Has body content?
Example:
(when (magit-section-content-p section)
(magit-section-show section))
(magit-section-match CONDITIONS &optional SECTION)
Conditions:
(TYPE VALUE) matches type and value[TYPE...] matches type hierarchyExample:
;; Check if section is a file
(when (magit-section-match 'file)
(message "Current section is a file"))
;; Match specific file
(when (magit-section-match '(file "README.md"))
(message "On README.md"))
;; Match hierarchy: hunk within file
(when (magit-section-match [file hunk])
(message "In a hunk within a file section"))
(magit-region-sections &optional CONDITION MULTIPLE)
Get sibling sections in active region.
Example:
(let ((selected-files (magit-region-sections 'file t)))
(dolist (section selected-files)
(message "Selected: %s" (oref section value))))
(magit-describe-section &optional SECTION INTERACTIVE)
(magit-describe-section-briefly &optional SECTION INTERACTIVE)
Display detailed section information for debugging.
Keybinding: C-h . (in magit-section buffers)
Define per-type keybindings using the :keymap class slot:
(defclass my-file-section (magit-section)
((keymap :initform 'my-file-section-map)))
(defvar my-file-section-map
(let ((map (make-sparse-keymap)))
(define-key map (kbd "RET") 'my-open-file)
(define-key map (kbd "d") 'my-delete-file)
map))
Example:
(magit-insert-section (my-file-section filename)
(magit-insert-heading filename)
(insert "Content..."))
;; RET and d keys work only on this section type
;; Highlight current section
(setq magit-section-highlight-current t)
;; Highlight region selection
(setq magit-section-highlight-selection t)
;; Show number of children in headings
(setq magit-section-show-child-count t)
;; Customize expansion/collapse indicators
(setq magit-section-visibility-indicators
'((expanded . "▼")
(collapsed . "▶")))
;; Cache visibility across refreshes
(setq magit-section-cache-visibility t)
;; Cache only specific section types
(setq magit-section-cache-visibility '(file commit))
;; Set initial visibility by type
(setq magit-section-initial-visibility-alist
'((stash . hide)
(untracked . hide)))
;; Disable line numbers in section buffers (default)
(setq magit-section-disable-line-numbers t)
(defun my-section-buffer ()
"Create a buffer with collapsible sections."
(interactive)
(let ((buf (get-buffer-create "*My Sections*")))
(with-current-buffer buf
(magit-section-mode)
(let ((inhibit-read-only t))
(erase-buffer)
(magit-insert-section (root)
(magit-insert-heading "My Data")
(magit-insert-section (files)
(magit-insert-heading "Files")
(dolist (file (directory-files default-directory))
(magit-insert-section (file file)
(insert file "\n"))))
(magit-insert-section (buffers)
(magit-insert-heading "Buffers")
(dolist (buf (buffer-list))
(magit-insert-section (buffer buf)
(insert (buffer-name buf) "\n")))))))
(pop-to-buffer buf)))
(defvar-local my-refresh-function nil)
(defun my-section-refresh ()
"Refresh current section buffer."
(interactive)
(when my-refresh-function
(let ((inhibit-read-only t)
(line (line-number-at-pos))
(col (current-column)))
(erase-buffer)
(funcall my-refresh-function)
(goto-char (point-min))
(forward-line (1- line))
(move-to-column col))))
(defun my-create-buffer ()
(let ((buf (get-buffer-create "*My Data*")))
(with-current-buffer buf
(magit-section-mode)
(setq my-refresh-function #'my-insert-content)
(local-set-key (kbd "g") #'my-section-refresh)
(my-section-refresh))
buf))
(defun my-insert-git-status ()
"Insert git status output as sections."
(magit-insert-section (status)
(magit-insert-heading "Git Status")
(let ((start (point)))
(call-process "git" nil t nil "status" "--short")
(save-restriction
(narrow-to-region start (point))
(goto-char start)
(while (not (eobp))
(let ((line-start (point))
(file (buffer-substring (+ (point) 3)
(line-end-position))))
(magit-insert-section (file file)
(forward-line 1))))))))
(defclass file-section (magit-section)
((keymap :initform 'file-section-map)))
(defvar file-section-map
(let ((map (make-sparse-keymap)))
(define-key map (kbd "RET") 'my-visit-file)
(define-key map (kbd "d") 'my-delete-file)
(define-key map (kbd "r") 'my-rename-file)
map))
(defun my-visit-file ()
"Visit file in current section."
(interactive)
(when-let ((section (magit-current-section)))
(when (eq (oref section type) 'file-section)
(find-file (oref section value)))))
(defun my-delete-file ()
"Delete file in current section."
(interactive)
(when-let ((section (magit-current-section)))
(when (and (eq (oref section type) 'file-section)
(yes-or-no-p (format "Delete %s? "
(oref section value))))
(delete-file (oref section value))
(my-section-refresh))))
(magit-insert-section (expensive-data)
(magit-insert-heading "Large Dataset")
(magit-insert-section-body
;; Only computed when section first expanded
(insert (format-large-dataset (compute-expensive-data)))))
(add-hook 'magit-section-set-visibility-hook
(lambda (section)
;; Keep commit details hidden by default
(when (eq (oref section type) 'commit-details)
'hide)))
(defun my-section-context-menu (menu section)
"Add items to context menu based on section."
(when (eq (oref section type) 'file)
(define-key menu [my-open]
'("Open File" . my-visit-file))
(define-key menu [my-delete]
'("Delete File" . my-delete-file)))
menu)
(add-hook 'magit-menu-alternative-section-hook
#'my-section-context-menu)
(defun my-file-browser (dir)
"Browse directory with collapsible sections."
(interactive "DDirectory: ")
(let ((buf (get-buffer-create (format "*Files: %s*" dir))))
(with-current-buffer buf
(magit-section-mode)
(let ((inhibit-read-only t)
(default-directory dir))
(erase-buffer)
(magit-insert-section (root)
(magit-insert-heading (format "Directory: %s" dir))
(my-insert-directory-tree "."))))
(pop-to-buffer buf)))
(defun my-insert-directory-tree (path)
"Recursively insert directory structure."
(dolist (file (directory-files path))
(unless (member file '("." ".."))
(let ((full-path (expand-file-name file path)))
(if (file-directory-p full-path)
(magit-insert-section (directory full-path)
(magit-insert-heading (concat file "/"))
(my-insert-directory-tree full-path))
(magit-insert-section (file full-path)
(insert file "\n")))))))
(defun my-log-viewer (log-file)
"View log file with collapsible sections per entry."
(interactive "fLog file: ")
(let ((buf (get-buffer-create "*Log Viewer*")))
(with-current-buffer buf
(magit-section-mode)
(let ((inhibit-read-only t))
(erase-buffer)
(magit-insert-section (root)
(magit-insert-heading (format "Log: %s" log-file))
(with-temp-buffer
(insert-file-contents log-file)
(goto-char (point-min))
(my-parse-log-entries)))))
(pop-to-buffer buf)))
(defun my-process-monitor ()
"Display running processes in sections."
(interactive)
(let ((buf (get-buffer-create "*Processes*")))
(with-current-buffer buf
(magit-section-mode)
(setq my-refresh-function #'my-insert-processes)
(local-set-key (kbd "g") #'my-section-refresh)
(local-set-key (kbd "k") #'my-kill-process)
(my-section-refresh))
(pop-to-buffer buf)))
(defun my-insert-processes ()
"Insert process list as sections."
(magit-insert-section (root)
(magit-insert-heading "Running Processes")
(dolist (proc (process-list))
(magit-insert-section (process proc)
(magit-insert-heading
(format "%s [%s]"
(process-name proc)
(process-status proc)))
(insert (format " Command: %s\n"
(mapconcat #'identity
(process-command proc)
" ")))))))
(defun my-config-inspector ()
"Inspect Emacs configuration in sections."
(interactive)
(let ((buf (get-buffer-create "*Config*")))
(with-current-buffer buf
(magit-section-mode)
(let ((inhibit-read-only t))
(erase-buffer)
(magit-insert-section (root)
(magit-insert-heading "Emacs Configuration")
(magit-insert-section (variables)
(magit-insert-heading "Custom Variables")
(dolist (var (sort (my-get-custom-vars) #'string<))
(magit-insert-section (variable var)
(magit-insert-heading (symbol-name var))
(insert (format " %S\n" (symbol-value var))))))
(magit-insert-section (features)
(magit-insert-heading "Loaded Features")
(dolist (feature features)
(magit-insert-section (feature feature)
(insert (format "%s\n" feature))))))))
(pop-to-buffer buf)))
;; Ensure root section exists
(defun my-ensure-root-section ()
(unless magit-root-section
(error "Buffer does not have a root section. Enable magit-section-mode.")))
;; Validate section type
(defun my-require-file-section ()
(let ((section (magit-current-section)))
(unless (eq (oref section type) 'file)
(user-error "Not on a file section"))))
(defun my-safe-section-value ()
"Get section value safely."
(when-let ((section (magit-current-section)))
(ignore-errors
(oref section value))))
Use magit-insert-section-body for expensive operations:
(magit-insert-section (large-data)
(magit-insert-heading "Large Dataset")
(magit-insert-section-body
;; Only executed when expanded
(my-compute-and-insert-large-data)))
Cache section visibility to preserve state across refreshes:
(setq magit-section-cache-visibility t)
;; Preserve visibility during refresh
(let ((magit-section-preserve-visibility t))
(my-refresh-buffer))
Minimize full buffer refreshes:
;; Update single section instead of full refresh
(defun my-update-section (section)
(save-excursion
(goto-char (oref section start))
(let ((inhibit-read-only t)
(hidden (oref section hidden)))
(delete-region (oref section start) (oref section end))
(my-insert-section-content section)
(when hidden
(magit-section-hide section)))))
Enable in buffers using sections:
(define-derived-mode my-viewer-mode magit-section-mode "MyViewer"
"Major mode for viewing data with sections."
(setq-local my-refresh-function #'my-insert-data))
Customize appearance:
(custom-set-faces
'(magit-section-heading ((t (:weight bold :foreground "blue"))))
'(magit-section-highlight ((t (:background "gray95")))))
Mouse clicks on section margins toggle visibility automatically.
;; Describe current section
(call-interactively #'magit-describe-section)
;; Brief description
(magit-describe-section-briefly)
(defun my-debug-section ()
"Debug current section structure."
(interactive)
(let ((section (magit-current-section)))
(message "Type: %S, Value: %S, Hidden: %S, Children: %d"
(oref section type)
(oref section value)
(oref section hidden)
(length (oref section children)))))
magit-section offers superior interactivity and data association:
;; outline-mode
(outline-hide-subtree)
;; magit-section equivalent
(magit-section-hide (magit-current-section))
Use magit-section for custom data not suited to org's document structure:
;; org-mode cycling
(org-cycle)
;; magit-section cycling
(magit-section-cycle)