freshlybakedca.ke
Git fork
1gitfaq(7)
2=========
3
4NAME
5----
6gitfaq - Frequently asked questions about using Git
7
8SYNOPSIS
9--------
10gitfaq
11
12DESCRIPTION
13-----------
14
15The examples in this FAQ assume a standard POSIX shell, like `bash` or `dash`,
16and a user, A U Thor, who has the account `author` on the hosting provider
17`git.example.org`.
18
19Configuration
20-------------
21
22[[user-name]]
23What 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+
29This configuration doesn't have any effect on authenticating to remote services;
30for that, see `credential.username` in linkgit:git-config[1].
31
32[[http-postbuffer]]
33What 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+
40Leaving this value at the default size is fine unless you know that either the
41remote server or a proxy in the middle doesn't support HTTP/1.1 (which
42introduced the chunked transfer encoding) or is known to be broken with chunked
43data. This is often (erroneously) suggested as a solution for generic push
44problems, but since almost every server and proxy supports at least HTTP/1.1,
45raising this value usually doesn't solve most push problems. A server or proxy
46that didn't correctly support HTTP/1.1 and chunked transfer encoding wouldn't be
47that useful on the Internet today, since it would break lots of traffic.
48+
49Note that increasing this value will increase the memory used on every relevant
50push that Git does over HTTP or HTTPS, since the entire buffer is allocated
51regardless of whether or not it is all used. Thus, it's best to leave it at the
52default unless you are sure you need a different value.
53
54[[configure-editor]]
55How 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+
62If you want to configure a general editor for most programs which need one, you
63can edit your shell configuration (e.g., `~/.bashrc` or `~/.zshenv`) to contain
64a line setting the `EDITOR` or `VISUAL` environment variable to an appropriate
65value. For example, if you prefer the editor `nano`, then you could write the
66following:
67+
68----
69export VISUAL=nano
70----
71+
72If 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
74can see linkgit:git-var[1] for details on the order in which these options are
75consulted.
76+
77Note that in all cases, the editor value will be passed to the shell, so any
78arguments containing spaces should be appropriately quoted. Additionally, if
79your editor normally detaches from the terminal when invoked, you should specify
80it with an argument that makes it not do that, or else Git will not see any
81changes. An example of a configuration addressing both of these issues on
82Windows would be the configuration `"C:\Program Files\Vim\gvim.exe" --nofork`,
83which quotes the filename with spaces and specifies the `--nofork` option to
84avoid backgrounding the process.
85
86Credentials
87-----------
88
89[[http-credentials]]
90How 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+
100In addition, you can use the `store` credential manager which stores in a file
101in your home directory, or the `cache` credential manager, which does not
102permanently store your credentials, but does prevent you from being prompted for
103them for a certain period of time.
104+
105You can also just enter your password when prompted. While it is possible to
106place the password (which must be percent-encoded) in the URL, this is not
107particularly secure and can lead to accidental exposure of credentials, so it is
108not recommended.
109
110[[http-credentials-environment]]
111How 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+
116Such a shell command can be specified by starting the option value with an
117exclamation point. If your password or token were stored in the `GIT_TOKEN`,
118you 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]]
126How 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]]
139How 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]]
152How 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+
161Most hosting providers use a single SSH account for pushing; that is, all users
162push to the `git` account (e.g., `git@git.example.org`). If that's the case for
163your provider, you can set up multiple aliases in SSH to make it clear which key
164pair 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.
169Host 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.
176Host 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+
184Then, 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
186git@example_author:org1/project1.git`).
187
188Transfers
189---------
190
191[[sync-working-tree]]
192How do I sync a working tree across systems?::
193 First, decide whether you want to do this at all. Git works best when you
194 push or pull your work using the typical `git push` and `git fetch` commands
195 and isn't designed to share a working tree across systems. This is
196 potentially risky and in some cases can cause repository corruption or data
197 loss.
198+
199Usually, doing so will cause `git status` to need to re-read every file in the
200working tree. Additionally, Git's security model does not permit sharing a
201working tree across untrusted users, so it is only safe to sync a working tree
202if it will only be used by a single user across all machines.
203+
204It is important not to use a cloud syncing service to sync any portion of a Git
205repository, since this can cause corruption, such as missing objects, changed
206or added files, broken refs, and a wide variety of other problems. These
207services tend to sync file by file on a continuous basis and don't understand
208the structure of a Git repository. This is especially bad if they sync the
209repository in the middle of it being updated, since that is very likely to
210cause incomplete or partial updates and therefore data loss.
211+
212An example of the kind of corruption that can occur is conflicts over the state
213of refs, such that both sides end up with different commits on a branch that
214the other doesn't have. This can result in important objects becoming
215unreferenced and possibly pruned by `git gc`, causing data loss.
216+
217Therefore, it's better to push your work to either the other system or a central
218server using the normal push and pull mechanism. However, this doesn't always
219preserve important data, like stashes, so some people prefer to share a working
220tree across systems.
221+
222If you do this, the recommended approach is to use `rsync -a --delete-after`
223(ideally with an encrypted connection such as with `ssh`) on the root of
224repository. You should ensure several things when you do this:
225+
226* If you have additional worktrees or a separate Git directory, they must be
227 synced at the same time as the main working tree and repository.
228* You are comfortable with the destination directory being an exact copy of the
229 source directory, _deleting any data that is already there_.
230* The repository (including all worktrees and the Git directory) is in a
231 quiescent state for the duration of the transfer (that is, no operations of
232 any sort are taking place on it, including background operations like `git
233 gc` and operations invoked by your editor).
234+
235Be aware that even with these recommendations, syncing in this way has some risk
236since it bypasses Git's normal integrity checking for repositories, so having
237backups is advised. You may also wish to do a `git fsck` to verify the
238integrity of your data on the destination system after syncing.
239
240Common Issues
241-------------
242
243[[last-commit-amend]]
244I've made a mistake in the last commit. How do I change it?::
245 You can make the appropriate change to your working tree, run `git add
246 <file>` or `git rm <file>`, as appropriate, to stage it, and then `git
247 commit --amend`. Your change will be included in the commit, and you'll
248 be prompted to edit the commit message again; if you wish to use the
249 original message verbatim, you can use the `--no-edit` option to `git
250 commit` in addition, or just save and quit when your editor opens.
251
252[[undo-previous-change]]
253I've made a change with a bug and it's been included in the main branch. How should I undo it?::
254 The usual way to deal with this is to use `git revert`. This preserves
255 the history that the original change was made and was a valuable
256 contribution, but also introduces a new commit that undoes those changes
257 because the original had a problem. The commit message of the revert
258 indicates the commit which was reverted and is usually edited to include
259 an explanation as to why the revert was made.
260
261[[ignore-tracked-files]]
262How do I ignore changes to a tracked file?::
263 Git doesn't provide a way to do this. The reason is that if Git needs
264 to overwrite this file, such as during a checkout, it doesn't know
265 whether the changes to the file are precious and should be kept, or
266 whether they are irrelevant and can safely be destroyed. Therefore, it
267 has to take the safe route and always preserve them.
268+
269It's tempting to try to use certain features of `git update-index`, namely the
270assume-unchanged and skip-worktree bits, but these don't work properly for this
271purpose and shouldn't be used this way.
272+
273If your goal is to modify a configuration file, it can often be helpful to have
274a file checked into the repository which is a template or set of defaults which
275can then be copied alongside and modified as appropriate. This second, modified
276file is usually ignored to prevent accidentally committing it.
277
278[[files-in-gitignore-are-tracked]]
279I asked Git to ignore various files, yet they are still tracked::
280 A `gitignore` file ensures that certain file(s) which are not
281 tracked by Git remain untracked. However, sometimes particular
282 file(s) may have been tracked before adding them into the
283 `.gitignore`, hence they still remain tracked. To untrack and
284 ignore files/patterns, use `git rm --cached <file/pattern>`
285 and add a pattern to `.gitignore` that matches the <file>.
286 See linkgit:gitignore[5] for details.
287
288[[fetching-and-pulling]]
289How do I know if I want to do a fetch or a pull?::
290 A fetch stores a copy of the latest changes from the remote
291 repository, without modifying the working tree or current branch.
292 You can then at your leisure inspect, merge, rebase on top of, or
293 ignore the upstream changes. A pull consists of a fetch followed
294 immediately by either a merge or rebase. See linkgit:git-pull[1].
295
296[[proxy]]
297Can I use a proxy with Git?::
298 Yes, Git supports the use of proxies. Git honors the standard `http_proxy`,
299 `https_proxy`, and `no_proxy` environment variables commonly used on Unix, and
300 it also can be configured with `http.proxy` and similar options for HTTPS (see
301 linkgit:git-config[1]). The `http.proxy` and related options can be
302 customized on a per-URL pattern basis. In addition, Git can in theory
303 function normally with transparent proxies that exist on the network.
304+
305For SSH, Git can support a proxy using OpenSSH's `ProxyCommand`. Commonly used
306tools include `netcat` and `socat`. However, they must be configured not to
307exit when seeing EOF on standard input, which usually means that `netcat` will
308require `-q` and `socat` will require a timeout with something like `-t 10`.
309This is required because the way the Git SSH server knows that no more requests
310will be made is an EOF on standard input, but when that happens, the server may
311not have yet processed the final request, so dropping the connection at that
312point would interrupt that request.
313+
314An example configuration entry in `~/.ssh/config` with an HTTP proxy might look
315like this:
316+
317----
318Host git.example.org
319 User git
320 ProxyCommand socat -t 10 - PROXY:proxy.example.org:%h:%p,proxyport=8080
321----
322+
323Note that in all cases, for Git to work properly, the proxy must be completely
324transparent. The proxy cannot modify, tamper with, or buffer the connection in
325any way, or Git will almost certainly fail to work. Note that many proxies,
326including many TLS middleboxes, Windows antivirus and firewall programs other
327than Windows Defender and Windows Firewall, and filtering proxies fail to meet
328this standard, and as a result end up breaking Git. Because of the many
329reports of problems and their poor security history, we recommend against the
330use of these classes of software and devices.
331
332Merging and Rebasing
333--------------------
334
335[[long-running-squash-merge]]
336What kinds of problems can occur when merging long-lived branches with squash merges?::
337 In general, there are a variety of problems that can occur when using squash
338 merges to merge two branches multiple times. These can include seeing extra
339 commits in `git log` output, with a GUI, or when using the `...` notation to
340 express a range, as well as the possibility of needing to re-resolve conflicts
341 again and again.
342+
343When Git does a normal merge between two branches, it considers exactly three
344points: the two branches and a third commit, called the _merge base_, which is
345usually the common ancestor of the commits. The result of the merge is the sum
346of the changes between the merge base and each head. When you merge two
347branches with a regular merge commit, this results in a new commit which will
348end up as a merge base when they're merged again, because there is now a new
349common ancestor. Git doesn't have to consider changes that occurred before the
350merge base, so you don't have to re-resolve any conflicts you resolved before.
351+
352When you perform a squash merge, a merge commit isn't created; instead, the
353changes from one side are applied as a regular commit to the other side. This
354means that the merge base for these branches won't have changed, and so when Git
355goes to perform its next merge, it considers all of the changes that it
356considered the last time plus the new changes. That means any conflicts may
357need to be re-resolved. Similarly, anything using the `...` notation in `git
358diff`, `git log`, or a GUI will result in showing all of the changes since the
359original merge base.
360+
361As a consequence, if you want to merge two long-lived branches repeatedly, it's
362best to always use a regular merge commit.
363
364[[merge-two-revert-one]]
365If I make a change on two branches but revert it on one, why does the merge of those branches include the change?::
366 By default, when Git does a merge, it uses a strategy called the `ort`
367 strategy, which does a fancy three-way merge. In such a case, when Git
368 performs the merge, it considers exactly three points: the two heads and a
369 third point, called the _merge base_, which is usually the common ancestor of
370 those commits. Git does not consider the history or the individual commits
371 that have happened on those branches at all.
372+
373As a result, if both sides have a change and one side has reverted that change,
374the result is to include the change. This is because the code has changed on
375one side and there is no net change on the other, and in this scenario, Git
376adopts the change.
377+
378If this is a problem for you, you can do a rebase instead, rebasing the branch
379with the revert onto the other branch. A rebase in this scenario will revert
380the change, because a rebase applies each individual commit, including the
381revert. Note that rebases rewrite history, so you should avoid rebasing
382published branches unless you're sure you're comfortable with that. See the
383NOTES section in linkgit:git-rebase[1] for more details.
384
385Hooks
386-----
387
388[[restrict-with-hooks]]
389How do I use hooks to prevent users from making certain changes?::
390 The only safe place to make these changes is on the remote repository
391 (i.e., the Git server), usually in the `pre-receive` hook or in a
392 continuous integration (CI) system. These are the locations in which
393 policy can be enforced effectively.
394+
395It's common to try to use `pre-commit` hooks (or, for commit messages,
396`commit-msg` hooks) to check these things, which is great if you're working as a
397solo developer and want the tooling to help you. However, using hooks on a
398developer machine is not effective as a policy control because a user can bypass
399these hooks with `--no-verify` without being noticed (among various other ways).
400Git assumes that the user is in control of their local repositories and doesn't
401try to prevent this or tattle on the user.
402+
403In addition, some advanced users find `pre-commit` hooks to be an impediment to
404workflows that use temporary commits to stage work in progress or that create
405fixup commits, so it's better to push these kinds of checks to the server
406anyway.
407
408Cross-Platform Issues
409---------------------
410
411[[windows-text-binary]]
412I'm on Windows and my text files are detected as binary.::
413 Git works best when you store text files as UTF-8. Many programs on
414 Windows support UTF-8, but some do not and only use the little-endian
415 UTF-16 format, which Git detects as binary. If you can't use UTF-8 with
416 your programs, you can specify a working tree encoding that indicates
417 which encoding your files should be checked out with, while still
418 storing these files as UTF-8 in the repository. This allows tools like
419 linkgit:git-diff[1] to work as expected, while still allowing your tools
420 to work.
421+
422To do so, you can specify a linkgit:gitattributes[5] pattern with the
423`working-tree-encoding` attribute. For example, the following pattern sets all
424C files to use UTF-16LE-BOM, which is a common encoding on Windows:
425+
426----
427*.c working-tree-encoding=UTF-16LE-BOM
428----
429+
430You will need to run `git add --renormalize` to have this take effect. Note
431that if you are making these changes on a project that is used across platforms,
432you'll probably want to make it in a per-user configuration file or in the one
433in `$GIT_DIR/info/attributes`, since making it in a `.gitattributes` file in the
434repository will apply to all users of the repository.
435+
436See the following entry for information about normalizing line endings as well,
437and see linkgit:gitattributes[5] for more information about attribute files.
438
439[[windows-diff-control-m]]
440I'm on Windows and git diff shows my files as having a `^M` at the end.::
441 By default, Git expects files to be stored with Unix line endings. As such,
442 the carriage return (`^M`) that is part of a Windows line ending is shown
443 because it is considered to be trailing whitespace. Git defaults to showing
444 trailing whitespace only on new lines, not existing ones.
445+
446You can store the files in the repository with Unix line endings and convert
447them automatically to your platform's line endings. To do that, set the
448configuration option `core.eol` to `native` and see
449<<recommended-storage-settings,the question on recommended storage settings>>
450for information about how to configure files as text or binary.
451+
452You can also control this behavior with the `core.whitespace` setting if you
453don't wish to remove the carriage returns from your line endings.
454
455[[always-modified-files-case]]
456Why do I have a file that's always modified?::
457 Internally, Git always stores file names as sequences of bytes and doesn't
458 perform any encoding or case folding. However, Windows and macOS by default
459 both perform case folding on file names. As a result, it's possible to end up
460 with multiple files or directories whose names differ only in case. Git can
461 handle this just fine, but the file system can store only one of these files,
462 so when Git reads the other file to see its contents, it looks modified.
463+
464It's best to remove one of the files such that you only have one file. You can
465do this with commands like the following (assuming two files `AFile.txt` and
466`afile.txt`) on an otherwise clean working tree:
467+
468----
469$ git rm --cached AFile.txt
470$ git commit -m 'Remove files conflicting in case'
471$ git checkout .
472----
473+
474This avoids touching the disk, but removes the additional file. Your project
475may prefer to adopt a naming convention, such as all-lowercase names, to avoid
476this problem from occurring again; such a convention can be checked using a
477`pre-receive` hook or as part of a continuous integration (CI) system.
478+
479It is also possible for perpetually modified files to occur on any platform if a
480smudge or clean filter is in use on your system but a file was previously
481committed without running the smudge or clean filter. To fix this, run the
482following on an otherwise clean working tree:
483+
484----
485$ git add --renormalize .
486----
487
488[[recommended-storage-settings]]
489What's the recommended way to store files in Git?::
490 While Git can store and handle any file of any type, there are some
491 settings that work better than others. In general, we recommend that
492 text files be stored in UTF-8 without a byte-order mark (BOM) with LF
493 (Unix-style) endings. We also recommend the use of UTF-8 (again,
494 without BOM) in commit messages. These are the settings that work best
495 across platforms and with tools such as `git diff` and `git merge`.
496+
497Additionally, if you have a choice between storage formats that are text based
498or non-text based, we recommend storing files in the text format and, if
499necessary, transforming them into the other format. For example, a text-based
500SQL dump with one record per line will work much better for diffing and merging
501than an actual database file. Similarly, text-based formats such as Markdown
502and AsciiDoc will work better than binary formats such as Microsoft Word and
503PDF.
504+
505Similarly, storing binary dependencies (e.g., shared libraries or JAR files) or
506build products in the repository is generally not recommended. Dependencies and
507build products are best stored on an artifact or package server with only
508references, URLs, and hashes stored in the repository.
509+
510We also recommend setting a linkgit:gitattributes[5] file to explicitly mark
511which files are text and which are binary. If you want Git to guess, you can
512set the attribute `text=auto`.
513+
514With text files, Git will generally ensure that LF endings are used in the
515repository. The `core.autocrlf` and `core.eol` configuration variables specify
516what line-ending convention is followed when any text file is checked out. You
517can also use the `eol` attribute (e.g., `eol=crlf`) to override which files get
518what line-ending treatment.
519+
520For example, generally shell files must have LF endings and batch files must
521have CRLF endings, so the following might be appropriate in some projects:
522+
523----
524# By default, guess.
525* text=auto
526# Mark all C files as text.
527*.c text
528# Ensure all shell files have LF endings and all batch files have CRLF
529# endings in the working tree and both have LF in the repo.
530*.sh text eol=lf
531*.bat text eol=crlf
532# Mark all JPEG files as binary.
533*.jpg binary
534----
535+
536These settings help tools pick the right format for output such as patches and
537result in files being checked out in the appropriate line ending for the
538platform.
539
540GIT
541---
542Part of the linkgit:git[1] suite