Metadata-Version: 2.4
Name: git-acta
Version: 1.0.0
Summary: Structured git workflow CLI: conventional commits, trunk-based branches, GitHub PR lifecycle
Project-URL: Homepage, https://github.com/nicobc/git-acta
Project-URL: Source, https://github.com/nicobc/git-acta
Project-URL: Issues, https://github.com/nicobc/git-acta/issues
Author-email: Nicolas Contreras <nicolas.b.contreras@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Description-Content-Type: text/markdown

# git-acta

[![PyPI version](https://img.shields.io/pypi/v/git-acta)](https://pypi.org/project/git-acta/)
[![Python versions](https://img.shields.io/pypi/pyversions/git-acta)](https://pypi.org/project/git-acta/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![CI](https://github.com/nicobc/git-acta/actions/workflows/test.yml/badge.svg)](https://github.com/nicobc/git-acta/actions/workflows/test.yml)

A structured git workflow CLI for [conventional commits](https://www.conventionalcommits.org/), trunk-based branching, and a clean GitHub PR lifecycle — all from the command line.

## Philosophy

git-acta is built on three practices that reinforce each other: [trunk-based development](https://trunkbaseddevelopment.com/), [conventional commits](https://www.conventionalcommits.org/), and squash-merge-only history. Short-lived branches stay close to `main`. Squash merges keep `main`'s history linear and readable — one commit per feature. Conventional commit types make that history meaningful at a glance. git-acta connects all three as a unit: you name your branch `feat/user-auth` once, and every commit message, PR title, and release tag follows from that single decision.

## Opinions

git-acta is intentionally opinionated. These constraints are not configurable:

- **GitHub only** — PR and release operations rely on `gh`. GitLab and Bitbucket are not supported.
- **Squash merges** — `ship` always squash-merges to keep `main`'s history linear.
- **Single trunk** — `main` is the only integration branch. `develop`, `release/*`, and similar long-lived branches are out of scope. The trunk name is not configurable — repositories using a different default branch are not supported.
- **Conventional commits** — branch names must follow `type/scope` using one of the [11 standard types](https://www.conventionalcommits.org). An optional third segment (`type/scope/topic`) carries a human-readable topic; the commit type and scope are derived from the first two.

If your workflow diverges from any of these, git-acta is not the right tool.

## Prerequisites

**Local**

- Python 3.10+
- [uv](https://docs.astral.sh/uv/) for installation
- [GitHub CLI](https://cli.github.com/) (`gh`) 2.0 or later, authenticated to your GitHub account

**Repository configuration**

git-acta assumes the repository is configured to match its workflow. Without this, the tool still works but its guarantees don't hold — anyone can bypass conventions by using `git` and `gh` directly.

Ask your infra or platform team to configure:

- **Squash merges only** — disable merge commits and rebase merges so `main` stays linear
- **Branch protection on `main`** — require pull requests before merging; disallow direct pushes
- **Required status checks** — require CI to pass before a PR can be merged; this makes `acta ship`'s CI gate structural rather than advisory

## Installation

```sh
uv tool install git-acta
```

This installs the `acta` command. All commands below are invoked as `acta <subcommand>`.

## Workflow walkthrough

Here is a complete cycle from starting a feature to tagging a release.

**1. Create a branch**

```sh
acta branch feat/user-auth
```

Fetches the latest `origin/main` and creates `feat/user-auth` from it. The branch name is the only thing you decide upfront — type and scope flow into every subsequent command automatically.

**2. Do your work, then commit**

```sh
acta commit -A "add login form"
```

Stages all changes and commits with the message `feat(user-auth): add login form`. The type and scope come from the branch name — you only write the description.

For commits that need more context, pass the body with `-b` or open your editor with `-e`:

```sh
acta commit -A "add login form" -b "Supports email and SSO providers."
# → commits with inline body (useful in scripts and LLM workflows)

acta commit -A -e "add login form"
# → opens $EDITOR for the body, then commits
```

You can commit as many times as you want. Only the squash commit that lands on `main` is permanent.

**3. Open a PR**

```sh
acta pr "Add login form"
```

Pushes the branch with upstream tracking set, creates the PR against `main`, prints the URL, then watches CI checks until they complete. You can share the URL while CI is still running.

By default no body is added. To add one:

```sh
acta pr "Add login form" -b "Adds email/password and SSO login.

## Changes
- Email/password with bcrypt hashing
- SSO via Google and GitHub

Closes #42."
# inline body

acta pr -e "Add login form"
# opens $EDITOR for the body
```

**4. Ship it**

Once CI is green:

```sh
acta ship
```

Shows you the PR title and number, asks for confirmation, then: squash-merges into `main`, deletes the remote branch, switches to local `main`, pulls, and force-deletes the local branch. You end up on a clean, up-to-date `main` in one step.

**5. Tag a release**

```sh
acta release
```

Detects your versioning scheme from existing tags, computes the next version, shows you the tag, and asks for confirmation before pushing. On a fresh repo with no tags, it prompts you to choose CalVer or SemVer.

## Board workflow

The board commands add a lightweight project layer on top of the core workflow using GitHub Milestones and Issues. They are optional, the branch/commit/pr/ship workflow works the same with or without them.

**Create a milestone**

```sh
acta milestone new "Auth System" --scope auth
# Milestone #1 created.

acta milestone new "Auth System" -d "Handles login, registration, and SSO." --scope auth
# → with inline description

acta milestone new "Auth System" --scope auth -e
# → opens $EDITOR for the description
```

The `--scope` is used to derive branch names for all issues in this milestone. Every issue started under the milestone will live on a `type/scope/N-title-slug` branch.

**Create issues**

```sh
acta issue new "Add login form" --type feat --milestone 1
acta issue new "Fix token expiry" --type fix --milestone 1
acta issue new "Write auth docs" --type docs --milestone 1
```

A type is required. A milestone is optional at creation time — an issue without one sits in the backlog. Both are required before `issue start` can be used.

**Start an issue**

```sh
acta issue start 1
# On branch 'feat/auth/1-add-login', active issue is #1.
#
# ## Description
# Login form with magic link.
```

Creates the branch from the issue's type and the milestone's scope, with a third segment from the issue number and title slug (`feat/auth/1-add-login`), switches to it, records the active issue in local git config, and prints the issue body so you have the description and acceptance criteria in front of you as you begin. From here, the standard commit/PR/ship workflow applies.

**PR body gets `Closes #N` automatically**

Because `issue start` recorded the active issue, `acta pr` appends `Closes #1` to the PR body without any extra flags. The issue is closed on GitHub when the PR is squash-merged.

**Ship closes the milestone when all issues are done**

```sh
acta ship
```

Clears the active issue after merging. If the milestone has no remaining open issues, git-acta closes it automatically and prints a confirmation.

**Other board commands**

```sh
acta board                          # session snapshot: active work + current milestone
acta milestone list                 # list open milestones with issue counts
acta milestone reopen 1             # reopen a closed milestone
acta issue list                     # list open issues, grouped by milestone
acta issue list --milestone 1       # filter to one milestone (flat list)
acta issue discard 3                # close an issue as not planned
```

## Commands

### `branch TYPE/scope`

Fetches the latest `origin/main` and creates a new branch from it.

```sh
acta branch feat/user-auth          # → feat/user-auth
acta branch fix/payment-api         # → fix/payment-api
acta branch chore/deps              # → chore/deps
acta branch feat/user-auth/sso      # → feat/user-auth/sso
```

The branch name is the only decision you make upfront. Every subsequent `commit` and `pr` command reads the type and scope from it — you never repeat yourself.

You may add an optional third segment for a human-readable topic — `feat/user-auth/sso`. The type and scope are read from the first two segments (`feat`, `user-auth`); the topic keeps the branch name distinct and descriptive, so two branches sharing a type and scope can coexist.

The fetch happens before branch creation, so you always start from the latest `main` regardless of how long ago you last pulled. If the branch already exists locally, git will error — delete it first or choose a different name.

### `commit DESCRIPTION`

Creates a conventional commit by reading the type and scope from the current branch name. The commit message header is always `type(scope): description` — you only supply the description.

```sh
acta commit "add login form"
# → feat(user-auth): add login form
```

**Body**

By default there is no body — most commits don't need one. There are two ways to add one:

```sh
# Inline — pass the body with -b. Useful in scripts and LLM-driven workflows.
acta commit "add login form" -b "Supports email and SSO providers."

# Interactive — open $EDITOR. Save and exit to use the body; quit without
# saving to abort.
acta commit -e "add login form"
```

`-b` and `-e` are mutually exclusive. An empty string passed to `-b` is treated the same as no body — only a non-empty string is included in the commit.

**Options**

| Flag | Description |
|------|-------------|
| `-A` / `--stage-all` | Stage all changes (`git add -A`) before committing |
| `-P` / `--push` | Push to origin after committing (combine as `-AP`) |
| `-b BODY` / `--body` | Commit body (mutually exclusive with `-e`) |
| `-e` / `--edit` | Open `$EDITOR` to write the commit body interactively |
| `-t TYPE` / `--type` | Override the type inferred from the branch name |
| `-s SCOPE` / `--scope` | Override the scope inferred from the branch name |

The `-t` and `-s` overrides are for cases where the commit type or scope differs from the branch — for example, bumping a lockfile on a `feat` branch:

```sh
acta commit -t chore "update lockfile"    # chore(user-auth): update lockfile
acta commit -s auth-core "fix token TTL"  # feat(auth-core): fix token TTL
```

`-P` pushes after committing, handy for follow-up commits once a PR is already open. It prints a reminder to refresh the PR description, since new commits may change the PR's scope.

### `pr TITLE`

Pushes the current branch to origin (with upstream tracking), creates a GitHub PR against `main` with a conventional title derived from the branch name, prints the PR URL, then watches CI checks until they complete.

The PR title is constructed the same way as a commit header: `type(scope): title`. You supply only the human-readable title. Pass `--breaking` to mark a breaking change — it appends `!` to give `type(scope)!: title`, the conventional-commits marker. Because `ship` squash-merges the PR title onto `main`, this is where the breaking marker is recorded in history.

**Body**

By default no body is added. There are two ways to add one:

```sh
# Inline — pass the body with -b. Useful in scripts and LLM-driven workflows.
acta pr "Add login form" -b "Adds email/password and SSO login. Closes #42."

# Interactive — open $EDITOR. Save and exit to use the body;
# quit without saving to abort.
acta pr -e "Add login form"
```

`-b` and `-e` are mutually exclusive. An empty string passed to `-b` is treated the same as no body.

**Options**

| Flag | Description |
|------|-------------|
| `-b BODY` / `--body` | PR body (mutually exclusive with `-e`) |
| `-e` / `--edit` | Open `$EDITOR` to write the PR body interactively |
| `-t TYPE` / `--type` | Override the type in the PR title |
| `-s SCOPE` / `--scope` | Override the scope in the PR title |
| `--breaking` | Append `!` to `type(scope)` to mark a breaking change |

The PR URL is printed to stdout as soon as the PR is created, before CI checks begin — you can share it while checks are still running. If checks fail, the run ends with a non-zero exit code.

If `issue start` was used to begin work on the current branch, `pr` automatically appends `Closes #N` to the PR body so the linked issue is closed when the PR merges.

### `ship`

Squash-merges the current branch's PR and brings your local environment back to a clean state on `main`. Must be run from the feature branch, not from `main`.

```sh
acta ship
```

Displays the PR title and number, asks for confirmation, then executes in order:

1. Squash-merges the PR into `main`
2. Deletes the remote branch
3. Switches to local `main`
4. Pulls latest from `origin/main`
5. Force-deletes the local branch

You end up on a clean, up-to-date `main` in one step.

If the branch was started with `issue start`, `ship` also clears the active issue from local git config. If the linked issue's milestone has no remaining open issues after the merge, the milestone is closed automatically.

**Options**

| Flag | Description |
|------|-------------|
| `-y` / `--yes` | Skip the confirmation prompt |
| `-u BRANCH` | After shipping, switch to BRANCH and merge `origin/main` into it |

`-u` is for cases where you paused work on one branch to ship a dependency first:

```sh
# Shipping fix/tech-debt while feat/user-auth is parked
acta ship -u feat/user-auth
# → ships fix/tech-debt, then switches to feat/user-auth and merges origin/main
```

`-y` is useful in automated contexts where you want to ship without interactive confirmation:

```sh
acta ship -y
```

### `watch`

Re-attaches to CI checks for the current branch's PR. Useful when you want to check in on CI after navigating away from the terminal during a `pr` run.

```sh
acta watch
```

### `board`

Prints a session snapshot: the current branch and active issue, the milestone in focus with its open issues expanded, and the remaining open milestones as one-line counts. The focused milestone is the active issue's milestone, or the first open milestone when no issue is active.

```sh
acta board
# Current branch: feat/foundation
# Active issue: #4 Auth
#
# #1  Foundation — 3 issues open, 2 closed
#   #3  chore  Full data model — schema and migrations
#   #4  feat   Auth — magic link login, session, protected routes
#
# #2  Portfolio — 2 issues open
```

### `milestone new TITLE`

Creates a GitHub Milestone. The `--scope` option is required and determines the branch name prefix used by all issues in this milestone.

```sh
acta milestone new "Auth System" --scope auth
acta milestone new "Auth System" -d "Handles login and SSO." --scope auth
acta milestone new "Auth System" -e --scope auth    # opens $EDITOR
```

**Options**

| Flag | Description |
|------|-------------|
| `--scope SCOPE` | Branch scope for all issues in this milestone (required) |
| `-d DESC` / `--description` | Milestone description (mutually exclusive with `-e`) |
| `-e` / `--edit` | Open `$EDITOR` for the description |

### `milestone list`

Lists open milestones with their open/closed issue counts, under a repo header.

```sh
acta milestone list
# renov milestones:
# #1  Foundation — 3 issues open, 2 closed
# #2  Portfolio — 2 issues open
```

The closed count is omitted when nothing is closed.

### `milestone reopen NUMBER`

Reopens a closed milestone.

```sh
acta milestone reopen 1
```

### `issue new TITLE`

Creates a GitHub Issue. `--type` is required. `--milestone` is optional — an issue without one sits in the backlog. Both are required before `issue start` can be used. Type labels are created in the repository automatically on first use.

```sh
acta issue new "Add login form" --type feat
acta issue new "Add login form" --type feat --milestone 1
acta issue new "Add login form" --type feat --milestone 1 -b "Magic-link login."
acta issue new "Add login form" --type feat --milestone 1 -e
```

**Options**

| Flag | Description |
|------|-------------|
| `--type TYPE` | Conventional commit type label (required) |
| `--milestone NUMBER` | Milestone number |
| `-b BODY` / `--body` | Issue body (mutually exclusive with `-e`) |
| `-e` / `--edit` | Open `$EDITOR` for the issue body |

### `issue list`

Lists open issues grouped by milestone. With `--milestone`, lists just that milestone's issues as a flat list.

```sh
acta issue list
# #1 Foundation
#   #3  chore  Full data model — schema and migrations
#   #4  feat   Auth — magic link login, session, protected routes
#
# #2 Portfolio
#   #6  feat   Portfolio

acta issue list --milestone 1
# #3  chore  Full data model — schema and migrations
# #4  feat   Auth — magic link login, session, protected routes
```

Issues with no milestone are grouped last under `No milestone`.

### `issue start NUMBER`

Starts work on an issue: creates the branch from the milestone's scope, switches to it, records the active issue in local git config, and prints the issue body. Requires the issue to have a type label and be assigned to a milestone.

The branch is `type/scope/N-title-slug` — the issue's type and the milestone's scope, plus a third segment built from the issue number and a slug of its title. This keeps each issue on a distinct, self-describing branch even when several issues in a milestone share the same type and scope.

```sh
acta issue start 1
# On branch 'feat/auth/1-add-login', active issue is #1.
#
# ## Description
# Login form with magic link.
```

The issue body is printed so the description and acceptance criteria are in front of you as you start. The recorded active issue is used by `pr` (to append `Closes #N`) and cleared by `ship` (after merging).

### `issue discard NUMBER`

Closes an issue as "not planned".

```sh
acta issue discard 3
```

### `release`

Tags the current tip of `origin/main` and pushes the tag. It fetches the latest tags, computes the next version, shows it, and asks for confirmation before pushing. Supports CalVer and SemVer.

For SemVer the bump is derived from the conventional-commit subjects since the last tag: a `feat` bumps minor, anything else bumps patch, and once the project is stable (1.0+) a `!` breaking change bumps major. While still 0.x a breaking change is capped at minor, since a pre-1.0 breaking change must not force `v1.0.0`. There is no `--bump`: the commits decide.

```sh
acta release                  # derive and tag the next version (auto-detects scheme)
acta release --scheme semver  # force SemVer (only needed for the very first tag)
acta release --scheme calver  # use calendar versioning instead
acta release --stable         # one-time promotion of a 0.x project to v1.0.0
```

**Going stable.** `v1.0.0` is the one version the commits cannot derive: the 0.x cap stops at minor, because declaring stability is a deliberate decision. Pass `--stable` once to make that jump. After 1.0, breaking changes drive majors automatically, so there is no further override.

**Scheme detection.** If the repository already has version tags, git-acta detects the scheme automatically, so `--scheme` is not needed. If no tags exist yet, it prompts you to choose. If both CalVer and SemVer tags are found, it exits with an error; pass `--scheme` explicitly to proceed.

**Options**

| Flag | Description |
|------|-------------|
| `--scheme SCHEME` | Versioning scheme: `calver` or `semver` |
| `--stable` | Promote a 0.x project to `v1.0.0` (SemVer only, one-time) |
| `-y` / `--yes` | Skip the confirmation prompt |

## Versioning schemes

### CalVer — `vYYYY.MM.N`

Tags are tied to the calendar month, with a sequential counter that resets each month:

```
v2026.06.1
v2026.06.2
v2026.07.1   ← new month, counter resets
```

Good fit for projects that ship continuously and want version numbers that communicate when something was released.

### SemVer — `vMAJOR.MINOR.PATCH`

Standard semantic versioning. The first tag on a repo with no prior tags starts at `v0.1.0`.

```
v0.1.0 → v0.1.1   (patch)
v0.1.1 → v0.2.0   (minor)
v0.2.0 → v1.0.0   (major)
```

The tag is always placed on `origin/main`, so run `release` after shipping all PRs for the version.

## Branch naming

All commands that read from the branch name (`commit`, `pr`) expect the format `type/scope`, with an optional third `topic` segment:

```
feat/user-auth
fix/payment-timeout
chore/upgrade-deps
docs/api-reference
feat/user-auth/sso
```

The type must be one of the standard conventional commit types: `build`, `chore`, `ci`, `docs`, `feat`, `fix`, `perf`, `refactor`, `revert`, `style`, `test`. The scope must start with a letter or digit and may contain letters, digits, hyphens, and underscores — spaces and special characters are not allowed. An optional third segment may follow the scope (`type/scope/topic`) to give the branch a distinct, human-readable name; the type and scope are read from the first two segments. Type and scope are validated by `branch` before the branch is created, and by `commit` and `pr` when reading the current branch name.

## License

MIT
