github-mirror/rclone
2
0
Fork 0
mirror of https://github.com/rclone/rclone.git synced 2024-11-25 09:41:44 +08:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

cmd/gitannex: Update command docs

Browse Source 
Mentioned the possibility of skipping the symlink for new versions of
git-annex. (Probably deserves a test once the new git-annex trickles
down to CI platforms.)

I stopped trying to explain each config parameter here. Rather, the doc
now shows the user how to ask git-annex to describe config parameters
with `--whatelse`.
This commit is contained in:
Dan McArdle 2024-05-18 14:53:57 -04:00 committed by Nick Craig-Wood
parent 446d6b28b8
commit dac7f76b14
1 changed files with 50 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
cmd/gitannex/gitannex.md
View File

@ -1,37 +1,54 @@
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"
2. Add a new external remote to your git-annex repo.
# Verify the new symlink is on your PATH.
which git-annex-remote-rclone-builtin
```
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.
[10.20240430]: https://git-annex.branchable.com/news/version_10.20240430/
* 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:
2. Add a new remote to your git-annex repo. This new remote will connect
git-annex with the `rclone gitannex` subcommand.
| config for "rclone" | config for "rclone-builtin" |
|:--------------------|:----------------------------|
| `prefix` | `rcloneprefix` |
| `target` | `rcloneremotename` |
| `rclone_layout` | `rclonelayout` |
Start by asking git-annex to describe the remote's available configuration
parameters.
```sh
# If you skipped step 1:
git annex initremote MyRemote type=rclone --whatelse
# 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.
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 \
@ -39,11 +56,14 @@ Installation on Linux
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!