gec

gec is a command-line utility written in Bash with convenience commands for using gocryptfs with git, specifically with GitHub. It refrains from doing anything clever, making it possible to naively fallback to the underlying gocryptfs or git commands if a need should arise.

It transparently uses data encryption, both at rest and on the remotes. It uses version control and leverages redundant remote storage. The implemented remote commands require GitHub. Git users will be at home with it.

:warning: Before continuing, save the link to the official Gitee mirror of this repo.

Contents

• Screenshot
• Links
• Limitations
• Requirements
• Installation
• Development
• Setup
• Directories
• Workflow
• Commands
• Migration

Screenshot

Links

| Caption | Link | |-----------|-----------------------------------------------| | Repo | https://github.com/impredicative/gec | | Changelog | https://github.com/impredicative/gec/releases | | Mirror | https://gitee.com/impredicative/gec |

Limitations

The known applicable size limits for GitHub is tabulated below. If a hard limit is violated during a commit, gec will attempt to check it and error early, otherwise a push will fail.

| Size of | SI Value | Type | Enforcer | Action by gec | |---------|-----------------------|------|----------|-----------------| | File | 100M | Hard | GitHub | Error | | Push | 2G | Hard | GitHub | Error | | Repo | 5G | Soft | GitHub | Warning | | Repo | 100G (presumed) | Hard | GitHub | Error |

Due to the use of the gocryptfs -sharedstorage option, a hardlink cannot be created in a decrypted repo.

Requirements

Linux is required, along with a few tools which are covered in the Installation section.

A dedicated GitHub account is required. If using Firefox, the Multi-Account Containers add-on can be very useful to separate them from your primary accounts on these sites.

Installation

Linux

These steps were tested on Ubuntu. On other distros, ensure that the executables are available in the PATH.

Ensure curl ≥7.74.0, git ≥2.25.1, jq ≥1.5:

sudo apt install curl git jq

Install gocryptfs ≥2.2.1:

# Install on amd64:
RELEASE=$(curl https://api.github.com/repos/rfjakob/gocryptfs/releases | jq -r .[0].tag_name)
wget -qO- https://github.com/rfjakob/gocryptfs/releases/download/${RELEASE}/gocryptfs_${RELEASE}_linux-static_amd64.tar.gz | sudo tar -xz -f - -C /usr/local/sbin/ gocryptfs gocryptfs-xray

# Install on arm64 on Ubuntu:
sudo apt install gocryptfs

Install git-sizer ≥1.3.0:

# Install on amd64:
VERSION=$(curl https://api.github.com/repos/github/git-sizer/releases | jq -r .[0].tag_name | tr -d v)
wget -qO- https://github.com/github/git-sizer/releases/download/v${VERSION}/git-sizer-${VERSION}-linux-amd64.zip | sudo busybox unzip - git-sizer -d /usr/local/sbin/
sudo chmod +x /usr/local/sbin/git-sizer

# Install on arm64 on Ubuntu:
sudo apt install git-sizer

Install gec:

# Install program
RELEASE=$(curl https://api.github.com/repos/impredicative/gec/releases | jq -r .[0].tag_name)
sudo wget https://raw.githubusercontent.com/impredicative/gec/${RELEASE}/gec.sh -O /usr/local/sbin/gec
sudo chmod +x /usr/local/sbin/gec

# Install completion script if using Bash on Linux:
mkdir -p ~/.local/share/bash-completion/completions
wget https://raw.githubusercontent.com/impredicative/gec/${RELEASE}/completion.bash -O ~/.local/share/bash-completion/completions/gec
source ~/.local/share/bash-completion/completions/gec  # This is automatic if bash-completion is installed, but can do manually for current terminal only.

# Install completion script if using Fish on Linux:
mkdir -p ~/.config/fish/completions
wget https://raw.githubusercontent.com/impredicative/gec/${RELEASE}/completion.fish -O ~/.config/fish/completions/gec.fish
source ~/.config/fish/completions/gec.fish  # This is automatic, but can do manually for current terminal only.

For future updates to gec, running gec install will install its latest release.

Development

This section is for gec development only; it is not applicable for routine use.

# Clone repo
git clone git@github.com:impredicative/gec.git
cd ./gec

# Link program if on Linux
sudo ln -s "${PWD}/gec.sh" /usr/local/sbin/gec

Setup

In the steps below, <owner> refers to a username in GitHub.

On each device:

1. Run gec config core.owner <owner> once for all future repos.
2. Run ssh-keygen -f ~/.ssh/id_gec once to create a new SSH key. Optionally use and securely save a passphrase for this key to minimize the risk of any unauthorized push.
3. Add the ~/.ssh/id_gec.pub file for the key created above into the <owner> account in GitHub.
4. Create or prepend (not append) to ~/.ssh/config the specific contents:

   Match host github.com exec "[[ $(git config user.name) = gec ]]"
       IdentityFile ~/.ssh/id_gec
   

5. Run chmod go-rw ~/.ssh/config to tighten permissions of the file as is advised in man ssh_config.
6. Run gec test.ssh to test GitHub access via SSH, ensuring that the <owner> name is printed for both.
7. Run gec test.token to test GitHub access via a personal access token for each. The GitHub token must have access to the repo and delete_repo scopes.

Directories

Storage repos are created in ~/gec/. This location is created automatically. Both encrypted and decrypted repos and their files are organized in this location. Although this location is not currently configurable, a softlink or hardlink can be used to redirect it elsewhere if needed.

For each repo, these directories are created and used:

| Location | Description | |-------------------------------|-----------------------------------------------| | ~/gec/encrypted/<repo> | git repo contents | | ~/gec/encrypted/<repo>/.git | .git directory of git repo | | ~/gec/encrypted/<repo>/fs | encrypted filesystem contents within git repo | | ~/gec/decrypted/<repo> | decrypted filesystem mountpoint |

Workflow

To create and provision a new repo:

• gec init <repo>
• gec use <repo>
• touch .Trash-${UID} (Avoids deleting files to Trash on Ubuntu)

To provision an existing repo:

• gec clone <repo>

To use a provisioned repo, these are some of the many commands:

• gec pull [<repo>] (If and when changed on remote)
• gec use [<repo>] (Remember to exit the shell after using)
• gec status [<repo>]
• gec done <repo> "a non-secret commit message" (If files changed)
• gec umount <repo>

Refer to the repo-specific commands section for details on using the commands in the workflows above.

Commands

Repo-agnostic

• config <key> [<val>]: Get or set a value of key from configuration file ~/.gec. To list all values, specify -l.
• install [<release>]: Update to the named or latest release of gec.
• list: Alias of ls.
• ls [pattern]: List the output of the state command for matching repos in ~/gec/encrypted. If specifying a pattern, it may need to be quoted.
• lock: Unmount all mounted repos.
• test.ssh: Test access to GitHub via SSH.
• test.token: Test access to GitHub via a personal access token for each.

Repo-specific

In the commands below, <repo> refers to an identical repository name, e.g. "travel-ak", in GitHub. It can be auto-determined if a command is run from its encrypted or decrypted directory. When it can be auto-determined, to disambiguate a command's arguments that follow, it can alternatively be specified as a period.

The minimally relevant repo-specific commands are listed in the Workflow section.

Informational

• check.dec [<repo>]: Check decrypted file sizes. Error if a size limit is exceeded. The repo must be in a mounted state. It is run automatically by commit when needed if mounted.
• check.git [<repo>]: Check encrypted file sizes, and use git-sizer to check the size of the git repo. Error if a size limit is exceeded. It is run automatically by commit when needed.
• du [<repo>]: Print the human-friendly disk usage of the git repo directory for a depth of one.
• du.dec [<repo>]: Print the human-friendly disk usage of the decrypted directory for a depth of one. The repo must be in a mounted state.
• du.enc [<repo>]: Print the human-friendly disk usage of the encrypted filesystem directory for a depth of one.
• info [<repo>]: Alias of status.
• log [<repo>] [options]: Print the git log for the last ten commits. Options, if any, are forwarded to git log. If specifying any options, to auto-determine <repo>, specify a period in its place.
• logs [<repo>]: Alias of log.
• state [<repo>]: Print the repo mount state, .git directory disk usage, encrypted filesystem directory disk usage, total disk usage, and repo name.
• status [<repo>]: Print the repo name, mount state, and short git status. If mounted, also print the change status of decrypted paths plus the mount information.

Remote oriented

A [GitHub token](https: