# Publishing a dirty local tree safely

Use this when a user asks whether a GitHub repository is current and the local checkout contains uncommitted work.

## Distinguish the three states

Check each independently:

1. **Remote divergence:** fetch with the repository-specific credential and compare `HEAD...origin/<branch>`.
2. **Working-tree state:** inspect `git status --short --branch`, including untracked files.
3. **Runtime validity:** build and test the complete working tree before publishing it.

`HEAD == origin/<branch>` only proves committed history is synchronized. If tracked or untracked local work exists, GitHub is still missing that work and should not be reported as current relative to the checkout.

## Completeness pitfalls

- `git diff --stat` excludes untracked files. Use `git status --short`, then stage the intended roots and inspect `git diff --cached --stat` or the staged file list before committing.
- Run `git diff --check` and check staged paths for databases, `.env` files, tokens, secrets, generated artefacts, and other private/runtime data.
- For stateful applications, create the documented database/data backup before migrations, rebuilds, or container startup that may alter persisted state.
- Do not publish a dirty tree merely because the frontend builds. Exercise backend tests, frontend/type build, service health, and relevant smoke endpoints.

## Time- and state-dependent tests

A repository update can expose stale tests whose fixtures trigger date-dependent penalties, lazy closing, migrations, or other background state changes. If product behavior is correct, make assertions relative to captured pre-action state rather than hard-coded global balances:

```python
before = get_summary()
perform_action()
after = get_summary()
assert after["posted"] == before["posted"] + expected_delta
```

For idempotency, also filter transactions by the action-specific type/comment/key instead of asserting the entire ledger has exactly one row; unrelated legitimate transactions may already exist. Preserve explicit assertions about the action response and transaction type so relative assertions do not hide regressions.

## Publish and verify

1. Stage only intended project roots/files.
2. Review staged status and staged diff statistics.
3. Commit with a feature-level message.
4. Push using a credential-safe one-shot helper.
5. Verify `git rev-parse HEAD` equals `git ls-remote origin refs/heads/<branch>`.
6. Confirm the working tree is clean and report tests/build/backup evidence separately from push evidence.