10.2.3 Matching Sections

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

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

Function: magit-section-ident section

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

Function: magit-get-section ident &optional root

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.

• [CLASS...]

  matches if the section’s class is the same as the first CLASS or a subclass of that; the section’s parent class matches the second CLASS; and so on.

• [* CLASS...]

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

• CLASS

  matches if the section’s class is the same as CLASS or a subclass of that; regardless of the classes of the parent sections.

Each CLASS should be a class symbol, identifying a class that derives from magit-section. For backward compatibility CLASS can also be a "type symbol". A section matches such a symbol if the value of its type slot is eq. If a type symbol has an entry in magit--section-type-alist, then a section also matches that type if its class is a subclass of the class that corresponds to the type as per that alist.

Note that it is not necessary to specify the complete section lineage as printed by magit-describe-section-briefly, unless of course you want to be that precise.

Function: magit-section-value-if condition &optional section

If the section at point matches CONDITION, then return its value.

If optional SECTION is non-nil then test whether that matches instead. If there is no section at point and SECTION is nil, then return nil. If the section does not match, 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.