Related articles
Git is the version control system (VCS) designed and developed by Linus Torvalds, the creator of the Linux kernel. Git is now used to maintainAUR packages, as well as many other projects, including sources for the Linux kernel.
Install thegit package. For the development version, install thegit-gitAUR package. Check the optional dependencies when using tools such asgit svn,git gui andgitk.
See alsogit GUI Clients.
LC_MESSAGESenvironment variable. SeeFS#28181 and theaspell article.In order to use Git you need to set at least a name and email:
$ git config --global user.name "John Doe"$ git config --global user.email "johndoe@example.com"
SeeGetting Started - First-Time Git Setup.
See#Tips and tricks for more settings.
A Git repository is contained in a.git directory, which holds the revision history and other metadata. The directory tracked by the repository, by default the parent directory, is called the working directory. Changes in the working tree need to be staged before they can be recorded (committed) to the repository. Git also lets you restore, previously committed, working tree files.
SeeGetting Started.
SeeGetting a Git Repository - Git Basics
SeeRecording Changes to the Repository - Git Basics
SeeViewing the Commit History - Git Basics
SeeUndoing Things - Git Basics
SeeWorking with Remotes - Git Basics
SeeBranching in a Nutshell - Git Branching
SeeBasic Branching and Merging - Git Branching
SeeBranch Management - Git Branching
SeeBranching Workflows - Git Branching
SeeRemote Branches - Git Branching
SeeDistributed Workflows - Distributed Git
SeeContributing to a Project - Distributed Git
SeeMaintaining a Project - Distributed Git
SeeRevision Selection - Git Tools
SeeInteractive Staging - Git Tools
SeeStashing and Cleaning - Git Tools
SeeSigning Your Work - Git Tools
SeeRewriting History - Git Tools
SeeReset Demystified - Git Tools
SeeAdvanced Merging - Git Tools
SeeDebugging with Git - Git Tools
SeeCredential Storage - Git Tools
Git reads its configuration from four INI-type configuration files:
/etc/gitconfig for system-wide defaults~/.gitconfig and~/.config/git/config (since 1.7.12) for user-specific configuration.git/config for repository-specific configurationThese files can be edited directly, but the usual method is to usegit config, as shown in the examples below.
List the currently set variables:
$ git config list {--local,--global,--system}Set the default editor fromvim tonano:
$ git config --global core.editor "nano -w"
Set the default push action:
$ git config --global push.default simple
Set a different tool forgit difftool (meld by default):
$ git config --global diff.tool vimdiff
Seegit-config(1) andGit Configuration for more information.
Sincev1.7.10 in 2012, Git is able to build a configuration file that is split into multiple configuration files using theinclude keyword inside thegitconfig file.
--local or--global flags. To enable it, use the--includes flag with thegit config get andgit config list commands.You may wish to avoid the hassle of authenticating interactively at every push to the Git server.
Git may fetch your credentials from anorg.freedesktop.secrets compatible keyring likeGNOME Keyring,KeePassXC orKDE Wallet. Therefore set up one compatible keyring and check if a keyring is registered to dbus using:
$ dbus-send --session --print-reply --dest=org.freedesktop.DBus / \ org.freedesktop.DBus.GetConnectionUnixProcessID \ string:org.freedesktop.secrets
then run
$ git config --global credential.helper /usr/lib/git-core/git-credential-libsecret
to set up git.
Git can read thenetrc file to access credentials. First, direct Git to the netrc helper script:
$ git config --global credential.helper /usr/share/git/credential/netrc/git-credential-netrc.perl
Then,create a.netrc file:
~/.netrc
machine git-hostlogin usernamepassword password
The credential helper also supportsgpg-encrypted files (~/.netrc.gpg) if you like to keep your secrets safe.
If you are running a multiplexed SSH connection as shown above, Git over SSH might be faster than HTTPS. Also, some servers (like the AUR) only allow pushing via SSH. For example, the following configuration will set Git over SSH for any repository hosted on the AUR.
~/.gitconfig
[url "ssh://aur@aur.archlinux.org/"]insteadOf = https://aur.archlinux.org/insteadOf = http://aur.archlinux.org/insteadOf = git://aur.archlinux.org/
In order to enable Bash completion, source/usr/share/git/completion/git-completion.bash in aBash startup file. Alternatively, installbash-completion.
The Git package comes with a prompt script. To enable it, source the/usr/share/git/completion/git-prompt.sh and set a custom prompt with the%s parameter:
PS1='[\u@\h \W$(__git_ps1 " (%s)")]\$ 'setopt PROMPT_SUBST ; PS1='[%n@%m %c$(__git_ps1 " (%s)")]\$ 'vcs_info function which can be used as an alternative. Seezshcontrib(1) § GATHERING INFORMATION FROM VERSION CONTROL SYSTEMS.Note that the command substitution must be escaped, seeBash/Prompt customization#Embedding commands for details. SeeCommand-line shell#Configuration files for persistent configuration.
When changing to a directory of a Git repository, the prompt will change to show the branch name. Extra details can be set to be shown by the prompt by setting the corresponding environment variable:
| Shell variable | Information |
|---|---|
| GIT_PS1_SHOWDIRTYSTATE | + for staged,* if unstaged. |
| GIT_PS1_SHOWSTASHSTATE | $ if something is stashed. |
| GIT_PS1_SHOWUNTRACKEDFILES | % if there are untracked files. |
| GIT_PS1_SHOWUPSTREAM | <,>,<> behind, ahead, or diverged from upstream. |
| GIT_PS1_STATESEPARATOR | separator between branch name and state symbols |
| GIT_PS1_DESCRIBE_STYLE | show commit relative to tag or branch, when detached HEAD |
| GIT_PS1_SHOWCOLORHINTS | display in color |
The full documentation for the environment variables is available in the comments of the script.
$(__git_ps1) returns((unknown)), then there is a.git folder in your current directory which does not contain any repository, and therefore Git does not recognize it. This can, for example, happen if you mistake Git's configuration file to be~/.git/config instead of~/.gitconfig.GIT_PS1_SHOWUNTRACKEDFILES option, which triggers a full directory tree scan every time to detect new files, causing noticeable performance impact. To disable this option locally for those repositories, you can use the commandgit config --local bash.showUntrackedFiles false.Alternatively, you can use one of git shell prompt customization packages fromAUR such asbash-git-promptAUR orgittifyAUR.
To get an idea of the amount of work done:
$ git diff --stat
git log with forking representation:
$ git log --graph --oneline --decorate
git log graph alias (i.e.git graph will show a decorated version):
$ git config --global alias.graph 'log --graph --oneline --decorate'
Reset to previous commit (very dangerous, erases all tracked files to the specified commit):
$ git reset --hard HEAD~
If a repository address gets changed, its remote location will need to be updated:
$ git remote set-url origin git@address:user/repo.git
Alternatively, edit.git/config with the new location.
Signed-off-by line append (a name-email signature is added to the commit which is required by some projects):
$ git commit -s
Signed-off-by automatically append to patches (when usinggit format-patchcommit):
$ git config --local format.signoff true
Commit specific parts of files that have changed. This is useful if there are a large number of changes made that would be best split into several commits:
$ git add -p
Git allows commits and tags to be signed usingGnuPG, seeSigning Your Work.
export GPG_TTY=$(tty) (alternatively use pinentry-tty) otherwise the signing step will fail if GPG is currently in a locked state (since it cannot prompt for pin).To configure Git to automatically sign commits:
$ git config --global commit.gpgSign true
Occasionally a maintainer will ask that work be done on a branch. These branches are often calleddevel ortesting. Begin by cloning the repository.
To enter another branch beside master (git clone only shows master branch but others still exist,git branch -a to show):
$ git checkout -bbranch origin/branch
Now edit normally; however to keep the repository tree in sync be sure to use both:
$ git pull --all$ git push --all
If you want to send patches directly to a mailing list, you have to install the following packages:perl-authen-sasl andperl-io-socket-ssl.
Make sure you have configured your username and e-mail address, see#Configuration.
Configure your e-mail settings:
$ git config --global sendemail.smtpserversmtp.example.com$ git config --global sendemail.smtpserverport465$ git config --global sendemail.smtpencryptionssl$ git config --global sendemail.smtpuserfoobar@example.com
Now you should be able to send the patch to the mailing list (see alsoOpenEmbedded: Sending the Patches via Email andgit-send-email.io):
$ git addfilename$ git commit -s$ git send-email --to=pacman-contrib@lists.archlinux.org --confirm=always -M -1
When working with a large remote repository, a significant amount of data has to be fetched. The following examples use the Linux kernel to illustrate how to work with such codebases.
The easiest solution is to get the entire repository:
$ git clonegit://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
git clone cannot be resumed if interrupted.You can update your repository bygit pull.
To limit your local repository to a smaller subset of the origin, say after v4.14 to bisect a bug, use a shallow clone:
$ git clone --shallow-exclude v4.13git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git
You will get v4.14 and later, but not v4.13 and older.
If you only want the latest snapshot, ignoring all history (If a tarball is available and it suffices, choose that; downloading from a git repository needs more bandwidth.), you can get it with:
$ git clone --depth 1git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git
You can later obtain older commits, as the two following examples show:
$ git fetch --tags --shallow-exclude v4.1$ git fetch --tags --shallow-since 2016-01-01
--tags, tags will not be fetched.Scalar, formerlyVirtual File System for Git (VFS for Git), allows to access git repositories without a local instance.
Seescalar(1).
Your local repository tracks, in the above example, only the mainline kernel, i.e. in which thelatest development is done. Suppose you want the latestLTS, for example the up-to-date 4.14 branch. You can get it by:
$ git remote set-branches --add origin linux-4.14.y$ git fetch --shallow-exclude v4.14$ git branch --track linux-4.14.y origin/linux-4.14.y
The last line is not mandatory, but probably wanted.(To know the name of the branch you want, there is no general rule. You can guess one by seeing the "ref" link in the gitweb interface.)
For the snapshot of linux-4.14.y, do
$ git checkout linux-4.14.y
Or to extract it in another directory,
$ mkdir /path/to/src-4.14; cd /path/to/src-4.14$ git clone --no-local --depth 1 -b linux-4.14.y ../linux-stable
As usual, dogit pull to update your snapshot.
Occasionally, software may keep plain-text passwords in configuration files, as opposed to hooking into a keyring. In these cases, git clean-filters may be handy to avoid accidentally committing confidential information. E. g., the following file assigns a filter to the file “some-dotfile”:
.gitattributes
some-dotfile filter=remove-pass
Whenever the file “some-dotfile” is checked into git, git will invoke the filter “remove-pass” on the file before checking it in. The filter must be defined in the git-configuration file, e. g.:
.git/config
[filter "remove-pass"]clean = "sed -e 's/^password=.*/#password=TODO/'"
Thegit help documentation is also available in HTML form by installinggit-htmldocsAUR. After installing, the HTML docs can be accessed by passing the-w flag. For example:
$ git help -w merge
The HTML documentation can be loaded by default by setting agit config option:
$ git config --global help.format html