1GITFAQ(7)                         Git Manual                         GITFAQ(7)
2
3
4

NAME

6       gitfaq - Frequently asked questions about using Git
7

SYNOPSIS

9       gitfaq
10

DESCRIPTION

12       The examples in this FAQ assume a standard POSIX shell, like bash or
13       dash, and a user, A U Thor, who has the account author on the hosting
14       provider git.example.org.
15

CONFIGURATION

17       What should I put in user.name?
18           You should put your personal name, generally a form using a given
19           name and family name. For example, the current maintainer of Git
20           uses "Junio C Hamano". This will be the name portion that is stored
21           in every commit you make.
22
23           This configuration doesn’t have any effect on authenticating to
24           remote services; for that, see credential.username in git-
25           config(1).
26
27       What does http.postBuffer really do?
28           This option changes the size of the buffer that Git uses when
29           pushing data to a remote over HTTP or HTTPS. If the data is larger
30           than this size, libcurl, which handles the HTTP support for Git,
31           will use chunked transfer encoding since it isn’t known ahead of
32           time what the size of the pushed data will be.
33
34           Leaving this value at the default size is fine unless you know that
35           either the remote server or a proxy in the middle doesn’t support
36           HTTP/1.1 (which introduced the chunked transfer encoding) or is
37           known to be broken with chunked data. This is often (erroneously)
38           suggested as a solution for generic push problems, but since almost
39           every server and proxy supports at least HTTP/1.1, raising this
40           value usually doesn’t solve most push problems. A server or proxy
41           that didn’t correctly support HTTP/1.1 and chunked transfer
42           encoding wouldn’t be that useful on the Internet today, since it
43           would break lots of traffic.
44
45           Note that increasing this value will increase the memory used on
46           every relevant push that Git does over HTTP or HTTPS, since the
47           entire buffer is allocated regardless of whether or not it is all
48           used. Thus, it’s best to leave it at the default unless you are
49           sure you need a different value.
50
51       How do I configure a different editor?
52           If you haven’t specified an editor specifically for Git, it will by
53           default use the editor you’ve configured using the VISUAL or EDITOR
54           environment variables, or if neither is specified, the system
55           default (which is usually vi). Since some people find vi difficult
56           to use or prefer a different editor, it may be desirable to change
57           the editor used.
58
59           If you want to configure a general editor for most programs which
60           need one, you can edit your shell configuration (e.g., ~/.bashrc or
61           ~/.zshenv) to contain a line setting the EDITOR or VISUAL
62           environment variable to an appropriate value. For example, if you
63           prefer the editor nano, then you could write the following:
64
65               export VISUAL=nano
66
67           If you want to configure an editor specifically for Git, you can
68           either set the core.editor configuration value or the GIT_EDITOR
69           environment variable. You can see git-var(1) for details on the
70           order in which these options are consulted.
71
72           Note that in all cases, the editor value will be passed to the
73           shell, so any arguments containing spaces should be appropriately
74           quoted. Additionally, if your editor normally detaches from the
75           terminal when invoked, you should specify it with an argument that
76           makes it not do that, or else Git will not see any changes. An
77           example of a configuration addressing both of these issues on
78           Windows would be the configuration "C:\Program Files\Vim\gvim.exe"
79           --nofork, which quotes the filename with spaces and specifies the
80           --nofork option to avoid backgrounding the process.
81

CREDENTIALS

