Repository files navigation

Git Cola is a powerful Git GUI with a slick and intuitive user interface.

git clone https://github.com/git-cola/git-cola.git

• Screenshots

• Downloads

• Keyboard shortcuts

• HTML documentation

• Git Cola documentation

• Git DAG documentation

• Contributing guidelines

• Sphinx is used to generate the documentation.

• Git 2.2.0 or newer.

• Python 3.6 or newer.

• QtPy 2.0.0 or newer.

Git Cola uses QtPy, so you can choose between PyQt6, PyQt5 and PySide2 by settingtheQT_API environment variable topyqt6,pyqt5 orpyside2 as desired.qtpy defaults topyqt5 and falls back topyqt6 andpyside2 ifpyqt5is not installed.

Any of the following Python Qt libraries must be installed:

• PyQt5 / PyQt65.9 or newer is required. Qt 6.2 or newer is also supported via QtPy.

• PySide25.12.0 or newer.

Git Cola enables additional features when the followingPython modules are installed.

Send2Trashenables cross-platform "Send to Trash" functionality.(source)

notify2enables delivery of desktop notifications.(source)

pyobjcenables macOS-specific application themes on macOS.(source)

There are several ways to install Git Cola but you do not need to "install" Git Colain order to run it.

Git Cola is designed to run directly from its source tree. Installation is optional.

The recommended approach for running the latest Git Cola version is to install itsPyQt dependencies using your distribution's package manager and then run./bin/git-cola directly from source.

Git Cola works with either PyQt5 or PyQt6 because it uses theqtpy library for PyQt compatibility.

Users on newer Debian/Ubuntu version can install a single package to run from source.

sudo apt install python3-qtpy

If you are on an older version that does not havepython3-qtpy available then you caninstall the following packages directly.

sudo apt install python3-pyqt5 python3-pyqt5.qtopengl python3-pyqt5.qtwebengine python3-pyqt5.qtsvg

If you'd like to use Git Cola with the newer PyQt6 ecosystem then you can install thesepackages instead of PyQt5.

sudo apt install python3-pyqt6 python3-pyqt6.qtsvg python3-pyqt6.qtwebengine

At this point you should be able to launch./bin/git-cola from the source tree andthere is nothing more to do.

The further instructions below detail how to install Git Cola from PyPI or how toinstall it into a location separate from the source tree.

Linux is it! Your distro has probably already packagedgit-cola.If not, please file a bug against your distribution ;-)

Available in theAUR.

apt install git-cola

dnf install git-cola

emerge git-cola

zypper install git-cola

Available inSlackBuilds.org.

See here for theversions that are available in Ubuntu's repositories.

# Install from official binary packagespkg install -r FreeBSD devel/git-cola# Build from sourcecd /usr/ports/devel/git-cola && make clean install

IMPORTANT: never runpip install orgarden install outside of aPython virtualenv or as root!

IMPORTANT: if you are on Linux distributions where PyQt6 or PyQt5 are available fromyour package manager then it is highly recommended to install those dependencies usingyour system's package manager. See the section above for details.

One way to install the latest released version is to usevenv (virtualenv) andpip.This installsgit-cola from pypi.org.

python3 -m venv --system-site-packages env3./env3/bin/pip install git-cola./env3/bin/git-cola

Add theenv3/bin directory to yourPATH or symlink tobin/git-cola fromsomewhere in yourPATH such as~/.local/bin/git-cola, and you can launchGit Cola like any other built-ingit command:

git colagit dag

If you don't have PyQt installed then the easiest way to get it is to use a Pythonvirtualenv and install Git Cola into it in "editable" mode.

This install method lets you upgrade Git Cola by runninggit pull.

# Create a virtualenv called "env3" and activate it.python3 -m venv --system-site-packages env3# Install PyQt and (optional) extra packages to enable all features../env3/bin/pip install --editable '.[extras,pyqt6]'# Run Git Cola via the "git-cola" Git subcommand.source env3/bin/activategit cola

If you addenv3/bin (or symlink toenv3/bin/git-cola ) somewhere in your$PATH then you canrungit cola as if it were a builtingit command from outside of the virtualenv(e.g. after running "deactivate" or when opening a new shell).

Runninggarden -D prefix=$HOME/.local install will install Git Cola in your$HOME/.local directory ($HOME/.local/bin/git-cola,$HOME/.local/lib, etc).

This installation method assumes that theqtpy andPyQt* dependencies havebeen pre-installed.

The Garden recipe also supportsDESTDIR to support creating packages for Linux packagemanagers:

garden -D DESTDIR=/tmp/stage -D prefix=/usr/local install

If you do not havegarden available thenmake can be used instead.TheMakefile supports staged installs using the conventionalDESTDIR andprefixvariables.

make DESTDIR=/tmp/stage prefix=/usr/local install

For most end-users we recommend using either Homebrew or installing intoa Python virtualenv as described above.

You can install Git Cola from source using the same steps as above.

An easy way to install Git Cola is to useHomebrew .Use Homebrew to install the git-cola recipe:

brew install git-cola

If you install using Homebrew you can stop at this step.You don't need to clone the repo or anything.

If you have all of the dependencies installed, either viapip orbrew thenyou can build a shellgit-cola.app app bundle wrapper for use in/Applications.

