mongez-pkgist-git-workflow

name

mongez-pkgist-git-workflow

description

pkgist git automation: `commit` field accepts `string` (explicit message), `true` (auto-generates `Released <new-version>`, added in 1.1.0), `false` (explicit skip), or omitted (skip, back-compat default). When git runs, pipeline is `git add -A → git commit → git push → git tag v<version> → git push origin --tags`. Family-level `commit` overrides per-package commit. Optional `branch` field overrides the push target.

Git workflow

pkgist optionally commits, tags, and pushes after each successful build. Whether git runs at all is controlled by the commit field.

The four commit shapes

Value	Behaviour
"explicit message" (string)	Use that exact message
true (boolean)	Auto-generate Released <new-version> (added in pkgist 1.1.0)
false (boolean)	Explicitly skip git for this package
omitted (undefined)	Skip git (back-compat default)

false and omitted are functionally identical. Use false when you want the intent to be obvious in the config diff.

// Explicit per-release message — most informative
{ name: "@scope/utils", root: "../utils", commit: "fix: prevent overflow on large arrays" }

// Hands-off auto-message — set once, never updates
{ name: "@scope/utils", root: "../utils", commit: true }
// → commits "Released 2.1.1", tags v2.1.1

// Build-only, no git side effects (for local testing)
{ name: "@scope/utils", root: "../utils" }
// or explicitly:
{ name: "@scope/utils", root: "../utils", commit: false }

What "git runs" actually means

When commit resolves to a non-empty message, pkgist runs this sequence in the package's root directory:

1. git add -A
2. git commit -m "<message>"
3. git push origin <branch>
4. git tag v<new-version>
5. git push origin --tags

The branch comes from pkg.branch if set, otherwise from git rev-parse --abbrev-ref HEAD in the package root. Step 5 pushes all local tags (--tags), which includes the v<new-version> just created.

The git add -A stages everything currently dirty in the working tree — not just the version-bumped package.json. If your working tree has unrelated work-in-progress, that gets bundled into the release commit. Clean the tree (or stash unrelated changes) before the build to keep release commits focused.

Family-level commit override

When a family declares commit, every member uses it — overriding any per-package commit. The shape is the same as per-package commit (string | true | false | undefined).

// One explicit message for every member
families: [
  {
    name: "atom-family",
    commit: "feat: improved subscribe contract",
    packages: [
      { name: "@scope/atom",       root: "../atom" },
      { name: "@scope/react-atom", root: "../react-atom", type: "react" },
    ],
  },
]

// Auto-generated for every member, with the shared family version
families: [
  {
    name: "atom-family",
    commit: true,
    packages: [ /* ... */ ],
  },
]
// → atom commits "Released 6.0.5", react-atom commits "Released 6.0.5"

Per-package commit on a family member is ignored when the family has commit set. Set per-package commit only when the family commit is unset and you want member-specific messages (rare — usually you want unified release commits).

Tagging

Tags follow the pattern v<new-version> — e.g. v2.1.1, v6.0.0-beta.1. They are created locally and pushed to the remote in the same step.

If a tag already exists for that version on the remote, the git push --tags step will fail loudly. Reasons this happens:

• Re-running a build for a version that was already released → bump the version first
• Concurrent releases racing → check the remote state with git fetch --tags before retrying

Branch handling

By default pkgist pushes to whatever branch is currently checked out in the package's root. Override with branch:

{ name: "@scope/utils", root: "../utils", commit: true, branch: "main" }

Use this when:

• The package has multiple long-lived branches and you only release from one
• You want a clear assertion in config that releases go to main specifically (defends against accidentally releasing from a feature branch)

Skipping git for local test builds

Three equivalent ways to disable git for a single package:

{ name: "@scope/test", root: "../test" }              // omitted
{ name: "@scope/test", root: "../test", commit: false } // explicit
{ name: "@scope/test", root: "../test", commit: "" }   // empty string also skips

Or skip git for the whole run regardless of config: pkgist build:all --no-git.

Overriding the commit per run (--commit)

You can override the configured commit for a single invocation with the --commit flag — no edit to pkgist.config.ts required:

pkgist build @scope/utils --commit "fix: guard against overflow"   # explicit message
pkgist build:family atom  --commit                                  # bare → auto "Released <version>"
pkgist build:all          --commit "chore: monthly release"         # one message for the whole fleet

--commit [message] mirrors the config commit shapes:

Invocation	Resolves to
--commit "some message"	that exact message
--commit (bare, no value)	auto-generated Released <new-version> (same as commit: true)
flag omitted	the package/family configured commit (unchanged)

Precedence: --commit (CLI) overrides a family-level commit, which overrides a per-package commit. To skip git for the run, use --no-git — it always wins over any resolved message, CLI or config.

This pairs with --bump (see the versioning and cli skills): together they move the two per-release values — the version and the message — onto the command line, so the config file stays static and parallel release runs never clobber each other's edits.

When commit resolves but --no-git is passed

--no-git always wins. The commit field is ignored for that invocation. Use this to do a "release everything to npm but don't touch git" pass — rare, but useful for hotfixes on packages where you can't push to git for some reason.