MyGit

A modern, independent, privacy-focused Git-like version control system.

---

Table of Contents

• Overview
• Why MyGit?
• Important Project Status
• Features
• System Requirements
• Installation
  • PyPI Installation
  • Development Installation
  • Verify Installation
• Quick Start
• First Project Walkthrough
• Core Concepts
• How MyGit Works Internally
• Architecture
• Command Reference Table
• Command Documentation
  • mygit init
  • mygit status
  • mygit add
  • mygit reset
  • mygit commit
  • mygit log
  • mygit show
  • mygit diff
  • mygit branch
  • mygit switch
  • mygit checkout
  • mygit merge
  • mygit rebase
  • mygit tag
  • mygit key
  • mygit secrets
  • mygit fsck
  • mygit gc
  • mygit doctor
  • mygit publish
  • mygit lfs
• Remote Repositories & Server
• Provider Integrations
  • GitHub Integration
  • GitLab Integration
  • Hugging Face Integration
• Python SDK Reference
• Security
• Privacy
• Repository Internal Structure
• Troubleshooting
• Development & Building
  • Running Tests
  • Building the Package
  • Publishing to PyPI
• Roadmap
• FAQ
• Contributing
• License

---

Overview

MyGit is an independent, content-addressed version-control ecosystem built from scratch in Python. It provides developers with a full-featured CLI (mygit) for initializing repositories, tracking working tree files, staging changes, creating immutable SHA-256 commits, managing branches, performing 3-way LCA graph merges, executing linear commit rebases, checking repository integrity, signing commits with Ed25519 keys, and synchronizing code with remote servers.

Important Architecture Note: MyGit is not a shell wrapper around git. It executes zero git command binaries under the hood. All object creation, zlib compression, index parsing, graph traversal, and diffing logic are natively implemented within mygit_core.

---

Why MyGit?

Modern version control ecosystems require clear security boundaries, content verification, and modular extensibility:

1. Independent Core Architecture: Operates as an extensible engine that can be embedded into Python applications, IDE extensions, or custom enterprise pipelines via mygit_sdk.
2. Built-in Security & Credential Scanning: Scans staged content for API keys, AWS tokens, and private keys before commits are recorded, preventing accidental leaks.
3. Cryptographic Signatures by Default: Native support for Ed25519 signing keys directly stored inside .mygit/.
4. Machine-Readable Outputs: Native --json options across core status and log commands for seamless integration with external tools and IDEs.

---

Important Project Status

Development Status: MyGit v1.0.0 is under active development. Core version control engine commands, 3-way merging, rebase, cryptographic signing, FSCK, local server APIs, and PyPI packaging are fully implemented and tested. Cloud hosting sync features are under active milestone expansion.

Feature	Status
Repository Initialization (init)	Implemented
Staging Index (add, reset)	Implemented
Commit Graph (commit, log, show)	Implemented
Status Analysis (status, --json)	Implemented
Branching & HEAD (branch, switch, checkout)	Implemented
3-Way LCA Merge Engine (merge, --abort, --continue)	Implemented
Rebase Engine (rebase, --abort)	Implemented
Repository Health Check (fsck)	Implemented
Garbage Collection (gc)	Implemented
Cryptographic Signing (key, commit --sign)	Implemented
Secret Scanning (secrets scan)	Implemented
Large File Tracking (lfs track)	Implemented
PyPI Packaging & Build	Implemented
FastAPI Remote Server (server)	Implemented
React Web Dashboard (apps/web)	Implemented
Python SDK (mygit_sdk)	Implemented
GitHub Provider Integration	Partial / API
GitLab Provider Integration	Partial / API
Hugging Face Integration	Partial / API
CI/CD Container Worker	Planned

---

Features

Currently Available Features

• SHA-256 Content Addressing: Immutable Blob, Tree, Commit, and Tag objects.
• Fast Binary/JSON Staging Index: Real-time tracking of file sizes, modification timestamps, modes, and hashes.
• Unified Diff Engine: Myers line diffing, diffstat metrics (--stat), and patch formatting.
• 3-Way Merge Strategy: Graph LCA (Lowest Common Ancestor) search algorithm and conflict marker generation (<<<<<<<, =======, >>>>>>>).
• Linear Rebase Engine: Sequential commit replay and branch re-basing.
• Security & Key Management: Ed25519 key generation, commit signing, and Shannon entropy secret scanning.
• Repository Integrity Verification: Full object database and reference consistency validation via mygit fsck.
• Garbage Collection: Pruning of unreachable dangling objects via mygit gc.
• FastAPI Remote Server: REST endpoints for repos, branches, JWT auth, and wire protocol push/fetch.
• React Web Dashboard: Browser UI for exploring code trees, commit history, and branches.

---

System Requirements

