Fit - Filesystem Inside Terminal

Fit is a production-grade distributed version control and backup system inspired by Git's internal architecture, written in C from scratch. It functions as both a version control system and a distributed personal backup solution between Linux machines.

Architecture

Fit reimplements Git's core concepts:

• Content-addressable storage using SHA-256 hashing
• Object model: blobs (files), trees (directories), commits
• Compression: zlib compression for all objects
• Packfiles: efficient object transfer format
• References: branches and HEAD management
• Garbage collection: removes unreachable objects
• Network protocol: custom TCP-based object transfer

Key Differences from Git

1. SHA-256 by default (Git uses SHA-1, transitioning to SHA-256)
2. Simplified protocol - custom lightweight TCP protocol with smart negotiation
3. Backup-first design - includes snapshot command for quick full-directory backups
4. Minimal dependencies - only zlib and OpenSSL
5. No delta compression yet - stores full objects (stretch goal)
6. RSA-signed commits - built-in commit signing with RSA keys
7. Shallow clone support - clone with limited history depth

Object Model

Storage Structure

.fit/
├── objects/
│   └── ab/
│       └── cdef123...  (compressed object)
├── refs/
│   └── heads/
│       └── main
├── HEAD
├── index
└── config

Object Types

1. Blob: Raw file content
2. Tree: Directory listing with modes, names, and hashes
3. Commit: Points to tree, parent commit, author, timestamp, message

Object Format

<type> <size>\0<data>

Compressed with zlib and stored at .fit/objects/<first-2-hex>/<remaining-hex>.

Network Protocol

Extensible TCP protocol on port 9418 with version negotiation:

Protocol Version 1 (Legacy)

[VERSION:1][COMMAND:1][PACKFILE_DATA]

Protocol Version 2+ (With Negotiation)

[VERSION:2][CMD_NEGOTIATE:3]
[CLIENT_MIN_VER:1][CLIENT_MAX_VER:1][CLIENT_CAPS:4]
[SERVER_MIN_VER:1][SERVER_MAX_VER:1][SERVER_CAPS:4]
[COMMAND:1][PACKFILE_DATA]

Commands:

• CMD_SEND_OBJECTS (1): Send packfile to server
• CMD_REQUEST_OBJECTS (2): Request objects from server
• CMD_NEGOTIATE (3): Initiate protocol negotiation

Capabilities:

• CAP_MULTI_THREADED: Server supports concurrent connections
• CAP_COMPRESSION: Enhanced compression support
• CAP_STREAMING: Optimized streaming transfer

The protocol automatically negotiates the highest common version and capability set between client and server, with automatic fallback to legacy protocol v1 for backward compatibility.

New Features

Signed Commits (RSA-2048)

Fit includes built-in commit signing using RSA-2048 keys, providing cryptographic verification of commit authorship without requiring external GPG setup.

• Key Generation: fit init-signing generates a private/public key pair
• Signing: Use --sign or -S flag when committing
• Verification: fit verify-commit <hash> verifies signatures
• Keys stored in: .fit/private_key.pem and .fit/public_key.pem

fit init-signing
fit commit -m "Secure commit" --sign
fit verify-commit abc123

Shallow Clones

Clone repositories with limited history depth, saving bandwidth and disk space for large repositories.

• Shallow Clone: fit clone <host> <branch> [dir] --depth <N>
• History Limit: Only fetches the last N commits
• Boundary Marker: .fit/shallow file tracks shallow boundaries
• Log Display: fit log shows "(shallow boundary)" at truncation point

fit clone server.local main ./project --depth 10

Installation

Arch Linux

# Install dependencies
sudo pacman -S gcc make zlib openssl

# Build
make

# Install
sudo make install

Alpine Linux

# Install dependencies
apk add gcc musl-dev make zlib-dev openssl-dev

# Build
make

# Install
make install

Usage

Basic Workflow

# Initialize repository
fit init

# Add files
fit add file1.txt file2.txt

# Commit changes
fit commit -m "Initial commit"

# View history
fit log

# Check status
fit status

# Compare commits
fit diff <commit1> <commit2>

Comparing Changes

# View differences between two commits
fit diff abc123 def456

# Compare a commit with HEAD
fit diff abc123

# See what changed in recent commits
fit log  # Get commit hashes
fit diff <older-hash> <newer-hash>

Branching

# List branches
fit branch

# Create branch
fit branch feature

# Switch branch (restores files)
fit checkout feature

# Merge branch
fit merge feature

Tag Management

# List tags
fit tag

# Create tag
fit tag v1.0.0

# Create tag with message
fit tag create v1.0.0 -m "Release version 1.0.0"

# Delete tag
fit tag delete v1.0.0

Remote Management

# List remotes
fit remote

# Add remote
fit remote add origin server.local

# Remove remote
fit remote remove origin

Stash

# Save uncommitted changes
fit stash

# Save with message
fit stash save -m "Work in progress"

# List stashes
fit stash list

# Apply and remove stash
fit stash pop

# Remove specific stash
fit stash drop stash@1234567890

Backup Mode

# Create snapshot of entire directory
fit snapshot -m "Backup before system upgrade"

# View snapshots
fit log

Remote Operations

# Start daemon on server
fit daemon --port 9418

# Push from client
fit push server.local main

# Pull from server
fit pull server.local main

# Clone repository
fit clone server.local main ~/myproject

