Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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.30.1			  02/08/2021			     GITFAQ(7)

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

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=gitfaq&sektion=7&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help