A Temporal Knowledge Graph for Git
GitAtlas converts Git repositories into a deterministic temporal knowledge graph stored in Apache HugeGraph. It indexes commits, branches, authors, and files as vertices and edges, enabling graph-based exploration of repository evolution through HugeGraph Hubble.
Deterministic before intelligent.
# 1. Build
go build -o gitatlas ./cmd/gitatlas-cli/
# 2. Start infrastructure
docker compose up -d
# 3. Initialize workspace
./gitatlas init
# 4. Verify everything is healthy
./gitatlas doctor
# 5. Index a repository
./gitatlas index https://github.com/apache/hugegraph.git
# 6. Open Hubble to explore the graph
open http://localhost:8088Git Repository
│
▼
Sync Engine ─── Git Provider (os/exec)
│
▼
Git Events (CommitDiscovered, FileModified, BranchCreated, ...)
│
▼
Graph Transformer
│
▼
Graph Events (AddVertex, AddEdge, ...)
│
▼
Validator
│
▼
Storage Adapter ─── HugeGraph (Gremlin)
Vertices: Repository, Branch, Commit, Author, File
Edges: HAS_BRANCH, HEAD, AUTHORED, PARENT, MODIFIED
- Git is the source of truth. The graph is derived entirely from Git history.
- Graph Events are the canonical protocol. Components communicate through immutable events.
- Storage is replaceable. The
StorageAdapterinterface decouples the engine from HugeGraph. - Incremental over full rebuilds. Only new commits are processed on re-sync.
- Deterministic. Given the same repository state, GitAtlas always produces an identical graph.
| Command | Description |
|---|---|
gitatlas init |
Initialize workspace directories |
gitatlas index <url> |
Clone and index a Git repository |
gitatlas sync |
Incrementally sync all indexed repositories |
gitatlas stats |
Display repository and graph statistics |
gitatlas doctor |
Verify infrastructure health (Git, Docker, HugeGraph, Hubble) |
gitatlas version |
Print version |
gitatlas/
├── cmd/gitatlas-cli/ # CLI entrypoint
├── internal/
│ ├── events/ # GitEvent and GraphEvent definitions
│ ├── git/ # GitProvider, NativeGitProvider, Scanner
│ ├── sync/ # SyncEngine (clone, fetch, incremental resume)
│ ├── schema/ # Graph vertex and edge label constants
│ ├── transformer/ # GitEvent → GraphEvent mapping
│ ├── validator/ # Graph integrity checks
│ └── storage/
│ ├── adapter.go # StorageAdapter interface
│ └── hugegraph/ # HugeGraph Gremlin implementation
├── docs/ # Architecture documentation
├── tests/ # Integration and e2e tests
├── docker-compose.yml # HugeGraph + Hubble stack
└── README.md
- Go 1.21+
- Git
- Docker and Docker Compose
# Clone the project
git clone https://github.com/bitflicker64/gitatlas.git
cd gitatlas
# Start HugeGraph and Hubble
docker compose up -d
# Wait for HugeGraph to become healthy (~30s)
docker compose ps
# Build
go build -o gitatlas ./cmd/gitatlas-cli/
# Run tests
go test -v ./...The docker-compose.yml provisions:
| Service | Port | Purpose |
|---|---|---|
| HugeGraph Server | 8080 |
Graph database (Gremlin endpoint) |
| Hubble | 8088 |
Web-based graph visualization |
# Start
docker compose up -d
# Check health
curl http://localhost:8080/versions
# Stop
docker compose downGitAtlas uses environment variables for configuration:
| Variable | Default | Description |
|---|---|---|
GITATLAS_HUGEGRAPH_URL |
http://localhost:8080/graphs/hugegraph |
HugeGraph Gremlin endpoint |
# Check container logs
docker compose logs hugegraph
# Restart
docker compose down && docker compose up -d- Ensure Docker is running:
docker ps - Wait for health check to pass:
docker compose ps - Verify manually:
curl http://localhost:8080/versions
- Verify the repository URL is correct and accessible.
- Check network connectivity.
- For private repositories, ensure Git credentials are configured.
- GitAtlas streams Git history and batches graph mutations (default: 500 events/batch).
- For very large repositories (100k+ commits), ensure sufficient system memory.
The following are explicitly out of scope:
- REST API / WebSockets
- AST parsing / code analysis
- Semantic search / embeddings
- AI / LLM integration
- Neo4j support
- Timeline replay / Story Mode
- Sigma.js frontend
MIT