I have trouble understanding what is said on this page. The page says one can do rclone backend help <backendname> and rclone backend help remote:. So I tried the first of those commands:
$ rclone backend help b2
2021/01/13 02:05:20 Failed to backend: b2 backend has no commands
Does that mean that a backend call 'b2' was recognised, but offers no backend commands? I presume 'yes'. OK. But now I tried the second command.
rclone backend help remote:
2021/01/13 02:05:29 Failed to backend: didn't find section in config file
$ rclone backend help remote:enc-b2
2021/01/13 02:05:47 Failed to backend: didn't find section in config file
$ rclone backend help remote:b2
Am I meant to specify the name of the remote? The documentation seems to leave that matter unclear. But then - as shown - I did try, with no success, to specify a remote: I had a remote called 'b2' (even though that's the same name - yes? - as the backend) and one called 'enc-b2' (which is the encrypted version of the first remote, or something like that).
Just like the other rclone commands, you substitute the remote name with a colon
So if you see something like:
rclone ls remote:
You replace the "remote:" with your rclone.conf's named "remote:"
Mine looks like:
[GD]
type = drive
scope = drive
So
felix@gemini:/opt/rclone$ rclone backend help GD:
### Backend commands
Here are the commands specific to the drive backend.
Run them with
rclone backend COMMAND remote:
The help below will explain what arguments each command takes.
See [the "rclone backend" command](/commands/rclone_backend/) for more
info on how to pass options and arguments.
These can be run on a running backend using the rc command
[backend/command](/rc/#backend/command).
#### get
Get command for fetching the drive config parameters
rclone backend get remote: [options] [<arguments>+]
This is a get command which will be used to fetch the various drive config parameters
Usage Examples:
rclone backend get drive: [-o service_account_file] [-o chunk_size]
rclone rc backend/command command=get fs=drive: [-o service_account_file] [-o chunk_size]
Options:
- "chunk_size": show the current upload chunk size
- "service_account_file": show the current service account file
#### set
Set command for updating the drive config parameters
rclone backend set remote: [options] [<arguments>+]
This is a set command which will be used to update the various drive config parameters
Usage Examples:
rclone backend set drive: [-o service_account_file=sa.json] [-o chunk_size=67108864]
rclone rc backend/command command=set fs=drive: [-o service_account_file=sa.json] [-o chunk_size=67108864]
Options:
- "chunk_size": update the current upload chunk size
- "service_account_file": update the current service account file
#### shortcut
Create shortcuts from files or directories
rclone backend shortcut remote: [options] [<arguments>+]
This command creates shortcuts from files or directories.
Usage:
rclone backend shortcut drive: source_item destination_shortcut
rclone backend shortcut drive: source_item -o target=drive2: destination_shortcut
In the first example this creates a shortcut from the "source_item"
which can be a file or a directory to the "destination_shortcut". The
"source_item" and the "destination_shortcut" should be relative paths
from "drive:"
In the second example this creates a shortcut from the "source_item"
relative to "drive:" to the "destination_shortcut" relative to
"drive2:". This may fail with a permission error if the user
authenticated with "drive2:" can't read files from "drive:".
Options:
- "target": optional target remote for the shortcut destination
#### drives
List the shared drives available to this account
rclone backend drives remote: [options] [<arguments>+]
This command lists the shared drives (teamdrives) available to this
account.
Usage:
rclone backend drives drive:
This will return a JSON list of objects like this
[
{
"id": "0ABCDEF-01234567890",
"kind": "drive#teamDrive",
"name": "My Drive"
},
{
"id": "0ABCDEFabcdefghijkl",
"kind": "drive#teamDrive",
"name": "Test Drive"
}
]
#### untrash
Untrash files and directories
rclone backend untrash remote: [options] [<arguments>+]
This command untrashes all the files and directories in the directory
passed in recursively.
Usage:
This takes an optional directory to trash which make this easier to
use via the API.
rclone backend untrash drive:directory
rclone backend -i untrash drive:directory subdir
Use the -i flag to see what would be restored before restoring it.
Result:
{
"Untrashed": 17,
"Errors": 0
}
Thanks. However, if you'd seen my previous attempt to file a pull request (which was not against this repository) then I believe you would not think that my so doing would reduce confusion! For, I bodged the pull request. Also, if all the rclone documents use that nomenclature - which I regard as unclear, because it doesn't distinguish the literal from that which one must substitute - then that's too much for me to change.
The rclone docs use the shorthand remote: to mean the name of a remote that you defined.
I agree this could be called out better in the docs.
What do you think the best way of doing this would be @LinuxOnTheDesktop ? I thought maybe I should have a box near the top of every backend page and one on the /docs page which says something like this
When you see remote: in the documentation, this is a place holder showing where you can put your own name. When you define a connection to a backend, known as a remote, you can use your own name for it. For example if you are making a Google Drive remote you might decide to call it gdrive. You would then use dgrive: wherever the docs say remote:
Though I don't like the reference to Google Drive if it is going on all the backend pages, but I do like having an example.
The documentation speaks often of 'remote:' and by so doing the documentation is unclear. For, is one or is one not meant to substitute text for 'remote'? Your answer is: yes, you are to substitute. Your proposed remedy for the unclarity is a kind of disclaimer, to that effect. That would be something. Would it not be better though to convey the point through the way the documentation refers to the remote? To that end that documentation might speak of '[your remote]' - though I would have used different symbols, were this otherwise admirable forum not to have mangled my symbols.
But that then assumes the user will delete the [ and ] and write their remote name, and not write [gdrive]:
There are >300 mentions of the word remote: in the docs so I think I prefer the disclaimer approach.
On the website I could do some magic so that the word remote: has an asterisk by it so the hover over text gives the disclaimer. This won't work for the man pages / text doc / etc but might be interesting.
I got the idea of the remote: syntax from a combination of the bookmarks feature in ncftp and the host syntax in ssh/sftp/rsync, so if it stands for anything it might be "remote bookmarked cloud storage".
Note the angle brackets and the hyphens (and indeed, if you can preserve this, the helpful colouration).
Now the trailing colon might confuse. Yet, when the documentation gives a general explanation of the formatting that it uses, it could mention the colon. For you could have something like the following.
NOTE. Angle brackets (a.k.a. chevrons) that appear within the documentation are not to be typed. Rather they signify text for which the user is to substitute something. Consider the following example. rclone copy <path-to-your-local-stuff> <name-of-your-remote>: You are to replace <path-to-your-local-stuff> with a path and <name-of-your-remote> with the name of the 'remote' at issue. Also, and the example just given means to show: within rclone commands, any mentions of a remote must be followed by a colon.
Adopting the format that I commend here would require many changes to the documentation. Perhaps though you could write a script to make the changes.
Note also that the while the above note is rather long, it is also, for the computer-literate user, mostly redundant. For, she will know that <remote> means whatever-your-remote-is. However, such a user may not realise that remote: (without the angle brackets) means your-remote and indeed that more specifically it means your-remote-followed-by-a-colon. Such indeed is the rationale for my proposed changes to the documentation.
One problem with using angle brackets is that they are really awkward to use in markdown which is what the docs are written in. They get confused with HTML markup which means the contents disappears (this is a problem I've had with the docs).
I wonder whether the guillemet would do instead of chevrons