• Operating Systems: Windows 10/11, Linux (Ubuntu/Debian/Fedora), macOS (10.15+).
• Python Version: Python 3.11 or higher.
• Disk Space: ~20 MB for CLI installation.
• Network Requirement: Core version control commands operate 100% offline. Network access is required only for remote operations (push, fetch, provider APIs).

---

Installation

PyPI Installation

Install the published package from PyPI:

pip install mygit

Verify that the CLI command is accessible:

mygit --version

Output:

MyGit version 1.0.0

---

Development Installation

To install MyGit from source for development or contribution:

# 1. Clone the repository
git clone https://github.com/YOUR_GITHUB_USERNAME/YOUR_REPOSITORY.git
cd YOUR_REPOSITORY

# 2. Create a virtual environment
python -m venv .venv

# 3. Activate the virtual environment
# On Windows:
.venv\Scripts\activate
# On Linux/macOS:
source .venv/bin/activate

# 4. Upgrade pip & install package in editable mode
python -m pip install --upgrade pip
pip install -e .

---

Verify Installation

Run the self-diagnostic command to verify system compatibility:

mygit doctor

Expected Output:

MyGit Doctor Diagnostics

CLI Installation: OK
Python Runtime:   3.11+ OK
Cryptography:     Ed25519 Supported
Repository:       No .mygit repository in current dir

No critical problems detected.

---

Quick Start

Initialize your first MyGit repository in 60 seconds:

# 1. Create a new directory
mkdir my-first-project
cd my-first-project

# 2. Initialize MyGit repository
mygit init

# 3. Configure author details
mygit config --global user.name "Developer"
mygit config --global user.email "developer@example.com"

# 4. Create a file
echo "# My First MyGit Repository" > README.md

# 5. Check status
mygit status

# 6. Stage the file
mygit add README.md

# 7. Commit changes
mygit commit -m "Initial commit"

# 8. View commit history
mygit log

---

First Project Walkthrough

Step-by-Step Command Flow:

# 1. Create feature branch
mygit switch -c feature/login

# 2. Create feature code
echo "def login(): pass" > auth.py

# 3. Stage and commit on feature branch
mygit add .
mygit commit -m "Add auth login placeholder"

# 4. Switch back to main branch
mygit switch main

# 5. Merge feature branch into main
mygit merge feature/login
# Output: Fast-forward merge to <commit-sha>.

# 6. Check repository integrity
mygit fsck

---

Core Concepts

• Repository: The project directory containing the working files and .mygit/ metadata database.
• Working Directory: The active directory containing raw files edited by the developer.
• Staging Area (Index): A fast state cache (.mygit/index) staging file snapshots before committing.
• Blob: Content-addressed object storing raw file bytes. Filename and mode metadata are omitted from blobs.
• Tree: Content-addressed object storing directory structure, mapping filenames and modes to Blob or Tree SHAs.
• Commit: Immutable object linking a root Tree SHA, parent commit SHAs, author metadata, timestamp, and message.
• Branch: A lightweight, mutable pointer referencing a specific commit SHA (e.g. refs/heads/main).
• HEAD: Pointer referencing the current active branch or detached commit SHA (.mygit/HEAD).
• Tag: Reference pointing to a commit, either lightweight or annotated with tagger metadata and message.

---

How MyGit Works Internally

flowchart LR
    File["Source File (auth.py)"] --> Blob["Blob Object (SHA-256)"]
    Blob --> Tree["Tree Object (root)"]
    Tree --> Commit["Commit Object (parents)"]
    Commit --> Ref["Branch Pointer (refs/heads/main)"]
    Ref --> HEAD["HEAD"]

1. Hashing: Raw data is hashed using SHA-256: $$\text{Hash} = \text{SHA-256}(\texttt{"blob \textbackslash 0"} \parallel \text{content})$$
2. Storage: Payload compressed via zlib is written to .mygit/objects/xx/yyyyyyyy....
3. Tree Assembly: Hierarchy of file entries is serialized into a deterministic Tree object.
4. Commit Record: Root Tree SHA is stored along with parent SHAs and committer signature.

---

Architecture

flowchart TD
    CLI["MyGit CLI (apps/cli)"] --> Core["MyGit Core (packages/core)"]
    Core --> Objects["Object Database (.mygit/objects)"]
    Core --> IndexManager["Staging Index (.mygit/index)"]
    Core --> MergeEngine["3-Way LCA Merge Engine"]
    Core --> Security["Security Subsystem (packages/security)"]
    Security --> Ed25519["Ed25519 Key Signing"]
    Security --> Secrets["Entropy Secret Scanner"]
    Core --> Protocol["Wire Protocol Client (packages/protocol)"]
    Protocol --> Server["FastAPI Server (apps/server)"]
    Server --> Web["React Web Dashboard (apps/web)"]

