git-clerk 0.1.0__py3-none-any.whl

git_clerk/__init__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("git-clerk")

git_clerk/branch.py

@@ -0,0 +1,38 @@
+import re
+
+TYPES = frozenset(
+    [
+        "build",
+        "chore",
+        "ci",
+        "docs",
+        "feat",
+        "fix",
+        "perf",
+        "refactor",
+        "revert",
+        "style",
+        "test",
+    ]
+)
+
+
+_BRANCH_RE = re.compile(r"([^/]+)/([^/]+)")
+_SCOPE_RE = re.compile(r"[a-z0-9][a-z0-9_-]*", re.IGNORECASE)
+
+
+def parse(branch: str) -> tuple[str, str]:
+    m = _BRANCH_RE.fullmatch(branch)
+    if not m:
+        raise ValueError(f"Branch '{branch}' does not follow type/scope convention")
+    type_ = m.group(1)
+    if type_ not in TYPES:
+        raise ValueError(
+            f"'{type_}' is not a conventional commit type. Use one of: {', '.join(sorted(TYPES))}"
+        )
+    scope = m.group(2)
+    if not _SCOPE_RE.fullmatch(scope):
+        raise ValueError(
+            f"'{scope}' is not a valid scope. Use letters, digits, hyphens, and underscores."
+        )
+    return type_, scope

git_clerk/cli.py

