Function: magit-insert-heading

magit-insert-heading is a byte-compiled function defined in magit-section.el.

Signature

(magit-insert-heading [CHILD-COUNT] &rest STRINGS)

Documentation

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, or nil, 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 object is the end of the heading (which lasts from start to content) and the beginning of the 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

If provided, optional CHILD-COUNT must evaluate to an integer or boolean. If t, then the count is determined once the children have been inserted, using magit-insert-child-count (which see). For historic reasons, if the heading ends with ":", the count is substituted for that, at this time as well. If magit-section-show-child-count is nil, no counts are inserted

Source Code

;; Defined in ~/.emacs.d/elpa/magit-section-20260330.1102/magit-section.el
(defun magit-insert-heading (&rest args)
  "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, or
nil, 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 object is the end of the
heading (which lasts from `start' to `content') and the beginning
of the 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

If provided, optional CHILD-COUNT must evaluate to an integer or
boolean.  If t, then the count is determined once the children have been
inserted, using `magit-insert-child-count' (which see).  For historic
reasons, if the heading ends with \":\", the count is substituted for
that, at this time as well.  If `magit-section-show-child-count' is nil,
no counts are inserted

\n(fn [CHILD-COUNT] &rest STRINGS)"
  (declare (indent defun))
  (when args
    (let ((count (and (or (integerp (car args))
                          (booleanp (car args)))
                      (pop args)))
          (heading (apply #'concat args)))
      (insert (if (or (text-property-not-all 0 (length heading)
                                             'font-lock-face nil heading)
                      (text-property-not-all 0 (length heading)
                                             'face nil heading))
                  heading
                (propertize heading 'font-lock-face 'magit-section-heading)))
      (when (and count magit-section-show-child-count)
        (insert (propertize (format " (%s)" count)
                            'font-lock-face 'magit-section-child-count)))))
  (unless (bolp)
    (insert ?\n))
  (when (fboundp 'magit-maybe-make-margin-overlay)
    (magit-maybe-make-margin-overlay))
  (oset magit-insert-section--current content
        (if magit-section-inhibit-markers (point) (point-marker))))