Handbook
Learn how to understand GitLocker
1. Synopsis
gitl [-v][-h][-g][-d <workdir>] Commands [args]
**Gitlocker Commands**
Encryption Setup:
init Initialize the remote transparent encryption key
File Operations:
encrypt Encrypt file/folder
decrypt Decrypt file/folder
status Show encryption status of file/folder
exportkey Export the encryption key for unlocking operations
OPTIONS
-v Show version information.
-h Show help information.
-g Display graphical user interface.
-d Set the git workspace folder (that contains .git), applicable to all commands.
-m Encryption mode (0-4), used with init command.
-p Password for encryption/decryption.
-k Key file path for encryption/decryption.
2. Description
2.1 init
Encryption Initialization
NAME:
gitl-init - Initialize the encryption key with password
SYNOPSIS
gitl init [-p your_password][-k key_file][-m mode][-c][-i][-g]
DESCRIPTION
When using gitl for the first time, it is necessary to initialize and generate
a key file(-p or -k), which will be used to encrypt the data. The key file can be exported
using the exportkey command.
When you do not need gitl, use the -c option to clear all encryption configurations.
GitLocker supports five encryption modes:
0: AES-CRT-128-simple - Simple mode with AES-128 in CTR mode
1: AES-CRT-256-simple - Simple mode with AES-256 in CTR mode
2: AES-GCM-256-simple - Simple mode with AES-256 in GCM mode (recommended)
3: AES-CRT-256-normal - Normal mode with AES-256 in CTR mode
4: AES-GCM-256-normal - Normal mode with AES-256 in GCM mode
Simple mode requires only password for decryption, while Normal mode allows optional
password protection of keys, requiring both the key file and password for decryption
on a new device.
OPTIONS
-p Specify your password. Gitl employs PBKDF2 algorithm to process your password,
generating a sufficiently secure key to encrypt your files.
-k Specify the key file path (exported by gitl exportkey).
-m Specify encryption mode (0-4). Default is 2 (AES-GCM-256-simple).
-c Clear all encryption configurations, and restore the git repository to an unencrypted state.
-i An indicator is displayed when there are files that need to be decrypted.
-g Display graphical user interface for initialization.
EXAMPLES
gitl init # Interactive mode
gitl init -p mypassword -m 2 # Initialize with password using AES-256-GCM-Simple
gitl init -k keyfile.key # Initialize with key file (Normal mode)
gitl init -c # Clear encryption information
gitl init -g # Show graphical interface
2.2 encrypt
Encrypt your files in git workspace:
NAME:
gitl-encrypt - Encrypt a file or directory
SYNOPSIS
gitl encrypt file/folder [-I][-E][-i][-g][-r]
DESCRIPTION
Encrypt the files of the git repository. By default, this command performs remote
encryption (files are encrypted when committed to the remote repository).
OPTIONS
-I Only encrypt files with specified extensions in the directory,
use semicolons to separate multiple file extensions, for example, "cpp;h;c".
-E Exclude files with specified extensions in the directory, use semicolons
to separate multiple file extensions, for example, "obj;a;so". -I and -E cannot
be used simultaneously.
-i Show indicator during encryption process.
-g Display graphical user interface for encryption.
-r Perform remote encryption (files are encrypted when committed to the remote repository).
This is the default behavior.
EXAMPLES
gitl encrypt src/ # Encrypt all files in src directory for remote repository
gitl encrypt . -I "cpp;h;c" # Only encrypt C/C++ source files in current directory
gitl encrypt . -E "obj;a;so" # Encrypt all files except object and library files
gitl encrypt . -g # Show graphical interface for encryption
2.3 decrypt
Decrypt your files in git workspace:
NAME:
gitl-decrypt - Decrypt a file or directory
SYNOPSIS
gitl decrypt file/folder [-I][-E][-i][-g][-r]
DESCRIPTION
Decrypt the files of the git repository. By default, this command performs remote
decryption (files are decrypted when pulled from the remote repository).
OPTIONS
-I Only decrypt files with specified extensions in the directory,
use semicolons to separate multiple file extensions, for example, "cpp;h;c".
-E Exclude files with specified extensions in the directory, use semicolons
to separate multiple file extensions, for example, "obj;a;so". -I and -E cannot
be used simultaneously.
-i Show indicator during decryption process.
-g Display graphical user interface for decryption.
-r Perform remote decryption (files are decrypted when pulled from the remote repository).
This is the default behavior.
EXAMPLES
gitl decrypt src/ # Decrypt all files in src directory from remote repository
gitl decrypt . -I "cpp;h;c" # Only decrypt C/C++ source files in current directory
gitl decrypt . -E "obj;a;so" # Decrypt all files except object and library files
gitl decrypt . -g # Show graphical interface for decryption
2.4 status
Show Encryption status:
NAME:
gitl-status - Show encryption information
SYNOPSIS
gitl status [file/folder]
DESCRIPTION
Display the encryption information of the file/folder. If no file or folder is specified,
shows the encryption status of the current directory.
The output shows the encryption status with the following indicators:
- R: File is encrypted for remote repository
EXAMPLES
gitl status # Show encryption status of current directory
gitl status src/ # Show encryption status of src directory
gitl status file.txt # Show encryption status of file.txt
2.5 exportkey
Export the encryption key for unlocking operations:
NAME:
gitl-exportkey - Export the encryption key
SYNOPSIS
gitl exportkey keypath [-g]
DESCRIPTION
Export the encryption key to the specified file path. This key can be used with
'gitl init -k keyfile' to initialize encryption on another device or after reinstallation.
For Normal mode encryption (modes 3 and 4), exporting the key is essential as the key
is not committed to the repository. Both the key file and password will be required
for decryption on a new device.
For Simple mode encryption (modes 0, 1, and 2), the key can be regenerated from the
password, but exporting provides a backup.
OPTIONS
-g Display graphical user interface for key export.
EXAMPLES
gitl exportkey ~/my-repo-key.key # Export key to specified file
gitl exportkey backup.key -g # Export key with graphical interface
3. Configuration file .gitlconf
.gitlconf is a configuration file placed in the git workspace, currently supporting the "include" and "exclude" fields, corresponding to the command line options -I and -E (command line takes precedence). The file format is as follows:
[config] include=c;cxx;h # or exclude=obj;a;so [encryption] mode=2
"include" and "exclude" fields cannot be used simultaneously.
The "mode" field in the [encryption] section specifies the encryption mode (0-4) as described in the init command section.
4. Shell Extensions
GitLocker provides shell extensions for different operating systems to make it easier to work with encrypted files directly from your file manager.
4.1 Windows Shell Extension
On Windows, GitLocker installs a shell extension (GitLockerShell.dll) that integrates with Windows Explorer. This extension adds context menu items when you right-click on files or folders in a Git repository.
Available context menu options:
- Init Crypt: Initialize encryption for the repository
- Encrypt: Encrypt selected files/folders for remote repository
- Decrypt: Decrypt selected files/folders from remote repository
- Encrypt Local: Encrypt selected files/folders locally
- Decrypt Local: Decrypt selected files/folders locally
- Edit Encrypted: Edit locally encrypted files
- Export Key: Export encryption key to a file
- Settings: Open GitLocker settings
The Windows shell extension is automatically registered during installation using the command:
regsvr32 /s path\GitLockerShell.dll
4.2 Linux Nautilus Extension
On Linux, GitLocker provides a Nautilus extension that adds similar functionality to the Nautilus file manager. The extension adds a "GitLocker" submenu to the context menu when right-clicking on files or folders.
4.3 macOS Finder Extension
On macOS, GitLocker integrates with Finder to provide similar functionality through context menus. The extension adds a "GitLocker" submenu to the context menu when right-clicking on files or folders.