Skip to content

Getting started

A five-minute path for adding TopMark safely to a repository.

1. Install TopMark

Stable releases are published on PyPI:

pip install topmark

Verify that the CLI is available:

# Display the installed TopMark version:
topmark version

# Display the command-line help:
topmark --help

2. Create a starter configuration

TopMark reads configuration from either:

  • topmark.toml
  • pyproject.toml

A minimal repository-level topmark.toml configuration may look like this:

[config]
root = true

[fields]
project = "MyProject"
license = "MIT"

[header]
fields = [
  "file",
  "file_relpath",
  "project",
  "license",
]

Note

When using pyproject.toml, TopMark settings must be placed under the tool.topmark table prefix (for example: [config] becomes [tool.topmark.config]).

Generate a documented starter configuration:

Repository-level configuration

Generate a topmark.toml configuration file at the repository root:

topmark config init --root >> topmark.toml

Alternatively, generate configuration inside pyproject.toml:

topmark config init --root --pyproject >> pyproject.toml

The --root option marks the repository boundary for TopMark configuration resolution and prevents configuration discovery from continuing into parent directories.

Local overrides

Generate a local override configuration:

topmark config init >> topmark.toml

Local overrides usually should not specify --root, so repository-level settings continue to apply before local overrides are merged.

Git repositories

When using git, you may want TopMark to:

  • ignore .git/
  • respect .gitignore

Add the following settings:

[files]
exclude_from = [".gitignore"]
exclude_patterns = [".git/"]

Further reading:

3. Preview header compliance

Check if the files have TopMark headers compliant with the settings defined.

topmark check .

Note

TopMark evaluates filesystem identity before processing files. Filesystem-identity normalization resolves equivalent path spellings, such as symlink spellings, to the selected processing path used for runtime processing and machine-readable output.

Configuration discovery is evaluated earlier. When TopMark discovers project configuration files, it starts from a discovery anchor (the current working directory or an input path) and walks the project chain from the resolved anchor location.

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 entire hard-link group without selecting a preferred source, target, winner, or loser path.

4. Preview changes (unified diff)

The precise changes TopMark will apply to files are generated as unified diff when specifying the --diff option:

topmark check --diff .

5. Apply changes

You can add / update the TopMark headers in files by specifying --apply:

topmark check --apply .

Tip

Generated filesystem-related header fields such as file_relpath and file_abspath describe the selected processing target. If a file is reached through a symlink, header metadata reflects the resolved target TopMark reads and writes.

Project configuration discovery follows the same resolved-anchor model. Symlink spellings used to reach a working directory or input path do not create separate project-chain discovery roots.

Files blocked by processing-target eligibility checks, such as hard-linked processing targets, are not modified and therefore do not receive updated header metadata.

6. Validate repeatability

Running topmark check . again should now report no pending changes.

This idempotent behavior is important for CI and repeatable repository automation workflows.

7. Add pre-commit validation

Add TopMark to .pre-commit-config.yaml:

repos:
  - repo: https://github.com/shutterfreak/topmark
    rev: v1.0.0
    hooks:
      - id: topmark-check

Install hooks:

pre-commit install
pre-commit run --all-files

For advanced hook usage and manual apply hooks, see:

8. Add CI validation

Validate repository headers in CI:

topmark check .

Exit code 3 means files would require header updates.

Further reading:

Next steps

Continue with: