Quick Start

This tutorial will guide you to configure and enable GitLocker strong encryption for your local Git repository in under 5 minutes.

Prerequisites

1. Install Client: Ensure you have downloaded and installed the GitLocker client program, and that the gitl command is added to your system environment variable PATH.
2. Initialize Git Repo: Enter your local project directory that needs to be encrypted:

   cd /path/to/your/repo
   git init
   

Step 1: One-command Initialization

Run the init command at the root of your local repository:

gitl init

GitLocker will automatically perform the following initialization for you:

1. Detect the current repository environment.
2. Register GitLocker's clean and smudge filters, as well as the custom merge driver.
3. If using the Personal Provider, it will generate a highly random, strong symmetric master key in your local secure credential store.
4. Generate the local encryption meta-configuration file .gitlocker/config.json.

Step 2: Set Encryption Rules

Define the files or directories that require encryption protection using the encrypt command. This is similar to configuring .gitignore.

For example, if you want to encrypt the production config file and all files in the secrets directory:

gitl encrypt "config/production.json" "secrets/**"

After running this command:

1. The rules will be automatically appended to the .gitattributes file at the root of the repository.
2. The configuration will look similar to:

   config/production.json filter=gitl-filter diff=gitl-diff merge=gitl-merge
   secrets/** filter=gitl-filter diff=gitl-diff merge=gitl-merge
   

3. You need to commit .gitattributes to Git:

   git add .gitattributes
   git commit -m "Configure GitLocker encryption rules"
   

Step 3: Transparent Commit and Push

Now that the security boundary is established, in your subsequent work, you can run native Git commands as you normally would!

1. Add files and commit:

   git add config/production.json secrets/api-key.env
   git commit -m "Secured database secrets"
   

   When you run git add / git commit, the GitLocker filter automatically intercepts these sensitive files in the staging area and converts them into strong AES-256-GCM ciphertext.

2. Push to remote:

   git push origin main
   

   Everything saved on the remote server (such as GitHub) is thoroughly encrypted ciphertext. Anyone who accesses it unauthorized will only see random binary garbage!

Step 4: Local Checkout (Automatic Decryption)

When you (or other team members authorized with the key) pull or check out the code locally:

git checkout main

GitLocker's smudge filter automatically extracts the matching ciphertext upon checkout and transparently decrypts it in your physical workspace. Your editor and development environment will see completely normal plaintext code.

Quick start in 5 minutes completed! Now your Git repository is hardened with military-grade tamper resistance.