Veridian is a simple Git-like version control system implemented in Rust. It supports basic Git functionality such as initializing a repository, storing objects, creating trees, and making commits. Veridian is designed as a learning project to understand the inner workings of Git and content-addressable storage.

• Initialize a Veridian repository (veridian init)
• Create objects from files (veridian hash-object <file>)
• Display object contents (veridian cat-file <hash>)
• Build trees from directories (veridian write-tree [path])
• Commit changes to the repository (veridian commit-tree <tree_hash> --message <message>)
• Supports parent commits and updates HEAD automatically
• Content integrity ensured through SHA-1 hashes
• Tree entries sorted by file name for consistent hashing
• Basic support for author and committer information via environment variables (GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL)

1. Ensure Rust is installed. If not, install it via rustup.
2. Clone the repository:

git clone https://github.com/Kayleexx/veridian
cd veridian

3. Build the project:

cargo build --release

4. Add the binary to your PATH (optional):

export PATH="$PATH:$(pwd)/target/release"

All commands are executed inside a Veridian repository (created via veridian init).

veridian init

Creates a .veridian folder with the following structure:

.veridian/
├─ objects/       # Stores blob, tree, and commit objects
├─ refs/
│  └─ heads/
│     └─ main     # Stores the latest commit hash for main branch
└─ HEAD           # Points to the current branch (e.g., refs/heads/main)

veridian hash-object <file>

• Converts a file into a blob object.
• Prepends a header blob <size>\0 to the file content.
• Computes SHA-1 hash of the blob.
• Stores the compressed blob in .veridian/objects/<hash_prefix>/<hash_suffix>.

Example:

veridian hash-object test.txt

Output:

3b18e512dba79e4c8300dd08aeb37f8e728b8dad

veridian cat-file <hash>

• Reads an object from .veridian/objects.
• Decompresses it using zlib.
• Parses object type (blob, tree, commit) and validates size.
• Prints content to stdout.

Examples:

veridian cat-file 3b18e512dba79e4c8300dd08aeb37f8e728b8dad
# Outputs file content

For tree objects:

100644  file1.txt  3b18e512dba79e4c8300dd08aeb37f8e728b8dad
40000   src        1f41476e6f40eabe0cbb70969d90ef46dbc1b527

For commit objects:

tree 72de2d9eced9c3e2bb07db39ae52c0d409f59a6c
parent <parent_hash>
author Unknown <Unknown> 1760211794 +0530
committer Unknown <Unknown> 1760211794 +0530

initial commit

veridian write-tree [path]

• Recursively hashes files and directories starting from the given path.
• Creates a tree object representing the directory structure.
• Stores the tree object in .veridian/objects.
• Outputs the SHA-1 hash of the tree.

Example:

veridian write-tree
Tree hash: 5a1629a0a7f0f69e80fd9f1b8fcaa8830f060a5b

veridian commit-tree <tree_hash> --message <message>

• Creates a commit object pointing to a tree.
• Includes optional parent commit (if HEAD exists).
• Records author and committer information using environment variables.
• Updates refs/heads/main and HEAD automatically.
• Stores commit object in .veridian/objects.

Example:

export GIT_AUTHOR_NAME="Alice"
export GIT_AUTHOR_EMAIL="[email protected]"

veridian commit-tree 5a1629a0a7f0f69e80fd9f1b8fcaa8830f060a5b --message "Initial commit"

Output:

Commit created (India Time): 189d8004443db9b25142154c16540dbe218a3dfa

• GIT_AUTHOR_NAME – sets author name (default: Unknown)
• GIT_AUTHOR_EMAIL – sets author email (default: Unknown)

Example:

export GIT_AUTHOR_NAME="Alice"
export GIT_AUTHOR_EMAIL="[email protected]"

Veridian objects mimic Git’s content-addressable structure:

Object types:
- Blob: stores raw file content (with "blob <size>\0" header)
- Tree: stores directory structure (file/directory names, modes, hashes)
- Commit: stores metadata, tree hash, parent, author/committer, and commit message

[file1.txt]       [file2.txt]         [src/]
    │                 │                  │
    └──> Blob        └──> Blob         └──> Tree
               ┌───────────────────────────────┐
               │            Tree                │
               │  (directory structure hash)   │
               └───────────────────────────────┘
                           │
                           └──> Commit
                                 (tree hash + parent + author + message)

• Blob: content of a single file
• Tree: organizes blobs and subtrees, stores SHA-1 hashes
• Commit: points to a tree, optionally references parent commit

• Veridian uses SHA-1 hashes for content addressing.
• Trees store only object hashes, not actual file content.
• Tree entries are sorted by filename to ensure consistent hashing.
• Only the main branch is supported; HEAD points to it.
• Logging and history commands are not implemented in this version.
• The .veridian/repo/mod.rs file is currently empty and reserved for future repo management modules.

# Initialize repository
veridian init

# Hash file objects
veridian hash-object file1.txt
veridian hash-object file2.txt

# Create tree object for current directory
veridian write-tree
# Example output: Tree hash: 72de2d9eced9c3e2bb07db39ae52c0d409f59a6c

# Commit tree with message
veridian commit-tree 72de2d9eced9c3e2bb07db39ae52c0d409f59a6c --message "Initial commit"

# View commit object
veridian cat-file <commit_hash>