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.
Changes from v2:
* Suggest that the user might prefer a different editor as an additional
reason for not choosing vi.
* Avoid needless use of the past subjunctive.
* Use a introductory clause that draws contrast when discouraging people
from putting passwords in their URLs.
* Mention the file into which the user should place their OpenSSH
configuration.
* Rephrase question to avoid a misplaced modifier.
* Fix section level.
* Fix several typographical errors.
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
Range-diff against v2:
1: e5d6363d4a ! 1: 56d75e7b57 docs: add a FAQ
@@ Documentation/gitfaq.txt (new)
+
+[[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 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
++ 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 preferred the editor `nano`, then you could write
-+the following:
++value. For example, if you prefer the editor `nano`, then you could write the
++following:
++
+----
+export VISUAL=nano
@@ Documentation/gitfaq.txt (new)
+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
++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.
+
@@ Documentation/gitfaq.txt (new)
+Most hosting providers use a single SSH account for pushing; that is, all users
+push to the `git` account (e.g., `git@xxxxxxxxxxxxxxx`). 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:
++pair to use. For example, you could write something like the following in
++`~/.ssh/config`, substituting the proper private key file:
++
+----
+# This is the account for author on git.example.org.
@@ Documentation/gitfaq.txt (new)
+ # 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.
++# This is the account for committer on git.example.org.
+Host example_committer
+ HostName git.example.org
+ User git
@@ Documentation/gitfaq.txt (new)
+[[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
++ <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
+ 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
@@ Documentation/gitfaq.txt (new)
+-----
+
+[[restrict-with-hooks]]
-+How do I prevent users from making certain changes with 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
@@ Documentation/gitfaq.txt (new)
+anyway.
+
+Cross-Platform Issues
-+~~~~~~~~~~~~~~~~~~~~~
++---------------------
+
+[[windows-text-binary]]
+I'm on Windows and my text files are detected as binary.::
@@ Documentation/gitfaq.txt (new)
+ 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
++To do so, you can specify a linkgit:gitattributes[5] pattern 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:
++
@@ Documentation/gitfaq.txt (new)
+
+[[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.
++ 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
++ 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
@@ Documentation/gitfaq.txt (new)
+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:
++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
++in some projects:
++
+----
+# By default, guess.
