citesync

Status: experimental. It may change in ways that break your code, without notice.

Questions and bugs: see CONTRIBUTING.md.

Generate software citation files from package metadata, then keep them in sync across CITATION.cff, codemeta.json, .zenodo.json and package manifests. Use the CLI, a pre-commit hook or the browser playground. Field mappings come from CodeMeta's crosswalks, as exported by codemeta-drift.

Usage

citesync compares eleven fields, from title to release date, with one file: the source. The source is CITATION.cff unless you pick another with --source. With neither, citesync exits 2. Use citesync through its command line and the pre-commit hook. Its Python modules are internal and may change in any release.

uv tool install citesync            # or run it once with uvx citesync check
citesync check                      # exit 0: no error finding; 1: an error finding; 2: citesync couldn't run
citesync check --source pyproject.toml
citesync write --diff               # print what write would change, and change nothing
citesync write                      # rewrite the other files to agree with the source
citesync init                       # write a CITATION.cff from codemeta.json, .zenodo.json and the manifests
citesync explain version-mismatch   # what a rule checks and how to fix it
citesync config                     # the config in use, and the file it came from

codemeta.json:3:3: error[version-mismatch] version: '2.0.0', CITATION.cff has '1.0.0'
  help: Make the file agree with the source, or the other way round if the source is wrong.
1 error, 0 warnings in 3 files
1 fixable with `citesync write`

A config is optional. A one-line citesync.toml is ignore = ["description-mismatch"].

citesync --help lists every command and option. The reference is in docs/:

• How check works: the fields, files, options and exit codes.
• How write works: what it changes and what it leaves alone.
• Supported files: which files citesync reads, updates and creates, including read-only Python distribution, R and Julia metadata.
• How init works: where a new CITATION.cff takes each field from.
• Rules: each rule id, what it checks and how to fix it.
• Configuration: where config goes, and every key.
• Use citation exports with Pandoc: cite software from the playground’s CSL-JSON or BibTeX files.
• Output formats: JSON, GitHub annotations and SARIF.
• Tested on real repositories: what citesync reports on five public repositories.

Browser playground

Generate citation files from existing metadata or basic project details, without installing Python. Open the playground or run it locally. Files are processed in the browser; downloading the converter requires a network connection.

Pre-commit hook

For prek or pre-commit, in .pre-commit-config.yaml:

repos:
  - repo: https://github.com/simonvanlierde/citesync
    rev: v0.3.0
    hooks:
      - id: citesync
      - id: citesync-write

The citesync hook runs when a commit changes a supported metadata file or a citesync config, at any depth. It checks every file, not only the staged ones, and fails the commit on an error finding. The citesync-write hook runs only when you ask for it: prek run citesync-write --stage manual --all-files.

Development

You need uv, just, Node.js 26 and pnpm.

uv sync
pnpm install --frozen-lockfile
uv tool install prek   # once per machine
prek install           # git hooks

just lists the tasks. They mirror what .github/workflows/ runs.

just check       # lint, types and tests for every stack here
just fmt         # apply each stack's fixes and formatting
just hooks       # the git hooks, as the checks workflow runs them

just mutation mutation-tests the modules only_mutate lists under [tool.mutmut] in pyproject.toml. CI doesn't run it. It fails when the tests miss a change that tests/mutation-baseline.txt doesn't list. A change that can't alter behaviour goes in that file, with the reason. It also fails when the tests now catch a listed change, so drop that line.

uv locks only releases at least a week old. If just check fails on a newer security fix, add the package to exclude-newer-package under [tool.uv] in pyproject.toml, and remove it a week later (how).

Licence

See LICENSE.