glossary

Monorepo Commits

Commit practices adapted for repositories containing multiple packages or services, using scope to indicate which package or service a change belongs to.

explanation

In a monorepo, a single git repository hosts multiple independently-releasable packages, services, or applications. Conventional Commits in this context rely heavily on the scope field to route changes to the right package changelog and trigger the correct version bump for that package only. Common monorepo tooling includes Nx, Turborepo, Lerna, and Rush. These tools integrate with conventional-changelog or semantic-release to generate per-package changelogs and release versions based on which scopes appear in commits since the last release tag for that package. A discipline challenge in monorepos is keeping commits scoped to the package they touch. A single commit that spans multiple packages (e.g., fixes a shared library and updates two consuming services) makes changelog attribution ambiguous. The preferred approach is one commit per package change, even when changes are coordinated. git-agent's atomic splitting handles this automatically by grouping changes by their package scope.

examples

feat(ui): add DateRangePicker component to design system

fix(api-gateway): increase timeout for upstream health checks

chore(shared): upgrade typescript to 5.4.0 across all packages

feat(billing): add prorated credit calculation for mid-cycle upgrades

test(auth-service): add refresh token expiry integration tests

how git-agent helps

git-agent reads your monorepo's directory structure during git-agent init to suggest per-package scopes. When you commit cross-package changes, the atomic splitter groups them by package scope into separate commits, keeping each package's changelog clean.

brew install gitagenthq/tap/git-agent

FAQ

Should shared utility changes be committed separately from the packages that use them?

Yes. Changes to a shared library and corresponding updates in consuming packages should be separate commits scoped to each package. This allows each package's changelog and version to reflect the actual scope of its change.

How does git-agent know which package a changed file belongs to?

git-agent uses file paths and the scope definitions in .git-agent/project.yml. During git-agent init, it reads package.json workspaces, go.work, or Cargo.toml workspace members to populate scope definitions automatically.

Can git-agent handle Nx or Turborepo affected project detection?

git-agent works at the git diff level and does not integrate directly with Nx or Turborepo affected algorithms. The atomic split groups changes by the file paths and scopes you defined, which naturally aligns with affected project boundaries.

Atomic commits Commit splitting Conventional changelog