Update syntax for argument to unlock (#14)

Author: AliSoftware

README.md

@@ -138,23 +138,26 @@ This will show the raw content as stored in the repository. So even if `cat my-s
 
 ### Unlock a repository
 
-After you freshly clone a repository which contains files which have been encrypted by `git-conceal`, you need to provide the symmetric key that your coworkers would have shared with you to decrypt it:
+After you freshly clone a repository which contains files which have been encrypted by `git-conceal`, you need to provide the symmetric key (that your coworkers would have shared with you) to decrypt it:
 
 ```bash
-# Option 1: Provide the key via an environment variable (base64 encoded). Recommended on CI.
-export GIT_SECRETS_KEY="YOUR_BASE64_KEY"
-git-conceal unlock env:GIT_SECRETS_KEY
-
-# Option 2: Provide the Base64-encoded key as command line argument. (Only use locally, as on CI this could leak the key in logs).
-git-conceal unlock "base64:c3VwcG9zZWRseS15b3VyLWJpbmFyeS1zZWNyZXRrZXk="
-
-# Option 3: Provide a path to a from file containing the raw binary, 32 bytes key.
-git-conceal unlock /path/to/key.bin
-
-# Option 4: Provide it via stdin (expects raw binary, 32 bytes as input)
-cat /path/to/key.bin | git-conceal unlock -
-# Or convert from base64. (Only use locally, as on CI this could leak the key in logs).
-echo "c3VwcG9zZWRseS15b3VyLWJpbmFyeS1zZWNyZXRrZXk=" | base64 -d | git-conceal unlock -
+# Option 1: Provide the Base64-encoded key directly as command line argument.
+# Only use locally, as on CI this could leak the key in logs.
+# Tip: start your command with a space to avoid it (and thus the key) being added to your shell's history
+$  git-conceal unlock "c3VwcG9zZWRseS15b3VyLWJpbmFyeS1zZWNyZXRrZXk="
+
+# Option 2: Provide the key via an environment variable (base64 encoded), by using the `env:` prefix.
+# Recommended on CI, where secret values like the key are usually exposed to jobs as env vars.
+# Prefer this over `git-conceal unlock $GIT_CONCEAL_SECRET_KEY` to reduce the risk of accidentally leaking
+# the key e.g. in CI logs (which might resolve `$VAR` env vars before printing the resolved command in logs)
+$ git-conceal unlock env:GIT_CONCEAL_SECRET_KEY
+
+# Option 3: Provide it via stdin (expects raw binary, 32 bytes as input)
+# For example, if you have the binary key in a file (which you would hopefully have protected properly!)
+$ git-conceal unlock - </path/to/keyfile.bin
+# Or if you have the base64-encoded key in your clipboard, you could do:
+$ pbpaste | base64 -d | git-conceal unlock -
+# (Though in that case `git-conceal unlock $(pbpaste)` would achieve the same thing)
 ```
 
 This will:
@@ -186,7 +189,7 @@ git-conceal status
 This shows:
 - Whether the repository is locked or unlocked
 - Whether filters are configured
-- Which file patterns are encrypted (from `.gitattributes`)
+- Which files are handled by `git-conceal` (i.e. tracked files matching one of the patterns with `filter=git-conceal` in your `.gitattributes`)
 
 ```bash
 git-conceal status <FILES>
@@ -205,7 +208,7 @@ git-conceal key show
 ### Rotate the encryption key
 
 There are times when you might need to rotate the encryption key used in an encrypted repository.
-For example, in the unfortunate even of the key leaking or when a coworker leaves your team/company and you want to ensure they can't access new secrets.
+For example, in the unfortunate event of the key leaking, or when a coworker leaves your team/company and you want to ensure they can't access new secrets.
 
 You can rotate the encryption key with:
 
@@ -245,15 +248,19 @@ For detailed security information, including key management, deterministic encry
 
 ## New releases
 
-Releases are automated by our CI every time we make a `git tag` on the repo. Be sure to update the version in the `Cargo.toml` first though.
+Releases are automated by our CI every time we make a `git tag` on the repo.
+
+<details><summary>Release instructions for maintainers</summary>
 
  - Create a `release/x.y.z` branch
  - Edit `Cargo.toml` to update the `version = "x.y.z"` field
- - Run `cargo check` to update the `Cargo.lock` and validate the code still compiles
+ - Run `cargo check` to update the `Cargo.lock` with the new version and validate the code still compiles
  - `git add Cargo.toml Cargo.lock` then `git commit -m "Bump version to x.y.z"`
- - Create a PR and get it merged
+ - Create a PR with those changes and get it merged into `trunk`
  - Once it has landed in `trunk`, push a new tag (`git tag "x.y.z"` then `git push origin "x.y.z"`)
- - Then let the CI build the release binaries for all platforms, create the GitHub Release, and attach the compiled binaries as assets.
+
+The CI will trigger on the Git tag and take care of building the release binaries for all platforms and creating the GitHub Release with those binaries attached as assets.
+</details>
 
 ## License
 

src/commands/init.rs

@@ -43,15 +43,14 @@ fn init_instructions(key_b64: &str) -> String {
             {key_b64}
 
             Once you share this key with users you trust, they can unlock their working copy using one of these methods:
+              - From base64-encoded key passed directly as argument:
+                {bin_name} unlock "{key_b64}"
               - From environment variable (base64):
-                export GIT_SECRETS_KEY='{key_b64}'
-                {bin_name} unlock env:GIT_SECRETS_KEY
-              - From base64-encoded key in the command line:
-                {bin_name} unlock "base64:{key_b64}"
-              - From file (raw binary, 32 bytes):
-                {bin_name} unlock /path/to/key.bin
+                export GIT_CONCEAL_SECRET_KEY='{key_b64}'
+                {bin_name} unlock env:GIT_CONCEAL_SECRET_KEY
               - From stdin (raw binary, 32 bytes):
                 echo '{key_b64}' | base64 -d | {bin_name} unlock -
+                {bin_name} unlock - < /path/to/raw-binary-key.bin
 
             To start adding files to be encrypted in this repository:
               - List files (or file patterns) you want to encrypt in your `.gitattributes` file, like this:

src/key.rs

@@ -72,10 +72,9 @@ impl Key {
     /// Read encryption key from various sources
     ///
     /// Supports:
-    /// - `"-"` for reading from stdin (raw binary format, 32 bytes)
+    /// - Base64-encoded key string (passed directly as argument)
     /// - `"env:VARNAME"` for reading from environment variable (base64 encoded)
-    /// - `"base64:BASE64_KEY"` for reading from base64-encoded key
-    /// - File path for reading from a file (raw binary format, 32 bytes)
+    /// - `"-"` for reading from stdin (raw binary format, 32 bytes)
     ///
     /// Returns the encryption key.
     pub fn read_from_source(key_source: &str) -> Result<Self> {
@@ -95,11 +94,9 @@ impl Key {
                 format!("Failed to read key from environment variable {}", env_var)
             })?;
             Self::from_base64(&key_b64)
-        } else if let Some(base64_key) = key_source.strip_prefix("base64:") {
-            Self::from_base64(base64_key)
         } else {
-            // Read from file (raw binary format)
-            Self::from_file(Path::new(key_source))
+            // Treat as base64-encoded key (unprefixed)
+            Self::from_base64(key_source)
         }
     }
 }
