> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ellomas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing

> Building, testing, and contributing to Graft.

# Contributing

## Building

```bash theme={null}
git clone https://github.com/tomiwa-amole/graft.git
cd graft
go build -o graft ./cmd/graft
```

## Project Structure

```
graft/
├── cmd/
│   ├── graft/              ← Main binary entry point
│   └── debug/              ← Debug/verification binary
├── internal/
│   ├── cli/                ← CLI commands (Cobra)
│   ├── dag/                ← DAG store, Merkle tree, object pool, verify
│   ├── docker/             ← Docker Engine SDK wrapper
│   ├── state/              ← State file management
│   └── volume/             ← Volume bridge + rsync engine
├── features.md             ← Implementation roadmap
├── project_deep_dive.md    ← Technical deep-dive
└── scope.md                ← MSc project scope
```

## Running Tests

### Unit Tests

```bash theme={null}
go test ./...
```

Unit tests cover:

* `dag/` — Merkle tree construction, object pool CRUD, store CRUD, verification
* `state/` — State file round-trip, path resolution, schema versioning
* `volume/` — rsync clone, hardlinks, excludes, permissions
* `docker/` — Client validation (skipped if Docker unavailable)
* `cli/` — Formatter functions

### End-to-End Tests

E2E tests require a running Docker environment and are gated behind `GRAFT_E2E=1`:

```bash theme={null}
GRAFT_E2E=1 go test -tags=e2e -v -count=1 ./internal/cli/
```

The e2e tests:

1. Start a real Postgres 16 container with a named volume
2. Run the graft CLI binary against it
3. Assert state.json, graft.db, and objects/ are correctly populated
4. Test branch creation, commit, verify, checkout, rollback, and delete

The first test run takes \~60 seconds (Docker image pull + Postgres startup).

### E2E Test Smoke Test

`TestE2ESmokeCLI` runs every CLI subcommand against a real Postgres container, including:

* `graft init` with volume selection
* `graft commit` with sync hashing
* `graft verify` on clean and dirty trees
* `graft checkout` for new and existing branches
* `graft rollback` to rewind state
* `graft delete` to clean up
* `graft list` to verify output formats