Skip to content

TopMark documentation (0.1.dev50+g93714a908)

TopMark inspects, inserts, updates, removes, and validates per-file headers across repositories. It is comment-aware, file-type-aware, and dry-run by default for safe local usage, CI validation, and repository automation.

Note

The canonical vocabulary used throughout the documentation is defined in Terminology and Canonical Vocabulary.

TopMark provides stable and consistent behavior across:

  • CLI execution and dry-run workflows
  • layered TOML configuration discovery from resolved discovery anchors and precedence
  • filesystem-identity evaluation, processing-path selection, and hard-link safety
  • configuration-source identity and layered provenance reporting
  • repository filtering and file-type resolution
  • probe and diagnostics workflows
  • machine-readable reporting and explainability
  • pre-commit and CI integration
  • stable public Python API overlays and runtime contracts

Start here

Goal Recommended page
Install TopMark and complete a safe first run Getting started
Understand the CLI structure and shared behavior Command overview
Configure discovery, layered runtime behavior, and policies Configuration
Understand repository filtering and file discovery Filtering
Understand machine-readable output, processing paths, and provenance Machine-readable output
Validate repositories in CI CI integration
Integrate TopMark with pre-commit Pre-commit integration
Understand stable exit-code behavior Exit codes
Upgrade older repositories to TopMark 1.0 Upgrading to TopMark 1.0
Use the public Python API Public API
Contribute to TopMark Contributing

What it does

  • Detects, inserts, updates, validates, and removes per-file headers
  • Honors shebangs, XML declarations, and native comment styles
  • Preserves newline style (LF/CRLF/CR) and BOM
  • Uses dry-run-first workflows for safe repository automation
  • Supports pre-commit and CI integration
  • Explains repository filtering, file-type resolution, and processor selection via topmark probe
  • Uses deterministic filesystem-identity evaluation, processing-path selection, and hard-link safety across CLI, API, CI, and machine-readable workflows
  • Exposes layered configuration provenance via topmark config dump --show-layers
  • Uses deterministic project-chain discovery and configuration-source identity for layered configuration evaluation
  • Provides stable machine-readable JSON and NDJSON output together with canonical registry metadata suitable for automation and reporting
  • Supports canonical qualified file type identifiers such as topmark:python
  • Supports local identifiers such as python when unambiguous

Commands

TopMark exposes a small set of dry-run-first CLI commands.

Configuration discovery starts from the resolved discovery anchor before runtime processing begins. For filesystem-processing commands, that anchor is derived from the first selected input path when available, or from the current working directory otherwise.

Filesystem-processing commands evaluate filesystem identity before runtime processing. Filesystem-identity normalization resolves equivalent path spellings, such as symlink spellings, to the selected processing path used by runtime processing and machine-readable output. Hard-link policy is evaluated as a processing-target eligibility check: if multiple selected paths refer to the same filesystem object through hard links, TopMark reports each affected path independently and blocks processing for the hard-link group.

For command structure, shared options, applicability rules, and common workflows, see:

Core commands: check, strip, probe, config, registry, version.

Informational commands (version, config defaults, config init, and registry commands) are file-agnostic: they do not accept positional paths or STDIN input modes and reject them as CLI usage errors before runtime processing begins.

Exit codes (overview)

TopMark uses a small stable set of exit codes suitable for CI and scripting:

  • SUCCESS (0) - success (no changes needed or changes applied)

  • WOULD_CHANGE (3) - dry-run indicates changes would be made (check, strip)

  • CONFIG_ERROR (78) - configuration validation failed (check, strip, probe, config check)

  • USAGE_ERROR (64) - CLI usage error (invalid options, unsupported STDIN modes, or positional paths on file-agnostic commands)

Additional codes are used for configuration-loading errors and runtime conditions (for example CONFIG_ERROR (78), FILE_NOT_FOUND (66)). These apply after CLI usage has been accepted.

See:

The probe command also reports explicitly requested paths that were filtered out during discovery.

File-type filtering accepts either local identifiers such as python or canonical qualified identifiers such as topmark:python.

The config command has the following subcommands: config check, config defaults, config dump, config init.

The registry command has the following subcommands: registry filetypes, registry processors, registry bindings.

Note

  • Verbosity (-v / --verbose) affects only TEXT rendering.
  • Quiet mode (-q / --quiet) suppresses TEXT rendering for commands that support it.
  • Markdown and machine-readable output are not affected by TEXT verbosity controls.

Machine-readable filesystem path fields report selected processing paths. Configuration provenance reports resolved configuration sources discovered from the resolved discovery anchor and explicit configuration overlays. Both contracts remain stable across supported platforms.

Use config dump --show-layers to inspect how configuration is built from individual sources and how precedence is applied.

TopMark supports two STDIN modes:

  • List mode: read newline-delimited paths or patterns via --files-from - (or --include-from - / --exclude-from -)
  • Content mode: process one file's content by passing - as the sole PATH together with --stdin-filename NAME

See shared input modes for the full STDIN contract, including why TopMark does not provide a --stdin option flag.

Next steps

Common reference pages:

For the canonical project overview and release information, see the project README on GitHub: