render

Documentation

Overview

Package render — pretty-mode policy.

PrettyMode lets callers override the default TTY+env auto-detection that gates ANSI rendering across the CLI. The shared decision function (Decide) centralizes precedence so every command surface that prints markdown answers the question "should I emit ANSI?" the same way:

user explicit  >  env opt-out  >  TTY auto-detect  >  content gate

Adding a new pretty-render surface means: parse a PrettyMode from args (see cmd.parsePrettyFlag) and call Decide — never re-implement the gate inline.

Package render contains terminal-output helpers shared across CLI commands. The pretty markdown renderer (pretty.go) is the primary caller-facing API.

Package render exposes shared output renderers used by multiple gitmap commands. repotermblock.go implements the "human-readable per-repo summary" emitted by --output terminal across the scan, clone-from, clone-next, and probe commands.

One renderer in one place keeps the four commands byte-identical in their per-repo block — users learn the format once and rely on it being grep-able regardless of which command produced it.

Format (intentionally fixed-width labels for column alignment):

N. <repo-name>
   branch:    <branch> (<source>)
   from:      <originalURL>
   to:        <targetURL>
   command:   <cloneCommand>

Any field that is empty is rendered as the literal string "(unknown)" so the block always has the same shape — readers don't have to special-case missing lines, and a diff between two runs of the same command stays line-by-line aligned.

Index

• Constants
• func Decide(mode PrettyMode, isTTY, isMarkdown bool) bool
• func HighlightQuotes(s string) string
• func HighlightQuotesANSI(s string) string
• func Render(md string) string
• func RenderANSI(md string) string
• func RenderRepoTermBlock(w io.Writer, b RepoTermBlock) error
• func RenderRepoTermBlocks(w io.Writer, blocks []RepoTermBlock) error
• func StdoutIsTerminal() bool
• type PrettyMode
• type RepoTermBlock
  • func FromScanRecord(idx int, r model.ScanRecord) RepoTermBlock
  • func FromScanRecords(records []model.ScanRecord) []RepoTermBlock

Constants

const (
	TokYellowOpen  = "[Y]"
	TokYellowClose = "[/Y]"
	TokCyanOpen    = "[C]"
	TokCyanClose   = "[/C]"
	TokMutedOpen   = "[M]"
	TokMutedClose  = "[/M]"
)

Token sentinels used by Render() so unit tests can assert on a stable, ANSI-free string. RenderANSI swaps these for real escape codes.

const EnvNoPretty = "GITMAP_NO_PRETTY"

EnvNoPretty is the shared opt-out env var name. Mirrors the convention of NO_COLOR but scoped to gitmap's pretty markdown pipeline so users can disable ANSI rendering across `help`, `templates show`, and `changelog` with a single export.

Functions

func Decide

func Decide(mode PrettyMode, isTTY, isMarkdown bool) bool

Decide returns true when the caller should emit ANSI-rendered markdown.

Inputs:

• mode: caller-supplied tri-state (parsed from --pretty / --no-pretty);
• isTTY: whether stdout is connected to a real terminal;
• isMarkdown: whether the content is markdown at all (callers that never produce markdown can pass true to skip this gate).

Precedence (first match wins):

1. PrettyOff → false (explicit user opt-out trumps everything).
2. !isMarkdown → false (no point rendering plain text as markdown).
3. PrettyOn → true (explicit user opt-in trumps env / TTY).
4. EnvNoPretty=… → false (shared environment opt-out).
5. isTTY → true (auto-detect: render only on a real terminal).
6. otherwise → false (pipes / redirects stay byte-faithful).

func HighlightQuotes

func HighlightQuotes(s string) string

