On 2020-03-18 at 23:00:30, Emily Shaffer wrote:
> On Sun, Mar 15, 2020 at 10:39:23PM +0000, brian m. carlson wrote:
> > Git is an enormously flexible and powerful piece of software.  However,
> > it can be intimidating for many users and there are a set of common
> > questions that users often ask.  While we already have some new user
> > documentation, it's worth adding a FAQ to address common questions that
> > users often have.  Even though some of this is addressed elsewhere in
> > the documentation, experience has shown that it is difficult for users
> > to find, so a centralized location is helpful.
> 
> It's true that some of it is duplicated; if we're worried about the info
> getting out of sync, we might be able to do something like
> Documentation/config so we're pulling in a single piece of text to both
> places.

I'm not worried about this, since most of it has been this way for a
long time.

> > +[[user-name]]
> > +What should I put in `user.name`?::
> > +  You should put your personal name; that is, the name that other humans call
> > +	you.  This will be the name portion that is stored in every commit you make.
> 
> I like the direction but I think it is still a little unclear. Other
> humans call me Emily, but I want to put "Emily Shaffer" in my user.name.
> I wonder how we can suggest full name in a way that's as universal as
> "the name that other humans call you"? I think I got around to this
> point by using examples when covering the SOB in MyFirstContribution, so
> I don't have a good answer off the top of my head.

Yeah, this is tricky, since in many contexts the phrase "full name"
implies using the entirety of every part of your name, and most people
with middle names don't put them in the "user.name" entry.  Yet we want
it to be appropriate for people across a wide variety of cultures.

Maybe we should say something like this:

  You should put your personal name, generally a form using a given name
  and family name.  This will be the name portion that is stored in
  every commit you make.

Many cultures have a given name and a family name of some sort.  If we
wanted to provide an example, we could use Junio:

  For example, the current maintainer of Git uses "Junio C Hamano".

> > +[[http-postbuffer]]
> > +What does `http.postBuffer` really do?::
> > +	This option changes the size of the buffer that Git uses when pushing data to
> > +	a remote over HTTP or HTTPS.  If the data is larger than this size, libcurl,
> > +	which handles the HTTP support for Git, will use chunked transfer encoding
> > +	since it isn't known ahead of time what the size of the pushed data will be.
> > ++
> > +Leaving this value at the default size is fine unless you know that either the
> > +remote server or a proxy in the middle doesn't support HTTP/1.1 (which
> > +introduced the chunked transfer encoding) or is known to be broken with chunked
> > +data.  People often suggest this as a solution for generic push problems, but
> > +since almost every server and proxy supports at least HTTP/1.1, raising this
> > +value usually doesn't solve most push problems.  A server or proxy that didn't
> 
> This might be burying the lede a little for someone frantically skimming
> for an answer. If I was really spinning my wheels I might read "People
> often suggest this as a solution for generic push problems" and go try
> it. Is "People often (erroneously) suggest this ..." too verbose?

No, I think that's a good answer.

> > +If you want to configure a general editor for most programs which need one, you
> > +can edit your shell configuration (e.g., `~/.bashrc` or `~/.zshenv`) to contain
> > +a line setting the `EDITOR` or `VISUAL` environment variable to an appropriate
> > +value.  For example, if you preferred the editor `nano`, then you could write
> > +the following:
> > ++
> > +----
> > +export VISUAL=nano
> > +----
> 
> I'll swallow my pride as a Vim user here and say that I think 'nano' is
> a good choice to reference directly here; it seems to fit right into the
> experience level this particular Q is targeting. Nice.

I'm also a Vim user, but I took this idea from Debian, which uses the
options nano, nano-tiny, and vi (in that order) for its sensible-editor
utility if the user hasn't specified an editor any other way.  In any
event, the user can extrapolate from the example if nano isn't to their
tastes.

> > +[[ignore-tracked-files]]
> > +How do I ignore changes to a tracked file?::
> > +  Git doesn't provide a way to do this.  The reason is that if Git needs to
> > +	overwrite this file, such as during a checkout, it doesn't know whether the
> > +	changes to the file are precious and should be kept, or whether they are
> > +	irrelevant and can safely be destroyed.  Therefore, it has to take the safe
> > +	route and always preserve them.
> > ++
> > +Some people are tempted to use certain features of `git update-index`, namely
> > +the assume-unchanged and skip-worktree bits, but these don't work properly for
> > +this purpose and shouldn't be used this way.
> 
> Not really on topic for this particular paragraph, but there are a lot
> of instances of "Some people ..." - in general, would it be less
> combative to say something like "It's tempting to..." or "It might seem
> like a good idea to..."? That way it feels less like "there are people
> who do X and they are wrong" and more like "X might seem like a good
> idea but it isn't". Or to put it another way, let's attack the bad idea,
> not the people who suggest it.

Sure, I think that's a good idea.  Thanks for the suggestion.
-- 
brian m. carlson: Houston, Texas, US
OpenPGP: https://keybase.io/bk2204