kingnstar 0.1.1
A Git-like Version Control System in Python
License: MIT
Requires Python: >=3.7
Keywords: version control vcs git alternative

# 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

```bash
pip install kingnstar
```

## Quick Start

```bash
# 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.

```bash
kingnstar add file.py
kingnstar add src/*.py
kingnstar add src/** tests/**
```

### `kingnstar commit -m "message"`
Create commit from staged files.

```bash
kingnstar commit -m "Add new feature"
```

### `kingnstar branch`
List all branches.

```bash
kingnstar branch
```

### `kingnstar new branch <name>`
Create password-protected branch.

```bash
kingnstar new branch feature
# Prompts for password twice
```

### `kingnstar switch <branch> [password]`
Switch to branch (requires password for protected branches).

```bash
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).

```bash
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