Provided by: git-man_2.51.0-1ubuntu1_all 
NAME
gitfaq - Frequently asked questions about using Git
SYNOPSIS
gitfaq
DESCRIPTION
The examples in this FAQ assume a standard POSIX shell, like bash or dash, and a user, A U Thor, who has
the account author on the hosting provider git.example.org.
CONFIGURATION
What should I put in user.name?
You should put your personal name, generally a form using a given name and family name. For example,
the current maintainer of Git uses "Junio C Hamano". This will be the name portion that is stored in
every commit you make.
This configuration doesn’t have any effect on authenticating to remote services; for that, see
credential.username in git-config(1).
What does http.postBuffer really do?
This option changes the size of the buffer that Git uses when pushing data to a remote over HTTP or
HTTPS. If the data is larger than this size, libcurl, which handles the HTTP support for Git, will
use chunked transfer encoding since it isn’t known ahead of time what the size of the pushed data
will be.
Leaving this value at the default size is fine unless you know that either the remote server or a
proxy in the middle doesn’t support HTTP/1.1 (which introduced the chunked transfer encoding) or is
known to be broken with chunked data. This is often (erroneously) suggested as a solution for generic
push problems, but since almost every server and proxy supports at least HTTP/1.1, raising this value
usually doesn’t solve most push problems. A server or proxy that didn’t correctly support HTTP/1.1
and chunked transfer encoding wouldn’t be that useful on the Internet today, since it would break
lots of traffic.
Note that increasing this value will increase the memory used on every relevant push that Git does
over HTTP or HTTPS, since the entire buffer is allocated regardless of whether or not it is all used.
Thus, it’s best to leave it at the default unless you are sure you need a different value.
How do I configure a different editor?
If you haven’t specified an editor specifically for Git, it will by default use the editor you’ve
configured using the VISUAL or EDITOR environment variables, or if neither is specified, the system
default (which is usually vi). Since some people find vi difficult to use or prefer a different
editor, it may be desirable to change the editor used.
If you want to configure a general editor for most programs which need one, you can edit your shell
configuration (e.g., ~/.bashrc or ~/.zshenv) to contain a line setting the EDITOR or VISUAL
environment variable to an appropriate value. For example, if you prefer the editor nano, then you
could write the following:
export VISUAL=nano
If you want to configure an editor specifically for Git, you can either set the core.editor
configuration value or the GIT_EDITOR environment variable. You can see git-var(1) for details on the
order in which these options are consulted.
Note that in all cases, the editor value will be passed to the shell, so any arguments containing
spaces should be appropriately quoted. Additionally, if your editor normally detaches from the
terminal when invoked, you should specify it with an argument that makes it not do that, or else Git
will not see any changes. An example of a configuration addressing both of these issues on Windows
would be the configuration "C:\Program Files\Vim\gvim.exe" --nofork, which quotes the filename with
spaces and specifies the --nofork option to avoid backgrounding the process.
CREDENTIALS
How do I specify my credentials when pushing over HTTP?
The easiest way to do this is to use a credential helper via the credential.helper configuration.
Most systems provide a standard choice to integrate with the system credential manager. For example,
Git for Windows provides the wincred credential manager, macOS has the osxkeychain credential
manager, and Unix systems with a standard desktop environment can use the libsecret credential
manager. All of these store credentials in an encrypted store to keep your passwords or tokens
secure.
In addition, you can use the store credential manager which stores in a file in your home directory,
or the cache credential manager, which does not permanently store your credentials, but does prevent
you from being prompted for them for a certain period of time.
You can also just enter your password when prompted. While it is possible to place the password
(which must be percent-encoded) in the URL, this is not particularly secure and can lead to
accidental exposure of credentials, so it is not recommended.
How do I read a password or token from an environment variable?
The credential.helper configuration option can also take an arbitrary shell command that produces the
credential protocol on standard output. This is useful when passing credentials into a container, for
example.
Such a shell command can be specified by starting the option value with an exclamation point. If your
password or token were stored in the GIT_TOKEN, you could run the following command to set your
credential helper:
$ git config credential.helper \
'!f() { echo username=author; echo "password=$GIT_TOKEN"; };f'
How do I change the password or token I’ve saved in my credential manager?
Usually, if the password or token is invalid, Git will erase it and prompt for a new one. However,
there are times when this doesn’t always happen. To change the password or token, you can erase the
existing credentials and then Git will prompt for new ones. To erase credentials, use a syntax like
the following (substituting your username and the hostname):
$ echo url=https://author@git.example.org | git credential reject
How do I use multiple accounts with the same hosting provider using HTTP?
Usually the easiest way to distinguish between these accounts is to use the username in the URL. For
example, if you have the accounts author and committer on git.example.org, you can use the URLs
https://author@git.example.org/org1/project1.git and
https://committer@git.example.org/org2/project2.git. This way, when you use a credential helper, it
will automatically try to look up the correct credentials for your account. If you already have a
remote set up, you can change the URL with something like git remote set-url origin
https://author@git.example.org/org1/project1.git (see git-remote(1) for details).
How do I use multiple accounts with the same hosting provider using SSH?
With most hosting providers that support SSH, a single key pair uniquely identifies a user.
Therefore, to use multiple accounts, it’s necessary to create a key pair for each account. If you’re
using a reasonably modern OpenSSH version, you can create a new key pair with something like
ssh-keygen -t ed25519 -f ~/.ssh/id_committer. You can then register the public key (in this case,
~/.ssh/id_committer.pub; note the .pub) with the hosting provider.
Most hosting providers use a single SSH account for pushing; that is, all users push to the git
account (e.g., git@git.example.org). If that’s the case for your provider, you can set up multiple
aliases in SSH to make it clear which key pair to use. For example, you could write something like
the following in ~/.ssh/config, substituting the proper private key file:
# This is the account for author on git.example.org.
Host example_author
HostName git.example.org
User git
# This is the key pair registered for author with git.example.org.
IdentityFile ~/.ssh/id_author
IdentitiesOnly yes
# This is the account for committer on git.example.org.
Host example_committer
HostName git.example.org
User git
# This is the key pair registered for committer with git.example.org.
IdentityFile ~/.ssh/id_committer
IdentitiesOnly yes
Then, you can adjust your push URL to use git@example_author or git@example_committer instead of
git@example.org (e.g., git remote set-url git@example_author:org1/project1.git).
TRANSFERS
How do I sync a working tree across systems?
First, decide whether you want to do this at all. Git works best when you push or pull your work
using the typical git push and git fetch commands and isn’t designed to share a working tree across
systems. This is potentially risky and in some cases can cause repository corruption or data loss.
Usually, doing so will cause git status to need to re-read every file in the working tree.
Additionally, Git’s security model does not permit sharing a working tree across untrusted users, so
it is only safe to sync a working tree if it will only be used by a single user across all machines.
It is important not to use a cloud syncing service to sync any portion of a Git repository, since
this can cause corruption, such as missing objects, changed or added files, broken refs, and a wide
variety of other problems. These services tend to sync file by file on a continuous basis and don’t
understand the structure of a Git repository. This is especially bad if they sync the repository in
the middle of it being updated, since that is very likely to cause incomplete or partial updates and
therefore data loss.
An example of the kind of corruption that can occur is conflicts over the state of refs, such that
both sides end up with different commits on a branch that the other doesn’t have. This can result in
important objects becoming unreferenced and possibly pruned by git gc, causing data loss.
Therefore, it’s better to push your work to either the other system or a central server using the
normal push and pull mechanism. However, this doesn’t always preserve important data, like stashes,
so some people prefer to share a working tree across systems.
If you do this, the recommended approach is to use rsync -a --delete-after (ideally with an encrypted
connection such as with ssh) on the root of repository. You should ensure several things when you do
this:
• If you have additional worktrees or a separate Git directory, they must be synced at the same
time as the main working tree and repository.
• You are comfortable with the destination directory being an exact copy of the source directory,
deleting any data that is already there.
• The repository (including all worktrees and the Git directory) is in a quiescent state for the
duration of the transfer (that is, no operations of any sort are taking place on it, including
background operations like git gc and operations invoked by your editor).
Be aware that even with these recommendations, syncing in this way has some risk since it
bypasses Git’s normal integrity checking for repositories, so having backups is advised. You may
also wish to do a git fsck to verify the integrity of your data on the destination system after
syncing.
COMMON ISSUES
I’ve made a mistake in the last commit. How do I change it?
You can make the appropriate change to your working tree, run git add <file> or git rm <file>, as
appropriate, to stage it, and then git commit --amend. Your change will be included in the commit,
and you’ll be prompted to edit the commit message again; if you wish to use the original message
verbatim, you can use the --no-edit option to git commit in addition, or just save and quit when your
editor opens.
I’ve made a change with a bug and it’s been included in the main branch. How should I undo it?
The usual way to deal with this is to use git revert. This preserves the history that the original
change was made and was a valuable contribution, but also introduces a new commit that undoes those
changes because the original had a problem. The commit message of the revert indicates the commit
which was reverted and is usually edited to include an explanation as to why the revert was made.
How do I ignore changes to a tracked file?
Git doesn’t provide a way to do this. The reason is that if Git needs to overwrite this file, such as
during a checkout, it doesn’t know whether the changes to the file are precious and should be kept,
or whether they are irrelevant and can safely be destroyed. Therefore, it has to take the safe route
and always preserve them.
It’s tempting to try to use certain features of git update-index, namely the assume-unchanged and
skip-worktree bits, but these don’t work properly for this purpose and shouldn’t be used this way.
If your goal is to modify a configuration file, it can often be helpful to have a file checked into
the repository which is a template or set of defaults which can then be copied alongside and modified
as appropriate. This second, modified file is usually ignored to prevent accidentally committing it.
I asked Git to ignore various files, yet they are still tracked
A gitignore file ensures that certain file(s) which are not tracked by Git remain untracked. However,
sometimes particular file(s) may have been tracked before adding them into the .gitignore, hence they
still remain tracked. To untrack and ignore files/patterns, use git rm --cached <file/pattern> and
add a pattern to .gitignore that matches the <file>. See gitignore(5) for details.
How do I know if I want to do a fetch or a pull?
A fetch stores a copy of the latest changes from the remote repository, without modifying the working
tree or current branch. You can then at your leisure inspect, merge, rebase on top of, or ignore the
upstream changes. A pull consists of a fetch followed immediately by either a merge or rebase. See
git-pull(1).
Can I use a proxy with Git?
Yes, Git supports the use of proxies. Git honors the standard http_proxy, https_proxy, and no_proxy
environment variables commonly used on Unix, and it also can be configured with http.proxy and
similar options for HTTPS (see git-config(1)). The http.proxy and related options can be customized
on a per-URL pattern basis. In addition, Git can in theory function normally with transparent proxies
that exist on the network.
For SSH, Git can support a proxy using OpenSSH’s ProxyCommand. Commonly used tools include netcat and
socat. However, they must be configured not to exit when seeing EOF on standard input, which usually
means that netcat will require -q and socat will require a timeout with something like -t 10. This is
required because the way the Git SSH server knows that no more requests will be made is an EOF on
standard input, but when that happens, the server may not have yet processed the final request, so
dropping the connection at that point would interrupt that request.
An example configuration entry in ~/.ssh/config with an HTTP proxy might look like this:
Host git.example.org
User git
ProxyCommand socat -t 10 - PROXY:proxy.example.org:%h:%p,proxyport=8080
Note that in all cases, for Git to work properly, the proxy must be completely transparent. The proxy
cannot modify, tamper with, or buffer the connection in any way, or Git will almost certainly fail to
work. Note that many proxies, including many TLS middleboxes, Windows antivirus and firewall programs
other than Windows Defender and Windows Firewall, and filtering proxies fail to meet this standard,
and as a result end up breaking Git. Because of the many reports of problems and their poor security
history, we recommend against the use of these classes of software and devices.
MERGING AND REBASING
What kinds of problems can occur when merging long-lived branches with squash merges?
In general, there are a variety of problems that can occur when using squash merges to merge two
branches multiple times. These can include seeing extra commits in git log output, with a GUI, or
when using the ... notation to express a range, as well as the possibility of needing to re-resolve
conflicts again and again.
When Git does a normal merge between two branches, it considers exactly three points: the two
branches and a third commit, called the merge base, which is usually the common ancestor of the
commits. The result of the merge is the sum of the changes between the merge base and each head. When
you merge two branches with a regular merge commit, this results in a new commit which will end up as
a merge base when they’re merged again, because there is now a new common ancestor. Git doesn’t have
to consider changes that occurred before the merge base, so you don’t have to re-resolve any
conflicts you resolved before.
When you perform a squash merge, a merge commit isn’t created; instead, the changes from one side are
applied as a regular commit to the other side. This means that the merge base for these branches
won’t have changed, and so when Git goes to perform its next merge, it considers all of the changes
that it considered the last time plus the new changes. That means any conflicts may need to be
re-resolved. Similarly, anything using the ... notation in git diff, git log, or a GUI will result in
showing all of the changes since the original merge base.
As a consequence, if you want to merge two long-lived branches repeatedly, it’s best to always use a
regular merge commit.
If I make a change on two branches but revert it on one, why does the merge of those branches include the
change?
By default, when Git does a merge, it uses a strategy called the ort strategy, which does a fancy
three-way merge. In such a case, when Git performs the merge, it considers exactly three points: the
two heads and a third point, called the merge base, which is usually the common ancestor of those
commits. Git does not consider the history or the individual commits that have happened on those
branches at all.
As a result, if both sides have a change and one side has reverted that change, the result is to
include the change. This is because the code has changed on one side and there is no net change on
the other, and in this scenario, Git adopts the change.
If this is a problem for you, you can do a rebase instead, rebasing the branch with the revert onto
the other branch. A rebase in this scenario will revert the change, because a rebase applies each
individual commit, including the revert. Note that rebases rewrite history, so you should avoid
rebasing published branches unless you’re sure you’re comfortable with that. See the NOTES section in
git-rebase(1) for more details.
HOOKS
How do I use hooks to prevent users from making certain changes?
The only safe place to make these changes is on the remote repository (i.e., the Git server), usually
in the pre-receive hook or in a continuous integration (CI) system. These are the locations in which
policy can be enforced effectively.
It’s common to try to use pre-commit hooks (or, for commit messages, commit-msg hooks) to check these
things, which is great if you’re working as a solo developer and want the tooling to help you.
However, using hooks on a developer machine is not effective as a policy control because a user can
bypass these hooks with --no-verify without being noticed (among various other ways). Git assumes
that the user is in control of their local repositories and doesn’t try to prevent this or tattle on
the user.
In addition, some advanced users find pre-commit hooks to be an impediment to workflows that use
temporary commits to stage work in progress or that create fixup commits, so it’s better to push
these kinds of checks to the server anyway.
CROSS-PLATFORM ISSUES
I’m on Windows and my text files are detected as binary.
Git works best when you store text files as UTF-8. Many programs on Windows support UTF-8, but some
do not and only use the little-endian UTF-16 format, which Git detects as binary. If you can’t use
UTF-8 with your programs, you can specify a working tree encoding that indicates which encoding your
files should be checked out with, while still storing these files as UTF-8 in the repository. This
allows tools like git-diff(1) to work as expected, while still allowing your tools to work.
To do so, you can specify a gitattributes(5) pattern with the working-tree-encoding attribute. For
example, the following pattern sets all C files to use UTF-16LE-BOM, which is a common encoding on
Windows:
*.c working-tree-encoding=UTF-16LE-BOM
You will need to run git add --renormalize to have this take effect. Note that if you are making
these changes on a project that is used across platforms, you’ll probably want to make it in a
per-user configuration file or in the one in $GIT_DIR/info/attributes, since making it in a
.gitattributes file in the repository will apply to all users of the repository.
See the following entry for information about normalizing line endings as well, and see
gitattributes(5) for more information about attribute files.
I’m on Windows and git diff shows my files as having a ^M at the end.
By default, Git expects files to be stored with Unix line endings. As such, the carriage return (^M)
that is part of a Windows line ending is shown because it is considered to be trailing whitespace.
Git defaults to showing trailing whitespace only on new lines, not existing ones.
You can store the files in the repository with Unix line endings and convert them automatically to
your platform’s line endings. To do that, set the configuration option core.eol to native and see the
question on recommended storage settings for information about how to configure files as text or
binary.
You can also control this behavior with the core.whitespace setting if you don’t wish to remove the
carriage returns from your line endings.
Why do I have a file that’s always modified?
Internally, Git always stores file names as sequences of bytes and doesn’t perform any encoding or
case folding. However, Windows and macOS by default both perform case folding on file names. As a
result, it’s possible to end up with multiple files or directories whose names differ only in case.
Git can handle this just fine, but the file system can store only one of these files, so when Git
reads the other file to see its contents, it looks modified.
It’s best to remove one of the files such that you only have one file. You can do this with commands
like the following (assuming two files AFile.txt and afile.txt) on an otherwise clean working tree:
$ git rm --cached AFile.txt
$ git commit -m 'Remove files conflicting in case'
$ git checkout .
This avoids touching the disk, but removes the additional file. Your project may prefer to adopt a
naming convention, such as all-lowercase names, to avoid this problem from occurring again; such a
convention can be checked using a pre-receive hook or as part of a continuous integration (CI)
system.
It is also possible for perpetually modified files to occur on any platform if a smudge or clean
filter is in use on your system but a file was previously committed without running the smudge or
clean filter. To fix this, run the following on an otherwise clean working tree:
$ git add --renormalize .
What’s the recommended way to store files in Git?
While Git can store and handle any file of any type, there are some settings that work better than
others. In general, we recommend that text files be stored in UTF-8 without a byte-order mark (BOM)
with LF (Unix-style) endings. We also recommend the use of UTF-8 (again, without BOM) in commit
messages. These are the settings that work best across platforms and with tools such as git diff and
git merge.
Additionally, if you have a choice between storage formats that are text based or non-text based, we
recommend storing files in the text format and, if necessary, transforming them into the other
format. For example, a text-based SQL dump with one record per line will work much better for diffing
and merging than an actual database file. Similarly, text-based formats such as Markdown and AsciiDoc
will work better than binary formats such as Microsoft Word and PDF.
Similarly, storing binary dependencies (e.g., shared libraries or JAR files) or build products in the
repository is generally not recommended. Dependencies and build products are best stored on an
artifact or package server with only references, URLs, and hashes stored in the repository.
We also recommend setting a gitattributes(5) file to explicitly mark which files are text and which
are binary. If you want Git to guess, you can set the attribute text=auto.
With text files, Git will generally ensure that LF endings are used in the repository. The
core.autocrlf and core.eol configuration variables specify what line-ending convention is followed
when any text file is checked out. You can also use the eol attribute (e.g., eol=crlf) to override
which files get what line-ending treatment.
For example, generally shell files must have LF endings and batch files must have CRLF endings, so
the following might be appropriate in some projects:
# By default, guess.
* text=auto
# Mark all C files as text.
*.c text
# Ensure all shell files have LF endings and all batch files have CRLF
# endings in the working tree and both have LF in the repo.
*.sh text eol=lf
*.bat text eol=crlf
# Mark all JPEG files as binary.
*.jpg binary
These settings help tools pick the right format for output such as patches and result in files being
checked out in the appropriate line ending for the platform.
GIT
Part of the git(1) suite
Git 2.51.0 08/28/2025 GITFAQ(7)