@@ -0,0 +1,259 @@
+import subprocess
+import sys
+from datetime import date
+
+import click
+
+from git_clerk import git
+from git_clerk import github as gh
+from git_clerk.branch import TYPES
+from git_clerk.branch import parse as parse_branch
+from git_clerk.release import CALVER, SEMVER, Scheme, detect_scheme, next_calver, next_semver
+
+TYPE_CHOICE = click.Choice(sorted(TYPES))
+
+
+class _Group(click.Group):
+    def invoke(self, ctx: click.Context) -> object:
+        try:
+            return super().invoke(ctx)
+        except subprocess.CalledProcessError as e:
+            sys.exit(e.returncode)
+        except RuntimeError as e:
+            raise click.ClickException(str(e)) from e
+
+
+def _strip_comments(text: str) -> str:
+    return "\n".join(line for line in text.splitlines() if not line.startswith("#")).strip()
+
+
+def _open_editor(hint: str) -> str:
+    template = f"# {hint}\n# Lines starting with '#' are ignored.\n\n"
+    raw = click.edit(template)
+    result = _strip_comments(raw or "")
+    if not result:
+        raise click.Abort()
+    return result
+
+
+@click.group(cls=_Group, invoke_without_command=True)
+@click.version_option(package_name="git-clerk")
+@click.pass_context
+def main(ctx: click.Context) -> None:
+    """Structured git workflow: conventional commits, trunk-based branches, GitHub PR lifecycle.
+
+    Branch names follow the type/scope convention from the conventional commits specification.
+    See https://www.conventionalcommits.org for the full spec.
+    """
+    if ctx.invoked_subcommand is None:
+        click.echo(ctx.get_help())
+
+
+@main.command()
+@click.argument("name", metavar="TYPE/scope")
+def branch(name: str) -> None:
+    """Create a branch from origin/main."""
+    try:
+        parse_branch(name)
+    except ValueError as e:
+        raise click.ClickException(str(e))
+    git.fetch_origin()
+    git.switch_new_branch(name)
+
+
+@main.command()
+@click.option("-A", "stage_all", is_flag=True, help="Stage all changes before committing.")
+@click.option(
+    "-t",
+    "--type",
+    "type_override",
+    default=None,
+    metavar="TYPE",
+    type=TYPE_CHOICE,
+    help="Override the commit type inferred from the branch name.",
+)
+@click.option(
+    "-s",
+    "--scope",
+    "scope_override",
+    default=None,
+    help="Override the commit scope inferred from the branch name.",
+)
+@click.option("-e", "--edit", "edit_body", is_flag=True, help="Open $EDITOR for commit body.")
+@click.argument("description")
+@click.argument("body", required=False, default=None)
+def commit(
+    stage_all: bool,
+    type_override: str | None,
+    scope_override: str | None,
+    edit_body: bool,
+    description: str,
+    body: str | None,
+) -> None:
+    """Create a conventional commit from the branch name.
+
+    Type and scope are derived from the branch. By default no body is added —
+    pass BODY as a second argument for an inline body, or use -e to open $EDITOR.
+    BODY and -e are mutually exclusive.
+    """
+    if body and edit_body:
+        raise click.UsageError("BODY and --edit are mutually exclusive")
+    br = git.current_branch()
+    try:
+        type_, scope = parse_branch(br)
+    except ValueError as e:
+        raise click.ClickException(str(e))
+    header = f"{type_override or type_}({scope_override or scope}): {description}"
+    if edit_body:
+        body = _open_editor(header)
+    if stage_all:
+        git.add_all()
+    git.commit(header, body)
+
+
+@main.command()
+@click.option(
+    "-t",
+    "--type",
+    "type_override",
+    default=None,
+    metavar="TYPE",
+    type=TYPE_CHOICE,
+    help="Override the PR title type inferred from the branch name.",
+)
+@click.option(
+    "-s",
+    "--scope",
+    "scope_override",
+    default=None,
+    help="Override the PR title scope inferred from the branch name.",
+)
+@click.option("-e", "--edit", "edit_body", is_flag=True, help="Open $EDITOR for the PR body.")
+@click.argument("title")
+@click.argument("body", required=False, default=None)
+def pr(
+    type_override: str | None,
+    scope_override: str | None,
+    edit_body: bool,
+    title: str,
+    body: str | None,
+) -> None:
+    """Push branch, open a PR against main, and watch CI.
+
+    By default no body is added — pass BODY as a second argument for an inline
+    body, or use -e to open $EDITOR. BODY and -e are mutually exclusive.
+    """
+    if body and edit_body:
+        raise click.UsageError("BODY and --edit are mutually exclusive")
+    br = git.current_branch()
+    try:
+        type_, scope = parse_branch(br)
+    except ValueError as e:
+        raise click.ClickException(str(e))
+    pr_title = f"{type_override or type_}({scope_override or scope}): {title}"
+    if edit_body:
+        body = _open_editor(f"{pr_title} ({br})")
+    git.push_head()
+    number, url = gh.pr_create(pr_title, body or "")
+    click.echo(url)
+    gh.pr_checks_watch(number)
+
+
+@main.command()
+@click.option(
+    "-u",
+    "--update",
+    "update_branch",
+    default=None,
+    metavar="BRANCH",
+    help="After shipping, switch to BRANCH and merge origin/main.",
+)
+@click.option("-y", "--yes", "confirmed", is_flag=True, help="Skip confirmation prompt.")
+def ship(update_branch: str | None, confirmed: bool) -> None:
+    """Ship the PR and return to a clean main.
+
+    Squash-merges the current branch's PR, deletes the remote branch, switches
+    to local main, pulls, and force-deletes the local branch.
+    """
+    br = git.current_branch()
+    if br == "main":
+        raise click.ClickException("run 'git clerk ship' from the feature branch, not main")
+    number, title = gh.pr_view()
+    prompt = f'Ship "{title}" (#{number})'
+    if update_branch:
+        prompt += f", then update {update_branch}"
+    if not confirmed:
+        click.confirm(prompt, abort=True)
+    if not gh.pr_checks_pass(number):
+        raise click.ClickException(
+            f"PR #{number} has failing or pending checks — run 'git clerk watch' to monitor"
+        )
+    gh.pr_merge(number)
+    git.switch_main()
+    git.pull_origin_main()
+    if git.branch_exists(br):
+        git.delete_branch(br)
+    else:
+        click.echo(f"warning: local branch '{br}' not found, skipping delete", err=True)
+    if update_branch:
+        git.switch_branch(update_branch)
+        git.merge_origin_main()
+
+
+@main.command()
+def watch() -> None:
+    """Watch CI checks for the current PR."""
+    number, _ = gh.pr_view()
+    gh.pr_checks_watch(number)
+
+
+@main.command()
+@click.option(
+    "--calver",
+    "scheme",
+    flag_value=CALVER,
+    default=None,
+    help="Use calendar versioning (vYYYY.MM.N).",
+)
+@click.option(
+    "--semver",
+    "scheme",
+    flag_value=SEMVER,
+    default=None,
+    help="Use semantic versioning (vMAJOR.MINOR.PATCH).",
+)
+@click.option(
+    "--bump",
+    type=click.Choice(["patch", "minor", "major"]),
+    default="patch",
+    help="SemVer component to increment (ignored for CalVer).",
+)
+@click.option("-y", "--yes", "confirmed", is_flag=True, help="Skip confirmation prompt.")
+def release(scheme: Scheme | None, bump: str, confirmed: bool) -> None:
+    """Tag origin/main and push the tag.
+
+    Auto-detects CalVer or SemVer from existing tags. Prompts for scheme on
+    first use. Pass --calver or --semver to skip the prompt.
+    """
+    git.fetch_tags()
+    existing = git.tags()
+    if not scheme:
+        try:
+            scheme = detect_scheme(existing)
+        except ValueError as e:
+            raise click.ClickException(str(e))
+    if not scheme:
+        click.echo("No existing tags found. Choose a versioning scheme:")
+        click.echo(
+            f"  {CALVER}   vYYYY.MM.N         — calendar versioning, counter resets each month"
+        )
+        click.echo(f"  {SEMVER}   vMAJOR.MINOR.PATCH — semantic versioning")
+        raw = click.prompt(
+            "Scheme", type=click.Choice([CALVER, SEMVER], case_sensitive=False), show_choices=False
+        )
+        scheme = CALVER if raw == CALVER else SEMVER
+    tag = next_calver(existing, date.today()) if scheme == CALVER else next_semver(existing, bump)
+    if not confirmed:
+        click.confirm(f"Tag and push {tag}", abort=True)
+    git.create_tag(tag)
+    click.echo(f"Tagged and pushed {tag}")

