Go to main content

man pages section 7: Standards, Environments, Macros, Character Sets, and Miscellany

Exit Print View

Updated: Wednesday, February 9, 2022
 
 

gitfaq (7)

Name

gitfaq - Frequently asked questions about using Git

Synopsis

gitfaq

Description

GITFAQ(7)                         Git Manual                         GITFAQ(7)



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

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
           recursive 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 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
       Part of the git(1) suite



Git 2.31.1                        03/26/2021                         GITFAQ(7)