[1/2] gitfaq: cleanup gitfaq.txt
diff mbox series

Message ID 20200406181216.5340-2-shouryashukla.oo@gmail.com
State New
Headers show
Series
  • Add more issues in gitfaq
Related show

Commit Message

Shourya Shukla April 6, 2020, 6:12 p.m. UTC
The file contained a lot of whitespace errors as well as some
grammatical mistakes. Amend them.

Signed-off-by: Shourya Shukla <shouryashukla.oo@gmail.com>
---
 Documentation/gitfaq.txt | 110 +++++++++++++++++++--------------------
 1 file changed, 55 insertions(+), 55 deletions(-)

Comments

Junio C Hamano April 6, 2020, 7:06 p.m. UTC | #1
Shourya Shukla <shouryashukla.oo@gmail.com> writes:

> The file contained a lot of whitespace errors as well as some
> grammatical mistakes. Amend them.
>
> Signed-off-by: Shourya Shukla <shouryashukla.oo@gmail.com>
> ---
>  Documentation/gitfaq.txt | 110 +++++++++++++++++++--------------------
>  1 file changed, 55 insertions(+), 55 deletions(-)
>
> diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
> index 1cf83df118..3ca16b1092 100644
> --- a/Documentation/gitfaq.txt
> +++ b/Documentation/gitfaq.txt
> @@ -23,7 +23,7 @@ Configuration
>  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
> +	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;
> @@ -32,7 +32,7 @@ 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
> +	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.
> @@ -40,15 +40,15 @@ What does `http.postBuffer` really do?::
>  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
> +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
> +raising this value usually doesn't solve most push problems. A server or proxy

All of the above look useless noise.  It's not like it is turning
multiple SP after full-stop into a single SP (there is one that is
not touched in the pre-context in the first hunk, for example)---
not that such a change is worth a churn.

Please split them out and concentrate on true errors and typoes;
otherwise it is too distracting and unreviewable.

Thanks.
Junio C Hamano April 6, 2020, 11:46 p.m. UTC | #2
Shourya Shukla <shouryashukla.oo@gmail.com> writes:

[jc: All other changes in 1/2 turned out to be removal of SP when
there were dot-SP-SP at the end of a sentence, which I am omitted
here as they were so distracting.]

