Junio C Hamano venit, vidit, dixit 26.08.2011 18:30: > Michael J Gruber <git@xxxxxxxxxxxxxxxxxxxx> writes: > >> Clarify that in list mode, "git replace" outputs the shortened ref >> names, not their values. >> >> Also, point to the difficult to find git show-ref $(git replace -l). >> >> Signed-off-by: Michael J Gruber <git@xxxxxxxxxxxxxxxxxxxx> >> --- >> Documentation/git-replace.txt | 8 ++++++++ >> 1 files changed, 8 insertions(+), 0 deletions(-) >> >> diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt >> index 17df525..cd00837 100644 >> --- a/Documentation/git-replace.txt >> +++ b/Documentation/git-replace.txt >> @@ -61,6 +61,13 @@ OPTIONS >> all if no pattern is given). >> Typing "git replace" without arguments, also lists all replace >> refs. >> ++ >> +Note that this lists the names of the replace refs, not their values >> +(not their replacements). You can get the latter like this, e.g.: > > Hmm, the update is _not wrong_ per-se, but... > > I highly doubt we would want to try to cover confusions that may come from > any and all different mis-/pre-conceptions people may have by making the > description _longer_. > > Which part of the wording in the existing description made you think that > the command might list both names and their contents? We should identify > that misleading description (if there is) and fix that, instead of tacking > clarifying clauses at the end. Full disclosure: I misunderstood it when I read it the first time. I never expected it to list pairs of refs, but the questions is: Does it list the original sha1 or the replacement sha1? "replace ref" can be very easily misunderstood as "the ref which replaces", i.e. the replacement sha1. I know a ref is not a rev, but "replace ref" can easily be misread as "replace rev", "replaced ref" etc. Secondly, "git replace -l sha1" is completely useless, and I did not expect that either. Granted, it outputs sha1 or not, depending on whether it is replaced or not, so "completely" is a bit harsh, but still. So, while I still have things to learn about git, I've also had my share of exposure to refs and revs, and if I misunderstand a man page, it indicates that there may be others whom I could help with what I've learned from my own misunderstandings. Also, as regards to clarifying: In out man pages, we often show practical, non-obvious ways in which a user can combine commands, and I think git show-ref $(git replace -l) is one of them. > Given these statements: > > "git replace" lists all replace refs. > "ls" lists paths in the directory. > > I would say a natural reading of them is that they list "replace refs" and > "paths", not "replace refs and their contents" and "paths and their contents". This is natural, and the confusion above is a non-issue, *if* the reader is very aware of the implementation of replacements as lightweight tag-like refs with the sha1 as refname. > By the way, one thing I forgot to say was that I do not think the variant > of the output you wanted to have is necessarily a bad thing (it is bad to > change the existing output to that variant, breaking other > people). Perhaps it can become "-v(erbose)" output? I'd say yes, Christian seems to prefer having "-v" even closer to "branch -v". I'd say a user has the right to expect "-v,--verbose" giving more information, but the type and extent of information should depend on the actual command :) Michael -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html