Problem (mine, but also its?) with documentation about the 'backend' command

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:

type = drive
scope = drive


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

#### 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]


- "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]


- "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.


    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:".


- "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


    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.


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.


        "Untrashed": 17,
        "Errors": 0

So what is actually meant is the following?

rclone backend help <name of backend>:

I think I will file a bug report. For, this documentation is inadequate.

The name of the backend in your rclone.conf as I shared above.

All the rclone commands use the remote: nomenclature in the majority of the documentation that I have read.

No need to fill a bug report, if you'd like to make it more clear, you can edit/submit a PR as well.

There is a quick how to here:

As everyone can help to make it more clear to avoid any confusion.

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.


Thank you for replying.

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.

Do you think that would be clearer? So if the docs said

To copy a file use

rclone copy /path/to/local/stuff yourremote:

Instead of

rclone copy /path/to/local/stuff remote:

I think people might just make the same mistake with yourremote: as remote:

So we could write

rclone copy /path/to/local/stuff [Your remote goes here]:

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".

How about the following format?

rclone copy <path-to-your-local-stuff> <name-of-your-remote>:

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.

Thank you for writing that up.

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

rclone copy «/path/to/local/stuff» «remote:path/to/dir»

Perhaps just using

rclone copy /path/to/your/local/stuff name-of-your-remote:path/to/your/remote/stuff

would be sufficient.

I certainly think some docs at the point where we introduce the remote: terminology are needed.

I think your guillemet solution is best and your slash-and-dash solution second best.

1 Like

This topic was automatically closed 3 days after the last reply. New replies are no longer allowed.