GITFAQ(7)                 (08/17/2021)                  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 doesncqt 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 isncqt 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 doesncqt 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 doesncqt solve most push
              problems. A server or proxy that didncqt correctly
              support HTTP/1.1 and chunked transfer encoding wouldncqt
              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, itcqs best to
              leave it at the default unless you are sure you need a
              different value.

     Page 1                     Git 2.33.0           (printed 5/22/22)

     GITFAQ(7)                 (08/17/2021)                  GITFAQ(7)

          How do I configure a different editor?
              If you havencqt specified an editor specifically for Git,
              it will by default use the editor youcqve 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

     Page 2                     Git 2.33.0           (printed 5/22/22)

     GITFAQ(7)                 (08/17/2021)                  GITFAQ(7)

              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 Icqve 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 doesncqt 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
              m[blue]https://author@git.example.org/org1/project1.gitm[]
              and
              m[blue]https://committer@git.example.org/org2/project2.gitm[].
              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

     Page 3                     Git 2.33.0           (printed 5/22/22)

     GITFAQ(7)                 (08/17/2021)                  GITFAQ(7)

              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, itcqs necessary to create a key pair
              for each account. If youcqre 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 thatcqs 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
          Icqve 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 youcqll
              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.

     Page 4                     Git 2.33.0           (printed 5/22/22)

     GITFAQ(7)                 (08/17/2021)                  GITFAQ(7)

          Icqve made a change with a bug and itcqs 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 doesncqt provide a way to do this. The reason is that
              if Git needs to overwrite this file, such as during a
              checkout, it doesncqt 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.

              Itcqs tempting to try to use certain features of git
              update-index, namely the assume-unchanged and
              skip-worktree bits, but these doncqt work properly for
              this purpose and shouldncqt 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

     Page 5                     Git 2.33.0           (printed 5/22/22)

     GITFAQ(7)                 (08/17/2021)                  GITFAQ(7)

          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 theycqre merged again,
              because there is now a new common ancestor. Git doesncqt
              have to consider changes that occurred before the merge
              base, so you doncqt have to re-resolve any conflicts you
              resolved before.

              When you perform a squash merge, a merge commit isncqt
              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 woncqt 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, itcqs 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

     Page 6                     Git 2.33.0           (printed 5/22/22)

     GITFAQ(7)                 (08/17/2021)                  GITFAQ(7)

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

              Itcqs common to try to use pre-commit hooks (or, for
              commit messages, commit-msg hooks) to check these
              things, which is great if youcqre 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 doesncqt 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 itcqs better to push these kinds of checks to
              the server anyway.

     CROSS-PLATFORM ISSUES
          Icqm 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 cancqt 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,

     Page 7                     Git 2.33.0           (printed 5/22/22)

     GITFAQ(7)                 (08/17/2021)                  GITFAQ(7)

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

          Icqm 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
              platformcqs 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 doncqt wish to remove the
              carriage returns from your line endings.

          Why do I have a file thatcqs always modified?
              Internally, Git always stores file names as sequences of
              bytes and doesncqt perform any encoding or case folding.
              However, Windows and macOS by default both perform case
              folding on file names. As a result, itcqs 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.

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

     Page 8                     Git 2.33.0           (printed 5/22/22)

     GITFAQ(7)                 (08/17/2021)                  GITFAQ(7)

              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 .

          Whatcqs 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

     Page 9                     Git 2.33.0           (printed 5/22/22)

     GITFAQ(7)                 (08/17/2021)                  GITFAQ(7)

              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

     Page 10                    Git 2.33.0           (printed 5/22/22)