From: "brian m. carlson" <sandals@crustytoothpaste.net>
To: "Martin Ågren" <martin.agren@gmail.com>
Cc: Git Mailing List <git@vger.kernel.org>,
Emily Shaffer <emilyshaffer@google.com>,
Junio C Hamano <gitster@pobox.com>,
Shourya Shukla <shouryashukla.oo@gmail.com>
Subject: Re: [PATCH v2] docs: add a FAQ
Date: Wed, 25 Mar 2020 11:03:28 +0000 [thread overview]
Message-ID: <20200325110328.GK6499@camp.crustytoothpaste.net> (raw)
In-Reply-To: <CAN0heSofpxFW81=sB+4ukx9S0JOJo_XuKDTBSkTy_-QK+jDz0Q@mail.gmail.com>
[-- Attachment #1: Type: text/plain, Size: 4471 bytes --]
On 2020-03-25 at 06:23:49, Martin Ågren wrote:
> 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.
Thanks, will fix.
> > +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?
I'll rephrase this to make it a little more obvious that this is a bad
idea.
> > +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`?
Ah, yes, we should tell that to the user.
> > ++
> > +----
> > +# 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/?
So I did.
> > +
> > +[[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"
Will fix.
> > +[[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.
How about, "How do I use hooks to prevent users from making certain
changes?" That seems to both read smoothly and avoid the misplaced
modifier.
> > +Cross-Platform Issues
> > +~~~~~~~~~~~~~~~~~~~~~
>
> I think you meant to use "--" as everywhere else instead of "~~". This
> is not a subsection of "Hooks".
Ah, yes. Apparently my fonts are so small that these are hard to
distinguish with bright white on grey. I typically use the
Setext style in my own documents, but that isn't what we do in Git.
> > +To do so, you can specify a linkgit:gitattributes[5] pattern with with the
>
> "with with"
Ah, normally Vim flags those things. Will fix.
> > +[[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).
This should be "is shown". I'm not sure if a comma after "shown" is
grammatical here as it stands, but I think we could write "is shown,
since" and that would be okay. I'll check a reference and rephrase if
necessary.
> > + 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:/
Will fix.
--
brian m. carlson: Houston, Texas, US
OpenPGP: https://keybase.io/bk2204
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 263 bytes --]
next prev parent reply other threads:[~2020-03-25 11:03 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-03-25 1:34 [PATCH v2 0/1] FAQ for common user questions brian m. carlson
2020-03-25 1:34 ` [PATCH v2] docs: add a FAQ brian m. carlson
2020-03-25 6:23 ` Martin Ågren
2020-03-25 11:03 ` brian m. carlson [this message]
2020-03-25 18:03 ` Martin Ågren
2020-03-25 6:10 ` [PATCH v2 0/1] FAQ for common user questions Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200325110328.GK6499@camp.crustytoothpaste.net \
--to=sandals@crustytoothpaste.net \
--cc=emilyshaffer@google.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=martin.agren@gmail.com \
--cc=shouryashukla.oo@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).