NAME
gitfaq - Frequently asked questions about using GitSYNOPSIS
gitfaqDESCRIPTION
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:
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.
export VISUAL=nano
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:
How do I change the password or token I’ve saved in my credential
manager?
$ git config credential.helper \ '!f() { echo username=author; echo "password=$GIT_TOKEN"; };f'
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):
How do I use multiple accounts with the same hosting provider using HTTP?
$ echo url=https://[email protected] | git credential reject
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://[email protected]/org1/project1.git and
https://[email protected]/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://[email protected]/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., [email protected]). 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:
Then, you can adjust your push URL to use git@example_author or
git@example_committer instead of [email protected] (e.g., git
remote set-url git@example_author:org1/project1.git).
# 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
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).
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:
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.
*.c working-tree-encoding=UTF-16LE-BOM
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 following
entry 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:
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:
What’s the recommended way to store files in Git?
$ git rm --cached AFile.txt $ git commit -m 'Remove files conflicting in case' $ git checkout .
$ git add --renormalize .
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. For example, the following might be
appropriate in some projects:
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.
# By default, guess. * text=auto # Mark all C files as text. *.c text # Mark all JPEG files as binary. *.jpg binary
GIT
Part of the git(1) suite02/28/2023 | Git 2.39.2 |