I'd like to point out that remove section isn't correct and may scare some people. I suggest to refer to use similar text as on https://fedoraproject.org/wiki/Package_maintenance_guide#Common_fedpkg_commands . So this is about referencing files uploaded in lookaside cache.

Well, new-sources does remove the filenames from sources file, but I agree it is not the best possible description.

Based on the linked document, the best I can come up with is this, which still quite bad.

• upload: Upload new source files to the lookaside cache
• new-sources: Upload new source files to the lookaside cache and set them as the only currently used sources

I read the guide again, and this time, I think "start from scratch" is the major difference between new-sources and upload, as described in below paragraph excerpted from the guide.

new-sources 'starts from scratch', replacing all files currently in the lookaside cache - you'll typically use this command for many packages with just a single source tarball, each time you update to a new upstream version. upload just adds the given file to those already in the cache. Do remember not to leave stale sources lying around.

Word "remove" would scare some people, however it is the truth of what new-sources does and it is already mentioned in its description text.

My proposed version based on Lubomir's comment is

• upload:
  • help: Upload new source files to the lookaside cache
  • description: This command will add a new source file(s) to the lookaside cache. All files that are already in lookaside cache still remain there. Both sources and .gitignore will be updated with new file(s). Please remember to commit them.
• new-sources:
  • help: Upload new source files to lookaside cache from scratch
  • description: This will upload new source files to the lookaside cache from scratch, and all files currently in lookaside cache will be replaced. Both sources and .gitignore will be updated with new uploaded file(s). Please remember to commit them.

Major points of update in this proposal are

• emphasize "from scratch" in new-sources
• remove word "remove" from description
• add information to tell nothing is removed from lookaside cache when uploading files by upload

@lsedlar @pbabinca what do you think? Looking forward to your comment.

Today I just found this is tracked in bug 1248737 and it was planned in next version rpkg-1.50 as well. So, we need to fix this. :)

Even when using new-sources nothing is ever removed from the cache itself. Only the filenames in sources file are removed. I'm still not convinced it's clear.

After discussion in irc channel, an updated version is

• upload:
  • help: Upload source files
  • description: This command will upload new source file(s) to lookaside cache. Source file names are appended to sources file, and .gitignore will be also updated with new uploaded file(s). Please remember to commit them.
• new-sources:
  • help: Upload source files
  • description: This will upload new source file(s) to lookaside cache, and all file names listed in sources file will be replaced. .gitignore will be also updated with new uploaded file(s). Please remember to commit them.

It's really hard to tell the difference in a short and simple sentence, so description text contains more information about the difference between these two commands.

+1 from me