> -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`,
> +Such a shell command can be specified by putting an exclamation point before
> +the option. If your password or token were stored in the `GIT_TOKEN`,
>  you could run the following command to set your credential helper:

Sorry, but I am not sure how this change is an improvement.  It is
not making it worse, but it is not making it any better, at least to
me.

> -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
> +How do I ignore changes made to a tracked file?::
> +	Git doesn't provide a way to do this. The reason is that if Git needs

Ah, strike what I said about your new section on ".gitignore"; this
is already the right place to describe it.

With or without 'made', I think the header says the same thing, but
I guess it does not hurt to be explicit.

By the way, if you still want to pursue "full-stop at the end of the
sentence MUST be followed by no more than one SP", I won't stop you,
but please do so in a separate patch that has NO OTHER CHANGES.
They drown other changes out that are not mechanical and makes them
hard to review.

Thanks.
brian m. carlson April 7, 2020, 1:07 a.m. UTC | #3
On 2020-04-06 at 23:46:28, Junio C Hamano wrote:
> Shourya Shukla <shouryashukla.oo@gmail.com> writes:
> 
> > -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
> > +How do I ignore changes made to a tracked file?::
> > +	Git doesn't provide a way to do this. The reason is that if Git needs
> 
> With or without 'made', I think the header says the same thing, but
> I guess it does not hurt to be explicit.

I'm fine with or without this change.  I think the original is clear to
a native English speaker, but if we think it will be easier to parse or
harder to misread with "made", then I'm in favor of the change.  I, of
course, cannot speak for how either one reads to a non-native speaker.

I'm not sure it's fair to categorize it as a "grammatical mistake",
though.
Junio C Hamano April 7, 2020, 3:15 a.m. UTC | #4
"brian m. carlson" <sandals@crustytoothpaste.net> writes:

> I'm fine with or without this change.  I think the original is clear to
> a native English speaker, but if we think it will be easier to parse or
> harder to misread with "made", then I'm in favor of the change.  I, of
> course, cannot speak for how either one reads to a non-native speaker.

I am not a native, but if I were writing it I would probably have
written without the "made", so I guess I am in slight favor of not
changing this part.

> I'm not sure it's fair to categorize it as a "grammatical mistake",
> though.

The patch certainly is an attempt to make the text better, but I
agree that the patch does not correct any "mistake".

Thanks.
Pratyush Yadav April 8, 2020, 6:22 p.m. UTC | #5
On 06/04/20 04:46PM, Junio C Hamano wrote:
> Shourya Shukla <shouryashukla.oo@gmail.com> writes:
> 
> By the way, if you still want to pursue "full-stop at the end of the
> sentence MUST be followed by no more than one SP", I won't stop you,
> but please do so in a separate patch that has NO OTHER CHANGES.
> They drown other changes out that are not mechanical and makes them
> hard to review.

Maybe we should just have a consistent convention throughout the 
documentation on whether to use one space after a full-stop or two. 
Right now in some places we use one space, in some others we use two, 
even in the same file. This is slightly distracting when reading. Having 
a convention would at least result in uniformity, even if it won't end 
the debate on which is better. And FWIW, our man pages are always 
rendered with one space, even if the source file has two.
Junio C Hamano April 10, 2020, 6:29 p.m. UTC | #6
Pratyush Yadav <me@yadavpratyush.com> writes:

> Maybe we should just have a consistent convention throughout the 
> documentation on whether to use one space after a full-stop or two. 
> Right now in some places we use one space, in some others we use two, 
> even in the same file. This is slightly distracting when reading.

As somebody who almost always goes to the source on a fixed width
font terminal and not to formatted output, I personally find it
distracting not to have the extra space at the end of a sentence.

> And FWIW, our man pages are always 
> rendered with one space, even if the source file has two.

Or three, for that matter ;-)

It is one of the reasons why we didn't really care and have not gone
churning the source.

> Having a convention would at least result in uniformity, even if
> it won't end the debate on which is better.

Yup.  If I were to dictate a convention, I'd say we should have one
extra space after a full-stop or similar that ends a sentence.

As you pointed out, the choice of the convention does not make any
difference to the end product for end users, and only affect those
who work on the source with mark-ups, that is a fairly easy thing
to declare, without letting anybody argue for or against---it is not
better or worse than the other choice, but choosing one and sticking
to it is probably much better than not having a uniform convention.

Having said that, let's not go berserk and start reformatting,
especially areas that are actively touched for non-stylistic
reasons.  Those other changes are much much more important.

Thanks.

Patch
diff mbox series

diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
index 1cf83df118..3ca16b1092 100644
--- a/Documentation/gitfaq.txt
+++ b/Documentation/gitfaq.txt
@@ -23,7 +23,7 @@  Configuration
 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
+	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;
@@ -32,7 +32,7 @@  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
+	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.
@@ -40,15 +40,15 @@  What does `http.postBuffer` really do?::
 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
+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
+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
+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]]
@@ -56,13 +56,13 @@  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 or prefer a different
+	`vi`). Since some people find `vi` difficult to use or prefer a different
 	editor, 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 prefer the editor `nano`, then you could write the
+value. For example, if you prefer the editor `nano`, then you could write the
 following:
 +
 ----
@@ -70,15 +70,15 @@  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
+`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
+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
+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.
@@ -89,11 +89,11 @@  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,
+	`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
+	desktop environment can use the `libsecret` credential manager. All of
 	these store credentials in an encrypted store to keep your passwords or
 	tokens secure.
 +
@@ -102,7 +102,7 @@  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.  While it is possible to
+You can also just enter your password when prompted. While it is possible to
 place the password (which must be percent-encoded) in the URL, this is not
 particularly secure and can lead to accidental exposure of credentials, so it is
 not recommended.
@@ -113,8 +113,8 @@  How do I read a password or token from an environment variable?::
 	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`,
+Such a shell command can be specified by putting an exclamation point before
+the option. If your password or token were stored in the `GIT_TOKEN`,
 you could run the following command to set your credential helper:
 +
 ----
@@ -125,10 +125,10 @@  $ git config credential.helper \
 [[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
+	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):
 +
 ----
@@ -138,12 +138,12 @@  $ 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`
+	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
+	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
+	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).
@@ -151,17 +151,17 @@  How do I use multiple accounts with the same hosting provider using HTTP?::
 [[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
+	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
+	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
+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 in
+pair to use. For example, you could write something like the following in
 `~/.ssh/config`, substituting the proper private key file:
 +
 ----
@@ -189,29 +189,29 @@  Common Issues
 -------------
 
 [[last-commit-amend]]
-I've made a mistake in the last commit.  How do I change it?::
+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 appropriate, to stage it, and then `git
-	commit --amend`.  Your change will be included in the commit, and you'll
+	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
+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
+	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
+How do I ignore changes made 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
+	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
@@ -220,7 +220,7 @@  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
+can then be copied alongside and modified as appropriate. This second, modified
 file is usually ignored to prevent accidentally committing it.
 
 Hooks
@@ -230,12 +230,12 @@  Hooks
 How do I use hooks to prevent users from making certain changes?::
 	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
+	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
+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
@@ -251,24 +251,24 @@  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
+	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
+	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
+	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 the
-`working-tree-encoding` attribute.  For example, the following pattern sets all
+`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
+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
@@ -279,13 +279,13 @@  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,
+	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 is shown
-	because it is considered to be trailing whitespace.  Git defaults to showing
+	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
+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.
 +
@@ -295,28 +295,28 @@  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
+	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
+	(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
+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
+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 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 linkgit: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
+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:
 +
 ----