Git Mailing List Archive on lore.kernel.org
 help / color / Atom feed
* [PATCH v2 0/1] FAQ for common user questions
@ 2020-03-25  1:34 brian m. carlson
  2020-03-25  1:34 ` [PATCH v2] docs: add a FAQ brian m. carlson
  2020-03-25  6:10 ` [PATCH v2 0/1] FAQ for common user questions Junio C Hamano
  0 siblings, 2 replies; 6+ messages in thread
From: brian m. carlson @ 2020-03-25  1:34 UTC (permalink / raw)
  To: git; +Cc: Emily Shaffer, Junio C Hamano, Shourya Shukla

Git is an enormously flexible and powerful piece of software, but many
people find it confusing and hard to use.  This patch introduces a FAQ
to address some common user questions and hopefully make it easier.

I know there are some plans to add additional entries to this.  I
propose we tack them on as additional patches, and if I need to reroll
this again, I can pick them up as part of the series, unless someone
has strong opinions about doing things differently.

Changes from v1:
* Fix various indentation issues.
* Avoid using "some people", except to state that "some people find `vi`
  difficult to use", preferring to use language addressing
  misconceptions more directly.
* Add "erroneously" to "This is often suggested" to avoid users
  accidentally doing what we recommend against.
* Attempt to come up with a better way to describe a personal name,
  using Junio as an example.

brian m. carlson (1):
  docs: add a FAQ

 Documentation/Makefile   |   1 +
 Documentation/gitfaq.txt | 337 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 338 insertions(+)
 create mode 100644 Documentation/gitfaq.txt


^ permalink raw reply	[flat|nested] 6+ messages in thread

* [PATCH v2] docs: add a FAQ
  2020-03-25  1:34 [PATCH v2 0/1] FAQ for common user questions brian m. carlson