---

Command Reference Table

Command	Subcommands / Options	Description	Status
mygit init	[dir], -b	Initialize a new empty MyGit repository	Implemented
mygit config	--global, --list, --unset	Get or set configuration options	Implemented
mygit status	--json	Show working tree and staging status	Implemented
mygit add	<path>, ., -A	Stage files into .mygit/index	Implemented
mygit reset	<path>	Unstage files from index	Implemented
mygit commit	-m, -S (sign)	Record snapshot of staged index	Implemented
mygit log	--oneline, -n	View chronological commit history	Implemented
mygit show	<commit-sha>	View commit details and patch diff	Implemented
mygit diff	--staged, --stat	Show line-by-line unified diff	Implemented
mygit branch	[name], -d	List, create, or delete branches	Implemented
mygit switch	<branch>, -c	Switch active branch or create new	Implemented
mygit checkout	<commit-sha>	Checkout commit in detached HEAD mode	Implemented
mygit merge	<branch>, --abort, --continue	Perform 3-way LCA branch merge	Implemented
mygit rebase	<upstream>, --abort	Replay commits onto target branch	Implemented
mygit tag	[name], -m	Create lightweight or annotated tags	Implemented
mygit key	generate, list, export	Manage Ed25519 cryptographic signing keys	Implemented
mygit secrets	scan	Scan repository for credentials/API keys	Implemented
mygit fsck	—	Check object database & ref integrity	Implemented
mygit gc	--prune	Clean up unreachable dangling objects	Implemented
mygit doctor	—	Run self-diagnostic environment checks	Implemented
mygit publish	—	One-command init, stage & commit workflow	Implemented
mygit lfs	track <pattern>	Track large binary files with LFS pointers	Implemented

---

Command Documentation

mygit init

Initialize a new empty MyGit repository structure.

mygit init
mygit init my-app --initial-branch main

Creates .mygit/ containing HEAD, config, index, objects/, refs/heads/, refs/tags/, refs/remotes/, logs/, hooks/.

---

mygit status

Displays working directory changes, staged files, untracked files, and current branch.

mygit status
mygit status --json

Example Output:

On branch main

Changes to be committed:
  (use "mygit reset <file>..." to unstage)

	new file:   README.md

Untracked files:
  (use "mygit add <file>..." to include in what will be committed)

	src/main.py

---

mygit add

Stages file content into .mygit/index and writes content-addressed blob objects.

mygit add file.py
mygit add .
mygit add -A

Runs secret scanning checks before staging. If high-entropy credentials are detected, warnings are emitted.

---

mygit reset

Unstages file entries from .mygit/index.

mygit reset file.py

---

mygit commit

Creates an immutable Commit object pointing to the root Tree SHA of staged files.

mygit commit -m "Add authentication module"
mygit commit -m "Signed release" --sign

---

mygit log

Traverses the commit graph backwards from current HEAD.

mygit log
mygit log --oneline
mygit log -n 5

---

mygit show

Shows commit header metadata and unified patch diff vs parent commit.

mygit show c83d91f

---

mygit diff

Calculates unified line diffs.

mygit diff           # Working directory vs staged index
mygit diff --staged  # Staged index vs HEAD commit
mygit diff --stat    # Diffstat summary metrics

---

mygit branch

Lists, creates, or deletes local branches.

mygit branch
mygit branch feature/login
mygit branch -d feature/login

---

mygit switch

Switches active working directory and index to match target branch.

mygit switch main
mygit switch -c feature/login

---

mygit checkout

Checkouts a commit in detached HEAD state.

mygit checkout c83d91f

---

mygit merge

Merges target branch into current active branch using Fast-Forward or 3-Way LCA Merge.

mygit merge feature/login
mygit merge --abort
mygit merge --continue

---

mygit rebase

Replays current branch commits sequentially on top of upstream branch.

mygit rebase main
mygit rebase --abort

---

mygit tag

Manages release tags.

mygit tag
mygit tag v1.0.0
mygit tag v1.0.0 -m "Release version 1.0.0"

---

mygit key

Generates Ed25519 keypair inside .mygit/ed25519.priv and .mygit/ed25519.pub.

mygit key generate
mygit key export

---

mygit secrets

Scans working tree files for hardcoded API keys, private keys, and high-entropy passwords.

mygit secrets scan

---

mygit fsck

Validates repository health, object decompression, and SHA-256 hashes.

mygit fsck

---

mygit gc

Prunes unreachable dangling objects from .mygit/objects/.

mygit gc

---

mygit doctor

Runs self-diagnostics checks on Python runtime, environment, and repository.

mygit doctor

---

mygit publish

Convenience workflow command that initializes, stages all files, and creates an initial commit.

mygit publish

---

