On Mon, 27 Nov 2006 14:05:27 -0800, Junio C Hamano wrote: > > Maybe that could be a good rule of thumb to have all porcelainish > > commands not have any hyphen in their name, like "diff", "commit", > > "add", etc. ? I like the proposed rule-of-thumb very much. (Particularly if "update-index" could be included on the list of things to eliminate, in favor of a new "git resolve" for resolving merges.) There's another rule-of-thumb I would like to propose that's a bit harder to state, but I think is just as important (if not more): For introductory documentation it should never make sense to introduce a command with specific command-line options before the same command without options. As examples, both "commit -a" and "cat-file -p" fail that test and both appear in the git tutorial here: http://www.kernel.org/pub/software/scm/git/docs/tutorial.html My proposals to fix those two are: commit -a Change "commit" to commit the working tree. The current "commit index" option would be made available with a new "-i" or "--index" option, which could easily be made the default in a config file for any users that always want it. For merging, commit would also use the working tree, but would balk at any unmerged paths in the index, (which would have to be fixed with "git resolve" first). cat-file -p Add new "cat" command with the functionality of "cat-file -p", (also succeeds in removing a hyphenated command from the tutorial). > I was also hoping that would become the case except verify-tag, > cherry-pick, and format-patch. Here are some none-too-considered options for even cleaning up those: verify-tag A new "git verify" which would accept any object specifier and do a restricted fsck on it, or a tag verification. Of course, the output should clearly indicate whether a signed-tag had been verified or just a tree object. [Perhaps the semantic mixing of signature verification and object integrity verification makes this a bad idea. I don't know.] cherry-pick The name "cherry" is promising, but problematic in that it's already used for another command, (which is definitely at a lower-level in functionality, so would violate the rule-of-thumb being considered here). format-patch I mentioned before that I'd like to see "export" and "import" as commands to replace the functionality of "format-patch" and "am". [These new names suggest something slightly different than formatting a patch for mailing and applying an email message, and perhaps even that difference should be taken advantage of.] > Also I was wondering if it would > make sense to give two dashes to the back-end ones that never > get invoked by the end users directly (e.g. merge--recursive, > upload--pack) but thought it was too ugly. If you're willing to consider breaking backwards compatibility for these, why not hide them even further? An idea I just had that would hide them quite well would be to tuck them away as sub-commands of a new "core" command. That is: git core merge-recursive git core http-fetch etc. That would bury these away from tab-completion of "git-" and even "git " with the completion scripts. It would still leave them available with "git core " with the completion scripts of course. It would also make things much more clear if these commands ever slipped into an introductory tutorial, etc. -Carl
Attachment:
pgpMuodXu3V8X.pgp
Description: PGP signature