HighlightQuotes wraps every "double-quoted span" in cyan tokens (TokCyanOpen/TokCyanClose). Single quotes are left untouched (they're usually apostrophes). The output uses sentinel tokens — call HighlightQuotesANSI to get a string with real ANSI escape codes, or run the result through RenderANSI's swap layer.

Exported so other CLI surfaces (e.g. the changelog pretty-printer) can share the exact same quote-rendering rule that the help-text renderer applies, keeping formatting consistent across commands.

func HighlightQuotesANSI

func HighlightQuotesANSI(s string) string

HighlightQuotesANSI applies the cyan double-quote rule (rule 2 of the pretty renderer) to a single string and returns it with real ANSI escape codes already substituted. Useful for callers that have their own block-level layout (e.g. the changelog bullet renderer) but still want quote highlighting consistent with the help-text pretty renderer.

func Render

func Render(md string) string

Render applies the four pretty-print rules to markdown input and returns a token-annotated string (no ANSI escape codes). Use RenderANSI when emitting to a terminal.

Rules:

1. A fenced code block whose body matches the immediately-preceding paragraph's text collapses to a single yellow "→ <content>" line and the fence is dropped.
2. Double-quoted strings ("like this") become cyan; single quotes are left alone (apostrophes).
3. An italic line directly under a heading renders as a muted subtitle.
4. Body content under a heading is indented by two spaces.

func RenderANSI

func RenderANSI(md string) string

RenderANSI is Render with ANSI codes substituted for the token sentinels.

func RenderRepoTermBlock

func RenderRepoTermBlock(w io.Writer, b RepoTermBlock) error

RenderRepoTermBlock writes one block to w. Returns the first write error so callers can surface broken pipes / closed stderr instead of silently dropping output.

The function is pure with respect to its inputs: same RepoTermBlock in → same bytes out, regardless of TTY / color settings. Color is deliberately omitted here so the same renderer works for both interactive terminals and CI logs that strip ANSI sequences.

func RenderRepoTermBlocks

func RenderRepoTermBlocks(w io.Writer, blocks []RepoTermBlock) error

RenderRepoTermBlocks renders a slice in order. Stops on first write error so a broken pipe doesn't cause us to keep formatting blocks the reader will never see.

func StdoutIsTerminal

func StdoutIsTerminal() bool

StdoutIsTerminal reports whether os.Stdout is connected to a real TTY using a dependency-free os.Stat / ModeCharDevice check. Exported so callers in cmd/, helptext/, and any future markdown-printing surface can share one TTY probe instead of reimplementing it locally.

Types

type PrettyMode

type PrettyMode int

PrettyMode is the tri-state requested by the caller.

const (
	// PrettyAuto is the default: render when stdout is a real TTY and the
	// shared GITMAP_NO_PRETTY env opt-out is unset.
	PrettyAuto PrettyMode = iota
	// PrettyOn forces ANSI rendering regardless of TTY / env. Useful when
	// piping into a renderer that understands ANSI (e.g. `less -R`).
	PrettyOn
	// PrettyOff suppresses ANSI rendering regardless of TTY / env. Use
	// when redirecting to a file or feeding the output into tools that
	// choke on escape codes (diff, sha256sum, grep -F).
	PrettyOff
)

type RepoTermBlock

type RepoTermBlock struct {
	// Index is the 1-based row number printed before the name.
	Index int
	// Name is the repo's short name (basename or RepoName).
	Name string
	// Branch is the detected branch ("main", "develop", …).
	Branch string
	// BranchSource describes how the branch was chosen: "HEAD",
	// "config", "default", "manifest", "detached", "unknown".
	BranchSource string
	// OriginalURL is the URL as discovered (HTTPS preferred,
	// SSH fallback) or as supplied by the user.
	OriginalURL string
	// TargetURL is the URL that will actually be passed to git
	// clone — may equal OriginalURL when no rewrite happens.
	TargetURL string
	// CloneCommand is the full `git clone …` invocation.
	CloneCommand string
}

RepoTermBlock is the input to RenderRepoTermBlock. All fields are strings so producers can pass through whatever they have without import cycles into model/probe/clonefrom packages.

func FromScanRecord

func FromScanRecord(idx int, r model.ScanRecord) RepoTermBlock

FromScanRecord builds a RepoTermBlock from a model.ScanRecord. idx is the 1-based row number to surface to the user.

CloneCommand defaults to the record's CloneInstruction, which the mapper has already shaped to "git clone [-b BRANCH] URL PATH". When the instruction is empty we synthesize a minimal command from the picked URL so the block is always populated.

func FromScanRecords

func FromScanRecords(records []model.ScanRecord) []RepoTermBlock

FromScanRecords maps a slice with 1-based indexing.