@ 2020-03-25  1:34 ` brian m. carlson
  2020-03-25  6:23   ` Martin Ågren
  2020-03-25  6:10 ` [PATCH v2 0/1] FAQ for common user questions Junio C Hamano
  1 sibling, 1 reply; 6+ messages in thread
From: brian m. carlson @ 2020-03-25  1:34 UTC (permalink / raw)
  To: git; +Cc: Emily Shaffer, Junio C Hamano, Shourya Shukla

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.

Add such a FAQ and fill it with some common questions and answers.
While there are few entries now, we can expand it in the future to cover
more things as we find new questions that users have.  Let's also add
section markers so that people answering questions can directly link
users to the proper answer.

The FAQ also addresses common configuration questions that apply not
only to Git as an independent piece of software but also the ecosystem
of CI tools and hosting providers that people use, since these are the
source of common questions.  An attempt has been made to avoid
mentioning any particular provider or tool, but to nevertheless cover
common configurations that apply to a wide variety of such tools.

Note that the long lines for certain questions are required, since
Asciidoctor does not permit broken lines there.
---
 Documentation/Makefile   |   1 +
 Documentation/gitfaq.txt | 338 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 339 insertions(+)
 create mode 100644 Documentation/gitfaq.txt

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 8fe829cc1b..59e6ce3a2a 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -30,6 +30,7 @@ MAN7_TXT += gitcredentials.txt
 MAN7_TXT += gitcvs-migration.txt
 MAN7_TXT += gitdiffcore.txt
 MAN7_TXT += giteveryday.txt
+MAN7_TXT += gitfaq.txt
 MAN7_TXT += gitglossary.txt
 MAN7_TXT += gitnamespaces.txt
 MAN7_TXT += gitremote-helpers.txt
diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
new file mode 100644
index 0000000000..ce447e2524
--- /dev/null
+++ b/Documentation/gitfaq.txt
@@ -0,0 +1,338 @@
+gitfaq(7)
+=========
+
+NAME
+----
+gitfaq - Frequently asked questions about using Git
+
+SYNOPSIS
+--------
+gitfaq
+
+DESCRIPTION
+-----------
+
+The examples in this FAQ assume a standard POSIX shell, like `bash` or `dash`,
+and a user, A U Thor, who has the account `author` on the hosting provider
+`git.example.org`.
+
+Configuration
+-------------
+
+[[user-name]]
+What should I put in `user.name`?::
+	You should put your personal name, generally a form using a given name
+	and family name.  For example, the current maintainer of Git uses "Junio
+	C Hamano".  This will be the name portion that is stored in every commit
+	you make.
++
+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, 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.  This is often (erroneously) suggested 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 correctly support HTTP/1.1 and chunked transfer encoding wouldn't be
+that useful on the Internet today, since it would break lots of traffic.
++
+Note that increasing this value will increase the memory used on every relevant
+push that Git does over HTTP or HTTPS, since the entire buffer is allocated
+regardless of whether or not it is all used.  Thus, it's best to leave it at the
+default unless you are sure you need a different value.
+
+[[configure-editor]]
+How do I configure a different editor?::
+	If you haven't specified an editor specifically for Git, it will by
+	default use the editor you've configured using the `VISUAL` or `EDITOR`
+	environment variables, or if neither is specified, the system default
+	(which is usually `vi`).  Since some people find `vi` difficult to use,
+	it may be desirable to change the editor used.
++
+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
+----
++
+If you want to configure an editor specifically for Git, you can either set the
+`core.editor` configuration value or the `GIT_EDITOR` environment variable.  You
+can see linkgit:git-var[1] for details on the order in which these options are
+consulted.
++
+Note that in all cases, the editor value will be passed to the shell, so any
+arguments containing spaces should be appropriately quoted.  Additionally, if
+your editor normally detaches from the terminal when invoked, you should specify
+it with an argument that makes it not do that, or else Git will not see any
+changes.  An example of a configuration addressing both of these issues on
+Windows would be the configuration `"C:\Program Files\Vim\gvim.exe" --nofork`,
+which quotes the filename with spaces and specifies the `--nofork` option to
+avoid backgrounding the process.
+
+Credentials
+-----------
+
+[[http-credentials]]
+How do I specify my credentials when pushing over HTTP?::
+	The easiest way to do this is to use a credential helper via the
+	`credential.helper` configuration.  Most systems provide a standard
+	choice to integrate with the system credential manager.  For example,
+	Git for Windows provides the `wincred` credential manager, macOS has the
+	`osxkeychain` credential manager, and Unix systems with a standard
+	desktop environment can use the `libsecret` credential manager.  All of
+	these store credentials in an encrypted store to keep your passwords or
+	tokens secure.
++
+In addition, you can use the `store` credential manager which stores in a file
+in your home directory, or the `cache` credential manager, which does not
+permanently store your credentials, but does prevent you from being prompted for
+them for a certain period of time.
++
+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.
+
+[[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 command that produces the credential protocol on standard output.
+	This is useful when passing credentials into a container, for example.
++
+Such a shell command can be specified by starting the option value with an
+exclamation point.  If your password or token were stored in the `GIT_TOKEN`,
+you could run the following command to set your credential helper:
++
+----
+$ git config credential.helper \
+	'!f() { echo username=author; echo "password=$GIT_TOKEN"; };f'
+----
+
+[[http-reset-credentials]]
+How do I change the password or token I've saved in my credential manager?::
+	Usually, if the password or token is invalid, Git will erase it and
+	prompt for a new one.  However, there are times when this doesn't always
+	happen.  To change the password or token, you can erase the existing
+	credentials and then Git will prompt for new ones.  To erase
+	credentials, use a syntax like the following (substituting your username
+	and the hostname):
++
+----
+$ echo url=https://author@git.example.org | git credential reject
+----
+
+[[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 username in the URL.  For example, if you have the accounts `author`
+	and `committer` on `git.example.org`, you can use the URLs
+	https://author@git.example.org/org1/project1.git and
+	https://committer@git.example.org/org2/project2.git.  This way, when you
+	use a credential helper, it will automatically try to look up the
+	correct credentials for your account.  If you already have a remote set
+	up, you can change the URL with something like `git remote set-url
+	origin https://author@git.example.org/org1/project1.git` (see
+	linkgit:git-remote[1] for details).
+
+[[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:
++
+----
+# 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.
+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
+----
++
+Then, you can adjust your push URL to use `git@example_author` or
+`git@example_committer` instead of `git@example.org` (e.g., `git remote set-url
+git@example_author:org1/project1.git`).
+
+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>` or `git rm <file>`, as approrpiate, 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 wish to use the
+	original message verbatim, you can use the `--no-edit` option to `git
+	commit` in addition, or just save and quit when your editor opens.
+
+[[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 is usually edited to include
+	an explanation as to why the revert was made.
+
+[[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.
++
+It's tempting to try 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.
++
+If your goal is to modify a configuration file, it can often be helpful to have
+a file checked into the repository which is a template or set of defaults which
+can then be copied alongside and modified as appropriate.  This second, modified
+file is usually ignored to prevent accidentally committing it.
+
+Hooks
+-----
+
+[[restrict-with-hooks]]
+How do I prevent users from making certain changes with hooks?::
+	The only safe place to make these changes is on the remote repository
+	(i.e., the Git server), usually in the `pre-receive` hook or in a
+	continuous integration (CI) system.  These are the locations in which
+	policy can be enforced effectively.
++
+It's common to try to use `pre-commit` hooks (or, for commit messages,
+`commit-msg` hooks) to check these things, which is great if you're working as a
+solo developer and want the tooling to help you.  However, using hooks on a
+developer machine is not effective as a policy control because a user can bypass
+these hooks with `--no-verify` without being noticed (among various other ways).
+Git assumes that the user is in control of their local repositories and doesn't
+try to prevent this or tattle on the user.
++
+In addition, some advanced users find `pre-commit` hooks to be an impediment to
+workflows that use temporary commits to stage work in progress or that create
+fixup commits, so it's better to push these kinds of checks to the server
+anyway.
+
+Cross-Platform Issues
+~~~~~~~~~~~~~~~~~~~~~
+
+[[windows-text-binary]]
+I'm on Windows and my text files are detected as binary.::
+	Git works best when you store text files as UTF-8.  Many programs on
+	Windows support UTF-8, but some do not and only use the little-endian
+	UTF-16 format, which Git detects as binary.  If you can't use UTF-8 with
+	your programs, you can specify a working tree encoding that indicates
+	which encoding your files should be checked out with, while still
+	storing these files as UTF-8 in the repository.  This allows tools like
+	linkgit:git-diff[1] to work as expected, while still allowing your tools
+	to work.
++
+To do so, you can specify a linkgit:gitattributes[5] pattern with with the
+`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:
++
+----
+*.c	working-tree-encoding=UTF-16LE-BOM
+----
++
+You will need to run `git add --renormalize` to have this take effect.  Note
+that if you are making these changes on a project that is used across platforms,
+you'll probably want to make it in a per-user configuration file or in the one
+in `$GIT_DIR/info/attributes`, since making it in a `.gitattributes` file in the
+repository will apply to all users of the repository.
++
+See the following entry for information about normalizing line endings as well,
+and see linkgit:gitattributes[5] for more information about attribute files.
+
+[[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
+	defaults to showing trailing whitespace only on new lines, not existing
+	ones.
++
+You can store the files in the repository with Unix line endings and convert
+them automatically to your platform's line endings.  To do that, set the
+configuration option `core.eol` to `native` and see the following entry for
+information about how to configure files as text or binary.
++
+You can also control this behavior with the `core.whitespace` setting if you
+don't wish to remove the carriage returns from your line endings.
+
+[[recommended-storage-settings]]
+What's the recommended way to store files in Git?::
+	While Git can store and handle any file of any type, there are some
+	settings that work better than others.  In general, we recommend that
+	text files be stored in UTF-8 without a byte-order mark (BOM) with LF
+	(Unix-style) endings.  We also recommend the use of UTF-8 (again,
+	without BOM) in commit messages.  These are the settings that work best
+	across platforms and with tools such as `git diff` and `git merge`.
++
+Additionally, if you have a choice between storage formats that are text based
+or non-text based, we recommend storing files in the text format and, if
+necessary, transforming them into the other format.  For example, a text-based
+SQL dump with one record per line will work much better for diffing and merging
+than an actual database file.  Similarly, text-based formats such as Markdown
+and AsciiDoc will work better than binary formats such as Microsoft Word and
+PDF.
++
+Similarly, storing binary dependencies (e.g., shared libraries or JAR files) or
+build products in the repository is generally not recommended.  Dependencies and
+build products are best stored on an artifact or package server with only
+references, URLs, and hashes stored in the repository.
++
+We also recommend setting a link:gitattributes[5] file to explicitly mark which
+files are text and which are binary.  If you want Git to guess, you can set the
+attribute `text=auto`.  For example, the following might be appropriate in some
+projects:
++
+----
+# By default, guess.
+*	text=auto
+# Mark all C files as text.
+*.c	text
+# Mark all JPEG files as binary.
+*.jpg	binary
+----
++
+These settings help tools pick the right format for output such as patches and
+result in files being checked out in the appropriate line ending for the
+platform.
+
+GIT
+---
+Part of the linkgit:git[1] suite

^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [PATCH v2 0/1] FAQ for common user questions
  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:10 ` Junio C Hamano
  1 sibling, 0 replies; 6+ messages in thread
From: Junio C Hamano @ 2020-03-25  6:10 UTC (permalink / raw)
  To: brian m. carlson; +Cc: git, Emily Shaffer, Shourya Shukla

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

> I know there are some plans to add additional entries to this.  I
> propose we tack them on as additional patches, and if I need to reroll
> this again, I can pick them up as part of the series, unless someone
> has strong opinions about doing things differently.

I do not have a strong opinion, but have a mild preference for the
way you are proposing.  Let's take this almost as-is (modulo
fixes to possible typos if people spot any soon enough) and leave
the enhancement to follow-up patches.

^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [PATCH v2] docs: add a FAQ
  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
  0 siblings, 1 reply; 6+ messages in thread
From: Martin Ågren @ 2020-03-25  6:23 UTC (permalink / raw)
  To: brian m. carlson
  Cc: Git Mailing List, Emily Shaffer, Junio C Hamano, Shourya Shukla

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?

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

> ++
> +----
> +# 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/?

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

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

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

^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [PATCH v2] docs: add a FAQ
  2020-03-25  6:23   ` Martin Ågren
@ 2020-03-25 11:03     ` brian m. carlson
  2020-03-25 18:03       ` Martin Ågren
  0 siblings, 1 reply; 6+ messages in thread
From: brian m. carlson @ 2020-03-25 11:03 UTC (permalink / raw)
  To: Martin Ågren
  Cc: Git Mailing List, Emily Shaffer, Junio C Hamano, Shourya Shukla

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

^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [PATCH v2] docs: add a FAQ
  2020-03-25 11:03     ` brian m. carlson
@ 2020-03-25 18:03       ` Martin Ågren
  0 siblings, 0 replies; 6+ messages in thread
From: Martin Ågren @ 2020-03-25 18:03 UTC (permalink / raw)
  To: brian m. carlson, Martin Ågren, Git Mailing List,
	Emily Shaffer, Junio C Hamano, Shourya Shukla

On Wed, 25 Mar 2020 at 12:03, brian m. carlson
<sandals@crustytoothpaste.net> wrote:
>
> On 2020-03-25 at 06:23:49, Martin Ågren wrote:
> > On Wed, 25 Mar 2020 at 02:37, brian m. carlson
> > 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.

Very nice.

Martin

^ permalink raw reply	[flat|nested] 6+ messages in thread

end of thread, back to index

Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
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
2020-03-25 18:03       ` Martin Ågren
2020-03-25  6:10 ` [PATCH v2 0/1] FAQ for common user questions Junio C Hamano

Git Mailing List Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/git/0 git/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 git git/ https://lore.kernel.org/git \
		git@vger.kernel.org
	public-inbox-index git

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.git


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git