templates

Documentation

Overview

Package templates — Diff primitive.

Diff compares the current on-disk content of a target file against what `add <kind> <lang>` would produce, focused exclusively on the gitmap-managed marker block. Hand edits OUTSIDE the block are invisible to the diff (consistent with Merge's contract: outside content is untouched, so a diff would only add noise).

The output is a small unified-style hunk list. We deliberately do not pull a Myers diff dependency — comparing two block bodies line-by-line covers every case `templates diff` cares about, in ~80 LOC.

Package templates ships curated .gitignore and .gitattributes content per language, with a user-overlay system for read-only install paths.

Resolution order for any (kind, lang):

1. <UserTemplatesDir>/<kind>/<lang><ext> (user override)
2. embedded assets/<kind>/<lang><ext> (built-in fallback)

Phase 0: package + embed + resolver + materializer only. CLI wiring arrives in Phase 2.

Package templates — Merge primitive.

Merge inserts (or updates in place) a gitmap-managed marker block inside a target file (.gitattributes or .gitignore). The block is bracketed by well-known sentinel comments so re-running the merge is idempotent:

# >>> gitmap:<kind>/<lang> >>>
... template body, verbatim ...
# <<< gitmap:<kind>/<lang> <<<

On the second and later runs, the existing marker block is located by regex, replaced with the new body, and the rest of the file is kept byte-for-byte. Hand edits OUTSIDE the block survive untouched; hand edits INSIDE the block are intentionally overwritten — the user is expected to fork the template to ~/.gitmap/templates/ if they want custom content.

Index

• Variables
• func EnsureUserDir() (string, error)
• func LoadFile(path string) ([]byte, bool, error)
• func Materialize() (string, []string, error)
• func UserDir() (string, error)
• type DiffResult
  • func Diff(targetPath, tag string, body []byte) (DiffResult, error)
• type DiffStatus
• type Entry
  • func List() ([]Entry, error)
• type MergeOutcome
• type MergeResult
  • func Merge(targetPath, tag string, body []byte) (MergeResult, error)
• type Resolved
  • func Resolve(kind, lang string) (Resolved, error)
• type Source

Variables

var FS embed.FS

FS holds the curated template corpus. Populated in Phase 1.

Functions

func EnsureUserDir

func EnsureUserDir() (string, error)

EnsureUserDir creates the user-overlay templates directory if it is missing. It is safe to call repeatedly.

func LoadFile

func LoadFile(path string) ([]byte, bool, error)

LoadFile is a thin os.ReadFile shim re-exported for callers (cmd package) that want to fall back gracefully when the target is missing without re-implementing the os.IsNotExist check.

func Materialize

func Materialize() (string, []string, error)

Materialize copies every embedded asset into the user-overlay directory, SKIPPING any file that already exists. This makes the call idempotent and preserves user edits.

Returns the overlay directory and the list of files actually written.

func UserDir

func UserDir() (string, error)

UserDir returns the absolute path to the user-overlay templates directory, e.g. C:\Users\me\.gitmap\templates or /home/me/.gitmap/templates.

The directory is NOT created here; call EnsureUserDir for that.

Types

type DiffResult

type DiffResult struct {
	Path     string
	Tag      string
	Status   DiffStatus
	Hunks    []string // unified-style "+/-" lines, banner-prefixed
	BlockOld []byte   // body bytes currently on disk (nil if absent)
	BlockNew []byte   // body bytes the template would write
}

DiffResult is the structured outcome of Diff. Hunks is empty when Status == DiffNoChange.

func Diff

func Diff(targetPath, tag string, body []byte) (DiffResult, error)

Diff loads targetPath, locates the gitmap:<tag> block (if any), and compares its body to body. Returns a structured result; never writes to disk. The caller decides how to render Hunks (raw/ANSI).

type DiffStatus

type DiffStatus int

DiffStatus enumerates the high-level outcomes of a single Diff call.

const (
	// DiffNoChange means the template body matches the on-disk block
	// (or both are absent). Exit code 0 territory.
	DiffNoChange DiffStatus = iota
	// DiffMissingBlock means the file exists but has no gitmap block
	// for tag — `add` would insert one.
	DiffMissingBlock
	// DiffMissingFile means the file itself is absent — `add` would
	// create it.
	DiffMissingFile
	// DiffBlockChanged means the file has a gitmap block but its body
	// differs from the template — `add` would update it.
	DiffBlockChanged
)

type Entry

type Entry struct {
	Kind   string // ignore | attributes | lfs
	Lang   string // common | go | node | ...
	Source Source // SourceUser or SourceEmbed
	Path   string // absolute (overlay) or virtual embed path
}

Entry describes one discoverable template.

func List

func List() ([]Entry, error)

List returns every available template, with the user-overlay copy shadowing the embedded one when both exist. Sorted by (kind, lang).

type MergeOutcome

type MergeOutcome int

MergeOutcome describes what Merge did to the target file.

const (
	// MergeCreated means the target file did not exist and was created.
	MergeCreated MergeOutcome = iota
	// MergeInserted means the file existed but had no prior gitmap block;
	// the new block was appended at the end.
	MergeInserted
	// MergeUpdated means a prior gitmap block was found and its body was
	// replaced (or kept identical — see Changed).
	MergeUpdated
)

type MergeResult

type MergeResult struct {
	Path     string       // absolute path of the target file
	Outcome  MergeOutcome // what happened on disk
	Changed  bool         // true when bytes on disk differ from before
	BlockTag string       // e.g. "lfs/common" — the marker tag used
}

MergeResult is the structured return value of Merge.

func Merge

func Merge(targetPath, tag string, body []byte) (MergeResult, error)

Merge writes (or refreshes) a gitmap-managed marker block in targetPath containing body, identified by tag (e.g. "lfs/common"). It is safe to call repeatedly: the second call is a no-op when body has not changed.

type Resolved

type Resolved struct {
	Kind    string
	Lang    string
	Path    string // overlay absolute path, or embedded virtual path
	Source  Source
	Content []byte
}

Resolved is a single template resolution result.

func Resolve

func Resolve(kind, lang string) (Resolved, error)

Resolve looks up a (kind, lang) template, preferring the user overlay over the embedded asset.

type Source

type Source int

Source describes where a resolved template came from.

const (
	SourceNone Source = iota
	SourceUser
	SourceEmbed
)