If you'd like to build agit-cola.app bundle for/Applications run this command:

garden macos/app

You will need to periodically rebuild the app wrapper whenever Python is upgraded.

Updating macOS can often break Homebrew-managed software.

If you update macOS and Git Cola stops working then then you probably need to re-installGit Cola's dependencies.

Re-installing from scratch using the instructions below can get things back in shape.

brew updatebrew uninstall git-colabrew uninstall pyqtbrew uninstall pyqt@5brew autoremovebrew install git-cola

IMPORTANT If you have a 64-bit machine, install the 64-bit versions only.Do not mix 32-bit and 64-bit versions.

Download and install the following:

• Git for Windows

• Git Cola

Once these are installed you can run Git Cola from the Start menu.

See "Windows (Continued)" below for more details.

If you'd like to install Git Cola withwinget run the following command:

winget install git-cola.git-cola

As there is no dependency resolution yet you have to install Git as well with:

winget install Git.Git

Git Cola ships with an interactive rebase editor calledgit-cola-sequence-editor.git-cola-sequence-editor is used to reorder and choose commits when rebasing.Start an interactive rebase through the "Rebase" menu, or through thegit cola rebase sub-command to use thegit-cola-sequence-editor:

git cola rebase @{upstream}

git-cola-sequence-editor can be launched independently of git cola by tellinggit rebase to use it as its editor through theGIT_SEQUENCE_EDITORenvironment variable:

export GIT_SEQUENCE_EDITOR="$HOME/git-cola/bin/git-cola-sequence-editor"git rebase -i @{upstream}

Shell completion scripts are available for bash and zsh.Each script contains instructions on how to install and activate the completions.

• bash completion script

• zsh completion script

Thegit-cola command exposes various sub-commands that allow you to quicklylaunch tools that are available from within the git-cola interface.For example,git cola find launches the file finder,andgit cola grep launches the grep tool.

Seegit cola --help-commands for the full list of commands.

$ git cola --help-commandsusage: git-cola [-h]                {cola,am,archive,branch,browse,config,                 dag,diff,fetch,find,grep,merge,pull,push,                 rebase,remote,search,stash,tag,version}                ...valid commands:  {cola,am,archive,branch,browse,config,   dag,diff,fetch,find,grep,merge,pull,push,   rebase,remote,search,stash,tag,version}    cola                start git-cola    am                  apply patches using "git am"    archive             save an archive    branch              create a branch    browse              browse repository    config              edit configuration    dag                 start git-dag    diff                view diffs    fetch               fetch remotes    find                find files    grep                grep source    merge               merge branches    pull                pull remote branches    push                push remote branches    rebase              interactive rebase    remote              edit remotes    search              search commits    stash               stash and unstash changes    tag                 create tags    version             print the version

If you already have Git Cola's dependencies installed then you canstartcola as a Python module if you have the source code available.

python -m colapython -m cola dag

The following commands should be run during development:

# Run the unit tests$ garden test# Run tests and doc checks$ garden check# Run tests against multiple python interpreters using tox$ garden tox

The test suite can be found in thetest directory.

Commits and pull requests are automatically tested for code qualityusingGitHub Actions.

Auto-formatcola/i18n/*.po files before committing when updating translations:

$ garden po

When submitting patches, consult thecontributing guidelines.

Git Cola installs its modules into the default Python site-packages directory(e.g.lib/pythonX.Y/site-packages) using setuptools.

While end-users can usepip install git-cola to install Git Cola, distributionpackagers should use thegarden -D prefix=/usr install process. Git Cola's Gardenrecipe wrapspip install --prefix=<prefix> to provide a packaging-friendlygarden install target.

Earlier versions of Git Cola may have shipped withoutvcruntime140.dll and maynot run on machines that are missing this DLL.

To fix this, download theMicrosoft Visual C++ 2015 Redistributableand install it

Git Cola v4.0.0 and newer include this DLL and do not require this to be installedseparately.

In order to develop Git Cola on Windows you will need to installPython3 and pip. Install PyQt5 usingpip install PyQt5to make the PyQt5 bindings available to Python.

Once these are installed you can usepython.exe to rundirectly from the source tree. For example, from a Git Bash terminal:

/c/Python39/python.exe ./bin/git-cola

If you have multiple versions of Python installed, thecontrib/win32/colalauncher script might choose the newer version instead of the pythonthat has PyQt installed. In order to resolve this, you can set thecola.pythonlocation git configuration variable to tell cola where tofind python. For example:

git config --global cola.pythonlocation /c/Python39

Windows installers are built using

• Pynsist.

• NSIS is also needed.

To build the installer using Pynsist run:

garden pynsist -vv

This will generate an installer inbuild/nsis/.

You may need to configure your history browser if you are upgrading from anolder version of Git Cola on Windows.

gitk was originally the default history browser, butgitk cannot belaunched as-is on Windows becausegitk is a shell script.

If you are configured to usegitk, then change your configuration togo through Git'ssh.exe on Windows. Similarly, we must go throughpython.exe if we want to usegit-dag.

If you want to use gitk as your history browser open thePreferences screen and change the history browser command to:

"C:/Program Files/Git/bin/sh.exe" --login -i C:/Git/bin/gitk

git-dag became the default history browser on Windows inv2.3, so newusers do not need to configure anything.