mygit lfs

Tracks large binary files and model weights via LFS pointer generation.

mygit lfs track "*.pt"
mygit lfs track "*.safetensors"

---

Remote Repositories & Server

MyGit FastAPI Remote Server

Launch the remote server backend:

python -m mygit_server.main

• Server API: http://localhost:8000
• Swagger Documentation: http://localhost:8000/docs

---

Provider Integrations

MyGit includes modular provider API wrappers:

• GitHub (packages/providers/mygit_providers/github.py): Authenticate, create repositories, and list remote repos via GitHub REST API v3.
• GitLab (packages/providers/mygit_providers/gitlab.py): Connect to GitLab instances via API v4.
• Hugging Face (packages/providers/mygit_providers/huggingface.py): Support for Hugging Face Hub Code, Model, and Dataset repositories.

---

Python SDK Reference

Embed MyGit VCS engine directly into Python scripts:

from mygit_sdk import RepositorySDK

# Initialize or open a repository
repo = RepositorySDK.open(".")

# View status
status_data = repo.status()
print("Staged files:", status_data["staged"]["new"])

# Stage file and commit
repo.add("app.py")
sha = repo.commit("Add app module", author="Developer <dev@example.com>")

# List branches
branches = repo.list_branches()
print("Branches:", [b["name"] for b in branches])

---

Security

MyGit enforces security-by-design principles:

1. Content Verification: All stored objects are verified against SHA-256 checksums upon read.
2. Ed25519 Signatures: Cryptographic proof of commit author identity.
3. Secret Isolation: Staged content is scanned to prevent committing secrets (.env, private keys, API tokens).
4. No Plaintext Passwords: Credentials are handled via environment tokens or secure helpers.
5. Path Traversal Protection: Prevents malicious relative path references outside the working directory root.

---

Privacy

• Offline First: All core commands (init, add, commit, status, log, branch, merge, rebase, fsck) operate 100% offline.
• No Unsolicited Telemetry: Telemetry is disabled by default.

---

Repository Internal Structure

Inside .mygit/, MyGit stores HEAD, config, index, objects/, refs/, logs/, and hooks/.

---

Troubleshooting

mygit: command not found

Ensure your virtual environment is activated or that Python script path is in your system PATH:

# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate

Fatal: Not a MyGit repository

Run mygit status or mygit init in the root project directory.

Merge Conflict Detected

Open reported conflicting files, edit sections surrounded by conflict markers (<<<<<<< OURS, =======, >>>>>>> THEIRS), stage changes with mygit add ., and complete merge with mygit merge --continue.

---

Development & Building

Running Tests

Execute pytest suite:

pytest tests/

Test Results:

tests/integration/test_workflow.py .                                     [ 14%]
tests/unit/test_merge.py ..                                              [ 42%]
tests/unit/test_objects.py ....                                          [100%]

============================== 7 passed in 0.36s ==============================

---

Building the Package

Build source distribution (sdist) and wheel (bdist_wheel):

python -m build

Build outputs in dist/:

• dist/mygit-1.0.0-py3-none-any.whl
• dist/mygit-1.0.0.tar.gz

---

Publishing to PyPI

Check package validity:

twine check dist/*

Publish package:

twine upload dist/*

---

Roadmap

• Repository initialization (init)
• Content-addressed SHA-256 object store (Blob, Tree, Commit, Tag)
• Staging Index (add, reset)
• Commit graph traversal & log viewer (commit, log, show)
• Branching & HEAD reference management (branch, switch, checkout)
• 3-Way LCA Merge Engine & conflict markers (merge)
• Linear Rebase Engine (rebase)
• Repository health check (fsck)
• Garbage collection (gc)
• Cryptographic Ed25519 signing (key)
• Shannon entropy secret scanner (secrets scan)
• LFS pointer tracking (lfs track)
• FastAPI remote server backend (server)
• React web interface (apps/web)
• PyPI packaging & wheel build
• GitHub & GitLab push sync handlers
• Hugging Face model LFS stream sync
• Containerized CI/CD runner worker

---

FAQ

What is MyGit?

MyGit is an independent version control system built from scratch in Python with its own object database, index, merge engine, CLI, and remote server.

Is MyGit a wrapper around Git?

No. MyGit does not call git CLI commands under the hood. All data structures and algorithms are implemented natively.

Does MyGit work offline?

Yes. All local repository operations work completely offline without internet connectivity.

Is MyGit free?

Yes. MyGit is released under the open-source MIT License.

---

Contributing

We welcome community contributions!

1. Fork the repository on GitHub.
2. Create a feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes (git commit -m 'Add amazing feature').
4. Run tests (pytest tests/).
5. Push to your branch and submit a Pull Request.

---

License

Distributed under the MIT License. See LICENSE for more information.