gitforgefs

Formerly gitlabfs

gitforgefs allows you to mount and navigate git forges (Github, Gitlab, Gitea, etc.) as a FUSE filesystem with every groups, organization, and users represented as a folder and every repositories represented as a symlink pointing on a local clone of the project. This is helpful to automate the organization of your local clones.

To help illustrate, this is the output of tree in a filesystem exposing all the repositories of a github user.

$ tree
.
└── badjware
    ├── aws-cloud-gaming -> /home/marchambault/.local/share/gitforgefs/github.com/257091317
    ├── certbot -> /home/marchambault/.local/share/gitforgefs/github.com/122014287
    ├── certbot-dns-cpanel -> /home/marchambault/.local/share/gitforgefs/github.com/131224547
    ├── certbot-dns-ispconfig -> /home/marchambault/.local/share/gitforgefs/github.com/227005814
    ├── CommonLibVR -> /home/marchambault/.local/share/gitforgefs/github.com/832968971
    ├── community -> /home/marchambault/.local/share/gitforgefs/github.com/424689724
    ├── docker-postal -> /home/marchambault/.local/share/gitforgefs/github.com/132605640
    ├── dotfiles -> /home/marchambault/.local/share/gitforgefs/github.com/192993195
    ├── ecommerce-exporter -> /home/marchambault/.local/share/gitforgefs/github.com/562583906
    ├── FightClub5eXML -> /home/marchambault/.local/share/gitforgefs/github.com/246177579
    ├── gitforgefs -> /home/marchambault/.local/share/gitforgefs/github.com/324617595
    ├── kustomize-plugins -> /home/marchambault/.local/share/gitforgefs/github.com/263480122
    ├── librechat-mistral -> /home/marchambault/.local/share/gitforgefs/github.com/753193720
    ├── PapyrusExtenderSSE -> /home/marchambault/.local/share/gitforgefs/github.com/832969611
    ├── Parsec-Cloud-Preparation-Tool -> /home/marchambault/.local/share/gitforgefs/github.com/258052650
    ├── po3-Tweaks -> /home/marchambault/.local/share/gitforgefs/github.com/832969112
    ├── prometheus-ecs-discovery -> /home/marchambault/.local/share/gitforgefs/github.com/187891900
    ├── simplefuse -> /home/marchambault/.local/share/gitforgefs/github.com/111226611
    ├── tmux-continuum -> /home/marchambault/.local/share/gitforgefs/github.com/160746043
    ├── ttyd -> /home/marchambault/.local/share/gitforgefs/github.com/132514236
    ├── usb-libvirt-hotplug -> /home/marchambault/.local/share/gitforgefs/github.com/128696299
    └── vfio-win10 -> /home/marchambault/.local/share/gitforgefs/github.com/388475049

24 directories, 0 files

Supported forges

Currently, the following forges are supported:

Forge	Name in configuration	API token permissions, if using an API key
Gitlab	gitlab	read_user, read_api
Github	github	repo
Gitea	gitea	organization: read, repository: read, user: read
Forgejo	gitea	organization: read, repository: read, user: read

Merge requests to add support to other forges are welcome.

Install

Install go and run

go install github.com/badjware/gitforgefs@latest

The executable will be in $GOPATH/bin/gitforgefs or ~/go/bin/gitforgefs by default. For convenience, add ~/go/bin in your $PATH if not done already.

Usage

Download the example configuration file and edit the default configuration to suit your needs.

Then, you can run gitforgefs as follows:

gitforgefs -config config.yaml /path/to/mountpoint

Stopping gitforgefs will unmount the filesystem. In the event the mountpoint is stuck in a bad state (eg: due to receiving a SIGKILL), you may need to manually cleanup using umount:

sudo umount /path/to/mountpoint

Running automatically on user login

See ./contrib/systemd for instructions on how to configure a systemd service to automatically run gitforgefs on user login.

Caching

Filesystem cache

To reduce the number of calls to the APIs and improve the responsiveness of the filesystem, gitforgefs will cache the content of the forge in memory. If a group or project is renamed, created or deleted from the forge, these change will not appear in the filesystem immediately. To force gitforgefs to refresh its cache, use touch .refresh in the folder to signal gitforgefs to refresh this folder.

Local repository cache

While the filesystem lives in memory, the git repositories that are cloned are saved on disk. By default, they are saved in $XDG_DATA_HOME/gitforgefs or $HOME/.local/share/gitforgefs, if $XDG_DATA_HOME is unset. gitforgefs symlink to the local clone of that repo. The local clone is unaffected by project rename or archive/unarchive in the forge and a given project will always point to the correct local folder.

Future improvements

• Cache persists forever until a manual refresh is requested. Some way to automatically refresh after a timeout would be nice.

Building from the repo

Simply use make to create the executable. The executable will be in bin/.

See make help for all available targets.

Troubleshooting

My application claims that a file or a folder doesn't exists.

Some applications doesn't resolve symlinks properly. Try setting the fs.use_symlinks configuration to false.

docker fails to run with the message error while creating mount source path

This happens because docker is running as a different user than the one who created the mount. Follow these steps to allow docker access to the mount:

1. Open the file /etc/fuse.conf as root.
2. Add user_allow_other to the file, then close and save your modifications.
3. Open your gitforgefs configuration.
4. Add the allow_other to your mountoptions. The mount option are configured in fs.mountoptions.

fs:
  mountoptions: allow_other,nodev,nosuid

5. Restart your mount.