Minor bug: Return code from `rclone check`

What is the problem you are having with rclone?

rclone check has exit code 1 when differences were found.

The Documentation state that this exit code means "Syntax or usage error"

But I think I'm using rclone check correctly.

Its just there are different files in each location.

Suggest a new exit code specifically for this scenario (or maybe exit code 2 as last resort)

FWIW exit code is 0 when there are no differences.

This is a really minor thing but in my application I capture the return code and map it to the description in the docs, and finally return it to my user.

The description "syntax or usage error" makes it seem like PEBKAC but really the user and rclone check are doing what they are supposed to.

Run the command 'rclone version' and share the full output of the command.

rclone-v1.65.1 version
rclone v1.65.1

  • os/version: Microsoft Windows 10 Enterprise 21H2 (64 bit)
  • os/kernel: 10.0.19044.3448 (x86_64)
  • os/type: windows
  • os/arch: amd64
  • go/version: go1.21.5
  • go/linking: static
  • go/tags: cmount

Which cloud storage system are you using? (eg Google Drive)

N/A

The command you were trying to run (eg rclone copy /tmp remote:tmp)

rclone-v1.65.1 check some_folder a_different_folder
...

echo $LastExitCode
1

The rclone config contents with secrets removed.

N/A

A log from the command with the -vv flag

N/A

Several of those documented exit codes are primarily for copy/sync and similar commands, I think. But yes, I agree that returning exit code 1 may be misleading. I think it would be pretty easy to improve this, the main challenge is to pick a number.. :sweat_smile:

Exit code 2 I don't think is even in use. It is documented as "Error not otherwise categorised", but can't find any traces of it ever being returned in code.

We could go all-in robocopy exit code style... or like I remember FSUM checksum tool did, which was to indicate actual number of errors (file mismatches) in the exit code. Would be doable, but probably not necessary, too much effort for too little gain? And I see a risk of it ending up in a can of worms.

So, should we try to turn those exit codes up to eleven then (I mean pick next unused exit code, 11)? Or any better ideas?

I think a new exit code sounds like the best idea - none of the other ones seem to fit!

bisync actually uses it:

But it probably ought to be consistent with the rest of rclone. I doubt anyone would mind if we changed it.

Exit code 2 has a traditional meaning for Unix CLI programs

Exit status 2: command line usage error

Though we seem to return exit code 1 for unknown flags

Yes, we return exit code 1 for both usage errors, like unknown flags or invalid number of arguments, as well as for general errors. I think exit code 1 definitively makes sense to use as a default, i.e. for "error not otherwise categorised", but then as you say, exit code 2 may be appropriate to use for usage errors.

So:

The documentation currently states:

  • 0 - success
  • 1 - Syntax or usage error
  • 2 - Error not otherwise categorised

What we actually do, currently:

  • 0 - success
  • 1 - Syntax or usage error, and errors not otherwise categorised
  • 2 - (Not in use - except bisync)

What we should do:

  • 0 - success
  • 1 - Errors not otherwise categorised
  • 2 - Syntax or usage error

(I've started testing this out, via a PR Changes to exit codes by albertony · Pull Request #7602 · rclone/rclone · GitHub)

I did a bit of a survey - it looks like when I said "Exit code 2 has a traditional meaning for Unix CLI programs" that wasn't terribly accurate!

$ ls --sdfsfsdf ; echo $?
ls: unrecognised option '--sdfsfsdf'
Try 'ls --help' for more information.
2
$ rsync --sdfsfsdf ; echo $?
rsync: --sdfsfsdf: unknown option
rsync error: syntax or usage error (code 1) at main.c(1795) [client=3.2.7]
1
$ vi --sdfsfsdf ; echo $?
VIM - Vi IMproved 8.2 (2019 Dec 12, compiled Dec 05 2023 17:58:57)
Unknown option argument: "--sdfsfsdf"
More info with: "vim -h"
1
$ less --sdfsfsdf ; echo $?
There is no sdfsfsdf option ("less --help" for help)
Missing filename ("less --help" for help)
0
$ zip --sdfsfsdf ; echo $?

zip error: Invalid command arguments (long option 'sdfsfsdf' not supported)
16
$ tar --sdfsfsdf ; echo $?
tar: unrecognised option '--sdfsfsdf'
Try 'tar --help' or 'tar --usage' for more information.
64
$ gzip --sdfsfsdf ; echo $?
gzip: unrecognized option '--sdfsfsdf'
Try `gzip --help' for more information.
1
$ git --sdfsfsdf ; echo $?
unknown option: --sdfsfsdf
usage: git [--version] [--help] [-C <path>] [-c <name>=<value>]
           [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
           [-p | --paginate | -P | --no-pager] [--no-replace-objects] [--bare]
           [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
           [--super-prefix=<path>] [--config-env=<name>=<envvar>]
           <command> [<args>]
129

So from that I think we can make up something different if we want!

Note that there are quite a few places where we do log.Fatal - I think these exit with error code 1 which is where those are coming from. (I'm trying to root out all the log.Fatal as they don't play nice with librclone though!)

This makes sense if we are using log.Fatal - leave it as the catch all then we can specifically use 2 for Syntax or usage error.

1 Like