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:
|
the file as it is now, so a just-written or just-fixed entry shows up |
|
the committed text |
|
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 |
|---|---|---|
|
|
the scopes of the new commit |
|
|
the fragments in the working tree |
|
|
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:
--module(-M).$MONETA_MODULE.The module whose
pathholds 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.