magit

name: magit description: Expert guide for Magit architecture, section API, buffer management, process handling, and mode patterns. Use when implementing or debugging magit-section, magit-mode, magit-insert-section, magit-process, or git porcelain UI.

Magit Expert

This skill provides comprehensive guidance for working with Magit — the Emacs Git porcelain — based on Magit 4.x source code and real-world usage in packages like beads.el and Forge.

When to Use This Skill

Invoke this skill when:

• Working with magit-section, magit-insert-section, section navigation
• Deriving from magit-mode or magit-section-mode
• Implementing buffer refresh patterns (magit-refresh)
• Using magit-process / process-file for Git execution
• Integrating with the Magit status buffer via hooks
• Building keyboard-driven UI in the Magit style
• Adding sections to magit-status-sections-hook

Core Architecture

special-mode
  └── magit-section-mode   (read-only, section navigation)
        └── magit-mode     (abstract, buffer lifecycle)
              ├── magit-status-mode
              ├── magit-log-mode
              ├── magit-diff-mode
              ├── magit-refs-mode
              └── (your-derived-mode)

Key files: magit-section.el, magit-mode.el, magit-process.el, magit-status.el, magit-git.el

Section API (magit-section.el)

Core Section Class

magit-section is an EIEIO class with key slots:

Sections are stored as the magit-section text property on buffer text.

Creating Sections

;; The primary macro for creating sections
(magit-insert-section (TYPE &optional VALUE HIDE)
  ;; Insert heading text here
  (magit-insert-heading "Section Title")
  ;; Insert child sections or content
  (dolist (item items)
    (magit-insert-section (item-type item)
      (insert (format "%s\n" item)))))

Parameters:

• TYPE — symbol naming this section type (e.g., 'file, 'hunk, 'commit)
• VALUE — arbitrary data stored in section's value slot
• HIDE — non-nil to start collapsed

Key pattern: always call magit-insert-heading before child content:

(magit-insert-section (mytype myvalue)
  (magit-insert-heading
    (propertize "Title" 'face 'magit-section-heading)
    ": "
    (propertize myvalue 'face 'magit-hash))
  ;; Child sections follow here
  (insert "child content\n"))

Section Retrieval

(magit-section-at)               ; Section at point (via text property)
(magit-current-section)          ; Section at point (context-menu aware)
(oref (magit-current-section) type)   ; Get section type
(oref (magit-current-section) value)  ; Get section value

;; Type checking
(magit-section-match 'file)           ; Is current section of type file?
(magit-section-match '(file hunk))    ; Match type hierarchy

Section Navigation Keys

Visibility Customization

;; Set initial visibility per section type
(setq magit-section-initial-visibility-alist
      '((stashes . hide)
        (upstream . show)))

;; Cache visibility across refreshes
(setq magit-section-cache-visibility t)

;; Custom visibility hook
(add-hook 'magit-section-set-visibility-hook #'my-visibility-fn)

Section Highlighting

Faces for styling:

• magit-section-highlight — Background of current section
• magit-section-heading — Section headings
• magit-section-heading-selection — Selected heading
• magit-section-secondary-heading — Secondary headings

Buffer Management (magit-mode.el)

Mode Setup

magit-section-mode sets up:

• buffer-read-only: t — No accidental edits
• buffer-disable-undo — Performance
• truncate-lines: t — No line wrapping
• Custom magit-section-mode-map

Creating Magit Buffers

(defvar-local my-buffer-var nil
  "Buffer-local context variable.")

(define-derived-mode my-magit-mode magit-section-mode "My Mode"
  "Description."
  :group 'my-group
  (setq-local revert-buffer-function #'my-refresh-buffer))

(defun my-display ()
  "Open my buffer."
  (interactive)
  (let ((buf (get-buffer-create (format "*my-buffer[%s]*"
                                        (project-root (project-current))))))
    (with-current-buffer buf
      (my-magit-mode)
      (my-refresh-buffer))
    (pop-to-buffer buf)))

(defun my-refresh-buffer (&rest _)
  "Refresh my buffer."
  (let ((inhibit-read-only t))
    (erase-buffer)
    (my-insert-sections)))

Buffer Naming

Magit uses format strings for buffer names:

(setq magit-buffer-name-format "*magit: %M%V*")
;; %M = mode name (e.g., "magit-status")
;; %V = value context (e.g., repo path)
;; %t = top-level directory

Display Strategies

;; Configurable display function
(setq magit-display-buffer-function
      #'magit-display-buffer-traditional)

;; Alternatives:
;; magit-display-buffer-same-window-except-diff-v1
;; magit-display-buffer-fullframe-status-v1

;; Low-level display
(magit-display-buffer buffer)

Refresh Mechanism

;; Trigger refresh
(magit-refresh)              ; Refresh current magit buffer
(magit-refresh-buffer buf)   ; Refresh specific buffer

;; Hooks (in order of execution)
magit-pre-refresh-hook       ; Before refresh (e.g., save buffers)
magit-refresh-buffer-hook    ; Per-buffer on each refresh
magit-post-refresh-hook      ; After refresh (e.g., auto-revert)
magit-create-buffer-hook     ; On first creation only

Status Buffer Sections Hook

;; Add your section to magit-status
(magit-add-section-hook 'magit-status-sections-hook
                        #'my-insert-section
                        nil   ; Append (vs position)
                        t)    ; Local to this buffer

;; Hook functions insert sections into status buffer
(defun my-insert-section ()
  "Insert my section into magit-status."
  (when (my-relevant-p)
    (magit-insert-section (my-type)
      (magit-insert-heading "My Section")
      (dolist (item (my-items))
        (magit-insert-section (my-item item)
          (insert (format "  %s\n" item)))))))

Built-in Status Sections

The magit-status-sections-hook runs these by default (in order):

• magit-insert-status-headers — Branch, remote, tracking info
• magit-insert-merge-log — Active merge state
• magit-insert-rebase-sequence — Active rebase state
• magit-insert-am-sequence — Active git am state
• magit-insert-sequencer-sequence — Cherry-pick/revert
• magit-insert-bisect-output — Bisect state
• magit-insert-untracked-files — Untracked files section
• magit-insert-unstaged-changes — Unstaged diffs
• magit-insert-staged-changes — Staged diffs
• magit-insert-stashes — Stash list
• magit-insert-unpushed-to-pushremote — Unpushed commits
• magit-insert-unpushed-to-upstream — Upstream unpushed

Process Handling (magit-process.el)

Tramp-Compatible Git Execution

Critical rule: Always use process-file, never call-process. This enables remote execution via Tramp.

;; Low-level: synchronous, captures output
(magit-call-git "commit" "-m" "message")

;; Higher-level: synchronous with error handling
(magit-git "log" "--oneline" "-10")

;; Async: runs in background, logs to process buffer
(magit-run-git-async "fetch" "--prune")

;; With environment
(let ((process-environment (cons "GIT_EDITOR=true"
                                 process-environment)))
  (magit-call-git "rebase" "--continue"))

Process Output Buffer

;; Get the process log buffer
(magit-process-buffer)

;; Control logging
(setq magit-process-log-max 32)          ; Keep last N sections
(setq magit-process-popup-time -1)        ; Never auto-show (-1)
                                          ; Or: seconds to wait

;; ANSI colors in process output
(setq magit-process-apply-ansi-colors t)

Error Handling

;; git exit code → signal error
(magit-call-git "commit") ; Raises error on non-zero exit

;; Custom error display
(setq magit-process-display-mode-line-error t)
(setq magit-process-error-tooltip-max-lines 20)

process-file vs call-process

;; For Tramp compatibility in your own code:
(process-file "git" nil t nil "log" "--oneline")
;;  ^program   ^stdin ^output ^display ^args...

;; NOT this (breaks on remote files):
(call-process "git" nil t nil "log" "--oneline")

When working with Tramp-hosted files, strip the Tramp prefix for paths passed to git:

(file-local-name default-directory)  ; "/ssh:host:/path" → "/path"

Transient Integration

Magit uses the transient library for all interactive menus. See the emacs-transient skill for full documentation.

Key Patterns from Magit

;; Magit's main dispatch
(transient-define-prefix magit-dispatch ()
  "Invoke a Magit command from a list of available commands."
  :man-page "git"
  ["Transient and dwim commands"
   [("A" "Apply"          magit-cherry-pick)
    ("b" "Branch"         magit-branch)
    ("c" "Commit"         magit-commit)]])

;; Context-aware suffix: checks section type
(transient-define-suffix magit-stage-file (file)
  "Stage FILE."
  (interactive
   (list (magit-read-file "Stage file")))
  (magit-run-git "add" "--" file))

Augmenting Existing Magit Transients

;; Add to magit-dispatch
(transient-append-suffix 'magit-dispatch "!"
  '("X" "My command" my-magit-command))

;; Add to magit-fetch
(transient-append-suffix 'magit-fetch "-p"
  '("-t" "Fetch tags" "--tags"))

Keymap Patterns

;; Derive from magit-section-mode-map
(defvar my-mode-map
  (let ((map (make-sparse-keymap)))
    (set-keymap-parent map magit-section-mode-map)
    (define-key map (kbd "RET") #'my-visit-section)
    (define-key map (kbd "o")   #'my-browse-section)
    (define-key map (kbd "g")   #'my-refresh-buffer)
    map)
  "Keymap for `my-mode'.")

;; Section-type-specific keymaps
(defvar my-item-section-map
  (let ((map (make-sparse-keymap)))
    (set-keymap-parent map magit-section-mode-map)
    (define-key map (kbd "d") #'my-delete-item)
    map))

;; Register section-type keymap
(magit-insert-section (my-item value nil my-item-section-map)
  (insert (format "%s\n" value)))

Common Patterns

Context-Aware Commands

(defun my-visit-thing ()
  "Visit the thing at point."
  (interactive)
  (let ((section (magit-current-section)))
    (pcase (oref section type)
      ('my-issue (my-visit-issue (oref section value)))
      ('my-pr    (my-visit-pr    (oref section value)))
      (_         (user-error "No thing at point")))))

Inserting Headers

(defun my-insert-headers ()
  "Insert header information."
  (magit-insert-section (my-headers)
    (magit-insert-heading "Status")
    (insert (format "%-10s %s\n"
                    (propertize "Branch:" 'face 'magit-header-line-key)
                    (propertize (magit-get-current-branch)
                                'face 'magit-branch-local)))))

Section with Clickable Items

(defun my-insert-items (items)
  "Insert ITEMS as clickable sections."
  (magit-insert-section (my-list)
    (magit-insert-heading
      (format "Items (%d)" (length items)))
    (dolist (item items)
      (magit-insert-section (my-item item)
        (insert
         (concat
          (propertize (my-item-id item)   'face 'magit-hash)
          " "
          (propertize (my-item-title item) 'face 'magit-section-secondary-heading)
          "\n"))))))

Integration with project.el

;; Discover .mydir from project root
(defun my-find-config ()
  "Find config starting from project root."
  (when-let ((root (magit-toplevel)))
    (locate-dominating-file root ".mydir")))

Important Notes

1. Read-only buffers: Use (let ((inhibit-read-only t)) ...) when inserting
2. Section text properties: Magit stores sections via magit-section text property
3. Buffer-local state: Use defvar-local for per-buffer context
4. Refresh pattern: erase-buffer + re-insert sections (don't patch in place)
5. Section hierarchy: magit-insert-heading must come before child magit-insert-section calls
6. process-file: Always for git commands — never call-process or shell-command

Common Gotchas

1. Missing magit-insert-heading: Content before it is part of the heading, not body
2. Wrong section keymap: Set the keymap as 4th arg to magit-insert-section
3. Forgetting inhibit-read-only: Buffer is read-only — wrap inserts
4. Not erasing before refresh: Old content persists underneath new
5. Calling call-process for git: Breaks Tramp — use process-file or magit-call-git

Version Notes

• Magit 4.x: Requires Emacs 26.1+, transient 0.7.0+
• Section API stable since Magit 3.x
• magit-section-mode is the new base (was magit-mode in older versions)