git_clerk/git.py

@@ -0,0 +1,89 @@
+import subprocess
+
+
+def _git(*args: str, capture: bool = False) -> str:
+    try:
+        result = subprocess.run(
+            ["git", *args],
+            check=True,
+            text=True,
+            stdout=subprocess.PIPE if capture else None,
+        )
+        return result.stdout.strip() if result.stdout else ""
+    except FileNotFoundError:
+        raise RuntimeError("'git' not found in PATH — install git: https://git-scm.com/install/")
+    except subprocess.CalledProcessError:
+        raise
+
+
+def current_branch() -> str:
+    return _git("branch", "--show-current", capture=True)
+
+
+def fetch_origin() -> None:
+    _git("fetch", "origin")
+
+
+def fetch_tags() -> None:
+    _git("fetch", "--tags", "origin")
+
+
+def switch_new_branch(name: str) -> None:
+    _git("switch", "-c", name, "origin/main")
+
+
+def switch_main() -> None:
+    _git("switch", "main")
+
+
+def pull_origin_main() -> None:
+    _git("pull", "origin", "main")
+
+
+def branch_exists(name: str) -> bool:
+    return bool(_git("branch", "--list", name, capture=True))
+
+
+def delete_branch(name: str) -> None:
+    _git("branch", "-D", name)
+
+
+def switch_branch(name: str) -> None:
+    _git("switch", name)
+
+
+def merge_origin_main() -> None:
+    _git("merge", "origin/main")
+
+
+def add_all() -> None:
+    _git("add", "-A")
+
+
+def commit(header: str, body: str | None = None) -> None:
+    args = ["commit", "-m", header]
+    if body:
+        args += ["-m", body]
+    _git(*args)
+
+
+def push_head() -> None:
+    _git("push", "--set-upstream", "origin", "HEAD")
+
+
+def remote_url(name: str) -> str:
+    return _git("remote", "get-url", name, capture=True)
+
+
+def tags(pattern: str = "v*") -> list[str]:
+    return [t for t in _git("tag", "--list", pattern, capture=True).splitlines() if t]
+
+
+def create_tag(tag: str, ref: str = "origin/main") -> None:
+    fetch_tags()
+    if tag in tags():
+        raise RuntimeError(
+            f"tag '{tag}' already exists — re-run 'git clerk release' to get the next version"
+        )
+    _git("tag", tag, ref)
+    _git("push", "origin", tag)

