Skip to content

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

License

Notifications You must be signed in to change notification settings

banach-space/gfg

Repository files navigation

Git From Glasgow

unittests pylint

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:

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

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

Less basic commands

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!):

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)

About

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

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published