10.2.3 Matching Sections

M-x magit-describe-section     (magit-describe-section)

Show information about the section at point. This command is intended for debugging purposes.

Function: magit-section-ident

Return an unique identifier for SECTION. The return value has the form ((TYPE . VALUE)...).

Function: magit-get-section

Return the section identified by IDENT. IDENT has to be a list as returned by magit-section-ident.

Function: magit-section-match condition &optional section

Return t if SECTION matches CONDITION. SECTION defaults to the section at point. If SECTION is not specified and there also is no section at point, then return nil.

CONDITION can take the following forms:

• (CONDITION...)

  matches if any of the CONDITIONs matches.

• [TYPE...]

  matches if the first TYPE matches the type of the section, the second matches that of its parent, and so on.

• [* TYPE...]

  matches sections that match [TYPE…] and also recursively all their child sections.

• TYPE

  matches sections of TYPE regardless of the types of the parent sections.

Each TYPE is a symbol. Note that it is not necessary to specify all TYPEs up to the root section as printed by magit-describe-type, unless of course you want to be that precise.

Function: magit-section-when condition &rest body

If the section at point matches CONDITION evaluate BODY.

If the section matches, then evaluate BODY forms sequentially with it bound to the section and return the value of the last form. If there are no BODY forms, then return the value of the section. If the section does not match or if there is no section at point then return nil.

See magit-section-match for the forms CONDITION can take.

Function: magit-section-case &rest clauses

Choose among clauses on the type of the section at point.

Each clause looks like (CONDITION BODY…). The type of the section is compared against each CONDITION; the BODY forms of the first match are evaluated sequentially and the value of the last form is returned. Inside BODY the symbol it is bound to the section at point. If no clause succeeds or if there is no section at point return nil.

See magit-section-match for the forms CONDITION can take. Additionally a CONDITION of t is allowed in the final clause and matches if no other CONDITION match, even if there is no section at point.

Variable: magit-root-section

The root section in the current buffer. All other sections are descendants of this section. The value of this variable is set by magit-insert-section and you should never modify it.

For diff related sections a few additional tools exist.

Function: magit-diff-type &optional section

Return the diff type of SECTION.

The returned type is one of the symbols staged, unstaged, committed, or undefined. This type serves a similar purpose as the general type common to all sections (which is stored in the type slot of the corresponding magit-section struct) but takes additional information into account. When the SECTION isn’t related to diffs and the buffer containing it also isn’t a diff-only buffer, then return nil.

Currently the type can also be one of tracked and untracked, but these values are not handled explicitly in every place they should be. A possible fix could be to just return nil here.

The section has to be a diff or hunk section, or a section whose children are of type diff. If optional SECTION is nil, return the diff type for the current section. In buffers whose major mode is magit-diff-mode SECTION is ignored and the type is determined using other means. In magit-revision-mode buffers the type is always committed.

Function: magit-diff-scope &optional section strict

Return the diff scope of SECTION or the selected section(s).

A diff’s "scope" describes what part of a diff is selected, it is a symbol, one of region, hunk, hunks, file, files, or list. Do not confuse this with the diff "type", as returned by magit-diff-type.

If optional SECTION is non-nil, then return the scope of that, ignoring the sections selected by the region. Otherwise return the scope of the current section, or if the region is active and selects a valid group of diff related sections, the type of these sections, i.e. hunks or files. If SECTION (or if the current section that is nil) is a hunk section and the region starts and ends inside the body of a that section, then the type is region.

If optional STRICT is non-nil then return nil if the diff type of the section at point is untracked or the section at point is not actually a diff but a diffstat section.