Controlz

A minimal Git-like version control system built in Node.js. Controlz implements core Git functionality including staging, committing, branching, and file tracking using content-addressable storage with SHA-1 hashing.

Features

• Initialize repositories
• Stage and commit changes
• Create and switch between branches
• View commit history and repository status
• Git-like object storage with SHA-1 hashing
• Working directory and staging area management

Installation

Local Development Setup

1. Clone the repository:

git clone <repository-url>
cd controlz

2. Install dependencies:

npm install

3. Link the CLI globally for development:

npm link

This makes the controlz command available globally in your terminal.

Verify Installation

Test that the installation worked:

controlz --help

You should see the help output with available commands.

Quick Start

1. Initialize a Repository

Create a new directory and initialize a Controlz repository:

mkdir my-project
cd my-project
controlz init

This creates a .controlz directory to store version control data.

2. Add Files

Create a file and add it to the staging area:

echo "Hello, Controlz!" > hello.txt
controlz add hello.txt

3. Commit Changes

Commit the staged files:

controlz commit -m "Initial commit"

4. Create a Branch

Create and work on a new feature branch:

controlz branch feature-branch
controlz checkout feature-branch

5. View History and Status

Check the commit log:

controlz log

Check repository status:

controlz status

Commands Reference

controlz init

Initialize a new Controlz repository in the current directory.

controlz init

Creates a .controlz directory with the necessary subdirectories and files.

controlz add <path>

Add a file to the staging area (index).

controlz add filename.txt
controlz add path/to/file.js

Note: Currently supports individual files only (no wildcard patterns).

controlz commit [-m <message>]

Commit staged changes to the repository.

# With message
controlz commit -m "Add new feature"

# Without message (defaults to "WIP")
controlz commit

Creates a commit object with:

• Staged file tree
• Reference to parent commit
• Author information (from environment)
• Timestamp

controlz branch <name>

Create a new branch pointing to the current HEAD commit.

controlz branch develop
controlz branch feature-login

Note: Requires at least one commit to exist in the repository.

controlz checkout <name>

Switch to an existing branch and update the working directory.

controlz checkout main
controlz checkout feature-branch

Warning: This overwrites files in your working directory without backup. Ensure your changes are committed before switching branches.

controlz log

Display the commit history from the current HEAD.

controlz log

Shows commits in reverse chronological order with:

• Commit hash
• Author
• Timestamp
• Commit message

controlz status

Show the current repository status.

controlz status

Displays:

• Current branch
• Staged files
• Modified files (compared to last commit)

Repository Structure

Controlz creates a .controlz directory with the following structure:

.controlz/
├── objects/           # Content-addressable object storage
│   └── XX/           # Objects stored by hash prefix
│       └── XXXXXX... # Object files (blobs, trees, commits)
├── refs/
│   └── heads/        # Branch references
│       ├── main      # Default branch
│       └── feature-* # Other branches
├── HEAD              # Current branch pointer
└── index.json        # Staging area

Object Types

• blob: File content
• tree: Directory snapshot (mapping of filenames to blob hashes)
• commit: Snapshot with metadata (tree hash, parent, author, message, timestamp)

Workflow Examples

Basic Development Workflow

# Initialize repository
controlz init

# Create and edit files
echo "console.log('Hello');" > app.js
echo "# My Project" > README.md

# Stage files
controlz add app.js
controlz add README.md

# Commit changes
controlz commit -m "Initial project setup"

# Check status
controlz status

Branching Workflow

# Create feature branch
controlz branch feature-auth
controlz checkout feature-auth

# Make changes
echo "function login() {}" >> app.js
controlz add app.js
controlz commit -m "Add login function"

# Switch back to main
controlz checkout main

# View commit history
controlz log

Multiple Files Workflow

# Add multiple files individually
controlz add file1.txt
controlz add file2.js
controlz add docs/readme.md

# Commit all staged files
controlz commit -m "Add multiple files"

Troubleshooting

Command Not Found Error

If you get controlz: command not found:

1. Ensure you've run npm link in the project directory
2. Check that npm's global bin directory is in your PATH
3. Try running with full path: ./bin/controlz.js --help

Repository Not Found Error

If you get "Not a controlz repository":

1. Ensure you're in a directory with a .controlz folder
2. Run controlz init to initialize a repository
3. Check that the .controlz directory wasn't accidentally deleted

File Not Found During Add

If controlz add fails:

1. Verify the file exists in the working directory
2. Use the correct relative path from the repository root
3. Ensure you have read permissions for the file

Limitations

• No merge functionality: Branches cannot be merged automatically
• File overwrites: Checkout operations overwrite files without conflict detection
• Flat tree structure: No support for nested directory trees in tree objects
• No partial staging: Entire files are staged, not individual lines/hunks
• No working tree protection: No checks for uncommitted changes during checkout
• Single file operations: No wildcard patterns for adding multiple files

Development

Project Structure

controlz/
├── bin/controlz.js    # CLI interface using Commander.js
├── lib/repo.js        # Core repository operations
├── package.json       # Dependencies and metadata
└── README.md          # This documentation

Adding New Commands

1. Add command definition in bin/controlz.js
2. Implement core logic in lib/repo.js
3. Export the function from the repo module
4. Follow the pattern: (cwd, ...args) => { /* implementation */ }

Dependencies

• commander: CLI argument parsing and command structure
• fs-extra: Enhanced filesystem operations
• crypto: SHA-1 hashing for object storage
• chalk: Terminal color output
• inquirer: Interactive prompts

License

ISC License - see package.json for details.

Author

Aravind Chowdary - aravi.me