Merge branch 'nk/perf-fsmonitor-cleanup'
[git] / Documentation / gitfaq.txt
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 [[files-in-gitignore-are-tracked]]
227 I asked Git to ignore various files, yet they are still tracked::
228         A `gitignore` file ensures that certain file(s) which are not
229         tracked by Git remain untracked.  However, sometimes particular
230         file(s) may have been tracked before adding them into the
231         `.gitignore`, hence they still remain tracked.  To untrack and
232         ignore files/patterns, use `git rm --cached <file/pattern>`
233         and add a pattern to `.gitignore` that matches the <file>.
234         See linkgit:gitignore[5] for details.
235
236 [[fetching-and-pulling]]
237 How do I know if I want to do a fetch or a pull?::
238         A fetch stores a copy of the latest changes from the remote
239         repository, without modifying the working tree or current branch.
240         You can then at your leisure inspect, merge, rebase on top of, or
241         ignore the upstream changes.  A pull consists of a fetch followed
242         immediately by either a merge or rebase.  See linkgit:git-pull[1].
243
244 Merging and Rebasing
245 --------------------
246
247 [[long-running-squash-merge]]
248 What kinds of problems can occur when merging long-lived branches with squash merges?::
249         In general, there are a variety of problems that can occur when using squash
250         merges to merge two branches multiple times.  These can include seeing extra
251         commits in `git log` output, with a GUI, or when using the `...` notation to
252         express a range, as well as the possibility of needing to re-resolve conflicts
253         again and again.
254 +
255 When Git does a normal merge between two branches, it considers exactly three
256 points: the two branches and a third commit, called the _merge base_, which is
257 usually the common ancestor of the commits.  The result of the merge is the sum
258 of the changes between the merge base and each head.  When you merge two
259 branches with a regular merge commit, this results in a new commit which will
260 end up as a merge base when they're merged again, because there is now a new
261 common ancestor.  Git doesn't have to consider changes that occurred before the
262 merge base, so you don't have to re-resolve any conflicts you resolved before.
263 +
264 When you perform a squash merge, a merge commit isn't created; instead, the
265 changes from one side are applied as a regular commit to the other side.  This
266 means that the merge base for these branches won't have changed, and so when Git
267 goes to perform its next merge, it considers all of the changes that it
268 considered the last time plus the new changes.  That means any conflicts may
269 need to be re-resolved.  Similarly, anything using the `...` notation in `git
270 diff`, `git log`, or a GUI will result in showing all of the changes since the
271 original merge base.
272 +
273 As a consequence, if you want to merge two long-lived branches repeatedly, it's
274 best to always use a regular merge commit.
275
276 [[merge-two-revert-one]]
277 If I make a change on two branches but revert it on one, why does the merge of those branches include the change?::
278         By default, when Git does a merge, it uses a strategy called the recursive
279         strategy, which does a fancy three-way merge.  In such a case, when Git
280         performs the merge, it considers exactly three points: the two heads and a
281         third point, called the _merge base_, which is usually the common ancestor of
282         those commits.  Git does not consider the history or the individual commits
283         that have happened on those branches at all.
284 +
285 As a result, if both sides have a change and one side has reverted that change,
286 the result is to include the change.  This is because the code has changed on
287 one side and there is no net change on the other, and in this scenario, Git
288 adopts the change.
289 +
290 If this is a problem for you, you can do a rebase instead, rebasing the branch
291 with the revert onto the other branch.  A rebase in this scenario will revert
292 the change, because a rebase applies each individual commit, including the
293 revert.  Note that rebases rewrite history, so you should avoid rebasing
294 published branches unless you're sure you're comfortable with that.  See the
295 NOTES section in linkgit:git-rebase[1] for more details.
296
297 Hooks
298 -----
299
300 [[restrict-with-hooks]]
301 How do I use hooks to prevent users from making certain changes?::
302         The only safe place to make these changes is on the remote repository
303         (i.e., the Git server), usually in the `pre-receive` hook or in a
304         continuous integration (CI) system.  These are the locations in which
305         policy can be enforced effectively.
306 +
307 It's common to try to use `pre-commit` hooks (or, for commit messages,
308 `commit-msg` hooks) to check these things, which is great if you're working as a
309 solo developer and want the tooling to help you.  However, using hooks on a
310 developer machine is not effective as a policy control because a user can bypass
311 these hooks with `--no-verify` without being noticed (among various other ways).
312 Git assumes that the user is in control of their local repositories and doesn't
313 try to prevent this or tattle on the user.
314 +
315 In addition, some advanced users find `pre-commit` hooks to be an impediment to
316 workflows that use temporary commits to stage work in progress or that create
317 fixup commits, so it's better to push these kinds of checks to the server
318 anyway.
319
320 Cross-Platform Issues
321 ---------------------
322
323 [[windows-text-binary]]
324 I'm on Windows and my text files are detected as binary.::
325         Git works best when you store text files as UTF-8.  Many programs on
326         Windows support UTF-8, but some do not and only use the little-endian
327         UTF-16 format, which Git detects as binary.  If you can't use UTF-8 with
328         your programs, you can specify a working tree encoding that indicates
329         which encoding your files should be checked out with, while still
330         storing these files as UTF-8 in the repository.  This allows tools like
331         linkgit:git-diff[1] to work as expected, while still allowing your tools
332         to work.
333 +
334 To do so, you can specify a linkgit:gitattributes[5] pattern with the
335 `working-tree-encoding` attribute.  For example, the following pattern sets all
336 C files to use UTF-16LE-BOM, which is a common encoding on Windows:
337 +
338 ----
339 *.c     working-tree-encoding=UTF-16LE-BOM
340 ----
341 +
342 You will need to run `git add --renormalize` to have this take effect.  Note
343 that if you are making these changes on a project that is used across platforms,
344 you'll probably want to make it in a per-user configuration file or in the one
345 in `$GIT_DIR/info/attributes`, since making it in a `.gitattributes` file in the
346 repository will apply to all users of the repository.
347 +
348 See the following entry for information about normalizing line endings as well,
349 and see linkgit:gitattributes[5] for more information about attribute files.
350
351 [[windows-diff-control-m]]
352 I'm on Windows and git diff shows my files as having a `^M` at the end.::
353         By default, Git expects files to be stored with Unix line endings.  As such,
354         the carriage return (`^M`) that is part of a Windows line ending is shown
355         because it is considered to be trailing whitespace.  Git defaults to showing
356         trailing whitespace only on new lines, not existing ones.
357 +
358 You can store the files in the repository with Unix line endings and convert
359 them automatically to your platform's line endings.  To do that, set the
360 configuration option `core.eol` to `native` and see the following entry for
361 information about how to configure files as text or binary.
362 +
363 You can also control this behavior with the `core.whitespace` setting if you
364 don't wish to remove the carriage returns from your line endings.
365
366 [[always-modified-files-case]]
367 Why do I have a file that's always modified?::
368         Internally, Git always stores file names as sequences of bytes and doesn't
369         perform any encoding or case folding.  However, Windows and macOS by default
370         both perform case folding on file names.  As a result, it's possible to end up
371         with multiple files or directories whose names differ only in case.  Git can
372         handle this just fine, but the file system can store only one of these files,
373         so when Git reads the other file to see its contents, it looks modified.
374 +
375 It's best to remove one of the files such that you only have one file.  You can
376 do this with commands like the following (assuming two files `AFile.txt` and
377 `afile.txt`) on an otherwise clean working tree:
378 +
379 ----
380 $ git rm --cached AFile.txt
381 $ git commit -m 'Remove files conflicting in case'
382 $ git checkout .
383 ----
384 +
385 This avoids touching the disk, but removes the additional file.  Your project
386 may prefer to adopt a naming convention, such as all-lowercase names, to avoid
387 this problem from occurring again; such a convention can be checked using a
388 `pre-receive` hook or as part of a continuous integration (CI) system.
389 +
390 It is also possible for perpetually modified files to occur on any platform if a
391 smudge or clean filter is in use on your system but a file was previously
392 committed without running the smudge or clean filter.  To fix this, run the
393 following on an otherwise clean working tree:
394 +
395 ----
396 $ git add --renormalize .
397 ----
398
399 [[recommended-storage-settings]]
400 What's the recommended way to store files in Git?::
401         While Git can store and handle any file of any type, there are some
402         settings that work better than others.  In general, we recommend that
403         text files be stored in UTF-8 without a byte-order mark (BOM) with LF
404         (Unix-style) endings.  We also recommend the use of UTF-8 (again,
405         without BOM) in commit messages.  These are the settings that work best
406         across platforms and with tools such as `git diff` and `git merge`.
407 +
408 Additionally, if you have a choice between storage formats that are text based
409 or non-text based, we recommend storing files in the text format and, if
410 necessary, transforming them into the other format.  For example, a text-based
411 SQL dump with one record per line will work much better for diffing and merging
412 than an actual database file.  Similarly, text-based formats such as Markdown
413 and AsciiDoc will work better than binary formats such as Microsoft Word and
414 PDF.
415 +
416 Similarly, storing binary dependencies (e.g., shared libraries or JAR files) or
417 build products in the repository is generally not recommended.  Dependencies and
418 build products are best stored on an artifact or package server with only
419 references, URLs, and hashes stored in the repository.
420 +
421 We also recommend setting a linkgit:gitattributes[5] file to explicitly mark
422 which files are text and which are binary.  If you want Git to guess, you can
423 set the attribute `text=auto`.  For example, the following might be appropriate
424 in some projects:
425 +
426 ----
427 # By default, guess.
428 *       text=auto
429 # Mark all C files as text.
430 *.c     text
431 # Mark all JPEG files as binary.
432 *.jpg   binary
433 ----
434 +
435 These settings help tools pick the right format for output such as patches and
436 result in files being checked out in the appropriate line ending for the
437 platform.
438
439 GIT
440 ---
441 Part of the linkgit:git[1] suite