83       How do I specify my credentials when pushing over HTTP?
84           The easiest way to do this is to use a credential helper via the
85           credential.helper configuration. Most systems provide a standard
86           choice to integrate with the system credential manager. For
87           example, Git for Windows provides the wincred credential manager,
88           macOS has the osxkeychain credential manager, and Unix systems with
89           a standard desktop environment can use the libsecret credential
90           manager. All of these store credentials in an encrypted store to
91           keep your passwords or tokens secure.
92
93           In addition, you can use the store credential manager which stores
94           in a file in your home directory, or the cache credential manager,
95           which does not permanently store your credentials, but does prevent
96           you from being prompted for them for a certain period of time.
97
98           You can also just enter your password when prompted. While it is
99           possible to place the password (which must be percent-encoded) in
100           the URL, this is not particularly secure and can lead to accidental
101           exposure of credentials, so it is not recommended.
102
103       How do I read a password or token from an environment variable?
104           The credential.helper configuration option can also take an
105           arbitrary shell command that produces the credential protocol on
106           standard output. This is useful when passing credentials into a
107           container, for example.
108
109           Such a shell command can be specified by starting the option value
110           with an exclamation point. If your password or token were stored in
111           the GIT_TOKEN, you could run the following command to set your
112           credential helper:
113
114               $ git config credential.helper \
115                       '!f() { echo username=author; echo "password=$GIT_TOKEN"; };f'
116
117       How do I change the password or token I’ve saved in my credential
118       manager?
119           Usually, if the password or token is invalid, Git will erase it and
120           prompt for a new one. However, there are times when this doesn’t
121           always happen. To change the password or token, you can erase the
122           existing credentials and then Git will prompt for new ones. To
123           erase credentials, use a syntax like the following (substituting
124           your username and the hostname):
125
126               $ echo url=https://author@git.example.org | git credential reject
127
128       How do I use multiple accounts with the same hosting provider using
129       HTTP?
130           Usually the easiest way to distinguish between these accounts is to
131           use the username in the URL. For example, if you have the accounts
132           author and committer on git.example.org, you can use the URLs
133           https://author@git.example.org/org1/project1.git and
134           https://committer@git.example.org/org2/project2.git. This way, when
135           you use a credential helper, it will automatically try to look up
136           the correct credentials for your account. If you already have a
137           remote set up, you can change the URL with something like git
138           remote set-url origin
139           https://author@git.example.org/org1/project1.git (see git-remote(1)
140           for details).
141
142       How do I use multiple accounts with the same hosting provider using
143       SSH?
144           With most hosting providers that support SSH, a single key pair
145           uniquely identifies a user. Therefore, to use multiple accounts,
146           it’s necessary to create a key pair for each account. If you’re
147           using a reasonably modern OpenSSH version, you can create a new key
148           pair with something like ssh-keygen -t ed25519 -f
149           ~/.ssh/id_committer. You can then register the public key (in this
150           case, ~/.ssh/id_committer.pub; note the .pub) with the hosting
151           provider.
152
153           Most hosting providers use a single SSH account for pushing; that
154           is, all users push to the git account (e.g., git@git.example.org).
155           If that’s the case for your provider, you can set up multiple
156           aliases in SSH to make it clear which key pair to use. For example,
157           you could write something like the following in ~/.ssh/config,
158           substituting the proper private key file:
159
160               # This is the account for author on git.example.org.
161               Host example_author
162                       HostName git.example.org
163                       User git
164                       # This is the key pair registered for author with git.example.org.
165                       IdentityFile ~/.ssh/id_author
166                       IdentitiesOnly yes
167               # This is the account for committer on git.example.org.
168               Host example_committer
169                       HostName git.example.org
170                       User git
171                       # This is the key pair registered for committer with git.example.org.
172                       IdentityFile ~/.ssh/id_committer
173                       IdentitiesOnly yes
174
175           Then, you can adjust your push URL to use git@example_author or
176           git@example_committer instead of git@example.org (e.g., git remote
177           set-url git@example_author:org1/project1.git).
178

COMMON ISSUES

180       I’ve made a mistake in the last commit. How do I change it?
181           You can make the appropriate change to your working tree, run git
182           add <file> or git rm <file>, as appropriate, to stage it, and then
183           git commit --amend. Your change will be included in the commit, and
184           you’ll be prompted to edit the commit message again; if you wish to
185           use the original message verbatim, you can use the --no-edit option
186           to git commit in addition, or just save and quit when your editor
187           opens.
188
189       I’ve made a change with a bug and it’s been included in the main
190       branch. How should I undo it?
191           The usual way to deal with this is to use git revert. This
192           preserves the history that the original change was made and was a
193           valuable contribution, but also introduces a new commit that undoes
194           those changes because the original had a problem. The commit
195           message of the revert indicates the commit which was reverted and
196           is usually edited to include an explanation as to why the revert
197           was made.
198
199       How do I ignore changes to a tracked file?
200           Git doesn’t provide a way to do this. The reason is that if Git
201           needs to overwrite this file, such as during a checkout, it doesn’t
202           know whether the changes to the file are precious and should be
203           kept, or whether they are irrelevant and can safely be destroyed.
204           Therefore, it has to take the safe route and always preserve them.
205
206           It’s tempting to try to use certain features of git update-index,
207           namely the assume-unchanged and skip-worktree bits, but these don’t
208           work properly for this purpose and shouldn’t be used this way.
209
210           If your goal is to modify a configuration file, it can often be
211           helpful to have a file checked into the repository which is a
212           template or set of defaults which can then be copied alongside and
213           modified as appropriate. This second, modified file is usually
214           ignored to prevent accidentally committing it.
215
216       I asked Git to ignore various files, yet they are still tracked
217           A gitignore file ensures that certain file(s) which are not tracked
218           by Git remain untracked. However, sometimes particular file(s) may
219           have been tracked before adding them into the .gitignore, hence
220           they still remain tracked. To untrack and ignore files/patterns,
221           use git rm --cached <file/pattern> and add a pattern to .gitignore
222           that matches the <file>. See gitignore(5) for details.
223
224       How do I know if I want to do a fetch or a pull?
225           A fetch stores a copy of the latest changes from the remote
226           repository, without modifying the working tree or current branch.
227           You can then at your leisure inspect, merge, rebase on top of, or
228           ignore the upstream changes. A pull consists of a fetch followed
229           immediately by either a merge or rebase. See git-pull(1).
230

