Re: [PATCH 1/1] docs: add a FAQ

[Junio C Hamano <gitster@pobox.com>]

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

> Note that the long lines for certain questions are required, since
> Asciidoctor does not permit broken lines there.

I didn't see "long lines", but was puzzled by a few lines with
ununiform indentation.

> +Configuration
> +-------------
> +
> +[[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.

Shouldn't the first line "You should put ..." be indented to the
same level as the second line, like the entry for http-postbuffer we
see below?

> ++
> +This configuration doesn't have any effect on authenticating to remote
> +services; for that, see `credential.username` in linkgit:git-config[1].
> +
> +[[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,
> ...

> +[[http-credentials-environment]]
> +How do I read a password or token from an environment variable?::
> +  The `credential.helper` configuration option can also take an arbitrary shell

Likewise.

> +[[multiple-accounts-http]]
> +How do I use multiple accounts with the same hosting provider using HTTP?::
> +  Usually the easiest way to distinguish between these accounts is to use the

Likewise.

> +Most hosting providers use a single SSH account for pushing; that is, all users
> +push to the `git` account (e.g., `git@git.example.org`).  If that's the case for
> +your provider, you can set up multiple aliases in SSH to make it clear which key
> +pair to use.  For example, you could write something like the following,
> +substituting the proper private key file:
> ++
> +----
> +# This is the account for author on git.example.org.
> +Host example_author
> +   HostName git.example.org
> +	 User git

Here, shouldn't HostName entry be indented the same way as User and
other entries for this "Host" entry?

> +	 # This is the key pair registered for author with git.example.org.
> +	 IdentityFile ~/.ssh/id_author
> +	 IdentitiesOnly yes
> +# This is the committer for author on git.example.org.
> +Host example_committer
> +   HostName git.example.org

Likewise.

> +Common Issues
> +-------------
> +
> +[[last-commit-amend]]
> +I've made a mistake in the last commit.  How do I change it?::
> +	You can make the appropriate change to your working tree, run `git add <file>`
> +	to stage it, and then `git commit --amend`.  Your change will be included in
> +	the commit, and you'll be prompted to edit the commit message again; if you
> +	don't want to edit it, you can use the `--no-edit` option to `git commit` in
> +	addition, or just save and quit when your editor opens.

When the undesired part of the last change was "I added a junk
file", then instead of `git add`, `git rm [--cached]` would become
necessary.

I personally would prefer to say "if you want to use the original
commit message verbatim" instead of "you do not want to edit", but
it may be just me.  I just find the document to give more positive
attitude if it avoids phrasing end-users' wishes in terms of what
they do not want to do.

> +[[undo-previous-change]]
> +I've made a change with a bug and it's been included in the main branch.  How should I undo it?::
> +	The usual way to deal with this is to use `git revert`.  This preserves the
> +	history that the original change was made and was a valuable contribution, but
> +	also introduces a new commit that undoes those changes because the original
> +	had a problem.  The commit message of the revert indicates the commit which
> +	was reverted and can be edited to include an explanation as to why the revert
> +	was made.

Can we phrase "and can be edited" in a bit more opinionated way?
The users are encouraged to describe why and that is why we open an
editor by default for them to do so.

> +[[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

Indentation.

> +----
> +# By default, guess.
> +*			text=auto
> +# Mark all C files as text.
> +*.c		text
> +# Mark all JPEG files as binary.
> +*.jpg	binary
> +----

The first entry text=auto is indented more deeply than others.  Intended?

Thanks.