git_clerk/github.py

@@ -0,0 +1,86 @@
+import functools
+import json
+import subprocess
+from urllib.parse import urlparse
+
+from git_clerk.git import remote_url
+
+
+def parse_repo_from_url(url: str) -> str:
+    if "://" in url:
+        path = urlparse(url).path.lstrip("/")
+    else:
+        _, _, path = url.partition(":")
+    repo = path.removesuffix(".git")
+    parts = repo.split("/")
+    if len(parts) != 2 or not all(parts):
+        raise ValueError(f"cannot parse GitHub repo from remote URL: {url}")
+    return repo
+
+
+def _gh(*args: str, capture: bool = False) -> str:
+    try:
+        result = subprocess.run(
+            ["gh", *args],
+            check=True,
+            text=True,
+            stdout=subprocess.PIPE if capture else None,
+        )
+        return result.stdout.strip() if result.stdout else ""
+    except FileNotFoundError:
+        raise RuntimeError(
+            "'gh' not found in PATH — install the GitHub CLI: https://cli.github.com"
+        )
+    except subprocess.CalledProcessError:
+        raise
+
+
+@functools.cache
+def repo() -> str:
+    url = remote_url("origin")
+    try:
+        return parse_repo_from_url(url)
+    except ValueError as e:
+        raise RuntimeError(str(e)) from e
+
+
+def pr_create(title: str, body: str, base: str = "main") -> tuple[int, str]:
+    out = _gh(
+        "pr",
+        "create",
+        "--base",
+        base,
+        "--title",
+        title,
+        "--body",
+        body,
+        "--repo",
+        repo(),
+        "--json",
+        "number,url",
+        capture=True,
+    )
+    data = json.loads(out)
+    return int(data["number"]), str(data["url"])
+
+
+def pr_view() -> tuple[int, str]:
+    out = _gh("pr", "view", "--repo", repo(), "--json", "number,title", capture=True)
+    data = json.loads(out)
+    return int(data["number"]), str(data["title"])
+
+
+def pr_checks_pass(pr_number: int) -> bool:
+    try:
+        _gh("pr", "checks", str(pr_number), "--repo", repo(), capture=True)
+        return True
+    except subprocess.CalledProcessError:
+        return False
+
+
+def pr_merge(pr_number: int) -> None:
+    _gh("pr", "merge", str(pr_number), "--squash", "--delete-branch", "--repo", repo())
+
+
+def pr_checks_watch(pr_number: int) -> None:
+    _gh("pr", "checks", str(pr_number), "--repo", repo(), "--watch")

git_clerk/release.py

@@ -0,0 +1,48 @@
+import re
+from datetime import date
+from typing import Final, Literal, TypeAlias
+
+CALVER: Final = "CalVer"
+SEMVER: Final = "SemVer"
+Scheme: TypeAlias = Literal["CalVer", "SemVer"]
+
+_CALVER_RE = re.compile(r"v\d{4}\.\d{2}\.\d+")
+_SEMVER_RE = re.compile(r"v\d+\.\d+\.\d+")
+
+
+def detect_scheme(tags: list[str]) -> Scheme | None:
+    found: set[Scheme] = set()
+    for t in tags:
+        if _CALVER_RE.fullmatch(t):
+            found.add(CALVER)
+        elif _SEMVER_RE.fullmatch(t):
+            found.add(SEMVER)
+    if not found:
+        return None
+    if len(found) > 1:
+        raise ValueError(
+            f"mixed {CALVER} and {SEMVER} tags found — pass --calver or --semver to proceed"
+        )
+    return next(iter(found))
+
+
+def next_calver(tags: list[str], today: date) -> str:
+    prefix = f"v{today.year}.{today.month:02d}."
+    existing = [t for t in tags if re.fullmatch(rf"{re.escape(prefix)}\d+", t)]
+    last = max((int(t[len(prefix) :]) for t in existing), default=0)
+    return f"{prefix}{last + 1}"
+
+
+def next_semver(tags: list[str], bump: str) -> str:
+    semver_tags = sorted(
+        [t for t in tags if _SEMVER_RE.fullmatch(t) and not _CALVER_RE.fullmatch(t)],
+        key=lambda t: tuple(int(x) for x in t[1:].split(".")),
+    )
+    if not semver_tags:
+        return "v0.1.0"
+    major, minor, patch = (int(x) for x in semver_tags[-1][1:].split("."))
+    if bump == "major":
+        return f"v{major + 1}.0.0"
+    if bump == "minor":
+        return f"v{major}.{minor + 1}.0"
+    return f"v{major}.{minor}.{patch + 1}"

