Skip to content
Skills Library
Programming · Automation

git-policy

/git-policy

WellForge git policy — linear history (no merge commits) and Conventional Commits, in every WellForge repo including generated ones. Use whenever writing a commit message, integrating a branch, opening or merging a PR, setting up a fresh clone, fixing a rejected commit or a red commit-lint / linear-history gate, or configuring branch protection. Authoritative reference for the commit format, the four enforcement layers (local config, committed hooks, CI gates, branch protection), the rebase-not-merge integration rule, and what to do when a gate rejects your commit.

Repository
wellforge ↗
Licence
MIT
Last repository change
14.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 14.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

WellForge git policy — linear history (no merge commits) and Conventional Commits, in every WellForge repo including generated ones. Use whenever writing a commit message, integrating a branch, opening or merging a PR, setting up a fresh clone, fixing a rejected commit or a red commit-lint / linear-history gate, or configuring branch protection. Authoritative reference for the commit format, the four enforcement layers (local config, committed hooks, CI gates, branch protection), the rebase-not-merge integration rule, and what to do when a gate rejects your commit.

Original author description

WellForge git policy — linear history (no merge commits) and Conventional Commits, in every WellForge repo including generated ones. Use whenever writing a commit message, integrating a branch, opening or merging a PR, setting up a fresh clone, fixing a rejected commit or a red commit-lint / linear-history gate, or configuring branch protection. Authoritative reference for the commit format, the four enforcement layers (local config, committed hooks, CI gates, branch protection), the rebase-not-merge integration rule, and what to do when a gate rejects your commit.

How it works

  1. The commit format
  2. Integration — rebase, never merge
  3. Four enforcement layers
  4. When a gate rejects you
  5. What this does not cover
Original SKILL.md headings · 86 lines, 665 words
SKILL.md preview
---
name: git-policy
description: >
  WellForge git policy — linear history (no merge commits) and Conventional Commits, in every
  WellForge repo including generated ones. Use whenever writing a commit message, integrating
  a branch, opening or merging a PR, setting up a fresh clone, fixing a rejected commit or a
  red commit-lint / linear-history gate, or configuring branch protection. Authoritative
  reference for the commit format, the four enforcement layers (local config, committed
  hooks, CI gates, branch protection), the rebase-not-merge integration rule, and what to do
  when a gate rejects your commit.
---

# Git policy — linear history and Conventional Commits

Two rules, non-negotiable in every WellForge repo and every project WellForge generates:

1. **Linear history.** No merge commits. Rebase onto the base branch, integrate with
   `--ff-only`, and land PRs as squash or rebase.
2. **Conventional Commits.** Every commit subject is `type(scope)!: description`.

They are not style preferences. A linear history makes `git log` a readable sequence of
changes and `git bisect` meaningful; Conventional Commits is what `/wellforge:release`
derives the version bump and CHANGELOG from, so a malformed subject silently produces a
wrong release.

## The commit format

```
<type>(<optional scope>)<optional !>: <description>

<optional body>

<optional footers>
```

Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`,
`revert`. `!` (or a `BREAKING CHANGE:` footer) marks a breaking change and drives a major
bump. Merge, revert, fixup, squash and amend commits are exempt — git generates them.

- **`feat` and `fix` move the version**, everything else does not. Choose the type by what
  the change *does* to users, not by how much work it was.
- The description says what changed, in the imperative. The body says **why**, and is where
  the failure shape belongs — the thing a future reader needs and `git log --oneline` can
  never carry.
- Reference the task and spec when there is one: `feat(export): add CSV serializer (T1,
  specs/002)`.

## Integration — rebase, never merge

```bash
git fetch origin
git rebase origin/main            # replay your work on top
git switch main && git merge --ff-only <branch>
```

`git merge --no-ff` is refused by config, by hook, and by CI. If `--ff-only` fails with
`fatal: Not possible to fast-forward`, the branch was not rebased onto the current tip —
rebase again and retry. That refusal is the policy working; reaching for a flag that forces
the merge through is the one response that is always wrong.

For a parallel batch integrating several worktree branches, [`worktree-isolation`](../worktree-isolation/SKILL.md) owns the
protocol (the rebase runs **inside** each worktree — the main tree cannot rebase a branch
that is checked out elsewhere).

## Four enforcement layers

Each catches what the previous one misses; none is sufficient alone.

| Layer | What it is | Catches |
|---|---|---|
| **Local config** | `merge.ff=only`, `pull.rebase=true`, `rebase.autoStash=true` | A merge commit before it exists. Per-clone, so it ships as a script, not a file. |
| **Committed hooks** | `gates/hooks/commit-msg`, `gates/hooks/pre-merge-commit` | A malformed subject at commit time, when fixing it is free. |
| **CI gates** | `commit-lint.yml`, `linear-history.yml`, called at **every** rigor tier | What a contributor's unconfigured clone let through. History hygiene is tier-independent — unlike coverage, it cannot be repaired after the fact without rewriting published history. |
| **Branch protection** | `required_linear_history`, `allow_merge_commit=false` | The merge button in the GitHub UI, which no local setting can reach. |

Run **`./scripts/setup-git-policy.sh`** once per clone (generated projects: `mise run
git-policy`) — it applies the config and installs the hooks. A fresh clone has none of it.

## When a gate rejects you

- **`commit-msg` hook rejected the subject** → `git commit --amend` with a conforming
  subject. The validator prints the expected shape and the type list.
- **`linear-history` CI is red** → the PR range contains a merge commit. Rebase the branch
  (`git rebase origin/main`) and force-push **with `--force-with-lease`**, which refuses if
  the remote moved under you. Plain `--force` is blocked by the plugin's bash guard for that
  reason.
- **`commit-lint` CI is red on an old commit** → rebase interactively and reword it. Fixing
  the tip alone leaves the range red.
- **You are mid-rebase and lost** → `git rebase --abort` returns you to where you started.
  Nothing is lost; the branch is unchanged until the rebase completes.

## What this does not cover

Squash-merging a PR in the GitHub UI produces one commit whose subject is the **PR title** —
so the PR title must be a Conventional Commit too. Branch protection cannot enforce that;
review it like any other line of the change.

Versions

RepositoryScoreLicence
This page · matteocodogno/wellforge100MIT
matteocodogno/wellforge100MIT

Database snapshot: 13.11.2026 · package version 1bf00adb4bb4 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100git-commit
    Guide for creating git commits in this repository: conventional commit format, allowed types, and branch naming conventions. Use when staging changes and writing a commit message, creating a branch, or naming a branch. Trigger on: "commit", "create a commit", "git commit",…
  • 100git-workflow
    Conventional commits, PR creation, and quality gate verification. Use when: commit, PR, branch, push, conventional commit, create pull request, git.
  • 100commit-message
    Generate conventional commit messages - use when creating commits, writing commit messages, or asking for git commit help
  • 100git-commit-and-workflow
    Git commit, branch and pull request best practices using Conventional Commits. Use whenever creating commits, naming branches, preparing pull requests, writing commit messages, or when asked to commit, push, merge or release code.
  • 100git-commit
    Inspect Git changes, organize logical commits, and write Conventional Commits messages. Use for /git-commit, explicit commit requests, message drafting, commit planning, and commit review. Excludes general Git troubleshooting, branch strategy, and history repair.
  • 100git-commit-hygiene-meaningful-commit-history
    Use this skill when crafting atomic Git commits, conventional commit messages, and clean linear Git branch histories.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.