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 .

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 .

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 2 means files would require header updates.

Further reading:

Next steps

Continue with: