Packages

A package is a set of files that Knope releases together with the same version. Knope can increase this version based on changes that affect the package.

A project can either consist of a single package:

knope.toml

[package]
# package config here

Or multiple packages:

knope.toml

[packages."<name>"]  # where you replace <name> with the name of the package
# package config here

[packages."<other_name>"]  # and so on
# package config here

versioned_files

The files within a package that contain the current version. Each file must have the same version number as all the other files.

An entry in this array can either be a string containing the path to a file, an object containing a path and specifying a dependency within the file to update, or an object with a path and regex for regex-based version matching:

[package]
versioned_files = [
    "Cargo.toml",
    "package.json",
    { path = "crates/knope/Cargo.toml", dependency = "knope-versioning" },
    { path = "README.md", regex = "version: (?<version>\\d+\\.\\d+\\.\\d+)" }
]

All paths should be relative to the config file.

Knope determines the type of the file using its name (independent of its path), so blah/Cargo.toml is a Cargo.toml file. If you specify a regex, Knope will use regex matching to find and replace the version instead of the built-in file support.

Knope supports the following file names:

Cargo.toml

For versioning Rust projects. There are a few different types of Cargo.toml supported.

Basic Rust package

If a Cargo.toml contains package.version, Knope can update that field for you when incrementing the version:

Cargo.toml

[package]
name = "my-package"
version = "1.0.0"

Update Rust dependencies

If you specify dependency in knope.toml, Knope will search for that crate name in the workspace.dependencies, dependencies, and dev-dependencies tables:

knope.toml

[package]
versioned_files = [
    { path = "crates/knope/Cargo.toml", dependency = "knope-versioning" }
]

Cargo.toml

[package]
name = "something-else"
version = "1.0.0"

[dependencies]
knope-versioning = "1.0.0"

Note

Members of Cargo workspaces are auto-detected when using the default config

Update a workspace version

If Cargo.toml contains workspace.package.version and not package.version, Knope will update that version.

• Cargo.toml
• Cargo.lock
• Directorysome-crate/

  • Cargo.toml
• knope.toml

Cargo.toml

[workspace.package]
version = "1.0.0"

some-crate/Cargo.toml

[package]
name = "something"
version.workspace = true

knope.toml

[package]
versioned_files = [
    "Cargo.toml", # NOT some-crate/Cargo.toml
    { path = "Cargo.lock", dependency = "some-crate" },
]

Caution

Knope will not search for the workspace file if you specify the member’s Cargo.toml. You must tell Knope to version that workspace file directly, as it contains the version.

Because the workspace Cargo.toml does not have a package.name, you must specify the dependency in Cargo.lock manually.

Cargo.lock

Knope can keep dependencies of a Rust project up to date by specifying a Cargo.lock file. By default, the dependency name is the package name in the first Cargo.toml file listed in versioned_files. You can override this by specifying the dependency field manually. If you provide neither, Knope will error.

gleam.toml

A Gleam configuration file.

dependency isn’t supported yet.

go.mod

For Go projects using modules. Must contain a module line which must end in the major version for any greater than 1. Can optionally contain a comment containing the full version. If this comment isn’t present, Knope uses the latest matching Git tag to find the version.

go.mod

module github.com/knope-dev/knope // v0.0.1

go.mod

module github.com/knope-dev/knope/v2 // v2.0.0

To omit the major version from the module line (e.g., for binaries, where it doesn’t matter much), use the ignore_go_major_versioning option.

dependency isn’t yet supported.

package.json

For JavaScript or TypeScript projects, must contain a root-level version field:

package.json

{
  "version": "1.0.0"
}

Note

NPM workspaces are only supported when using the default config

Dependencies Knope 0.21.0+

If you specify dependency in knope.toml, Knope will search for it in both dependencies and devDependencies:

knope.toml

[package]
versioned_files = [
    { path = "something/package.json", dependency = "@scope/depName" },
    { path = "somethingElse/package.json", dependency = "anotherName" },
]

something/package.json

{
  "dependencies": {
    "@scope/depName": "1.0.0"
  }
}

somethingElse/package.json

{
  "devDependencies": {
    "anotherName": "1.0.0"
  }
}

package-lock.json Knope 0.21.0+

Knope can update npm lock files with version 2+, corresponding to npm 7+. Just like package.json, Knope can either update the version for the lock file’s package, or for dependencies. When automatically detected using default config Knope will assume the lock file is for the current package, not a dependency.

Root package-lock.json example

A configuration like this might be used to update the lock file entry for a single package. This is equivalent to the default configuration for a directory containing those files. Knope will update root version property and the packages[""].version property in package-lock.json.

knope.toml

[package]
versioned_files = ["package.json", "package-lock.json"]

Dependencies in package-lock.json example

You can also update dependency entries matching a package name, useful for monorepos:

knope.toml

[packages.a]
versioned_files = [
  "packages/a/package.json",
  { path = "package-lock.json", dependency = "@myScope/packageA" },
]

With a config like this, Knope will update the version of all packages with the name of @myScope/packageA and any dependencies of any packages matching that same name.

package-lock.json

{
  "name": "",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "packages": {
    "": {
      "name": "",
      "version": "1.0.0",
      "license": "ISC",
      "workspaces": ["packages/a", "packages/b"]
    },
    "packages/b": {
      "name": "@myScope/packageB",
      "version": "1.0.0",
      "dependencies": {
        "@myScope/packageA": "0.1.0"
      }
    },
    "packages/a": {
      "name": "@myScope/packageA",
      "version": "0.1.0"
    }
  }
}

deno.json / deno.jsonc Knope 0.21.4+

For Deno projects, the manifest must include both a name and a version field at the top level. Knope accepts either plain JSON (deno.json) or JSON with comments (deno.jsonc). When updating the version number, Knope rewrites the manifest with the new value while preserving other settings and any existing comments.

deno.json

{
  "name": "@scope/my-module",
  "version": "1.0.0"
}

When both deno.json and deno.jsonc exist in the same directory, the .json file takes priority for version updates.

deno.lock Knope 0.21.4+

For Deno workspaces that publish to JSR or NPM, add a deno.lock entry with the dependency field set to the package name you want to keep in sync. Knope updates the specifiers, registry entries (jsr/npm), and workspace sections for that dependency to match the release version.

knope.toml

[packages."@scope/my-module"]
versioned_files = [
  "deno.json",
  { path = "deno.lock", dependency = "@scope/my-module" }
]

Only lock files using format version 5 are supported. Earlier versions must be migrated with deno lock --lock-write.

pyproject.toml

For Python projects using PEP-621 or Poetry. Must contain either a [project.version] or [tool.poetry.version] value, respectively. If it has both values, they must be the same.

pyproject.toml

[project]  # PEP-621
version = "1.0.0"

[tool.poetry]  # Poetry
version = "1.0.0"

dependency isn’t yet supported.

pom.xml

For Java projects using Maven, must contain a <version> field in the <project> section:

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.mycompany.app</groupId>
  <artifactId>my-app</artifactId>
  <version>1.2.3</version>
</project>

Neither dependencies nor multi-module projects are support yet.

pubspec.yaml

For Dart projects, must contain a version field:

pubspec.yaml

version: 1.0.0

dependency isn’t yet supported.

tauri.conf.json

Supports Tauri configuration files in json format. Also supports tauri.macos.conf.json, tauri.windows.conf.json, and tauri.linux.conf.json.

Regex patterns

For files that aren’t in a recognized format, you can use regex patterns to find and replace version strings. Specify the file with a path and a regex field containing a regular expression:

knope.toml

[package]
versioned_files = [
    { path = "README.md", regex = 'https:\/\/example.com\/download\/v(?<version>\d+\.\d+\.\d+).tgz' }
]

Caution

In TOML, make sure to either use single-quoted strings like '\s' or to escape all backslashes like "\\s".

The regex pattern must include a named capture group called version using the syntax (?<version>...). This capture group identifies the version number to replace. The matched string must be a valid semantic version and must match all other versions from other versioned_files.

You can use this for keeping version numbers up to date in documentation, CI or deployment configuration, custom scripts, or file types Knope doesn’t support yet.

Note

If you’re adding custom support for a common file type, consider contributing it to Knope!

changelog

The relative path to a Markdown file you’d like to add release notes to.

knope.toml

[package]
changelog = "CHANGELOG.md"

scopes

An array of conventional commit scopes that Knope should consider for the package. If not defined, Knope will consider all scopes. Commits with no scope are always considered.

knope.toml

[packages.knope]
scopes = ["knope", "all"]

[packages.changesets]
scopes = ["changesets", "all"]

extra_changelog_sections

An array of objects defining more sections for the changelog (or overrides for the default sections). Each object can optionally have an array of footers or an array of types.

Tip

Check out the custom changelogs recipe for a full example of how to use this feature.

[package]
extra_changelog_sections = [
    { name = "Security", footers = ["Security-Note"], types = ["security"]}
]

assets

Assets can either be a single “glob” string, or a list of files to upload to a GitHub release. They do nothing without GitHub configuration. Assets are per-package. When specifying an exact list, each asset can optionally have a name, this is what it’ll appear as in GitHub releases. The name defaults to the file name (the final component of the path).

Caution

Knope doesn’t yet support uploading assets to Gitea, declaring both [gitea] and assets is an error.

A single glob string

knope.toml

[package]
assets = "artifact/*"  # Upload all files in the artifact directory

A list of files

[package]

[[package.assets]]
path = "artifact/my-binary-linux-amd64.tgz"
name = "linux-amd64.tgz"

[[package.assets]]
path = "artifact/my-binary-darwin-amd64.tgz"  # name will be "my-binary-darwin-amd64.tgz"

ignore_go_major_versioning

Go has special rules about major versions above 1. Specifically, the module line in go.mod must end in the major version. By default, Knope follows these rules, so if there is no major version at the end of the module line, Knope will assume you’re updating the latest 1.x or 0.x tag.

To ignore this rule, and always use the latest tag (even if it doesn’t match the module line), set ignore_go_major_versioning to true in the package config:

knope.toml

[package]
versioned_files = ["go.mod"]
ignore_go_major_versioning = true

Tip

To maintain multiple major versions of a Go module, check out this recipe