GitFS is a FUSE-based virtual filesystem that mounts Mesa repositories as local read-only directories without cloning.
It is ideal for agents, CI pipelines, and large monorepos where a full clone is impractical. GitFS supports macOS and
Linux.
Effectively, when you’re running git-fs, all of GitHub becomes just a directory on your system:
- Want to learn more about Linux? —
ls /mnt/git-fs/github/torvalds/linux
- Where does FastAPI do serialization? —
grep -ir 'serialize' /mnt/git-fs/github/fastapi/fastapi
- How does GNOME interact with X11? —
grep -ir 'x11' /mnt/git-fs/gitlab/GNOME/gnome-shell
GitHub and GitLab are your oysters!
GitFS is early-stage, alpha software. We’ve tried our best to make it reliable, but you may encounter occasional
performance issues.If you run into any issues, we urge you to open issues. We are working towards supporting writes, esp. with a focus on automatic session management, so you don’t have to touch
git worktree ever again. Stay tuned for updates!
Installing
Deb (Ubuntu/Debian)
RPM (Fedora/Rocky/Alma)
Other Linux
macOS
From Source
Grab the latest release off of our GitHub Releases page
and install it with apt.curl -fsSL "https://github.com/mesa-dot-dev/git-fs/releases/latest/download/git-fs_$(lsb_release -si | tr A-Z a-z)-$(lsb_release -sr)_$(dpkg --print-architecture).deb" \
-o /tmp/git-fs.deb \
&& sudo apt install /tmp/git-fs.deb \
&& rm /tmp/git-fs.deb
source /etc/os-release \
&& DISTRO="$(echo "$ID" | tr A-Z a-z)-${VERSION_ID%%.*}" \
&& ARCH="$(uname -m)" \
&& curl -fsSL "https://github.com/mesa-dot-dev/git-fs/releases/latest/download/git-fs_${DISTRO}.${ARCH}.rpm" -o /tmp/git-fs.rpm \
&& sudo dnf install -y /tmp/git-fs.rpm \
&& rm /tmp/git-fs.rpm
Since our program is a fuse-based program, you will need to install libfuse3. From there, grab the latest
release and install it on your machine. On macOS, you need to install macFUSE. When you’re done with that, you can download
the latest release and install it on your machine.We are working towards shipping a homebrew package!
git-fs only requires libfuse-dev as a dependency. When you have that installed, grab a copy of the repo and run
cargo build:git clone https://github.com/mesa-dot-dev/git-fs.git
cd git-fs
cargo build --release
target/release/git-fs.Getting Started
The absolute easiest way to get started is to run git-fs:
git-fs will automatically generate a naive configuration file and automatically create a mount directory for you. This
mount directory is likely going to be in /run/user/<your-uid>/git-fs/mnt on Linux and ~/Library/Application Support/git-fs/mnt on macOS.
You can now run ls /run/user/$(id -u)/git-fs/mnt/github/daytonaio/daytona and should see the
Daytona source. When you’re done, hit CTRL+C and git-fs will clean up after
itself.
You cannot ls the whole github directory. There are at millions of github repos so calling ls mnt/github would
cause your system to grind to a halt!That’s why, if you run ls /run/user/$(id -u)/git-fs/mnt/github, you will see a “Permission denied” error. You must
always specify which repo you want to read, like so:ls /run/user/$(id -u)/git-fs/mnt/github/torvalds/linux
You can enable logs by controlling the
RUST_LOG environment
variable:$ RUST_LOG=debug git-fs run
Connecting with Mesa
To get access to your Mesa Repos, you need to configure your API key in the
configuration file. After your API key is provided, run:
ls /run/user/$(id -u)/git-fs/mnt/<your-org>/
Configuration
git-fs is configured through a config file. The configuration file is loaded by merging:
/etc/git-fs/config.toml (lowest priority),$HOME/.config/git-fs/config.toml$XDG_CONFIG_HOME/git-fs/config.toml (highest priority).
If git-fs fails to find any config file, it will create a configuration file in $XDG_CONFIG_HOME/git-fs/config.toml
with sane defaults.
You can override the path to the config file with the --config-path flag.
# git-fs configuration file
# mount-point specifies where the local filesystem will be mounted.
# Each of your orgs will be available as a top-level directory within
# this mount point.
#
# In this example, the resulting file tree will look like this:
#
# ~/mesa-mnt/
# ├── hooli-corp/
# │ ├── my-repo1
# │ └── my-repo2
# ├── globex-corp/
# │ ├── my-repo1
# │ └── my-repo2
# ├── github/
# │ ├── torvalds/
# │ │ ├── linux
# │ │ ├── uemacs
# │ │ └── ... (all repos available on github)
# │ └── ... (any other github org/repo you want)
# └── gitlab/
# └── ...(any gitlab repo you want)
mount-point = "/Users/marko/Library/Application Support/git-fs/mnt"
# When running git-fs in daemon moode, you will need to specify a file
# for the PID file. This prevents two daemons running at the same
# time.
[daemon]
# Path to the PID lock file.
path = "/Users/marko/Library/Application Support/git-fs/git-fs.pid"
# You can register any number of private organizations here. Each
# organization will be mounted within the mesa mount point as a
# top-level directory.
[organizations.hooli-corp]
api-key = "" # Your Mesa API key for this organization.
[organizations.globex-corp]
api-key = ""
# GitFS requires a local cache directory to store repository data.
[cache]
# Path to the cache.
path = "/Users/marko/Library/Application Support/git-fs/cache"
# Maximum size of the cache. When the cache exceeds this size, old
# data will be evicted. Note that this is currently not used.
max-size = "10GB"
Environment variable overrides
All configuration values can be overridden with MESAFS_-prefixed environment variables:
MESAFS_MOUNT_POINT="/opt/mesa/mnt" git-fs run
Daemon-mode
You can run git-fs in daemon mode. This will cause it to jump into the background and leave you alone. Note that
logs will go nowhere (we’re working on it).
Known Issues
git-fs does not currently support repos of which the branch name is not main.
