Git From Glasgow

A custom implementation of Git - for those curious how stuff works!

Git From Glasgow is a collection of Python scripts that implement the key Git data structures and the command line user interface. It follows a few basic design principles:

• Simplicity - Only selected, most popular Git commands are available.
• Compatibility with Git - Every command is fully compatible with its Git equivalent.
• Standalone - There are no external dependencies beyond Python.

To avoid confusion, the command-line interface in Git From Glasgow is called gfg rather than git.

About

Git From Glasgow implements the key elements of Git:

• index file (see git_index.py)
• various Git objects (e.g. blob, commit and commit, see git_object.py)
• Git command-line interface, which in Git From Glasgow is called gfg (see gfg)

Although only selected Git commands are supported (see Supported Git Commands), the available functionality is sufficient to:

• initialise a fresh repository (gfg init),
• add and commit new changes (e.g. gfg add and gfg commit),
• read the contents of an existing repository (e.g. gfg log and gfg cat-file).

The main goal of Git From Glasgow is to help understand how Git works (including the fine details). It is not meant as a replacement for Git. Indeed, some key and more advanced features are not available (e.g. packfiles). For this reason, it is best to experiment with GFG in a dedicated test repository.

Table of Contents

• Installing and Testing
• Supported Git Commands
• Contributing
• References

Installing and Testing

In order to use Git From Glasgow, you will require Python 3 (>= 3.6.9). In order to run the Git conformance tests, you will also have to install bats-core. Below is a full set-up that should work on most Unix platforms (tested on Ubuntu and MacOS):

# Clone GFG, add `gfg` to your path
git clone https://github.com/banach-space/gfg
export PATH=path/to/gfg:$PATH
# Clone bats-core so that you can run the conformance tests, add `bats` to your path
git clone https://github.com/bats-core/bats-core.git
export PATH=path/to/bats-core:$PATH
cd gfg/test
# Run Git conformance tests
bats -t .
# Run GFG unit tests
PYTHONPATH="../" python3 -m unittest

While I have strived to make GFG OS-agnostic, I have not been able to test it on Windows yet. Please let me know if you experience any issues!

Supported Git Commands

Below is a list of Git options supported by Git From Glasgow with the supported flags (note that Git equivalents of these options normally support more flags):

Basic commands

• gfg init (documentation)
• gfg add <files> (documentation)
• gfg commit -m message (documentation)
• gfg log (documentation)

Less basic commands

• git cat-file (-t | -p | <type> ) <object> (documentation)
• gfg hash-object [-w] [--stdin] <file> (documentation)
• gfg write-tree (documentation)
• gfg commit-tree -m message <tree> (documentation)

Contributing

Pull requests are very welcome! If you want to make a larger contribution (e.g. add a new option), please open an issue to track this.

Contributions in the form of bug reports, suggestions and general feedback are also much appreciated!

ToDo

Here's a list of things that I would like to add support for (PRs welcome!):

• testing on Windows (may require some refactoring to make GFG actually work on Windows)
• gfg rm (documentation)
• gfg branch (documentation)
• gfg checkout (documentation)
• gfg push (documentation)
• more tests

I'm also aware that there might be some inconsistencies in the code that would be nice to fix:

• hash, sha and object_hash are used interchangeably. Choose one instead.
• Classes in git_object.py have slightly inconsistent APIs.
• Reduce the use of class variables (e.g. in IndexEntry).

References

A list of my favourite resources on Git internals. I have found these incredibly helpful while working on Git From Glasgow.

• "Write yourself a Git!", Thibault Polge (link)
• "Git File format", Jelmer Vernooij (link)
• "Git from the inside out", Mary Rose Cook (link)
• "Unpacking Git packfiles", Aditya Mukerjee (link)