# Shallow clone (only last 5 commits)
fit clone server.local main ~/myproject --depth 5

Signed Commits

# Generate signing key pair (one-time setup)
fit init-signing

# Create signed commit
fit commit -m "Important change" --sign

# Alternative short flag
fit commit -m "Another change" -S

# Verify commit signature
fit verify-commit abc123def456

Disaster Recovery

# Restore files from a specific commit
fit restore <commit-hash>

# Or checkout a branch (restores files automatically)
fit checkout main

Maintenance

# Run garbage collection
fit gc

Docker Deployment

Run the Fit daemon 24/7 with Docker:

# Build and start server
docker-compose up -d

# View logs
docker-compose logs -f

# Stop server
docker-compose down

Auto-start on boot (systemd):

# Install as system service
chmod +x install_service.sh
./install_service.sh

# Check status
sudo systemctl status fit-server

# View logs
docker-compose logs -f

This will:

• Start Fit daemon on port 9418
• Auto-restart on failure
• Auto-start on system boot

Access:

• Daemon: fit push localhost main

Docker Deployment (Alt Method)

Build and Run

# Build image
docker build -t fit:latest .

# Run daemon
docker run -d -p 9418:9418 -v fit-data:/data/.fit fit:latest

# Or use docker-compose
docker-compose up -d

Auto-start on Boot

The docker-compose.yml includes restart: unless-stopped for automatic startup.

For systemd on bare metal:

# Create /etc/systemd/system/fit-daemon.service
[Unit]
Description=Fit Daemon
After=network.target

[Service]
Type=simple
User=fit
ExecStart=/usr/local/bin/fit daemon --port 9418
Restart=always

[Install]
WantedBy=multi-target.target

# Enable and start
sudo systemctl enable fit-daemon
sudo systemctl start fit-daemon

Two-Node Setup Example

Server (Alpine Linux - Laptop)

# Install Fit
make && sudo make install

# Initialize repository
mkdir -p ~/backup
cd ~/backup
fit init

# Start daemon
fit daemon --port 9418

# Or with Docker
docker-compose up -d

Client (Arch Linux - Main PC)

# Install Fit
make && sudo make install

# Initialize repository
cd ~/projects/myproject
fit init

# Create initial snapshot
fit snapshot -m "Initial backup"

# Push to laptop
fit push laptop.local main

# Continue working...
echo "new content" > file.txt
fit add file.txt
fit commit -m "Updated file"
fit push laptop.local main

Disaster Recovery

# On new machine or after data loss
fit init
fit pull laptop.local main  # (requires implementing pull)

# Or manually:
# 1. Copy .fit directory from backup server
# 2. Checkout desired commit

Testing

# Run test suite
make test

Manual Testing

# Test hashing
echo "test" > test.txt
fit init
fit add test.txt
fit commit -m "test"
fit log

# Test network transfer
# Terminal 1:
fit daemon --port 9418

# Terminal 2:
fit push localhost main

Performance Considerations

1. Object storage: Each object stored separately until packed
2. Compression: zlib level 6 (default) balances speed/size
3. Network: Streams packfiles, no chunking yet
4. Memory: Loads full objects into memory (optimize for large files later)
5. Multi-threading: Daemon now supports concurrent client connections via pthreads

Limitations & Future Work

Current Limitations

• No delta compression (stores full objects)
• No sparse checkout
• No complex merge algorithm (fast-forward only) Three-way merge implemented
• No encryption (transport or storage)
• No authentication
• Single-threaded daemon Multi-threaded daemon implemented
• No index v2 format (simple text format)

Stretch Goals

• Delta compression for packfiles
• Signed commits (RSA) - ✓ Implemented
• End-to-end encryption
• File chunking for large files
• Multi-threaded daemon - ✓ Implemented
• Smart protocol negotiation - ✓ Implemented
• Shallow clones - ✓ Implemented
• Submodule support
• Three-way merge algorithm - ✓ Implemented

Security Notes

• No authentication: Daemon accepts all connections
• No encryption: Data sent in plaintext (transport layer)
• Commit signing available: Use RSA-2048 signatures to verify commit authorship

For production use, run behind VPN or SSH tunnel:

# SSH tunnel example
ssh -L 9418:localhost:9418 laptop.local

# Then push to localhost
fit push localhost main

Troubleshooting

"Failed to add file"

• Check file exists and is readable
• Ensure .fit directory initialized

"Push failed"

• Verify daemon running: netstat -ln | grep 9418
• Check firewall rules
• Test connectivity: telnet server.local 9418

"No commits yet"

• Create initial commit before branching/pushing

Development

Project Structure

src/
├── main.c      - CLI interface
├── hash.c      - SHA-256 hashing
├── object.c    - Object storage
├── tree.c      - Tree objects
├── commit.c    - Commit objects
├── index.c     - Staging area
├── refs.c      - Reference management
├── pack.c      - Packfile format
├── network.c   - Network protocol
├── gc.c        - Garbage collection
└── util.c      - Utilities

include/
└── fit.h       - Public API

tests/
└── run_tests.sh

Contributing

This is a personal project demonstrating Git internals. Feel free to fork and extend.

License

MIT License - See LICENSE file

Credits

Inspired by:

• Git by Linus Torvalds
• "Git from the Bottom Up" by John Wiegley
• "Building Git" by James Coglan

Built from scratch without copying Git source code.

---

Fit - Because your filesystem belongs inside your terminal.