github-mirror/rclone
2
0
Fork 0
mirror of https://github.com/rclone/rclone.git synced 2024-11-22 12:36:38 +08:00
Code Issues Actions 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

80
cmd/gitannex/gitannex.md
View File

@ -1,49 +1,69 @@
Rclone's gitannex subcommand enables git-annex to store and retrieve content 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. from an rclone remote. It is meant to be run by git-annex, not directly by
It is an "external special remote program" as defined by git-annex. users.
[git-annex]: https://git-annex.branchable.com/
Installation on Linux 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.
ln -s "$(realpath rclone)" "$HOME/bin/git-annex-remote-rclone-builtin" ```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 [10.20240430]: https://git-annex.branchable.com/news/version_10.20240430/
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.
* NOTE: If you are porting a remote from git-annex-remote-rclone, first 2. Add a new remote to your git-annex repo. This new remote will connect
change the externaltype from "rclone" to "rclone-builtin". Watch out, our git-annex with the `rclone gitannex` subcommand.
configs have slightly different names:
| config for "rclone" | config for "rclone-builtin" | Start by asking git-annex to describe the remote's available configuration
|:--------------------|:----------------------------| parameters.
| `prefix` | `rcloneprefix` |
| `target` | `rcloneremotename` | ```sh
| `rclone_layout` | `rclonelayout` | # 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 The following example creates a new git-annex remote named "MyRemote" that
will use the rclone remote named "SomeRcloneRemote". This rclone remote must will use the rclone remote named "SomeRcloneRemote". That rclone remote must
be configured in your rclone.conf file, wherever that is located on your be one configured in your rclone.conf file, which can be located with `rclone
system. The rcloneprefix value ensures that content is only written into the config file`.
rclone remote underneath the "git-annex-content" directory.
git annex initremote MyRemote \ ```sh
type=external \ git annex initremote MyRemote \
externaltype=rclone-builtin \ type=external \
encryption=none \ externaltype=rclone-builtin \
rcloneremotename=SomeRcloneRemote \ encryption=none \
rcloneprefix=git-annex-content \ rcloneremotename=SomeRcloneRemote \
rclonelayout=nodir rcloneprefix=git-annex-content \
rclonelayout=nodir
```
3. Before you trust this command with your precious data, be sure to **test the 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 remote**. This command is very new and has not been tested on many rclone
backends. Caveat emptor! backends. Caveat emptor!
git annex testremote my-rclone-remote ```sh
git annex testremote MyRemote
```
Happy annexing! Happy annexing!