The magic behind Gitfs

A short introduction into how Gitfs was built, along with an overview of the Gitfs structure, classes, workers and views.

Gitfs is written exclusively in Python. It uses the fusepy module to expose the file system, backed by pygit2. It’s also thoroughly tested with over 95% coverage. It mounts a file system whose operations are mapped to the usual git ones. Whenever you write to a file in a gitfs-mounted file system, the file will be committed, and a push will be made to the origin.


Gitfs uses FUSE to create its filesystem. It’s used to create the current and history directories that you can find where you mounted the repository. More on that here.


pygit2 gives us direct access to Git and makes room for a lot of optimization. The alternative, using shell commands, would have been a pain to implement and so would have been tying it to a state too.


The Router class is used in order to dispatch paths to different Views.


Views are used to offer different functionality depending on your current path.

They are divided into two super classes: - PassthroughView - ReadOnlyView

The PassthroughView will work just like you would expect a normal directory to. It’s purpose is to map all of FUSE’s operations to the similar ones in Python.

The ReadOnlyView is used when user writes are not desired.

The subclasses of these are:

  • PassthroughView
    • CurrentView – this is the view which handles the current directory and does the automated commits and pushes
  • ReadOnlyView
    • HistoryView – this is the view which handles the history directory and categorizes commits by date
    • CommitView – this is the view which handles the history/*day* directory
    • IndexView – this is the view which handles the history/*day*/*commit* directory and shows you a read-only snapshot pointing to that commit


All workers inherit the Peasant class which is nothing more than a specialized Thread.

Here are the workers with their more than explicit names:

  • FetchWorker
  • MergeWorker

Idle mode

Gitfs uses the FetchWorker in order to bring your changes from upstream. The FetchWorker will fetch, by default, at a period of 30 seconds (you can change the timeout at mount, using -o fetch_timeout=5, for 5 seconds).

If nothing was changed, for more than 5min on the filesystem, Gitfs will enter in idle mode. In this mode, will fetch each 30min. You can modify those parameters using min_idle_times in order to change the amount of idle cycles required until Gitfs will go in idle mode (by default 10 times, which means 5min) and idle_fetch_timeout to control the period of time between fetches, for idle mode.

See Also

Gitfs Arguments

Gitfs can be customized and configured through a list of arguments, which we've described and [...]

Gitium Frequently Asked Questions

A selection of frequently asked questions regarding Gitium.

How to use Gitfs

Here you will find all the commands necessary to install and configure Gitfs, as well as a [...]

Install Gitium

Gitium can be installed and activated like any other WordPress plugin.