Quickstart

Getting Started

Platform Support

Starting with version 0.3.0, somesy supports Linux, MacOS and Windows.

Make sure that you use the latest version in order to avoid any problems.

! info

Poetry changed location of its project metadata with its version 2. Starting with version **0.7.0**, `somesy` supports both major versions of `poetry`, version 1 and 2.

! info

For `pyproject.toml`, `somesy` works with the *metadata standard*, not with the build backend. Any project that declares its metadata in the standard [PEP 621](https://peps.python.org/pep-0621/) `[project]` table is supported, no matter whether it is built with **uv**, **hatchling**, **flit**, **PDM**, **setuptools** or **Poetry 2.x**. Poetry is the exception that needs its own handling, because Poetry 1.x keeps metadata in `[tool.poetry]` and Poetry 2.x still extends the `[project]` table with Poetry-specific conventions. A leftover `[tool.poetry]` section in a project built with another backend is treated as what it is, configuration rather than metadata. Backend-specific settings such as `[tool.uv]`, `[tool.hatch]` or `[dependency-groups]` are never modified by `somesy`.

Installing somesy

Somesy requires Python >=3.10. To get a first impression, you can install the latest stable version of somesy from PyPI using pip:

pip install somesy

Note

If you use somesy as a pre-commit hook, you don't have to install somesy on your PC nor add it as a dependency in your Python project. Pre-commit will handle the installation automatically.

Configuring somesy

Yes, somesy is another tool with its own configuration. However, for your project metadata it is hopefully the last file you need, and the only one you have to think about, somesy will take care of the others for you!

To get started, create a file named somesy.toml:

[project]
name = "my-amazing-project"
version = "0.1.0"
description = "Brief description of my amazing software."

keywords = ["some", "descriptive", "keywords"]
license = ["MIT", "Apache-2.0"]
repository = "https://github.com/username/my-amazing-project"

# This is you, the proud author of your project:
[[project.people]]
given-names = "Jane"
family-names = "Doe"
email = "j.doe@example.com"
orcid = "https://orcid.org/0000-0000-0000-0001"
author = true      # is a full author of the project (i.e. appears in citations)
maintainer = true  # currently maintains the project (i.e. is a contact person)

# this person is an acknowledged contributor, but not author or maintainer:
[[project.people]]
given-names = "Another"
family-names = "Contributor"
email = "a.contributor@example.com"
orcid = "https://orcid.org/0000-0000-0000-0002"
# ... but for scientific publications, this contributor should be listed as author:
publication_author = true

# add an organization as a maintainer
[[project.entities]]
name = "My Super Organization"
email = "info@my-super-org.com"
website = "https://my-super-org.com"
rorid = "https://ror.org/02nv7yv05" # highly recommended set a ror id for your organization

[config]
verbose = true     # show detailed information about what somesy is doing

As Helmholtz Metadata Collaboration (HMC), our goal is to increase usage of metadata and improve metadata quality. Therefore, some fields in somesy.toml are set as required fields. This is to increase rigour and completeness of metadata recorded with somesy .

Alternatively, you can also add the somesy configuration to an existing pyproject.toml, package.json, Project.toml, or fpm.toml file. The somesy manual contains examples showing how to do that.

Initialize a project

For an existing project, somesy init harvests metadata from supported project files and Git history, merges it, and creates somesy.toml:

somesy init

The command asks only for required metadata that could not be harvested: project name, description, SPDX license, and one author. An author can be a person or an organization. Existing project files are enabled as sync targets; absent files are disabled. Use --output-file to choose another path or --overwrite to replace an existing file.

For scripts, somesy init --non-interactive never prompts. It writes the harvested metadata and warns about missing required values. To synchronize an incomplete file, explicitly use somesy sync --pass-validation or set pass_validation = true in the config.

somesy init --output-file somesy.toml --overwrite

For manual configuration of sync options, use somesy init config.

Update a scalar project-metadata value with somesy set:

somesy set version 1.2.3

Using somesy

Once somesy is installed and configured, somesy can take over and manage your project metadata. Now you can run somesy simply by using

somesy sync

The information in your somesy.toml is used as the primary and authoritative source for project metadata, which is used to update all supported (and enabled) target files. You can find an overview of supported formats further below.

By default, somesy will create (if they did not exist) or update CITATION.cff and codemeta.json files in your repository. When generating codemeta.json, Somesy retains metadata managed in somesy.toml and fills missing runtime, dependency, project-URL, and Git-history fields from enabled project files. See the CodeMeta enrichment details. If you happen to use

• pyproject.toml (in Python projects),
• package.json (in JavaScript projects),
• Project.toml (in Julia projects),
• fpm.toml (in Fortran projects),
• pom.xml (in Java projects),
• mkdocs.yml (in projects using MkDocs),
• Cargo.toml (in Rust projects)

then somesy would also update the respective information there.

You can see call available options with somesy --help, all of these can also be conveniently set in your somesy.toml file.

Somesy as a pre-commit hook

We highly recommend to use somesy as a pre-commit hook. A pre-commit hook runs on every commit to automatically point out issues or fix them on the spot, so if you do not use pre-commit in your project yet, you should start today! When used this way, somesy can fix most typical issues with your project metadata even before your changes can leave your computer.

To add somesy as a pre-commit hook, add it to your .pre-commit-config.yaml file in the root folder of your repository:

repos:
    # ... (your other hooks) ...
    - repo: https://github.com/Materials-Data-Science-and-Informatics/somesy
      rev: 'v0.8.1'
      hooks:
          - id: somesy

Note

Please add the latest version of Somesy to your project. You can update the version of Somesy in your config file now and later to use the newest versions as they become available.

Note that pre-commit gives somesy the staged version of files, so when using somesy with pre-commit, keep in mind that

• if somesy changed some files, you need to git add them again (and rerun pre-commit)
• if you explicitly run pre-commit, make sure to git add all changed files (just like before a commit)

Supported File Formats

Here is an overview of all the currently supported files and formats.

Input Formats	Status		Target Formats	Status
(.)somesy.toml	✓		-	✓
pyproject.toml	✓		pyproject.toml (PEP 621 [project] and Poetry)	✓(1.)
package.json	✓		package.json (JavaScript)	✓(2.)
Project.toml	✓		Project.toml (Julia)	✓
fpm.toml	✓		fpm.toml (Fortran)	✓(3.)
	✓		pom.toml (Java)	✓(4.)
Cargo.toml	✓		Cargo.toml (Rust)	✓
			mkdocs.yml	✓(5.)
			CITATION.cff	✓
			codemeta.json	✓(6.)

Notes:

1. pyproject.toml support is based on the metadata standard, not on the build backend: the PEP 621 [project] table is handled for uv, hatchling, flit, PDM, setuptools and Poetry 2.x, while Poetry 1.x is handled through its own [tool.poetry] table. somesy also supports PEP 621 dynamic fields — fields listed in dynamic (e.g. version) are not overwritten during sync
2. package.json only supports one author, so somesy will pick the first listed author
3. fpm.toml only supports one author and maintainer, so somesy will pick the first listed author and maintainer
4. pom.xml has no concept of maintainers, but it can have multiple licenses
5. mkdocs.yml is a bit special, as it is not a project file, but a documentation file. somesy will only update it if it exists and is enabled in the configuration
6. For handling codemeta.json different options exists: Either (A) somesy removes any prior existing codemata.json files and re-creates it anew, or (B) somesy merges an existing codemeta.json with the information handled by somesy. See the user manual for additional details about CodeMeta handling.