Skip to content

Usage documentation

This section contains the user-facing documentation for installing, running, configuring, and integrating TopMark.

The pages in this section focus on practical CLI usage, repository workflows, configuration, configuration discovery, validation, automation, filesystem identity, file discovery, and machine-readable integration.

Start here if you want to:

  • install TopMark and complete a safe first run;
  • run TopMark from the CLI;
  • upgrade an existing repository to TopMark 1.0;
  • configure header fields, policies, filtering, and file discovery;
  • understand configuration-discovery anchors, project-chain discovery, and layered precedence;
  • understand filesystem-identity evaluation, processing paths, symlink normalization, and hard-link policy;
  • integrate TopMark with pre-commit or CI;
  • understand exit codes, reports, and machine-readable output.

Common starting points

  • Getting started - install TopMark and complete a safe first run.
  • Upgrading to TopMark 1.0 - migrate repositories from earlier TopMark versions.
  • Command overview - understand the CLI structure and shared command behavior.
  • Shared options - learn about global options, dry-run behavior, verbosity, and output selection.
  • Configuration - understand discovery anchors, layered precedence, configuration-source identity, and runtime policy settings.
  • Filtering - include, exclude, and constrain file processing.
  • Machine-readable output - understand processing paths, configuration provenance, and stable automation contracts.
  • Policies - control insertion, update, validation, and stripping behavior.
  • Header placement - understand how TopMark locates and inserts headers.
  • Pre-commit integration - integrate TopMark into local developer workflows.
  • CI integration - validate repositories safely in CI pipelines.
  • Exit codes - interpret CLI exit status values in automation and scripting.

Command reference