gitfaq(7) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | CONFIGURATION | CREDENTIALS | COMMON ISSUES | MERGING AND REBASING | HOOKS | CROSS-PLATFORM ISSUES | GIT | COLOPHON

GITFAQ(7)                      Git Manual                      GITFAQ(7)

NAME         top

       gitfaq - Frequently asked questions about using Git

SYNOPSIS         top

       gitfaq

DESCRIPTION         top

       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         top

       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         top

       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).

COMMON ISSUES         top

       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         top

       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         top

       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         top

       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.

       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.
           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.

GIT         top

       Part of the git(1) suite

COLOPHON         top

       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 2023-12-22.  (At that time,
       the date of the most recent commit that was found in the
       repository was 2023-12-20.)  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.43.0.174.g055bb6         2023-12-20                      GITFAQ(7)

Pages that refer to this page: git(1)