MERGING AND REBASING

232       What kinds of problems can occur when merging long-lived branches with
233       squash merges?
234           In general, there are a variety of problems that can occur when
235           using squash merges to merge two branches multiple times. These can
236           include seeing extra commits in git log output, with a GUI, or when
237           using the ...  notation to express a range, as well as the
238           possibility of needing to re-resolve conflicts again and again.
239
240           When Git does a normal merge between two branches, it considers
241           exactly three points: the two branches and a third commit, called
242           the merge base, which is usually the common ancestor of the
243           commits. The result of the merge is the sum of the changes between
244           the merge base and each head. When you merge two branches with a
245           regular merge commit, this results in a new commit which will end
246           up as a merge base when they’re merged again, because there is now
247           a new common ancestor. Git doesn’t have to consider changes that
248           occurred before the merge base, so you don’t have to re-resolve any
249           conflicts you resolved before.
250
251           When you perform a squash merge, a merge commit isn’t created;
252           instead, the changes from one side are applied as a regular commit
253           to the other side. This means that the merge base for these
254           branches won’t have changed, and so when Git goes to perform its
255           next merge, it considers all of the changes that it considered the
256           last time plus the new changes. That means any conflicts may need
257           to be re-resolved. Similarly, anything using the ...  notation in
258           git diff, git log, or a GUI will result in showing all of the
259           changes since the original merge base.
260
261           As a consequence, if you want to merge two long-lived branches
262           repeatedly, it’s best to always use a regular merge commit.
263
264       If I make a change on two branches but revert it on one, why does the
265       merge of those branches include the change?
266           By default, when Git does a merge, it uses a strategy called the
267           ort strategy, which does a fancy three-way merge. In such a case,
268           when Git performs the merge, it considers exactly three points: the
269           two heads and a third point, called the merge base, which is
270           usually the common ancestor of those commits. Git does not consider
271           the history or the individual commits that have happened on those
272           branches at all.
273
274           As a result, if both sides have a change and one side has reverted
275           that change, the result is to include the change. This is because
276           the code has changed on one side and there is no net change on the
277           other, and in this scenario, Git adopts the change.
278
279           If this is a problem for you, you can do a rebase instead, rebasing
280           the branch with the revert onto the other branch. A rebase in this
281           scenario will revert the change, because a rebase applies each
282           individual commit, including the revert. Note that rebases rewrite
283           history, so you should avoid rebasing published branches unless
284           you’re sure you’re comfortable with that. See the NOTES section in
285           git-rebase(1) for more details.
286

HOOKS

288       How do I use hooks to prevent users from making certain changes?
289           The only safe place to make these changes is on the remote
290           repository (i.e., the Git server), usually in the pre-receive hook
291           or in a continuous integration (CI) system. These are the locations
292           in which policy can be enforced effectively.
293
294           It’s common to try to use pre-commit hooks (or, for commit
295           messages, commit-msg hooks) to check these things, which is great
296           if you’re working as a solo developer and want the tooling to help
297           you. However, using hooks on a developer machine is not effective
298           as a policy control because a user can bypass these hooks with
299           --no-verify without being noticed (among various other ways). Git
300           assumes that the user is in control of their local repositories and
301           doesn’t try to prevent this or tattle on the user.
302
303           In addition, some advanced users find pre-commit hooks to be an
304           impediment to workflows that use temporary commits to stage work in
305           progress or that create fixup commits, so it’s better to push these
306           kinds of checks to the server anyway.
307

CROSS-PLATFORM ISSUES

