Bug#1026833: git-annex: git-annex-addurl(1): Documentation and behaviour of --file= differ

[Axel Beckert]

Package: git-annex
Version: 10.20221003-3
Severity: minor
Tags: upstream

Hi,

Because youtube-dl can't cope with some sites, I downloaded a file with
yt-dlp manually and wanted to add it with "git annex addurl" later.

The man page says:

  --file=name

        Use with a filename that does not yet exist to add a new file
        with the specified name and the content downloaded from the url.

        If the file already exists, addurl will record that it can be
        downloaded from the specified url(s).

So I tried the following:

  $ yt-dlp -o existing_file.mp4 https://some.videosite.example.com/existing_file.mp4
  $ git annex addurl --raw --relaxed --file=existing_file.mp4 https://some.videosite.example.com/existing_file.mp4

But the latter failed as follows:

  addurl https://some.videosite.example.com/existing_file.mp4
    existing_file.mp4 already exists; not overwriting
  failed
  addurl: 1 failed

But that's not what is expected to happen according to the man page.

What actually did help was running the following command inbetween the
two commands above:

  $ git annex add existing_file.mp4

But that's not (exactly) what the man page says. So I see two ways to
fix this issue:

  1. Update the man page to state that "already exists" actually means
    "already exists in the index or repository".

  2. Update the behaviour of "git annex addurl --file=" to also accept
     existing, but not yet added files and add them in the same run,
     too.

(This is probably an upstream issue, tagging as such.)

-- System Information:
Debian Release: bookworm/sid
  APT prefers unstable
  APT policy: (990, 'unstable'), (600, 'testing'), (500, 'unstable-debug'), (500, 'buildd-unstable'), (110, 'experimental'), (1, 'experimental-debug'), (1, 'buildd-experimental')
merged-usr: no
Architecture: amd64 (x86_64)
Foreign Architectures: i386

Kernel: Linux 5.18.0-4-amd64 (SMP w/8 CPU threads; PREEMPT)
Kernel taint flags: TAINT_WARN
Locale: LANG=C.UTF-8, LC_CTYPE=C.UTF-8 (charmap=UTF-8), LANGUAGE not set
Shell: /bin/sh linked to /bin/dash
Init: sysvinit (via /sbin/init)
LSM: AppArmor: enabled

Versions of packages git-annex depends on:
ii  curl            7.86.0-2
ii  git             1:2.39.0-1
ii  libc6           2.36-6
ii  libffi8         3.4.4-1
ii  libgmp10        2:6.2.1+dfsg1-1.1
ii  libmagic1       1:5.41-4
ii  libsqlite3-0    3.40.0-2
ii  libyaml-0-2     0.2.5-1
ii  netbase         6.4
ii  openssh-client  1:9.1p1-1
ii  rsync           3.2.7-1
ii  zlib1g          1:1.2.13.dfsg-1

Versions of packages git-annex recommends:
ii  aria2              1.36.0-1
ii  bind9-host         1:9.18.8-1
ii  git-remote-gcrypt  1.5-1
ii  gnupg              2.2.40-1
ii  lsof               4.95.0-1
ii  nocache            1.1-1+b1

Versions of packages git-annex suggests:
ii  adb             1:29.0.6-21
ii  bup             0.32-3+b1
ii  libnss-mdns     0.15.1-3
ii  magic-wormhole  0.12.0-1
pn  tahoe-lafs      <none>
ii  tor             0.4.7.12-1
ii  uftp            4.10.2-1.1+b2
ii  xdot            1.2-3
ii  yt-dlp          2022.11.11-1

-- no debconf information