gcsf

GCSF is a virtual filesystem that allows users to mount their Google Drive account locally and interact with it as a regular disk partition. You can find out more in this paper

GCSF requires the stable branch of the Rust programming language, which can be installed following the instructions on rustup.rs. If you already have Rust installed, make sure that it is updated to the latest version:

$ rustup update stable

On Mac OSX, GCSF requires osxfuse and pkg-config:

$ brew update; brew install pkg-config; brew tap homebrew/cask; brew install --cask osxfuse

On Ubuntu / Debian, GCSF requires libfuse-dev, libssl-dev and pkg-config:

sudo apt-get install -y fuse3 libfuse-dev libssl-dev pkg-config

On Fedora, GCSF requires gcc, fuse3-devel, and pkg-config:

sudo dnf install -y gcc fuse3-devel pkg-config

An AUR package is maintained by axionl: gcsf-git.

sudo zypper install -y fuse-devel fuse rust pkgconf-pkg-config

Make sure you have pkg-config and the fuse library installed. These are usually found in the package repositories of major distributions.

Rust can be installed via the lang/rust port. You will need to install sysutils/fusefs-libs for the cairo install command to succeed.

Unfortunately, Windows is not supported at the time being. See issue #19.

After all requirements are met, GCSF can be installed using cargo:

$ cargo install gcsf

This will generate the gcsf binary in $HOME/.cargo/bin. Make sure that this directory is in your PATH variable: export PATH=$PATH:$HOME/.cargo/bin

Alternatively, you can download a release binary for your platform.

GCSF will attempt to create a configuration file in $XDG_CONFIG_HOME/gcsf/gcsf.toml, which is usually defined as $HOME/.config/gcsf/gcsf.toml. Credentials are stored in the same directory.

1. Visit console.developers.google.com and create a new project
2. Add the Google Drive API to the project
3. Configure an OAuth consent screen. Verification should not be required. Should be external unless this project is something internal to your GSuite
4. Configure an OAuth2.0 credential. Do not use WEB as the token type if adding gcsf to a headless server - you want to be using the urn:* URI (note: if using WEB, you'll need to set the accepted domains to include http://localhost:8081)
5. Configure GCSF to use the new client_id, client_secret, and project_id. You should have all these values after creating the credential.
6. Configure GCSF authorize_using_code=True if configuring for headless servers. If you do this, completing the OAuth flow in a different browser will provide you a code that you can give to GCSF.

Running gcsf login some_session_name at this point should show a URL with your client_id query parameter.

If you plan to run GCSF as a system service or for extended periods, it is recommended that your Google Cloud project be in Production mode, not Testing mode.

Access tokens for apps in Testing mode expire more frequently, which usually triggers a prompt on GCSF to re-authenticate. This can be inconvenient especially when running GCSF as a system service. Publishing the app to Production mode resolves this issue.

To publish your app:

1. Go to Google Cloud Console
2. Navigate to "APIs & Services" → "OAuth consent screen" -> "Audience"
3. Check the "Publishing status" at the top
4. If it says "Testing", click "Publish App"
5. Publishing to Production might require app verification. Follow the process in the "Verification centre" section.
6. After publishing, you must re-authenticate:

   gcsf logout your_session_name
   gcsf login your_session_name

Note: Publishing to Production does NOT require Google verification for personal use. Verification is only needed if you're distributing your app to many external users.

You can verify your authentication is working at any time:

$ gcsf verify your_session_name
Verifying authentication for session 'your_session_name'...
Authentication is valid.

The first step is to log in to Drive and authorize the application. A name must be provided for the session:

$ gcsf login some_session_name
Please direct your browser to https://accounts.google.com/o/oauth2/[...] and follow the instructions displayed there.
Successfully logged in. Saved credentials to "$HOME/.config/gcsf/some_session_name"

You can also list all existing sessions:

$ gcsf list
Sessions:
        - personal
        - some_session_name
        - work

And then mount one (or more) of them:

$ gcsf mount /mnt/gcsf -s some_session_name
INFO  gcsf > Creating and populating file system...
INFO  gcsf > File system created.
INFO  gcsf > Mounting to /mnt/gcsf
INFO  gcsf > Mounted to /mnt/gcsf

You can now find the contents of your Drive account in /mnt/gcsf:

Using Ranger:

Or Thunar:

GCSF exposes Drive metadata of every file and directory as extended attributes:

List them all with getfattr -d /mnt/gcsf/some_file, or xattr -l on macOS.

Drive provides no checksums or revisions for directories and Google Docs, Sheets, Slides, Drawings and Sites, so these have no such attributes. Neither does a file with modifications that have not been flushed to Drive yet.

The checksums let you verify a copy end to end against Drive, without reading the file through GCSF again:

$ cp /mnt/gcsf/backup.zip /tmp/
$ getfattr --only-values -n user.gcsf.md5 /mnt/gcsf/backup.zip; echo
9e107d9d372bb6826bd81d3542a419d6
$ md5sum /tmp/backup.zip
9e107d9d372bb6826bd81d3542a419d6  /tmp/backup.zip

On macOS, use xattr -p user.gcsf.md5 /mnt/gcsf/backup.zip instead of getfattr.

GCSF stands for "Google Conduce Sistem de Fișiere" which translated from Romanian is "Google Drive Filesystem". However GDFS already exists so it remains GCSF.

This error occurs when user_allow_other is not set in /etc/fuse.conf or the file has improper permissions. Fix by running (as root):

# echo 'user_allow_other' >> /etc/fuse.conf
# chmod 644 /etc/fuse.conf
# sudo chown root:root /etc/fuse.conf

The error code reported on macOS often does not reflect the actual cause.

With macFUSE 5.3 or later, GCSF must be built from this repository, which includes a fix for cberner/fuser#752. Builds from crates.io (cargo install gcsf) cannot mount until fuser releases a fix.

If the macFUSE kernel extension has not been approved or loaded:

1. Open System Settings → Privacy & Security and allow the system software from developer "Benjamin Fleischer" (macFUSE).
2. If nothing is shown there, load the extension manually. This prints the actual error and usually brings up the approval prompt (replace 27 with your macOS major version):

   sudo kmutil load -p /Library/Filesystems/macfuse.fs/Contents/Extensions/27/macfuse.kext

3. Restart if prompted, then mount again.

You installed the prebuilt binaries but couldn't run it. Fix by installing rust and building from source.

Contributions are welcome. Documentation available on docs.rs/gcsf. You can also help by reporting or fixing issues.