@@ -301,18 +298,6 @@ mod tests {
         assert!(result.unwrap_err().to_string().contains("Invalid key size"));
     }
 
-    #[test]
-    fn test_read_from_source_file() {
-        let temp_dir = TempDir::new().unwrap();
-        let key_file = temp_dir.path().join("test.key");
-
-        let key = test_key();
-        fs::write(&key_file, key.as_bytes()).unwrap();
-
-        let loaded_key = Key::read_from_source(key_file.to_str().unwrap()).unwrap();
-        assert_eq!(loaded_key.as_bytes(), key.as_bytes());
-    }
-
     /// This test must run serially (not in parallel with other tests) because it modifies
     /// environment variables. Environment variable modification is not thread-safe and can
     /// cause race conditions when tests run in parallel.
@@ -398,18 +383,23 @@ mod tests {
     fn test_read_from_source_base64() {
         let key = test_key();
         let b64 = key.to_base64();
-        let loaded_key = Key::read_from_source(&format!("base64:{}", b64)).unwrap();
+        let loaded_key = Key::read_from_source(&b64).unwrap();
         assert_eq!(loaded_key.as_bytes(), key.as_bytes());
     }
 
     // Note: Testing stdin reading is complex in unit tests as it requires
     // mocking stdin or using a separate process. This would be better suited
-    // for integration tests. The file and env var cases are tested above.
+    // for integration tests. The env var and base64 cases are tested above.
 
     #[test]
-    fn test_read_from_source_invalid_source() {
-        let result = Key::read_from_source("/nonexistent/path/key.bin");
+    fn test_read_from_source_invalid_base64() {
+        // A user accidentally passing a file path should be treated as base64 key and fail to decode
+        let result = Key::read_from_source("path/to/secret-symmetric-key.bin");
         assert!(result.is_err());
+        assert!(result
+            .unwrap_err()
+            .to_string()
+            .contains("Failed to decode base64 key"));
     }
 
     #[test]

src/main.rs

@@ -50,11 +50,10 @@ enum Commands {
     Unlock {
         /// Key source
         #[arg(
-            value_name = "KEY_SOURCE",
-            long_help = "- 'env:VARNAME': base64-encoded key in environment variable (recommended on CI)\n\
-                         - 'base64:BASE64_KEY': base64-encoded key\n\
-                         - '-': raw binary key from stdin\n\
-                         - <PATH>: raw binary key from file"
+            value_name = "KEY",
+            long_help = "- 'BASE64KEY': the base64-encoded key passed directly as argument\n\
+                         - 'env:VARNAME': read the base64-encoded key from the given environment variable (recommended on CI)\n\
+                         - '-': read the raw binary key from stdin (expects raw binary, 32 bytes as input)"
         )]
         key_source: String,
     },