Skip to content

"rsync for cloud storage" - Google Drive, S3, Dropbox, Backblaze B2, One Drive, Swift, Hubic, Wasabi, Google Cloud Storage, Azure Blob, Azure Files, Yandex Files

cmd/gitannex: Update command docs

Dan McArdledac7f76b1422
diff --git a/cmd/gitannex/gitannex.md b/cmd/gitannex/gitannex.md
index 87d0e8092..5ffa8872b 100644
--- a/cmd/gitannex/gitannex.md
+++ b/cmd/gitannex/gitannex.md
@@ -1,49 +1,69 @@
-Rclone's gitannex subcommand enables git-annex to store and retrieve content
-from an rclone remote. It expects to be run by git-annex, not directly by users.
-It is an "external special remote program" as defined by git-annex.
+Rclone's `gitannex` subcommand enables [git-annex] to store and retrieve content
+from an rclone remote. It is meant to be run by git-annex, not directly by
+users.
+
+[git-annex]: https://git-annex.branchable.com/
Installation on Linux
---------------------
-1. Create a symlink and ensure it's on your PATH. For example:
+1. Skip this step if your version of git-annex is [10.20240430] or newer.
+ Otherwise, you must create a symlink somewhere on your PATH with a particular
+ name. This symlink helps git-annex tell rclone it wants to run the "gitannex"
+ subcommand.
+
+ ```sh
+ # Create the helper symlink in "$HOME/bin".
+ ln -s "$(realpath rclone)" "$HOME/bin/git-annex-remote-rclone-builtin"
+
+ # Verify the new symlink is on your PATH.
+ which git-annex-remote-rclone-builtin
+ ```
- ln -s "$(realpath rclone)" "$HOME/bin/git-annex-remote-rclone-builtin"
+ [10.20240430]: https://git-annex.branchable.com/news/version_10.20240430/
-2. Add a new external remote to your git-annex repo.
+2. Add a new remote to your git-annex repo. This new remote will connect
+ git-annex with the `rclone gitannex` subcommand.
- The new remote's type should be "rclone-builtin". When git-annex interacts
- with remotes of this type, it will try to run a command named
- "git-annex-remote-rclone-builtin", so the symlink from the previous step
- should be on your PATH.
+ Start by asking git-annex to describe the remote's available configuration
+ parameters.
- * NOTE: If you are porting a remote from git-annex-remote-rclone, first
- change the externaltype from "rclone" to "rclone-builtin". Watch out, our
- configs have slightly different names:
+ ```sh
+ # If you skipped step 1:
+ git annex initremote MyRemote type=rclone --whatelse
- | config for "rclone" | config for "rclone-builtin" |
- |:--------------------|:----------------------------|
- | `prefix` | `rcloneprefix` |
- | `target` | `rcloneremotename` |
- | `rclone_layout` | `rclonelayout` |
+ # If you created a symlink in step 1:
+ git annex initremote MyRemote type=external externaltype=rclone-builtin --whatelse
+ ```
+
+ > **NOTE**: If you're porting an existing [git-annex-remote-rclone] remote to
+ > use `rclone gitannex`, you can probably reuse the configuration parameters
+ > verbatim without renaming them. Check parameter synonyms with `--whatelse`
+ > as shown above.
+ >
+ > [git-annex-remote-rclone]: https://github.com/git-annex-remote-rclone/git-annex-remote-rclone
The following example creates a new git-annex remote named "MyRemote" that
- will use the rclone remote named "SomeRcloneRemote". This rclone remote must
- be configured in your rclone.conf file, wherever that is located on your
- system. The rcloneprefix value ensures that content is only written into the
- rclone remote underneath the "git-annex-content" directory.
-
- git annex initremote MyRemote \
- type=external \
- externaltype=rclone-builtin \
- encryption=none \
- rcloneremotename=SomeRcloneRemote \
- rcloneprefix=git-annex-content \
- rclonelayout=nodir
+ will use the rclone remote named "SomeRcloneRemote". That rclone remote must
+ be one configured in your rclone.conf file, which can be located with `rclone
+ config file`.
+
+ ```sh
+ git annex initremote MyRemote \
+ type=external \
+ externaltype=rclone-builtin \
+ encryption=none \
+ rcloneremotename=SomeRcloneRemote \
+ rcloneprefix=git-annex-content \
+ rclonelayout=nodir
+ ```
3. Before you trust this command with your precious data, be sure to **test the
remote**. This command is very new and has not been tested on many rclone
backends. Caveat emptor!
- git annex testremote my-rclone-remote
+ ```sh
+ git annex testremote MyRemote
+ ```
Happy annexing!