drift

中文文档 · GitHub · Roadmap

Version control for creators — a content-addressed, chunk-deduplicated version control system designed for writers, illustrators, and designers. Unlike Git, which treats every file as opaque bytes, drift recognizes image and video formats, shows meaningful metadata in diffs, and stores only what actually changed through content-defined chunking.

Status: Phase 1–3.5 complete (local core + branches + filetype engines + remote sync). GUI desktop app is a planned phase; see docs/roadmap.md.

Why drift?

Features

• Content-addressed storage — BLAKE3 hashes verify integrity and dedupe automatically across snapshots and branches.
• CDC chunking — FastCDC for variable-size content-defined chunks, with a fixed-size fallback for very large files (>100 MB). zstd compression on top.
• No staging area — drift save captures the working tree as-is. Authors think about their work, not about indexes.
• Branches without merge — create experimental branches, switch freely, restore from anywhere. No merge conflicts, ever.
• Filetype engines — text (unified diff), image (format/dimension/size comparison, supports PNG/JPEG/GIF/WebP/BMP/TIFF), video (format detection + dimension parsing, supports MP4/MOV/AVI/MKV/WebM), binary (fallback). New engines plug in via a registry.
• Automatic watches — drift watch on periodically scans the workspace and auto-saves when changes are detected (default interval 300s), with auto-saves hidden from log by default.
• Remote sync — push/pull to remote storage via WebDAV or SMB, with incremental transfer and branch-scoped sync.
• Single binary — one static Go binary for macOS / Windows / Linux. No runtime, no daemons to install.

Install

go install github.com/Alei-001/drift/cmd/drift@latest

Or build from source (with version metadata injected via ldflags):

git clone https://github.com/Alei-001/drift.git
cd drift
go build -ldflags "-X github.com/Alei-001/drift/internal/version.Version=v0.1.0" -o drift ./cmd/drift

Requires Go 1.25+.

Upgrade

Once a GitHub release is published, self-upgrade to the latest version:

drift upgrade          # download and replace the current binary
drift upgrade --check  # only check for a newer release

Release assets follow the naming convention drift_<version>_<os>_<arch>.{zip|tar.gz} with an optional drift_<version>_checksums.txt (SHA-256) that is verified when present.

Quick start

# Initialize a project
cd my-novel
drift init

# Save a snapshot
drift save -m "Chapter 1 draft"

# See what changed since the last save
drift status

# Browse history (current branch chain)
drift log

# Try an experimental direction
drift branch create rewrite-ending
drift switch rewrite-ending
# ... edit files ...
drift save -m "Alt ending v1"

# Switch back; the rewrite is preserved on its own branch
drift switch main

# Inspect a specific snapshot's file changes
drift log --detail id:12ab

# Restore the workspace to a previous snapshot (auto-backs up first)
drift restore id:12ab

# Undo the last save
drift undo

# Configure a remote and sync
drift remote add origin --url https://example.com/dav/my-novel --user <user>
drift push origin            # push local data to remote
drift pull origin            # pull latest data from remote
drift clone https://example.com/dav/my-novel my-novel  # clone a remote repo

Commands

Version references

Commands that take a <version> accept:

• head — current HEAD snapshot
• id:<hash-prefix> — match by hash prefix (≥ 4 chars)
• tag:<name> — resolve via tag
• branch:<name> — resolve via branch head
• <bare-name> — shorthand for branch:<bare-name>

Project layout

cmd/                  CLI entry points (cobra commands) — no business logic
  drift/              main binary
internal/             business implementation (not importable externally)
  porcelain/          business logic: snapshot, branch, restore, lock, watch, gc
  filetype/           pluggable type engines (text/image/video/binary)
  chunker/            FastCDC + fixed-size chunking
  storage/            Storer interface + shared helpers
    backends/         filesystem (prod) and memory (tests) implementations
    refname/          branch / tag name validation
    stream/           chunk streaming helpers
  remote/             remote sync: WebDAV/SMB protocols, push/pull transfer
  core/               domain types: Hash, Chunk, Snapshot, FileEntry, Config, ...
  util/               fsutil, glob, pathutil, format, cache
  version/            build-time version metadata + self-upgrade
docs/                 design and reference docs

See AGENTS.md for the full layering rules and conventions.

Documentation

• docs/prd.md — product requirements
• docs/roadmap.md — development roadmap
• docs/cli-design.md — CLI design and output formats
• docs/architecture.md — layered architecture and data model
• docs/CODE_STANDARDS.md — coding conventions (authoritative)
• docs/CODE_REVIEW.md — code review standard
• docs/engine-plugin.md — guide for adding new filetype engines

Building and testing

go build ./...            # build all packages
go test ./...             # run all tests
go test -run TestFoo ./internal/porcelain/   # single test

No Makefile, no lint config — pure go toolchain. CI via GitHub Actions (see .github/workflows/).

Protobuf codegen

Generated files live in internal/core/*.pb.go. Regenerate with:

protoc --proto_path=internal/core --go_out=internal/core --go_opt=paths=source_relative internal/core/snapshot.proto
protoc --proto_path=internal/core --go_out=internal/core --go_opt=paths=source_relative internal/core/index.proto

The --go_opt=paths=source_relative flag is required (see AGENTS.md).

Key dependencies

• cobra — CLI framework
• zeebo/blake3 — content hashing
• klauspost/compress — zstd compression
• google.golang.org/protobuf — snapshot wire format
• PlakarKorp/go-cdc-chunkers — FastCDC implementation
• hashicorp/golang-lru/v2 — chunk and preview caches

License

MIT — see the LICENSE file for details.