kingnstar 0.1.1

A Git-like Version Control System in Python

Kingnstar VCS 🚀

A Git-like Version Control System written in pure Python. Installable via pip, usable via CLI.

Features

✅ Explicit, Deterministic Logic — No magic defaults
✅ Content-Addressed Storage — SHA-1 immutable objects
✅ Password-Protected Branches — With master password override
✅ Simple Cherry-Picking — kingnstar pull <branch> <commit_id>
✅ No Complex Merging — Just explicit file override

Installation

pip install kingnstar

Quick Start

# Initialize repository
kingnstar start

# Create and stage files
echo "Hello" > hello.txt
kingnstar add hello.txt

# Commit
kingnstar commit -m "Initial commit"

# Check status
kingnstar status

# Create protected branch
kingnstar new branch dev

# Switch branch
kingnstar switch dev MyPassword

# Pull commit from another branch
kingnstar pull master <commit_hash>

Commands

kingnstar start

Initialize a new Kingnstar repository (idempotent).

kingnstar add <pattern1> [<pattern2> ...]

Stage files matching glob patterns.

kingnstar add file.py
kingnstar add src/*.py
kingnstar add src/** tests/**

kingnstar commit -m "message"

Create commit from staged files.

kingnstar commit -m "Add new feature"

kingnstar branch

List all branches.

kingnstar branch

kingnstar new branch <name>

Create password-protected branch.

kingnstar new branch feature
# Prompts for password twice

kingnstar switch <branch> [password]

Switch to branch (requires password for protected branches).

kingnstar switch master              # No password needed
kingnstar switch dev MyPassword123   # With password
# Master password: Kingnstar@1604 (recovery option)

kingnstar status

Show current branch, commit, and staged files.

kingnstar pull <branch> <commit_id>

Cherry-pick commit from another branch (with conflict detection).

kingnstar pull dev abc123def456...
# Asks for confirmation if files conflict

Storage Model

All objects stored in .kingnstar/ hidden directory:

.kingnstar/
├── HEAD                 # Current branch pointer
├── index               # Staging area
├── objects/            # Content-addressed storage
│   ├── 24/
│   │   └── d11712a65d4...  (blob, tree, commit)
│   └── 68/
│       └── b9f0495f6a...
└── refs/heads/
    ├── master          # Branch pointers
    └── dev             # (with password hash)

Objects are SHA-1 hashed and immutable. Branches store commit hashes and optional password hashes.

Security

• Password Protection: All passwords hashed with SHA-256
• Master Password: Kingnstar@1604 overrides forgotten branch passwords
• No Auto-Merging: Explicit cherry-picking with user confirmation

Why Kingnstar?

Git's merging is complex (3-way conflicts, rebasing, marker symbols). Kingnstar simplifies:

• ❌ No complex merging algorithms
• ❌ No conflict markers in files
• ❌ No auto-conflict resolution
• ✅ Explicit cherry-picking
• ✅ User-controlled overrides
• ✅ Simple, predictable behavior

Requirements

• Python 3.7+
• click >= 8.0.0

License

MIT

Author

Kingnstar Team