# Git Workflow And Versioning

> Structures git workflow practices. Use when making any code change. Use when committing, branching, or when you need to organize work. Use when this capability is needed.

- Skill: `tomevault-io/git-workflow-and-versioning-11` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/git-workflow-and-versioning-11`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/git-workflow-and-versioning-11/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/git-workflow-and-versioning-11

---


# Git Workflow and Versioning

## Overview

Git is your safety net. Treat commits as save points, branches as sandboxes, and history as documentation. With TDD, each Red → Green → Refactor cycle produces a natural commit point.

## When to Use

Always. Every code change flows through git.

## Core Principles

### 1. Commit After Each TDD Cycle

Each successful Red → Green → Refactor cycle gets its own commit:

```
Write failing test (Red)
    → Make it pass (Green)
        → Refactor
            → npm test passes
                → Commit → Next cycle
```

### 2. Atomic Commits

Each commit does one logical thing:

```
# Good: Each commit is self-contained
a1b2c3d test: add failing test for metric calculation edge case
d4e5f6g feat: handle empty data arrays in calculateMetric
h7i8j9k refactor: extract threshold logic to utility function
m1n2o3p test: add regression test for tooltip bug #42

# Bad: Everything mixed together
x1y2z3a Add feature, fix sidebar, update deps, refactor utils
```

### 3. Descriptive Messages

```
<type>: <short description>

<optional body explaining why, not what>
```

**Types:**

- `feat` — New feature
- `fix` — Bug fix
- `refactor` — Code change that doesn't fix a bug or add a feature
- `test` — Adding or updating tests
- `docs` — Documentation only
- `chore` — Tooling, dependencies, config

### 4. Keep Concerns Separate

Don't combine formatting changes with behavior changes:

```
# Good: Separate concerns
git commit -m "refactor: extract data transform to shared utility"
git commit -m "feat: add confidence interval to scatter plot"

# Bad: Mixed concerns
git commit -m "refactor and add confidence interval"
```

### 5. Size Your Changes

```
~100 lines  → Easy to review, easy to revert
~300 lines  → Acceptable for a single logical change
~1000 lines → Split into smaller changes
```

## Branching Strategy

```
main (always deployable)
  │
  ├── feature/new-chart-type    ← One feature per branch
  ├── feature/tooltip-redesign  ← Parallel work
  └── fix/scatter-plot-crash    ← Bug fixes
```

- Branch from `main`
- Keep branches short-lived (merge within 1-3 days)
- Delete branches after merge

### Branch Naming

```
feature/<short-description>   → feature/box-plot-module
fix/<short-description>       → fix/bar-chart-null-data
chore/<short-description>     → chore/update-chartjs
refactor/<short-description>  → refactor/data-pipeline
```

## The TDD Save Point Pattern

```
Agent starts work
    │
    ├── Writes failing test (Red)
    │   ├── Implements code (Green) → Refactors → Tests pass? → Commit
    │   └── Tests fail unexpectedly? → git reset --hard HEAD → Investigate
    │
    ├── Writes next failing test (Red)
    │   ├── Implements → Green → Refactor → Commit
    │   └── Tests fail? → Revert to last commit → Investigate
    │
    └── Feature complete → Clean history of TDD cycles
```

## Pre-Commit Hygiene

Before every commit:

```bash
# 1. Check what you're about to commit
git diff --staged

# 2. Run tests
npm test

# 3. Verify build
npm run bundle

# 4. Ensure no secrets
git diff --staged | grep -i "password\|secret\|api_key\|token"
```

## Change Summaries

After any modification, provide a structured summary:

```
CHANGES MADE:
- src/scatterPlot/config.js: Added threshold line support
- tests/scatterPlot.test.js: Added TDD tests for threshold line

THINGS I DIDN'T TOUCH (intentionally):
- src/barChart/: Has similar gap but out of scope
- src/util/colors.js: Could use refactoring (separate task)

TDD EVIDENCE:
- Failing tests written before implementation
- All tests pass: npm test
- Build succeeds: npm run bundle
```

## Common Rationalizations

| Rationalization                        | Reality                                                                      |
| -------------------------------------- | ---------------------------------------------------------------------------- |
| "I'll commit when the feature is done" | One giant commit is impossible to review or revert. Commit each TDD cycle.   |
| "The message doesn't matter"           | Messages are documentation. Future you will need to understand what changed. |
| "I'll squash it all later"             | Squashing destroys the TDD narrative. Prefer clean incremental commits.      |

## Red Flags

- Large uncommitted changes accumulating
- Commit messages like "fix", "update", "misc"
- No evidence of TDD in commit history (no test commits before implementation commits)
- Formatting changes mixed with behavior changes
- Committing `node_modules/`, `.env`, or build artifacts

## Verification

For every commit:

- [ ] Commit does one logical thing
- [ ] Message explains the why, follows type conventions
- [ ] Tests pass before committing: `npm test`
- [ ] Build succeeds: `npm run bundle`
- [ ] No secrets in the diff
- [ ] `.gitignore` covers standard exclusions

---
> Source: [Gilead-BioStats/gsm.viz](https://github.com/Gilead-BioStats/gsm.viz) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->