Hi there,
I'm a relatively new to git-annex and quite impressed so far.
I've found the command to be somewhat less self-documenting than I'd like it to be for a new user.
Particularly, since it's a git subcommand, I'd wish for annex to 'mirror' as many subcommands as possible
with annex-enabled equivalents. My chief complaint at the moment is that it is a bit hard to remember the
specific commands for showing remotes (git annex info has no equivalent git info) and git annex remote
should ideally return a list of remotes for parallelism.
Similarly, it'd be nice if some of the commands were a bit nested to match git semantics. This would increase discoverability:
For instance, git annex enableremote -> git annex remote enable or git annex renameremote -> git annex remote rename. Then subcommands for dealing with remotes
could be more easily summarized on a single page in the git-annex-remote section.
It's worth noting that such changes could happen alongside the current commands without a loss of functionality. Git core has recently gone through a similar process to simplify the semantics of some of its commands. I'd ask for such changes to be considered.
Daven
wontfix at least for the listed things, for reasons explained in my comment below. --Joey
git-annex can't be limited to commands that happen to have equivilant git commands.
git annex dropalso has no equivilant in git, but is fundamental to git-annex.If you're thinking of
git annex infoas equivilant togit remotein listing remotes, that does not consider everything the info command does.git remotelists all remotes including git-annex special remotes, sogit annex remotewould be unnecessary duplication.This would encourage drawing a false equivilance with
git remote rename.I'm also not convinced that stacking subcommands 3 levels deep is a good idea. The user has to dig through every level to find something then.
There's also an intentional similarity in naming between
git annex initandgit annex initremote, which I think makes sense and helps users learn and remember the latter command after having first learned the former. Andenableremoteandrenameremotethen flow naturally from that. This is, IMHO, a more natural learning flow than searching for strained equivilances togit remotecommands.I do think that
git annex addhas a very good reason to parallelgit add, and if there are other git-annnex commands that could directly parallel a git command like that and don't, that would be worth addressing.Fair enough, I suppose. However, I think that feedback from early-stage users should be weighted highly, as we interact with "onboarding"/"discoverability" problems that eventually fade from being users' primary impediments to use.
I'm not suggesting that all commands should have
gitequivalents. Instead, when a commonly used equivalent (or close relative) is available, the name should be mirrored to increase discoverability of common idioms.I'm not quite sure why the equivalence would be false — yes, the commands do somewhat different things. But they both fundamentally rename a remote.
Again, I am not sure the equivalences are so strained. Users should not (and I think broadly won't) expect a git-annex subcommand to do exactly the same thing as a git equivalent. But semantic-level parallelism with git top-level commands, and adopting git's pattern of grouping like functionality into subcommands, could greatly improve discoverability. As it stands, the goals of preventing confusion between similarly named functionality and allowing functionality to be easily found are in tension.
Another way to frame my suggestion is to consider the layout of the
git-annexcommand line help output. Right now, when seeking assistance, the user is presented with a long list of commands and has to hunt for related functionality (renameremote,enableremote, etc.) within it. In contrast, when I typegit remote --help, I see all of the commands for managing remotes in a single, shorter output. It is another nesting level, true, but I think a help page entry ofremote - manages git-annex special remoteswould be easier to parse than the current output.Anyway, I appreciate your work on this system and consideration of user feedback.
Regards, Daven