Insert a section at point.
TYPE is the section type, a symbol. Many commands that act on the
current section behave differently depending on that type. Also if
a variable magit-TYPE-section-map exists, then use that as the
text-property keymap of all text belonging to the section (but this
may be overwritten in subsections). TYPE can also have the form
(eval FORM) in which case FORM is evaluated at runtime.
Optional VALUE is the value of the section, usually a string that is required when acting on the section.
When optional HIDE is non-nil collapse the section body by default,
i.e., when first creating the section, but not when refreshing the
buffer. Otherwise, expand it by default. This can be overwritten using
magit-section-set-visibility-hook. When a section is recreated
during a refresh, then the visibility of predecessor is inherited
and HIDE is ignored (but the hook is still honored).
BODY is any number of forms that actually insert the section’s heading and body. Optional NAME, if specified, has to be a symbol, which is then bound to the struct of the section being inserted.
Before BODY is evaluated the start of the section object is set to
the value of point and after BODY was evaluated its end is set to
the new value of point; BODY is responsible for moving point
forward.
If it turns out inside BODY that the section is empty, then
magit-cancel-section can be used to abort and remove all traces of
the partially inserted section. This can happen when creating a
section by washing Git’s output and Git didn’t actually output
anything this time around.
Insert the heading for the section currently being inserted.
This function should only be used inside magit-insert-section.
When called without any arguments, then just set the content slot of
the object representing the section being inserted to a marker at
point. The section should only contain a single line when this
function is used like this.
When called with arguments ARGS, which have to be strings, then
insert those strings at point. The section should not contain any
text before this happens and afterwards it should again only contain
a single line. If the face property is set anywhere inside any of
these strings, then insert all of them unchanged. Otherwise use the
magit-section-heading face for all inserted text.
The content property of the section struct is the end of the heading
(which lasts from start to content) and the beginning of the body
(which lasts from content to end). If the value of content is nil,
then the section has no heading and its body cannot be collapsed.
If a section does have a heading then its height must be exactly one
line, including a trailing newline character. This isn’t enforced;
you are responsible for getting it right. The only exception is
that this function does insert a newline character if necessary.
Cancel the section currently being inserted. This exits the
innermost call to magit-insert-section and removes all traces of
what has already happened inside that call.
Define an interactive function to go to section SYM. TITLE is the displayed title of the section.
Return the section at point.
Return a list of the selected sections.
When the region is active and constitutes a valid section
selection, then return a list of all selected sections. This is
the case when the region begins in the heading of a section and
ends in the heading of the same section or in that of a sibling
section. If optional MULTIPLE is non-nil, then the region cannot
begin and end in the same section.
When the selection is not valid, then return nil. In this case,
most commands that can act on the selected sections will instead
act on the section at point.
When the region looks like it would in any other buffer then
the selection is invalid. When the selection is valid then the
region uses the magit-section-highlight face. This does not
apply to diffs where things get a bit more complicated, but even
here if the region looks like it usually does, then that’s not
a valid selection as far as this function is concerned.
If optional CONDITION is non-nil, then the selection not only
has to be valid; all selected sections additionally have to match
CONDITION, or nil is returned. See magit-section-match for the
forms CONDITION can take.
Return a list of the values of the selected sections.
Return the values that themselves would be returned by
magit-region-sections (which see).
Show information about the section at point. This command is intended for debugging purposes.
Return an unique identifier for SECTION. The return value has the
form ((TYPE . VALUE)...).
Return the section identified by IDENT. IDENT has to be a list as
returned by magit-section-ident.
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.
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.
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.
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.
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.
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.