Introducing Orma: The ‘Memory’ for Your Code

Ever felt like you’ve used a tool a thousand times but don’t really know how it works? For me, that tool was Git. I could commit, push, and pull with the best of them, but the magic happening behind the scenes was a total mystery.

This curiosity led me down a rabbit hole, and I decided the best way to understand the magic was to create it myself. The result is Orma, a simple version control system written in Python. The name “Orma” (ഓർമ്മ) means “memory” in my native language, Malayalam, which felt perfect for a tool designed to remember every step of a project’s life.

The “Aha!” Moment: Why Build Another Git?

My goal was never to replace Git — it’s a masterpiece of engineering. The real goal was to learn and create something that felt more intuitive for the everyday workflow. I wanted to strip away the complexity and focus on the two most fundamental actions: saving a snapshot and travelling back in time.

The idea was to build a version control system that works like an “undo” history for your entire project. You don’t need to think about complex branching or staging areas. You simply:

1. save your work when you reach a good milestone.

2. revert to any previous save if you need to go back.

This led me to create a simplified command-line tool with a handful of easy-to-understand commands like start, save, history, and revert. It’s designed to give you the core power of version control without the steep learning curve.

How Orma Works: A Look Inside the Engine

At its heart, a version control system has to do two things very well:

1. Store snapshots of your project efficiently.

2. Link those snapshots together to form a history.

Orma, like Git, does this using a hidden .orma directory and a clever system of objects. When you run orma start, it simply creates this "memory box" for your project.

Inside this box, everything is stored as one of three types of objects: a Blob, a Tree, or a Commit.

1. Blobs: The Raw Content

A blob is the simplest object. It’s just the content of your file — nothing more.

Imagine you have a file hello.txt containing "hello world". Orma doesn't store the filename or any other metadata. It just takes the "hello world" content, compresses it using (zlib) , and saves it in the .orma/objects folder.

To give this content a unique ID, it uses a SHA-1 hash. This hash acts as a unique fingerprint for the content. If two files have the exact same content, they will point to the exact same blob! This is how Orma efficiently stores data without duplication.

2. Trees: The Directory Structure

A blob is just content. It has no name, no location. So how does Orma know that the content “hello world” belongs in a file named hello.txt? That's the job of a tree.

A tree object is like a blueprint for a folder. It contains a list of all the items in that folder. For each item, the tree stores:

• Its type (a blob for a file, or another tree for a subdirectory).

• Its name (e.g., hello.txt).

• The unique hash (pointer) to its corresponding blob or tree object.

The write-tree function scans your current directory, creates blobs for all the files, and then builds a single tree object that represents the entire directory structure at that moment. This tree gets its own unique SHA-1 hash.

3. Commits: The Story’s Chapters

We now have snapshots of our content (blobs) and our directory structure (trees). The final piece is the commit. A commit brings everything together to tell a story.

A commit object is a snapshot in time. It’s like a labelled photograph in an album and contains:

1. A pointer to the main tree: The hash of the tree object that represents the project’s root folder for this snapshot.

2. A pointer to the parent commit: The hash of the previous commit. This is what links all the commits together into a historical chain.

3. A message: The description you provide, like “Initial commit.”

4. Author info: Who made the change.

The orma save "My awesome message" command is the grand finale. It:

1. Creates a tree from the current state of your project (write-tree).

2. Gets the hash of the last commit (the parent).

3. Creates a new commit object, linking the new tree, the parent, and your message (commit-tree).

4. Updates a file called HEAD to point to this shiny new commit, so Orma knows what the "current" version is.

And that’s it! The orma history command simply starts from the HEAD, follows the parent pointer from one commit to the next, and prints the messages along the way. The orma revert <hash> command finds the commit, grabs its tree, and rebuilds your files exactly as they were in that snapshot.

Installation and Usage

Ready to give Orma a spin? Getting started is easy. You can find the complete source code on my GitHub page.

GitHub: https://github.com/vyshnav-tr/orma-version-control-system

Since Orma is a single Python script, you don’t need a complicated installation. Just follow these steps in your terminal:

1. Clone the Repository First, download the code from GitHub.

First, download the code from GitHub.

git clone https://github.com/vyshnav-tr/orma-version-control-system

2. Navigate into the Directory

cd orma

3. Run Orma Now you can start using it! Initialize a new Orma repository in your project folder.

python3 orma.py start

That’s it! You’ve created your project’s “memory box.” Now you can create some files and save your first snapshot.

# Create a new file
echo "My first line of code" > app.py

# Save the state
python3 orma.py save "Initial commit"# Check the history
python3 orma.py history

Optional: Going Global

To make your script globally accessible so you can run orma help from any directory

Here’s a step-by-step guide for Linux and macOS.

Make the script Executable

Right now, your script is just a text file. You need to give it “execute permissions” so the system knows it can be run as a program.

Navigate to your project’s directory in the terminal and run this command:

chmod +x orma.py

• chmod is the command to change file permissions.

• +x means "add the executable permission."

Your computer has a list of special directories where it looks for commands. This list is stored in an environment variable called $PATH. To make orma a global command, you need to move your script into one of these directories.

The standard directory for user-installed command-line tools is /usr/local/bin.

In your terminal, run the following command to move and rename your script. Renaming it from orma.py to just orma makes the command cleaner.

sudo mv orma.py /usr/local/bin/orma

Let’s break down that command:

• sudo: This runs the command with administrator privileges, which is required to move files into system directories like /usr/local/bin. You'll be prompted to enter your computer's password.

• mv orma.py: This specifies the file you want to move.

• /usr/local/bin/orma: This is the destination. You're moving the file to the /usr/local/bin directory and renaming it to orma at the same time.

Test It!

You’re all set! Open a new terminal window to ensure the system recognizes the new command. Now you can run orma from anywhere.

Try it out:

# Navigate to any other folder, for example, your Desktop
cd ~/Desktop

# Create a test project folder
mkdir my-new-project
cd my-new-project# It works!
orma start
orma help

Feel free to play around with the commands and peek at the code. I’d love to hear what you think!