Re: [PATCH v2] doc: clarify that "git bisect" accepts one or more good commits
Junio C Hamanowrites: > "Robert P. J. Day" writes: > >> in this sense, i don't think "indicate" and "identify" are >> completely interchangeable. in my mind, the word "identify" does >> nothing more than, you know, point at something and say, "that one, >> that's the one i'm talking about;" it goes no further than that. >> >> on the other hand, the word "indicate" (in my mind) implies that >> you're about to provide some *property* or *quality* of something, and >> you do exactly that in the earlier quote: > > I do not think the two words have different connotations, so we are > in agreement. You do not necessarily need a property in mind when Eek. I do do think the two words are not interchangeable. I should stop typing late at night.
Re: [PATCH v2] doc: clarify that "git bisect" accepts one or more good commits
"Robert P. J. Day"writes: > in this sense, i don't think "indicate" and "identify" are > completely interchangeable. in my mind, the word "identify" does > nothing more than, you know, point at something and say, "that one, > that's the one i'm talking about;" it goes no further than that. > > on the other hand, the word "indicate" (in my mind) implies that > you're about to provide some *property* or *quality* of something, and > you do exactly that in the earlier quote: I do not think the two words have different connotations, so we are in agreement. You do not necessarily need a property in mind when you "identify" a commit. You could just "identify" this and that commits to yourself, to keep them in mind. You _also_ can have a property in mind and "identify" this commit as a good one, and that commit as a bad one. But identifying a commit as bad (or another one as good) alone to yourself does not get anything started. In order to advance the bisection process, you need to tell the "git bisect" machinery that "this commit is good", "that commit is bad", etc. I would think "indicate" is a verb with better connotation than "identify" for describing that action. You indicate something *to* *somebody, and in this case you indicate that this commit is good and that commit is bad to git.
Re: [PATCH v2] doc: clarify that "git bisect" accepts one or more good commits
On Fri, 24 Nov 2017, Junio C Hamano wrote: > "Robert P. J. Day"writes: ... snip ... > > -to indicate that it was after. > > +to indicate a single commit after that change. > > As to "identify", I would say it is better to consistently use > "indicate" like the original of these two hunks at the end says, > i.e. "indicate that it is bad/new (or they are good/old)". i'm going to ponder this, but let me explain why i am such an annoying stickler for the choice of words at times, and you can read all about it here: http://twain.lib.virginia.edu/projects/rissetto/offense.html in particular, i draw your attention to twain's trashing of cooper for, in many cases, using *almost* the right word, but not *quite* the right word: "Cooper's word-sense was singularly dull. When a person has a poor ear for music he will flat and sharp right along without knowing it. He keeps near the tune, but is not the tune. When a person has a poor ear for words, the result is a literary flatting and sharping; you perceive what he is intending to say, but you also perceive that he does not say it. This is Cooper. He was not a word-musician. His ear was satisfied with the approximate words. I will furnish some circumstantial evidence in support of this charge. My instances are gathered from half a dozen pages of the tale called "Deerslayer." He uses "Verbal" for "oral"; "precision" for "facility"; "phenomena" for "marvels"; "necessary" for "predetermined"; "unsophisticated" for "primitive"; "preparation" for "expectancy"; "rebuked" for "subdued"; "dependent on" for "resulting from"; "fact" for "condition"; "fact" for "conjecture"; "precaution" for "caution"; "explain" for "determine"; "mortified" for "disappointed"; "meretricious" for "factitious"; "materially" for "considerably"; "decreasing" for "deepening"; "increasing" for "disappearing"; "embedded" for "inclosed"; "treacherous" for "hostile"; "stood" for "stooped"; "softened" for "replaced"; "rejoined" for "remarked"; "situation" for "condition"; "different" for "differing"; "insensible" for "unsentient"; "brevity" for "celerity"; "distrusted" for "suspicious"; "mental imbecility" for "imbecility"; "eyes" for "sight"; "counteracting" for "opposing"; "funeral obsequies" for "obsequies." in this sense, i don't think "indicate" and "identify" are completely interchangeable. in my mind, the word "identify" does nothing more than, you know, point at something and say, "that one, that's the one i'm talking about;" it goes no further than that. on the other hand, the word "indicate" (in my mind) implies that you're about to provide some *property* or *quality* of something, and you do exactly that in the earlier quote: > As to "identify", I would say it is better to consistently use > "indicate" like the original of these two hunks at the end says, > i.e. "indicate that it is bad/new (or they are good/old)". as in, you "identify" a commit, but you "indicate" that it represents a good or bad commit. i know this sounds picky, but it is exactly this tendency of using *almost* the right word that makes a lot of documentation potentially confusing. given this distinction, depending on the word to be used, i would write one of: 1) "first, identify the bad commit and one or more good commits..." 2) "first, indicate which commit is the bad commit, and which commits are the good commits ..." the eventual meaning *should* be the same, but the choice of words can make the meaning clear, or can confuse the reader. thoughts? rday -- Robert P. J. Day Ottawa, Ontario, CANADA http://crashcourse.ca Twitter: http://twitter.com/rpjday LinkedIn: http://ca.linkedin.com/in/rpjday
Re: [PATCH v2] doc: clarify that "git bisect" accepts one or more good commits
"Robert P. J. Day"writes: > This command uses a binary search algorithm to find which commit in > -your project's history introduced a bug. You use it by first telling > -it a "bad" commit that is known to contain the bug, and a "good" > -commit that is known to be before the bug was introduced. Then `git > -bisect` picks a commit between those two endpoints and asks you > +your project's history introduced a bug. You use it by first telling it > +a "bad" commit that is known to contain the bug, and one or more "good" > +commits that are known to be before the bug was introduced. Then `git > +bisect` picks a commit somewhere in between those commits and asks you Good. > -Once you have specified at least one bad and one good commit, `git > +Once you have specified one bad and one or more good commits, `git > bisect` selects a commit in the middle of that range of history, > checks it out, and outputs something similar to the following: Good. > @@ -137,7 +137,7 @@ respectively, in place of "good" and "bad". (But note > that you cannot > mix "good" and "bad" with "old" and "new" in a single session.) > > In this more general usage, you provide `git bisect` with a "new" > -commit that has some property and an "old" commit that doesn't have that > +commit with some property and some "old" commits that don't have that > property. Each time `git bisect` checks out a commit, you test if that Good. > @@ -145,19 +145,19 @@ will report which commit introduced the property. > > To use "old" and "new" instead of "good" and bad, you must run `git > bisect start` without commits as argument and then run the following > -commands to add the commits: > +commands to identify the commits: I am not sure if this is an improvement (see below). > > > -git bisect old [] > +git bisect old [...] > Good. > -to indicate that a commit was before the sought change, or > +to identify one or more commits before the sought change, or > > > -git bisect new [...] > +git bisect new [] > Good. > -to indicate that it was after. > +to indicate a single commit after that change. As to "identify", I would say it is better to consistently use "indicate" like the original of these two hunks at the end says, i.e. "indicate that it is bad/new (or they are good/old)". Regarding the earlier "add the commits", I do not think the original is confusing and any reasonable reader would get that the verb is a casually (or "carelessly") used short-hand for "add the commits to the set of commits the bisect algorithm cares about", and turning it to "identify" adds much clarity. As it is immediately followed by two illustrations to use old and new, I would think that we could just stop the sentence at "then run the following commands:" without saying anything else. If you really want to phrase it differently from the two sentences to describe use of old and new, because this is acting as a headline for these two, perhaps it is an improvement to say something like "then run the following commands to limit the bisection range"; that would explain _why_ these commits are "added" and would give additional information to the readers.