|
NAME | SYNOPSIS | DESCRIPTION | CONFIGURATION | CREDENTIALS | COMMON ISSUES | HOOKS | CROSS-PLATFORM ISSUES | GIT | COLOPHON |
GITFAQ(7) Git Manual GITFAQ(7)
gitfaq - Frequently asked questions about using Git
gitfaq
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.
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.
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).
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).
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.
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 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.
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. For example, the
following might be appropriate in some projects:
# By default, guess.
* text=auto
# Mark all C files as text.
*.c text
# 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.
Part of the git(1) suite
This page is part of the git (Git distributed version control system)
project. Information about the project can be found at
⟨http://git-scm.com/⟩. If you have a bug report for this manual page,
see ⟨http://git-scm.com/community⟩. This page was obtained from the
project's upstream Git repository ⟨https://github.com/git/git.git⟩ on
2020-08-13. (At that time, the date of the most recent commit that
was found in the repository was 2020-08-11.) If you discover any
rendering problems in this HTML version of the page, or you believe
there is a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
man-pages@man7.org
Git 2.28.0.202.g7814e8 08/12/2020 GITFAQ(7)
Pages that refer to this page: git(1)