Skip to content

TopMark documentation (1.0.1)

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 and precedence
  • 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

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 layered runtime behavior and policies Configuration
Understand repository filtering and file discovery Filtering
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
  • Exposes layered configuration provenance via topmark config dump --show-layers
  • Provides machine-readable JSON and NDJSON output 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:

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 (2) - dry-run indicates changes would be made (check, strip)
  • FAILURE (1) - validation failed (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.

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: