Commands

moneta --help lists them all; this page is the part worth knowing before reading the flags.

Writing an entry

$ moneta new -k added -m "Support nested .changes directories" -i 42
$ moneta create

new takes every field as a flag and is what a script calls. create asks for the kind and the scopes — both come from lists the project already defines — and then opens the fragment itself in $EDITOR, frontmatter included, so what you commit is what you looked at. Nothing is written until the editor exits with an entry in it.

A fragment is Markdown with YAML frontmatter:

---
id: 01a0cea8-4790-7c3e-9d1a-5b2f0e8c4a71
kind: added
scope: [parser, config]
issues: [42]
breaking: false
---

Support nested `.changes` directories.

scope: takes a string or a list. issues: and merge_requests: take numbers or strings, so a project that writes GH-3 needs no migration. breaking: true forces a major bump whatever the kind’s own bump is. retracted: true takes the entry out of the changelog, released versions included. id: names the entry in place of the filename, so the entry is followed through a move or a rename; it can be added after the release. new, create and commit write one, a UUIDv7, unless moneta.id says otherwise. modules: is for a repository with modules. released_in: names the release tag an entry shipped in, one per module, overriding the tag trees; it is for importing another tool’s changelog, whose releases hold no fragments, and new --released-in writes it. The tag has to exist, which moneta check verifies.

The filename is the description, then the UTC date and time, as in support-nested-changes-directories-2026-09-25-14-30.md. That makes it conflict-free: two merge requests collide only by landing in the same minute with the same description. There is no index file, so git has nothing to conflict on either.

Entries of one kind are listed in the order of their keys. The id: is a UUIDv7, which starts with the time it was made, so that order is chronological.

moneta.filename in omniblack.yaml decides the shape, over {{ .Slug }}, {{ .Year }}, {{ .Month }}, {{ .Day }}, {{ .Hour }}, {{ .Minute }}, {{ .Timestamp }}, {{ .Kind }}, {{ .Scope }} and {{ .UUID }}. {{ .UUID }} is the same UUID the default id: has.

Rendering

$ moneta render                                  # Markdown, every version
$ moneta render --format rst -o docs/changes.rst
$ moneta render --format json                    # the contract other tools read
$ moneta render --version current --format md    # this tag's release notes
$ moneta render --version v1.2.0 --body          # a release page's body

--version current is the release path: inside a tag pipeline HEAD is detached at the tag being built, and what you want is that tag’s notes, not an Unreleased section that is empty because everything just shipped.

--body leaves out the version heading, because a GitLab release shows its tag as the title already. The kind headings move up to ## in Markdown. It fails unless the selection holds exactly one version: with no headings, nothing would show where one release stops and the next starts.

Release headings link to whatever the project publishes per version, when moneta.releases.url says where:

moneta:
  releases:
    url: "https://gitlab.com/terryp/moneta/-/releases/{{ .Tag }}"

Only the version is the link — the date and the [YANKED] marker stay outside it — and Unreleased is never linked, because it has no tag to build a URL from. With no moneta.releases.url the headings are plain, which is what they were before.

--content decides where everything an entry says comes from — its text, kind, scopes, modules and retracted: — and never which version it is in:

worktree (default)

the file as it is now, so a just-written or just-fixed entry shows up

head

the committed text

as-published

every released entry as its own release shipped it

Under worktree and head, an entry whose fragment was deleted renders from its last version: the copy in HEAD if the deletion is not committed yet, else the copy the deleting commit removed. Deleting a fragment tidies .changes without erasing the entry or the corrections made to it. retracted: true takes an entry out.

Releasing

$ moneta next              # the version to cut
$ moneta next --bump-only  # major | minor | patch | none
$ moneta next --tag --push

The bump comes from the kinds waiting to be released: a breaking change moves the major, a feature the minor, a fix the patch. Below 1.0 the default policy softens that — a breaking change is a minor bump, anything else a patch — until moneta.pre-1.0.policy: strict says otherwise.

moneta only ever suggests. A tag someone typed is the truth, and --tag refuses to add a second tag to a commit that already has one unless --force says so.

--sign makes it a signed tag, with the key and format git is configured with. A key that is missing or locked fails the command before the tag exists, so unlike tag.gpgsign in your git config it cannot quietly produce an unsigned tag on another machine.

moneta release does all of it for a Go project: it tags the version next suggests, builds each platform through your mage target, packs, signs, pushes and publishes a GitLab release with the notes. moneta snapshot builds and packs the same files with no tag. Cutting a release explains both.

$ moneta release --plan     # what would be released
$ moneta snapshot           # build and pack; no tag, nothing published
$ moneta release

Checking

$ moneta check                      # parse and validate every fragment
$ moneta check --commits            # also: every commit scope on the branch
$ moneta check --require-fragment   # also: changed code, added no entry
$ moneta check feature              # all of the above for a commit, not the checkout
$ moneta commit-msg .git/COMMIT_EDITMSG

A commit subject is scope: Subject, a,b: Subject, or Subject with no scope. Text before the first colon is a scope list only if it has no spaces, so Fix a bug: the parser is an unscoped subject. fixup!, squash! and amend! prefixes and git’s Revert "…" are looked through, so a revert has the scopes of the commit it reverts. When omniblack.yaml has a scopes list, every commit scope must be in it.

Without a ref, check reads the fragments in the working tree, and the branch is HEAD. With a ref, it checks that commit instead: the fragments in its tree, and the commits and changes from the base to it. It does not read the working tree, so the result is the same whatever is checked out. When the ref is a release tag, the base is the latest release in its history. The check then covers everything that the release adds, and not the empty difference from the default branch. The first release has no release before it and uses the default branch.

--require-fragment is a gate for merge requests. A branch that changes files outside .changes must add a fragment, unless every commit on it is in an internal scope. Several scopes on one commit name one part of the project, so one internal scope makes the whole commit internal: docs,infra is the infrastructure of the docs, even if docs alone is not internal. An unscoped commit is not internal. Merge commits are not counted. There is no skip trailer and no exempt path list: the one way past the gate is written in each commit subject and in omniblack.yaml, where a reviewer sees it. check.require-fragment: true in omniblack.yaml turns the gate on without the flag, and --require-fragment=false turns it off for one run.

$ moneta commit
$ moneta commit -- -a                # anything after -- goes to git commit

commit asks for the scopes, from the scopes list, and the subject. Then it opens git commit with scope: Subject already in the editor. Internal scopes are in the list and are marked. If you pick no internal scope, somebody who uses the project can see the change, so commit offers to write a fragment first, the same way create does. It fills in the name and scopes from the commit and stages the fragment into the same commit. The offer defaults to no when the branch or the index already adds a fragment. If you decline or abandon the fragment, the commit still continues. --dry-run prints the subject and the fragment, and writes nothing.

commit-msg checks one message and is the body of a git commit-msg hook. It does not ask for a fragment, because the fragment can be in any commit on the branch.

A wrk environment sets up the hooks with a module:

wrk = {...}: {
  imports = [moneta.wrkModules.default];
  moneta.enable = true;
};

Entering the checkout with wrk puts moneta on PATH and registers three config-based git hooks in the repository:

Event

Runs

Checks

commit-msg

moneta commit-msg

the scopes of the new commit

pre-commit

moneta check --require-fragment=false

the fragments in the working tree

pre-push

moneta check --commits --require-fragment <ref>

the gate a merge request meets, for each ref pushed

The pre-push hook gives a tag to check by name, so a release tag is checked against the release before it.

The hooks run beside any hook in .git/hooks, and do not take over core.hooksPath. git push --no-verify skips pre-push. If your git does not run config-based hooks, wrk prints a warning for each one. moneta.package picks the moneta put on PATH, and moneta.command the command the hooks run.

Without nix, set the commit-msg hook yourself. Git runs a hook from the top of the working tree and appends the message file to its command:

$ git config set hook.moneta-commit-msg.command 'moneta commit-msg'
$ git config set hook.moneta-commit-msg.event commit-msg

This repository’s dev shell sets the same hooks with go run ./cmd/moneta in place of moneta, so the rules being checked are the ones in the checkout, as in the changelog job.

Looking

$ moneta list
VERSION     DATE        ENTRIES  FROM
Unreleased              2        v0.1.0
v0.1.0      2026-09-23  7

The FROM column names the releases whose contents formed that version’s baseline, which is the quickest way to see why an entry landed where it did.

Modules

In a repository with modules (see the Modules section of Configuration), each command that reads a changelog works on one module. moneta finds the module in this order:

  1. --module (-M).

  2. $MONETA_MODULE.

  3. The module whose path holds the directory that moneta runs in.

If none of these gives a module, moneta stops and lists the modules. It does not select a default module, because the wrong changelog looks the same as the correct one.

release and snapshot use only --module, or --all for every module that has a release: block. A release cannot be taken back, so it is of a module you named.

$ moneta -M core render --version current   # core's release notes
$ moneta -M cli next --tag                  # tags cli/v0.4.0
$ cd core && moneta list                     # core, from its path

new, create and commit write the modules into the fragment. --module can be given more than once for them. create and commit ask for the modules, and select the module found above.

check does not use a module. It checks every fragment against every module.