# squash-for-github branch strategy

`squash-for-github` is a curated public-facing branch. It has its own orphan
history (unrelated to `main`) and grows by appending one large squash commit
each time you want to publish a batch of work.

## When to use

Whenever `main` has accumulated enough work worth publishing — typically after a
meaningful feature set or before tagging a release.

## How it works

`squash-for-github` and `main` have completely unrelated histories (different
root commits). Because of this, `git merge --squash` won't work. Instead, use
`git commit-tree` to create a new commit that carries **main's file tree** but
is **parented to the current squash-for-github tip**.

## Steps

1. **Collect commit messages** to write the summary:

   ```bash
   git log --oneline main ^squash-for-github
   ```

2. **Switch to the branch:**

   ```bash
   git checkout squash-for-github
   ```

3. **Create the squash commit** (replace the message with your summary):

   ```bash
   NEW=$(git commit-tree main^{tree} -p HEAD -m "feat: your summary here")
   git reset --hard $NEW
   ```

   Or as a one-liner with a heredoc for a multi-line message:

   ```bash
   git reset --hard $(git commit-tree main^{tree} -p HEAD -m "$(cat <<'EOF'
   feat: short title

   - bullet one
   - bullet two
   EOF
   )")
   ```

4. **Verify:**

   ```bash
   git log --oneline squash-for-github | head -5
   ```

5. **Push** when ready:

   ```bash
   git push origin squash-for-github
   # or force-push if you've rewritten history on the remote:
   git push --force origin squash-for-github
   ```

6. **Return to main:**

   ```bash
   git checkout main
   ```

## Why not `git merge --squash`?

The two branches share no common ancestor, so git refuses with
`fatal: refusing to merge unrelated histories`. `git commit-tree` bypasses this
by directly constructing the commit object: it takes the tree (file snapshot)
from `main`, sets the parent to the current `squash-for-github` tip, and
attaches your custom message — no merge machinery needed.