309       I’m on Windows and my text files are detected as binary.
310           Git works best when you store text files as UTF-8. Many programs on
311           Windows support UTF-8, but some do not and only use the
312           little-endian UTF-16 format, which Git detects as binary. If you
313           can’t use UTF-8 with your programs, you can specify a working tree
314           encoding that indicates which encoding your files should be checked
315           out with, while still storing these files as UTF-8 in the
316           repository. This allows tools like git-diff(1) to work as expected,
317           while still allowing your tools to work.
318
319           To do so, you can specify a gitattributes(5) pattern with the
320           working-tree-encoding attribute. For example, the following pattern
321           sets all C files to use UTF-16LE-BOM, which is a common encoding on
322           Windows:
323
324               *.c     working-tree-encoding=UTF-16LE-BOM
325
326           You will need to run git add --renormalize to have this take
327           effect. Note that if you are making these changes on a project that
328           is used across platforms, you’ll probably want to make it in a
329           per-user configuration file or in the one in
330           $GIT_DIR/info/attributes, since making it in a .gitattributes file
331           in the repository will apply to all users of the repository.
332
333           See the following entry for information about normalizing line
334           endings as well, and see gitattributes(5) for more information
335           about attribute files.
336
337       I’m on Windows and git diff shows my files as having a ^M at the end.
338           By default, Git expects files to be stored with Unix line endings.
339           As such, the carriage return (^M) that is part of a Windows line
340           ending is shown because it is considered to be trailing whitespace.
341           Git defaults to showing trailing whitespace only on new lines, not
342           existing ones.
343
344           You can store the files in the repository with Unix line endings
345           and convert them automatically to your platform’s line endings. To
346           do that, set the configuration option core.eol to native and see
347           the following entry for information about how to configure files as
348           text or binary.
349
350           You can also control this behavior with the core.whitespace setting
351           if you don’t wish to remove the carriage returns from your line
352           endings.
353
354       Why do I have a file that’s always modified?
355           Internally, Git always stores file names as sequences of bytes and
356           doesn’t perform any encoding or case folding. However, Windows and
357           macOS by default both perform case folding on file names. As a
358           result, it’s possible to end up with multiple files or directories
359           whose names differ only in case. Git can handle this just fine, but
360           the file system can store only one of these files, so when Git
361           reads the other file to see its contents, it looks modified.
362
363           It’s best to remove one of the files such that you only have one
364           file. You can do this with commands like the following (assuming
365           two files AFile.txt and afile.txt) on an otherwise clean working
366           tree:
367
368               $ git rm --cached AFile.txt
369               $ git commit -m 'Remove files conflicting in case'
370               $ git checkout .
371
372           This avoids touching the disk, but removes the additional file.
373           Your project may prefer to adopt a naming convention, such as
374           all-lowercase names, to avoid this problem from occurring again;
375           such a convention can be checked using a pre-receive hook or as
376           part of a continuous integration (CI) system.
377
378           It is also possible for perpetually modified files to occur on any
379           platform if a smudge or clean filter is in use on your system but a
380           file was previously committed without running the smudge or clean
381           filter. To fix this, run the following on an otherwise clean
382           working tree:
383
384               $ git add --renormalize .
385
386       What’s the recommended way to store files in Git?
387           While Git can store and handle any file of any type, there are some
388           settings that work better than others. In general, we recommend
389           that text files be stored in UTF-8 without a byte-order mark (BOM)
390           with LF (Unix-style) endings. We also recommend the use of UTF-8
391           (again, without BOM) in commit messages. These are the settings
392           that work best across platforms and with tools such as git diff and
393           git merge.
394
395           Additionally, if you have a choice between storage formats that are
396           text based or non-text based, we recommend storing files in the
397           text format and, if necessary, transforming them into the other
398           format. For example, a text-based SQL dump with one record per line
399           will work much better for diffing and merging than an actual
400           database file. Similarly, text-based formats such as Markdown and
401           AsciiDoc will work better than binary formats such as Microsoft
402           Word and PDF.
403
404           Similarly, storing binary dependencies (e.g., shared libraries or
405           JAR files) or build products in the repository is generally not
406           recommended. Dependencies and build products are best stored on an
407           artifact or package server with only references, URLs, and hashes
408           stored in the repository.
409
410           We also recommend setting a gitattributes(5) file to explicitly
411           mark which files are text and which are binary. If you want Git to
412           guess, you can set the attribute text=auto. For example, the
413           following might be appropriate in some projects:
414
415               # By default, guess.
416               *       text=auto
417               # Mark all C files as text.
418               *.c     text
419               # Mark all JPEG files as binary.
420               *.jpg   binary
421
422           These settings help tools pick the right format for output such as
423           patches and result in files being checked out in the appropriate
424           line ending for the platform.
425

GIT

427       Part of the git(1) suite
428
429
430
431Git 2.36.1                        2022-05-05                         GITFAQ(7)
Impressum