Ævar Arnfjörð Bjarmason wrote: > The below for-show patch[2] shows an alternate approach that I think is > a better direction than this series. > > It shows how some of the s/he|she/they/g search-replacements you did > could IMO be better if we simply reduced the amount of prose, e.g. in > strbuf.h changing: > > passes a context pointer, which can be used by the programmer of the > callback as she sees fit. > > To: > > passes a `void *context` to the callback `fn` > > Is a better change than a mere s/she/they/g. Nobody needs all this > verbosity to understand the common pattern of passing a user-controlled > 'void *` to a callback. It's implicitly understood by the technical > level of the reader this documentation is targeted at. !00% agreed. > --- a/Documentation/CodingGuidelines > +++ b/Documentation/CodingGuidelines > @@ -551,6 +551,31 @@ Writing Documentation: > documentation, please see the documentation-related advice in the > Documentation/SubmittingPatches file). > > + Prefer succinctness and matter-of-factly describing functionality in > + the abstract. E.g.: > + > + --short:: Emit output in the short-format. > + > + Not something like these overly verbose alternatives: > + > + --short:: Use this to emit output in the short-format. > + --short:: You can use this to get output in the short-format. > + --short:: A user who prefers shorter output could.... > + --short:: Should a person and/or program want shorter output, he > + she/they/it can... I'm a big fan of this succinct approach. > --- a/Documentation/git-push.txt > +++ b/Documentation/git-push.txt > @@ -240,17 +240,17 @@ already exists on the remote side. > This option overrides this restriction if the current value of the > remote ref is the expected value. "git push" fails otherwise. > + > +When collaborating with others this is safer than using the `--force` option. > Imagine that you have to rebase what you have already published. > -You will have to bypass the "must fast-forward" rule in order to > -replace the history you originally published with the rebased history. > -If somebody else built on top of your original history while you are > -rebasing, the tip of the branch at the remote may advance with her > -commit, and blindly pushing with `--force` will lose her work. > -+ > -This option allows you to say that you expect the history you are > -updating is what you rebased and want to replace. If the remote ref > -still points at the commit you specified, you can be sure that no > -other people did anything to the ref. It is like taking a "lease" on > +By using `--force` you might inadvertently clobber commits that > +someone else pushed on top of branch. * the branch? > ++ > + > +Unlike `--force`, `--force-with-lease` will transmit the expected > +object ID to the remote server (similar to linkgit:git-update-ref[1]'s > +`<oldvalue>`, and thus provides a safeguard against inadvertently > +clobbering remote refs which have changed since you retrieved them > +with `git fetch`. Using this option has the effect of taking a "lease" on Clearer and more useful. I didn't even notice where the gender of the reader was replaced, or where it supposedly came from. Instead we focus on what's important: instructing the user. > the ref without explicitly locking it, and the remote ref is updated > only if the "lease" is still valid. > + > diff --git a/config.h b/config.h > index 9038538ffd..a2200f3111 100644 > --- a/config.h > +++ b/config.h > @@ -450,8 +450,8 @@ void git_configset_init(struct config_set *cs); > /** > * Parses the file and adds the variable-value pairs to the `config_set`, > * dies if there is an error in parsing the file. Returns 0 on success, or > - * -1 if the file does not exist or is inaccessible. The user has to decide > - * if he wants to free the incomplete configset or continue using it when > + * -1 if the file does not exist or is inaccessible. The caller decides > + * whether to free the incomplete configset or continue using it when Gramatically correct and clear. This is a good change. > * the function returns -1. > */ > int git_configset_add_file(struct config_set *cs, const char *filename); > diff --git a/strbuf.h b/strbuf.h > index 223ee2094a..c7c67cfe14 100644 > --- a/strbuf.h > +++ b/strbuf.h > @@ -337,8 +337,8 @@ const char *strbuf_join_argv(struct strbuf *buf, int argc, > * placeholder is unknown, then the percent sign is copied, too. > * > * In order to facilitate caching and to make it possible to give > - * parameters to the callback, `strbuf_expand()` passes a context pointer, > - * which can be used by the programmer of the callback as she sees fit. > + * parameters to the callback, `strbuf_expand()` passes a > + * `void *context` to the callback `fn` Simple and to the point. +1 Cheers. -- Felipe Contreras
