Skip to content

developer-guide.md

Latest commit

 

History

History
169 lines (119 loc) · 5.21 KB

developer-guide.md

File metadata and controls

169 lines (119 loc) · 5.21 KB
Raw

Developer Guide

This guide describes the current git-drs architecture after the CLI and internal cleanup passes.

High-Level Model

git-drs sits between normal Git workflows and Syfon/Gen3-backed object workflows.

Use the tools at the right layer:

  • use git for commits, branches, merges, git pull, and plain git push
  • use git-drs for remote configuration, tracking rules, object hydration, object registration/upload, and tracked-file delete reconciliation

The important command split is:

  • git pull updates Git history and checkout state
  • git drs pull hydrates tracked pointer files already present in the checkout
  • git drs push performs the managed data push path: metadata registration, upload when needed, delete reconciliation, and then the Git push flow
  • plain git push is plain Git only

Current Package Ownership

The current codebase is organized around a few clear owners:

  • cmd/...
    • CLI entrypoints and command-local workflow
    • commands may still own substantial logic when that logic is specific to one command
  • internal/transfer
    • upload/download execution
    • pull/push progress rendering
    • delete reconciliation derived from pushed Git history
  • internal/filter
    • clean/smudge logic
    • long-running Git filter-process protocol handling
    • skip-smudge behavior
  • internal/lookup
    • scoped DRS object lookup and record matching
  • internal/gitrepo
    • repo-local Git wiring
    • .gitattributes tracking manipulation
    • repo-local path/config helpers
  • internal/remoteruntime
    • live remote runtime/client assembly from stored config
    • credential refresh/bootstrap needed to build a working client context
  • internal/config
    • persisted repo config model and config I/O
  • internal/precommit_cache
    • pre-commit cache layout, JSON types, and shared cache-path helpers
    • not the owner of hook policy

Repository-Local State

git-drs keeps local state under .git/drs/.

The important split is:

  • .git/drs/lfs/objects
    • authoritative local DRS metadata objects
    • consumed directly by commands such as git drs push and git drs query
  • .git/drs/pre-commit
    • rebuildable local cache for path/OID/external URL bookkeeping
    • currently written by git drs precommit and git drs add-url

The pre-commit cache is non-authoritative and safe to rebuild. The local DRS metadata objects are the real local source of truth.

Current Workflow Paths

Setup path

The provider-neutral git drs remote add [name] <endpoint-or-alias> ... is the standard entrypoint for connecting a repository. Provider selection, scope, authentication, and credential sources are flags rather than subcommands.

That path:

  • stores or refreshes remote config
  • prepares credentials for the selected runtime
  • bootstraps repo-local git-drs wiring when it is missing

You can still run git drs init explicitly, but the normal onboarding path is remote add.

Push path

git drs push:

  • traverses newly reachable Git objects and extracts every supported LFS/DRS pointer
  • subtracts the remote refs/git-drs/synced/* acknowledgment history
  • negotiates only unsatisfied content-addressed objects with Syfon
  • registers only missing scoped records
  • uploads only missing local payload bytes
  • pushes Git refs and then advances the synchronization acknowledgment

The acknowledgment ref is remote synchronization state, not a local cursor. It allows a later invocation from another clone to recover objects that arrived through plain git push. Removing a path does not delete its DRS record while the pointer remains reachable from retained Git history; cleanup is a separate retention operation.

The managed push path runs directly through the current Syfon client/runtime stack.

Pull path

git drs pull:

  • scans tracked pointer files in the current checkout
  • resolves matching DRS records for the configured remote scope
  • downloads payload bytes into the local cache/object area
  • hydrates worktree files

It does not run git pull.

Filter path

Git clean/smudge/filter-process integration is handled by the current filter stack:

  • git-drs clean
  • git-drs smudge
  • git-drs filter

These commands use internal/filter plus internal/transfer rather than an old custom transfer-agent model.

Pre-Commit Ownership

The current hook story is narrower than older versions of the repo:

  • git drs precommit
    • reads staged Git content only
    • updates the rebuildable .git/drs/pre-commit cache
    • does not perform network I/O
  • git drs add-url
    • writes a pointer file
    • writes authoritative local DRS metadata
    • updates the pre-commit cache for local coherence

Neither plain git push nor git drs push depends on the pre-commit cache for remote registration.

Development Notes

Building

go build

Compile-oriented sweep

GOCACHE=$(pwd)/.gocache go test ./... -run TestDoesNotExist -count=1 -vet=off

Lint

GOCACHE=$(pwd)/.gocache make lint

Real-repo verification

When debugging behavior, validate the actual workflow split:

git drs remote list
git drs ls-files
git drs ls-files --drs
git drs pull --dry-run

That usually distinguishes:

  • remote/config issues
  • tracking issues
  • hydration issues
  • DRS registration issues