@matheusbsbs / matheus-bagliano / commits / 2149b6748f
Fork 0

docs: add a FAQ

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. Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>

brian m. carlson committed Mar 30, 2020 at 11:55 UTC 2149b6748f478badf1e19a8f11190837b2dccb6b
2 files changed +338
Documentation/Makefile
+1
@@ -30,6 +30,7 @@ MAN7_TXT += gitcredentials.txt
30 MAN7_TXT += gitcvs-migration.txt
31 MAN7_TXT += gitdiffcore.txt
32 MAN7_TXT += giteveryday.txt
33 +MAN7_TXT += gitfaq.txt
34 MAN7_TXT += gitglossary.txt
35 MAN7_TXT += gitnamespaces.txt
36 MAN7_TXT += gitremote-helpers.txt
Documentation/gitfaq.txt new
+337
@@ -0,0 +1,337 @@
1 +gitfaq(7)
2 +=========
3 +
4 +NAME
5 +----
6 +gitfaq - Frequently asked questions about using Git
7 +
8 +SYNOPSIS
9 +--------
10 +gitfaq
11 +
12 +DESCRIPTION
13 +-----------
14 +
15 +The examples in this FAQ assume a standard POSIX shell, like `bash` or `dash`,
16 +and a user, A U Thor, who has the account `author` on the hosting provider
17 +`git.example.org`.
18 +
19 +Configuration
20 +-------------
21 +
22 +[[user-name]]
23 +What should I put in `user.name`?::
24 + You should put your personal name, generally a form using a given name
25 + and family name. For example, the current maintainer of Git uses "Junio
26 + C Hamano". This will be the name portion that is stored in every commit
27 + you make.
28 ++
29 +This configuration doesn't have any effect on authenticating to remote services;
30 +for that, see `credential.username` in linkgit:git-config[1].
31 +
32 +[[http-postbuffer]]
33 +What does `http.postBuffer` really do?::
34 + This option changes the size of the buffer that Git uses when pushing
35 + data to a remote over HTTP or HTTPS. If the data is larger than this
36 + size, libcurl, which handles the HTTP support for Git, will use chunked
37 + transfer encoding since it isn't known ahead of time what the size of
38 + the pushed data will be.
39 ++
40 +Leaving this value at the default size is fine unless you know that either the
41 +remote server or a proxy in the middle doesn't support HTTP/1.1 (which
42 +introduced the chunked transfer encoding) or is known to be broken with chunked
43 +data. This is often (erroneously) suggested as a solution for generic push
44 +problems, but since almost every server and proxy supports at least HTTP/1.1,
45 +raising this value usually doesn't solve most push problems. A server or proxy
46 +that didn't correctly support HTTP/1.1 and chunked transfer encoding wouldn't be
47 +that useful on the Internet today, since it would break lots of traffic.
48 ++
49 +Note that increasing this value will increase the memory used on every relevant
50 +push that Git does over HTTP or HTTPS, since the entire buffer is allocated
51 +regardless of whether or not it is all used. Thus, it's best to leave it at the
52 +default unless you are sure you need a different value.
53 +
54 +[[configure-editor]]
55 +How do I configure a different editor?::
56 + If you haven't specified an editor specifically for Git, it will by default
57 + use the editor you've configured using the `VISUAL` or `EDITOR` environment
58 + variables, or if neither is specified, the system default (which is usually
59 + `vi`). Since some people find `vi` difficult to use or prefer a different
60 + editor, it may be desirable to change the editor used.
61 ++
62 +If you want to configure a general editor for most programs which need one, you
63 +can edit your shell configuration (e.g., `~/.bashrc` or `~/.zshenv`) to contain
64 +a line setting the `EDITOR` or `VISUAL` environment variable to an appropriate
65 +value. For example, if you prefer the editor `nano`, then you could write the
66 +following:
67 ++
68 +----
69 +export VISUAL=nano
70 +----
71 ++
72 +If you want to configure an editor specifically for Git, you can either set the
73 +`core.editor` configuration value or the `GIT_EDITOR` environment variable. You
74 +can see linkgit:git-var[1] for details on the order in which these options are
75 +consulted.
76 ++
77 +Note that in all cases, the editor value will be passed to the shell, so any
78 +arguments containing spaces should be appropriately quoted. Additionally, if
79 +your editor normally detaches from the terminal when invoked, you should specify
80 +it with an argument that makes it not do that, or else Git will not see any
81 +changes. An example of a configuration addressing both of these issues on
82 +Windows would be the configuration `"C:\Program Files\Vim\gvim.exe" --nofork`,
83 +which quotes the filename with spaces and specifies the `--nofork` option to
84 +avoid backgrounding the process.
85 +
86 +Credentials
87 +-----------
88 +
89 +[[http-credentials]]
90 +How do I specify my credentials when pushing over HTTP?::
91 + The easiest way to do this is to use a credential helper via the
92 + `credential.helper` configuration. Most systems provide a standard
93 + choice to integrate with the system credential manager. For example,
94 + Git for Windows provides the `wincred` credential manager, macOS has the
95 + `osxkeychain` credential manager, and Unix systems with a standard
96 + desktop environment can use the `libsecret` credential manager. All of
97 + these store credentials in an encrypted store to keep your passwords or
98 + tokens secure.
99 ++
100 +In addition, you can use the `store` credential manager which stores in a file
101 +in your home directory, or the `cache` credential manager, which does not
102 +permanently store your credentials, but does prevent you from being prompted for
103 +them for a certain period of time.
104 ++
105 +You can also just enter your password when prompted. While it is possible to
106 +place the password (which must be percent-encoded) in the URL, this is not
107 +particularly secure and can lead to accidental exposure of credentials, so it is
108 +not recommended.
109 +
110 +[[http-credentials-environment]]
111 +How do I read a password or token from an environment variable?::
112 + The `credential.helper` configuration option can also take an arbitrary
113 + shell command that produces the credential protocol on standard output.
114 + This is useful when passing credentials into a container, for example.
115 ++
116 +Such a shell command can be specified by starting the option value with an
117 +exclamation point. If your password or token were stored in the `GIT_TOKEN`,
118 +you could run the following command to set your credential helper:
119 ++
120 +----
121 +$ git config credential.helper \
122 + '!f() { echo username=author; echo "password=$GIT_TOKEN"; };f'
123 +----
124 +
125 +[[http-reset-credentials]]
126 +How do I change the password or token I've saved in my credential manager?::
127 + Usually, if the password or token is invalid, Git will erase it and
128 + prompt for a new one. However, there are times when this doesn't always
129 + happen. To change the password or token, you can erase the existing
130 + credentials and then Git will prompt for new ones. To erase
131 + credentials, use a syntax like the following (substituting your username
132 + and the hostname):
133 ++
134 +----
135 +$ echo url=https://author@git.example.org | git credential reject
136 +----
137 +
138 +[[multiple-accounts-http]]
139 +How do I use multiple accounts with the same hosting provider using HTTP?::
140 + Usually the easiest way to distinguish between these accounts is to use
141 + the username in the URL. For example, if you have the accounts `author`
142 + and `committer` on `git.example.org`, you can use the URLs
143 + https://author@git.example.org/org1/project1.git and
144 + https://committer@git.example.org/org2/project2.git. This way, when you
145 + use a credential helper, it will automatically try to look up the
146 + correct credentials for your account. If you already have a remote set
147 + up, you can change the URL with something like `git remote set-url
148 + origin https://author@git.example.org/org1/project1.git` (see
149 + linkgit:git-remote[1] for details).
150 +
151 +[[multiple-accounts-ssh]]
152 +How do I use multiple accounts with the same hosting provider using SSH?::
153 + With most hosting providers that support SSH, a single key pair uniquely
154 + identifies a user. Therefore, to use multiple accounts, it's necessary
155 + to create a key pair for each account. If you're using a reasonably
156 + modern OpenSSH version, you can create a new key pair with something
157 + like `ssh-keygen -t ed25519 -f ~/.ssh/id_committer`. You can then
158 + register the public key (in this case, `~/.ssh/id_committer.pub`; note
159 + the `.pub`) with the hosting provider.
160 ++
161 +Most hosting providers use a single SSH account for pushing; that is, all users
162 +push to the `git` account (e.g., `git@git.example.org`). If that's the case for
163 +your provider, you can set up multiple aliases in SSH to make it clear which key
164 +pair to use. For example, you could write something like the following in
165 +`~/.ssh/config`, substituting the proper private key file:
166 ++
167 +----
168 +# This is the account for author on git.example.org.
169 +Host example_author
170 + HostName git.example.org
171 + User git
172 + # This is the key pair registered for author with git.example.org.
173 + IdentityFile ~/.ssh/id_author
174 + IdentitiesOnly yes
175 +# This is the account for committer on git.example.org.
176 +Host example_committer
177 + HostName git.example.org
178 + User git
179 + # This is the key pair registered for committer with git.example.org.
180 + IdentityFile ~/.ssh/id_committer
181 + IdentitiesOnly yes
182 +----
183 ++
184 +Then, you can adjust your push URL to use `git@example_author` or
185 +`git@example_committer` instead of `git@example.org` (e.g., `git remote set-url
186 +git@example_author:org1/project1.git`).
187 +
188 +Common Issues
189 +-------------
190 +
191 +[[last-commit-amend]]
192 +I've made a mistake in the last commit. How do I change it?::
193 + You can make the appropriate change to your working tree, run `git add
194 + <file>` or `git rm <file>`, as appropriate, to stage it, and then `git
195 + commit --amend`. Your change will be included in the commit, and you'll
196 + be prompted to edit the commit message again; if you wish to use the
197 + original message verbatim, you can use the `--no-edit` option to `git
198 + commit` in addition, or just save and quit when your editor opens.
199 +
200 +[[undo-previous-change]]
201 +I've made a change with a bug and it's been included in the main branch. How should I undo it?::
202 + The usual way to deal with this is to use `git revert`. This preserves
203 + the history that the original change was made and was a valuable
204 + contribution, but also introduces a new commit that undoes those changes
205 + because the original had a problem. The commit message of the revert
206 + indicates the commit which was reverted and is usually edited to include
207 + an explanation as to why the revert was made.
208 +
209 +[[ignore-tracked-files]]
210 +How do I ignore changes to a tracked file?::
211 + Git doesn't provide a way to do this. The reason is that if Git needs
212 + to overwrite this file, such as during a checkout, it doesn't know
213 + whether the changes to the file are precious and should be kept, or
214 + whether they are irrelevant and can safely be destroyed. Therefore, it
215 + has to take the safe route and always preserve them.
216 ++
217 +It's tempting to try to use certain features of `git update-index`, namely the
218 +assume-unchanged and skip-worktree bits, but these don't work properly for this
219 +purpose and shouldn't be used this way.
220 ++
221 +If your goal is to modify a configuration file, it can often be helpful to have
222 +a file checked into the repository which is a template or set of defaults which
223 +can then be copied alongside and modified as appropriate. This second, modified
224 +file is usually ignored to prevent accidentally committing it.
225 +
226 +Hooks
227 +-----
228 +
229 +[[restrict-with-hooks]]
230 +How do I use hooks to prevent users from making certain changes?::
231 + The only safe place to make these changes is on the remote repository
232 + (i.e., the Git server), usually in the `pre-receive` hook or in a
233 + continuous integration (CI) system. These are the locations in which
234 + policy can be enforced effectively.
235 ++
236 +It's common to try to use `pre-commit` hooks (or, for commit messages,
237 +`commit-msg` hooks) to check these things, which is great if you're working as a
238 +solo developer and want the tooling to help you. However, using hooks on a
239 +developer machine is not effective as a policy control because a user can bypass
240 +these hooks with `--no-verify` without being noticed (among various other ways).
241 +Git assumes that the user is in control of their local repositories and doesn't
242 +try to prevent this or tattle on the user.
243 ++
244 +In addition, some advanced users find `pre-commit` hooks to be an impediment to
245 +workflows that use temporary commits to stage work in progress or that create
246 +fixup commits, so it's better to push these kinds of checks to the server
247 +anyway.
248 +
249 +Cross-Platform Issues
250 +---------------------
251 +
252 +[[windows-text-binary]]
253 +I'm on Windows and my text files are detected as binary.::
254 + Git works best when you store text files as UTF-8. Many programs on
255 + Windows support UTF-8, but some do not and only use the little-endian
256 + UTF-16 format, which Git detects as binary. If you can't use UTF-8 with
257 + your programs, you can specify a working tree encoding that indicates
258 + which encoding your files should be checked out with, while still
259 + storing these files as UTF-8 in the repository. This allows tools like
260 + linkgit:git-diff[1] to work as expected, while still allowing your tools
261 + to work.
262 ++
263 +To do so, you can specify a linkgit:gitattributes[5] pattern with the
264 +`working-tree-encoding` attribute. For example, the following pattern sets all
265 +C files to use UTF-16LE-BOM, which is a common encoding on Windows:
266 ++
267 +----
268 +*.c working-tree-encoding=UTF-16LE-BOM
269 +----
270 ++
271 +You will need to run `git add --renormalize` to have this take effect. Note
272 +that if you are making these changes on a project that is used across platforms,
273 +you'll probably want to make it in a per-user configuration file or in the one
274 +in `$GIT_DIR/info/attributes`, since making it in a `.gitattributes` file in the
275 +repository will apply to all users of the repository.
276 ++
277 +See the following entry for information about normalizing line endings as well,
278 +and see linkgit:gitattributes[5] for more information about attribute files.
279 +
280 +[[windows-diff-control-m]]
281 +I'm on Windows and git diff shows my files as having a `^M` at the end.::
282 + By default, Git expects files to be stored with Unix line endings. As such,
283 + the carriage return (`^M`) that is part of a Windows line ending is shown
284 + because it is considered to be trailing whitespace. Git defaults to showing
285 + trailing whitespace only on new lines, not existing ones.
286 ++
287 +You can store the files in the repository with Unix line endings and convert
288 +them automatically to your platform's line endings. To do that, set the
289 +configuration option `core.eol` to `native` and see the following entry for
290 +information about how to configure files as text or binary.
291 ++
292 +You can also control this behavior with the `core.whitespace` setting if you
293 +don't wish to remove the carriage returns from your line endings.
294 +
295 +[[recommended-storage-settings]]
296 +What's the recommended way to store files in Git?::
297 + While Git can store and handle any file of any type, there are some
298 + settings that work better than others. In general, we recommend that
299 + text files be stored in UTF-8 without a byte-order mark (BOM) with LF
300 + (Unix-style) endings. We also recommend the use of UTF-8 (again,
301 + without BOM) in commit messages. These are the settings that work best
302 + across platforms and with tools such as `git diff` and `git merge`.
303 ++
304 +Additionally, if you have a choice between storage formats that are text based
305 +or non-text based, we recommend storing files in the text format and, if
306 +necessary, transforming them into the other format. For example, a text-based
307 +SQL dump with one record per line will work much better for diffing and merging
308 +than an actual database file. Similarly, text-based formats such as Markdown
309 +and AsciiDoc will work better than binary formats such as Microsoft Word and
310 +PDF.
311 ++
312 +Similarly, storing binary dependencies (e.g., shared libraries or JAR files) or
313 +build products in the repository is generally not recommended. Dependencies and
314 +build products are best stored on an artifact or package server with only
315 +references, URLs, and hashes stored in the repository.
316 ++
317 +We also recommend setting a linkgit:gitattributes[5] file to explicitly mark
318 +which files are text and which are binary. If you want Git to guess, you can
319 +set the attribute `text=auto`. For example, the following might be appropriate
320 +in some projects:
321 ++
322 +----
323 +# By default, guess.
324 +* text=auto
325 +# Mark all C files as text.
326 +*.c text
327 +# Mark all JPEG files as binary.
328 +*.jpg binary
329 +----
330 ++
331 +These settings help tools pick the right format for output such as patches and
332 +result in files being checked out in the appropriate line ending for the
333 +platform.
334 +
335 +GIT
336 +---
337 +Part of the linkgit:git[1] suite