Re: [PATCH v2] docs: add a FAQ

From: Martin Ågren <martin.agren@gmail.com>
Date: Mar 25, 2020, 06:23 UTC
Message-ID: <CAN0heSofpxFW81=sB+4ukx9S0JOJo_XuKDTBSkTy_-QK+jDz0Q@mail.gmail.com>
In-Reply-To: <20200325013434.219775-2-sandals@crustytoothpaste.net>

On Wed, 25 Mar 2020 at 02:37, brian m. carlson <sandals@crustytoothpaste.net> wrote:

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

Missing sign-off.

[Snipping lots of very well-written Q&As...]

> +You can also just enter your password when prompted, or you can place the
> +password (which must be percent-encoded) in the URL.  The latter option is not
> +particularly secure and can lead to accidental exposure of credentials, so it is
> +not recommended.

So should we even mention it? Or should we use the "it is sometimes (erroneously) suggested" construct?

Show 15 quoted lines

> +[[multiple-accounts-ssh]]
> +How do I use multiple accounts with the same hosting provider using SSH?::
> +       With most hosting providers that support SSH, a single key pair uniquely
> +       identifies a user.  Therefore, to use multiple accounts, it's necessary
> +       to create a key pair for each account.  If you're using a reasonably
> +       modern OpenSSH version, you can create a new key pair with something
> +       like `ssh-keygen -t ed25519 -f ~/.ssh/id_committer`.  You can then
> +       register the public key (in this case, `~/.ssh/id_committer.pub`; note
> +       the `.pub`) with the hosting provider.
> ++
> +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:

Would this be in `~/.ssh/config`?

Show 10 quoted lines

> ++
> +----
> +# This is the account for author on git.example.org.
> +Host example_author
> +       HostName git.example.org
> +       User git
> +       # 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.

Looks like you did s/account/committer/ instead of s/author/committer/?

Show 7 quoted lines

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

Show 5 quoted lines

> +
> +[[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>` or `git rm <file>`, as approrpiate, to stage it, and then `git

typoed "appropriate"

> +[[restrict-with-hooks]]
> +How do I prevent users from making certain changes with hooks?::

I read this as:

  How do I prevent users from making "certain changes with hooks"?

As opposed to your intended meaning:

  How do I (with hooks) prevent users from making certain changes?

I'm not suggesting the latter as a "fix" for this "problem" though, since it's a bit clumsy. How about adding a comma:

  How do I prevent users from making certain changes, with hooks?

Or maybe just dropping those last two words.

Please trust your judgement on whether this is a problem, and if so, how to go about addressing it -- I know you have lots of such judgement.

> +Cross-Platform Issues
> +~~~~~~~~~~~~~~~~~~~~~

I think you meant to use "--" as everywhere else instead of "~~". This is not a subsection of "Hooks".

> +To do so, you can specify a linkgit:gitattributes[5] pattern with with the

"with with"

> +`working-tree-encoding` attribute.  For example, the following pattern sets all
> +C files to use UTF-16LE-BOM, which is a common encoding on Windows:

Show 5 quoted lines

> +[[windows-diff-control-m]]
> +I'm on Windows and git diff shows my files as having a `^M` at the end.::
> +       By default, Git expects files to be stored with Unix line endings.  As
> +       such, the carriage return (`^M`) that is part of a Windows line ending
> +       results is show because it is considered to be trailing whitespace.  Git

"results is show"? "is shown"? Perhaps with a comma after "shown" for better reading flow (IMVHO).

> +       defaults to showing trailing whitespace only on new lines, not existing
> +       ones.

> +We also recommend setting a link:gitattributes[5] file to explicitly mark which

s/link:/linkgit:/

Thanks a lot. This is really well-written, and I think the selection of questions makes a lot of sense.

Martin