[PATCH v3 0/1] FAQ for common user questions

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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.



[Index of Archives]     [Linux Kernel Development]     [Gcc Help]     [IETF Annouce]     [DCCP]     [Netdev]     [Networking]     [Security]     [V4L]     [Bugtraq]     [Yosemite]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Linux SCSI]     [Fedora Users]

  Powered by Linux