Repository: borgbackup/borg

Issue:
borg diff --help should be more specific
Borg diff shows this: (tested with windows build)

```
bin>borg diff
usage: borg diff [-h] [--critical] [--error] [--warning] [--info] [--debug]
                 [--lock-wait N] [--show-version] [--show-rc]
                 [--no-files-cache] [--umask M] [--remote-path PATH]
                 [-e PATTERN] [--exclude-from EXCLUDEFILE] [--numeric-owner]
                 [--same-chunker-params] [--sort]
                ARCHIVE1 ARCHIVE2 [PATH [PATH ...]]
borg diff: error: the following arguments are required: ARCHIVE1, ARCHIVE2, PATH
```

So I assumed the syntax would be **archive1 archive2 path** 
In my case `borg diff MyData1 MyData2 \\WDMYCLOUD\Backups\PC\Dateien-Borg`

But the right syntax is **path::archive1 archive2** or
`borg diff  \\WDMYCLOUD\Backups\PC\Dateien-Borg::MyData1 MyData2`



Discussion:
PATH is a (optional) path inside the archive, it is not the repository's path.

If you see REPO or REPOSITORY as placeholder, that is the repo path (or url).
If you see ARCHIVE, it usually means REPO::ARCHIVE.

Not for ARCHIVE2 here obviously (which might be confusing) as that must be in same repo.


Resolving patch:
diff --git a/src/borg/archiver.py b/src/borg/archiver.py
--- a/src/borg/archiver.py
+++ b/src/borg/archiver.py
@@ -1937,10 +1937,11 @@ def build_parser(self, prog=None):
                                help='paths to extract; patterns are supported')
 
         diff_epilog = textwrap.dedent("""
-            This command finds differences in files (contents, user, group, mode) between archives.
+            This command finds differences (file contents, user/group/mode) between archives.
 
-            Both archives need to be in the same repository, and a repository location may only
-            be specified for ARCHIVE1.
+            A repository location and an archive name must be specified for REPO_ARCHIVE1.
+            ARCHIVE2 is just another archive name in same repository (no repository location
+            allowed).
 
             For archives created with Borg 1.1 or newer diff automatically detects whether
             the archives are created with the same chunker params. If so, only chunk IDs
@@ -1974,14 +1975,14 @@ def build_parser(self, prog=None):
         subparser.add_argument('--sort', dest='sort',
                                action='store_true', default=False,
                                help='Sort the output lines by file path.')
-        subparser.add_argument('location', metavar='ARCHIVE1',
+        subparser.add_argument('location', metavar='REPO_ARCHIVE1',
                                type=location_validator(archive=True),
-                               help='archive')
+                               help='repository location and ARCHIVE1 name')
         subparser.add_argument('archive2', metavar='ARCHIVE2',
                                type=archivename_validator(),
-                               help='archive to compare with ARCHIVE1 (no repository location)')
+                               help='ARCHIVE2 name (no repository location allowed)')
         subparser.add_argument('paths', metavar='PATH', nargs='*', type=str,
-                               help='paths to compare; patterns are supported')
+                               help='paths of items inside the archives to compare; patterns are supported')
 
         rename_epilog = textwrap.dedent("""
         This command renames an archive in the repository.


Test patch: