SourceControl

███████╗ ██████╗ ██╗ ██╗██████╗ ██████╗███████╗
██╔════╝██╔═══██╗██║ ██║██╔══██╗██╔════╝██╔════╝
███████╗██║ ██║██║ ██║██████╔╝██║ █████╗
╚════██║██║ ██║██║ ██║██╔══██╗██║ ██╔══╝
███████║╚██████╔╝╚██████╔╝██║ ██║╚██████╗███████╗
╚══════╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝ ╚═════╝╚══════╝
██████╗ ██████╗ ███╗ ██╗████████╗██████╗ ██████╗ ██╗
██╔════╝██╔═══██╗████╗ ██║╚══██╔══╝██╔══██╗██╔═══██╗██║
██║ ██║ ██║██╔██╗ ██║ ██║ ██████╔╝██║ ██║██║
██║ ██║ ██║██║╚██╗██║ ██║ ██╔══██╗██║ ██║██║
╚██████╗╚██████╔╝██║ ╚████║ ██║ ██║ ██║╚██████╔╝███████╗
╚═════╝ ╚═════╝ ╚═╝ ╚═══╝ ╚═╝ ╚═╝ ╚═╝ ╚═════╝ ╚══════╝

A Git-like version control system implemented from scratch in Go.

---

Overview

SourceControl (srcc) is a ground-up implementation of the core Git object model and workflow in Go. It reproduces the fundamental mechanics of Git — content-addressed object storage, a binary staging index, branch references, and commit history — while serving as a clear, well-structured reference for how version control systems work internally.

This is not a wrapper around Git. Every component — blob/tree/commit objects, the index, reference management, and the working directory reconciler — is written from scratch.

---

Features

• Core object model — blob, tree, and commit objects stored with DEFLATE compression and SHA-1 addressing
• Staging area — binary index with SHA-1 checksum integrity and O(1) entry lookup
• Branch management — create, delete, rename, and checkout branches including orphan branches and detached HEAD
• Commit history — BFS traversal of the commit DAG with configurable depth
• Working directory status — detects modified, deleted, and untracked files
• Hierarchical configuration — command-line > repo > user > system precedence
• Colored terminal output — readable, Git-familiar UI via lipgloss
• Cross-platform — Linux, macOS (Intel + ARM), Windows
• Concurrent operations — generic worker pool for parallel object processing

---

Installation

Prerequisites

• Go 1.24.2 or later

Build from source

git clone https://github.com/utkarsh5026/SourceControl.git
cd SourceControl/sourcecontrol
make build

The binary is written to bin/sourcecontrol. Add it to your $PATH:

# Linux / macOSexport PATH="$PATH:$(pwd)/bin"# Or install to $GOPATH/bin
make install

Cross-platform builds

make build-all
# Produces:# bin/sourcecontrol-linux-amd64# bin/sourcecontrol-darwin-amd64# bin/sourcecontrol-darwin-arm64# bin/sourcecontrol-windows-amd64.exe

---

Quick Start

# Initialize a new repository
srcc init
# Create some filesecho"Hello, world!"> hello.txt
# Stage files
srcc add hello.txt
# Commit
srcc commit -m "Initial commit"# Check status
srcc status
# View history
srcc log

---

Commands

srcc init [path]

Initialize a new repository. Creates a .source/ directory (analogous to .git/).

srcc init # Initialize in current directory
srcc init ./myproject # Initialize in a specific path

---

srcc add <file...>

Stage file contents to the index.

srcc add file.txt # Stage a single file
srcc add src/main.go tests/ # Stage multiple files/directories

Output shows added:, modified:, or failed: per file.

---

srcc commit -m <message>

Create a commit from staged changes.

srcc commit -m "Fix authentication bug"

---

srcc status

Show working directory status. Displays modified, deleted, and untracked files relative to the index.

srcc status

---

srcc log

Show commit history from HEAD.

srcc log # Detailed view, last 20 commits
srcc log -n 50 # Show last 50 commits
srcc log --table # Compact table format

---

srcc branch

List, create, delete, or rename branches.

srcc branch # List all branches
srcc branch -v # List with commit info
srcc branch feature-x # Create a branch at HEAD
srcc branch feature-x abc123 # Create a branch at a specific commit
srcc branch --start-point=main fix # Create from another branch
srcc branch -d old-branch # Delete a branch
srcc branch -D old-branch # Force delete
srcc branch -m new-name # Rename current branch
srcc branch -m old new # Rename a specific branch
srcc branch -M old new # Force rename

---

srcc checkout <branch|commit>

Switch branches or check out a commit.

srcc checkout main # Switch to existing branch
srcc checkout -b feature-x # Create and switch to new branch
srcc checkout -b new abc123 # Create branch from specific commit
srcc checkout abc123 # Detached HEAD at a commit
srcc checkout -f branch # Force (discard local changes)
srcc checkout --orphan root # New orphan branch (no parents)
srcc checkout --detach HEAD # Explicitly detach HEAD

---

Global flags

--log-level string Log level: debug, info, warn, error (default "info")
--log-format string Log format: text, json (default "text")
-v, --verbose Enable verbose output (sets log level to debug)

---

Architecture

Storage layout

SourceControl uses a .source/ directory at the repository root instead of .git/:

.source/
├── objects/
│ └── ab/
│ └── cdef1234... # DEFLATE-compressed object (SHA-1 addressed)
├── refs/
│ └── heads/
│ └── main # Plain-text SHA-1 of branch tip
├── HEAD # "ref: refs/heads/main" or bare SHA-1
└── index # Binary staging area with SHA-1 checksum

Object model

All stored data is one of three object types, mirroring Git's model:

Type	Description
blob	Raw file content
tree	Directory listing (name + mode + object hash per entry)
commit	Snapshot: tree hash, parent hashes, author/committer, message

Objects are serialized as <type> <size>\0<content>, DEFLATE-compressed, and stored at a path derived from their SHA-1 hash.

Package structure

pkg/
├── objects/ # Object types and serialization
├── index/ # Staging area (binary format, O(1) entryMap)
├── store/ # File-based object store
├── commitmanager/ # Commit creation + BFS history traversal
├── refs/branch/ # Branch and HEAD management
├── workdir/ # Working directory reconciler
├── config/ # Hierarchical configuration
├── repository/ # Repository interface, path types, .gitignore
└── common/
├── err/ # Typed error system
├── fileops/ # Atomic file writes
├── logger/ # slog-based structured logging
└── concurrency/ # Generic worker pool

---

Development

All commands run from the sourcecontrol/ directory.

Running tests

make test# All tests with race detection + coverage
make test-coverage # Tests + generate coverage.html
make bench # Benchmarks# Specific package
go test -v -race ./pkg/index/...

Code quality

make fmt # Format with gofmt
make lint # golangci-lint (falls back to go vet)

Test structure

• Unit tests — per-package, table-driven with t.Run()
• Integration tests — full init → add → commit → branch workflows (integration_test.go, integration_complex_test.go)
• Compatibility tests — compare output against real Git (git_compat_test.go)

---

Dependencies

Package	Purpose
spf13/cobra	CLI framework
charmbracelet/lipgloss	Terminal styling
olekukonko/tablewriter	Table output
stretchr/testify	Test assertions
golang.org/x/sync	errgroup for concurrent ops

---

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Make your changes, ensuring make test and make lint pass
4. Run make fmt to format code before committing
5. Submit a pull request

See CHANGELOG.md for version history.