git_clerk-0.1.0.dist-info/METADATA

@@ -0,0 +1,344 @@
+Metadata-Version: 2.4
+Name: git-clerk
+Version: 0.1.0
+Summary: Structured git workflow CLI: conventional commits, trunk-based branches, GitHub PR lifecycle
+Project-URL: Homepage, https://github.com/nicobc/git-clerk
+Project-URL: Source, https://github.com/nicobc/git-clerk
+Project-URL: Issues, https://github.com/nicobc/git-clerk/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-clerk
+
+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-clerk 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-clerk 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-clerk 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).
+
+If your workflow diverges from any of these, git-clerk 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`) authenticated to your GitHub account
+
+**Repository configuration**
+
+git-clerk 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 `git clerk ship`'s CI gate structural rather than advisory
+
+## Installation
+
+```sh
+uv tool install git-clerk
+```
+
+To use it as `git clerk` (recommended) rather than `git-clerk`, register a git alias:
+
+```sh
+git config --global alias.clerk '!git-clerk'
+```
+
+After this, `git clerk` prints help and `git clerk commit --help` (any subcommand) works as expected. Note that `git clerk --help` will not work — git intercepts `--help` before running the alias and tries to open a man page. Use `git clerk` or `git-clerk --help` for top-level help instead.
+
+## Workflow walkthrough
+
+Here is a complete cycle from starting a feature to tagging a release.
+
+**1. Create a branch**
+
+```sh
+git clerk 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
+git clerk 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 as a second argument or open your editor with `-e`:
+
+```sh
+git clerk commit -A "add login form" "Supports email and SSO providers."
+# → commits with inline body (useful in scripts and LLM workflows)
+
+git clerk 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
+git clerk 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
+git clerk pr "Add login form" "Adds email/password and SSO login. Closes #42."
+# inline body
+
+git clerk pr -e "Add login form"
+# opens $EDITOR for the body
+```
+
+**4. Ship it**
+
+Once CI is green:
+
+```sh
+git clerk 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
+git clerk 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.
+
+## Commands
+
+### `branch TYPE/scope`
+
+Fetches the latest `origin/main` and creates a new branch from it.
+
+```sh
+git clerk branch feat/user-auth     # → feat/user-auth
+git clerk branch fix/payment-api    # → fix/payment-api
+git clerk branch chore/deps         # → chore/deps
+```
+
+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.
+
+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 [BODY]`
+
+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
+git clerk 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 three ways to add one:
+
+```sh
+# Inline — pass the body as a second positional argument.
+# Useful in scripts and LLM-driven workflows.
+git clerk commit "add login form" "Supports email and SSO providers."
+
+# Interactive — open $EDITOR. Save and exit to use the body; quit without
+# saving to commit with no body.
+git clerk commit -e "add login form"
+```
+
+An empty string passed as BODY is treated the same as no body — only a non-empty string is included in the commit.
+
+**Options**
+
+| Flag | Description |
+|------|-------------|
+| `-A` | Stage all changes (`git add -A`) before committing |
+| `-e` | Open `$EDITOR` to write the commit body interactively |
+| `-t TYPE` | Override the type inferred from the branch name |
+| `-s 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
+git clerk commit -t chore "update lockfile"    # chore(user-auth): update lockfile
+git clerk commit -s auth-core "fix token TTL"  # feat(auth-core): fix token TTL
+```
+
+### `pr TITLE [BODY]`
+
+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.
+
+**Body**
+
+By default no body is added. There are two ways to add one:
+
+```sh
+# Inline — pass the body as a second positional argument.
+# Useful in scripts and LLM-driven workflows.
+git clerk pr "Add login form" "Adds email/password and SSO login. Closes #42."
+
+# Interactive — open $EDITOR. Save and exit to use the body;
+# quit without saving to create the PR with no body.
+git clerk pr -e "Add login form"
+```
+
+An empty string passed as BODY is treated the same as no body.
+
+**Options**
+
+| Flag | Description |
+|------|-------------|
+| `-e` | Open `$EDITOR` to write the PR body interactively |
+| `-t TYPE` | Override the type in the PR title |
+| `-s SCOPE` | Override the scope in the PR title |
+
+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.
+
+### `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
+git clerk 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 local branch doesn't exist — because you're shipping someone else's PR, or because a previous partial run already cleaned it up — step 5 is skipped with a warning rather than erroring.
+
+**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
+git clerk 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
+git clerk 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
+git clerk watch
+```
+
+### `release`
+
+Tags the current tip of `origin/main` and pushes the tag. Supports CalVer and SemVer.
+
+git-clerk fetches the latest tags, computes the next version, shows you what it's about to create, and asks for confirmation before pushing anything.
+
+```sh
+git clerk release                      # auto-detect scheme, bump patch
+git clerk release --semver --bump minor
+git clerk release --semver --bump major
+git clerk release --calver
+```
+
+**Scheme detection**
+
+If the repository already has version tags, git-clerk detects the scheme automatically — `--calver` and `--semver` are not needed. If no tags exist yet, git-clerk prompts you to choose interactively. Pass `--calver` or `--semver` to skip the prompt.
+
+If both CalVer and SemVer tags are found (e.g. after a scheme migration), git-clerk exits with an error. Pass `--calver` or `--semver` explicitly to proceed.
+
+**Options**
+
+| Flag | Description |
+|------|-------------|
+| `--calver` | Use calendar versioning |
+| `--semver` | Use semantic versioning |
+| `--bump patch\|minor\|major` | SemVer component to increment (default: `patch`, ignored for CalVer) |
+| `-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`:
+
+```
+feat/user-auth
+fix/payment-timeout
+chore/upgrade-deps
+docs/api-reference
+```
+
+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. Both are validated by `branch` before the branch is created, and by `commit` and `pr` when reading the current branch name.
+
+## License
+
+MIT

git_clerk-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+git_clerk/__init__.py,sha256=8BtIFmZ7QzCXpAOVOP2WRuwGPff3ys5oDGy40GaeMPs,75
+git_clerk/branch.py,sha256=BspKuAphvFLn9goWtL-ZsRViHdhLLNLZ3HjfgyNoCAY,916
+git_clerk/cli.py,sha256=I8w0UPQBwbLZHbjCGlpu23lOnn9hg4PG0wS6Rozsga0,8094
+git_clerk/git.py,sha256=uF5sgn9wqyxjE6VEq1s9YGncVvAUxcUbfKt9F2X2GUQ,2039
+git_clerk/github.py,sha256=lzAYGSFboxkFPkp4S2PAMCx6tuNaRBMuUXzfElMBZzk,2238
+git_clerk/release.py,sha256=b4njsPuDXVSqbtZqAmiiEZ_sLlqFl0WqAXTzYAR92ZA,1543
+git_clerk-0.1.0.dist-info/METADATA,sha256=1XtEA76QxVguLWL4tZrFu-8hhSX0-XY8uJ4MGjj0B_Q,13093
+git_clerk-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+git_clerk-0.1.0.dist-info/entry_points.txt,sha256=awNt9zi4cbzw_UuwiHwBozIbLWiv050FymS2dj22B-s,49
+git_clerk-0.1.0.dist-info/licenses/LICENSE,sha256=fXPx6-tt0xoJ3o87wko0BcBptkIprKNhzwrZTek3_7c,1074
+git_clerk-0.1.0.dist-info/RECORD,,

git_clerk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

git_clerk-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+git-clerk = git_clerk.cli:main

git_clerk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nicolas Contreras
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.