1 # git-cola: The highly caffeinated Git GUI
3 Git Cola is a powerful Git GUI with a slick and intuitive user interface.
5 git clone https://github.com/git-cola/git-cola.git
7 [![License](https://img.shields.io/:license-GPL-green.svg)](LICENSE)
8 [![Build status](https://github.com/git-cola/git-cola/actions/workflows/ci.yml/badge.svg?event=push)](https://github.com/git-cola/git-cola/actions/workflows/main.yml)
9 [![OpenSSF Best Practices](https://bestpractices.coreinfrastructure.org/projects/251/badge)](https://bestpractices.coreinfrastructure.org/projects/251)
10 [![pre-commit.ci](https://results.pre-commit.ci/badge/github/git-cola/git-cola/main.svg)](https://results.pre-commit.ci/latest/github/git-cola/git-cola/main)
12 * [Screenshots](https://git-cola.github.io/screenshots.html)
14 * [Downloads](https://git-cola.github.io/downloads.html)
19 * [Keyboard shortcuts](https://git-cola.github.io/share/doc/git-cola/hotkeys.html)
21 * [HTML documentation](https://git-cola.readthedocs.io/en/latest/)
23 * [Git Cola documentation](docs/git-cola.rst)
25 * [Git DAG documentation](docs/git-dag.rst)
27 * [Contributing guidelines](CONTRIBUTING.md)
34 * [Sphinx](http://sphinx-doc.org/) is used to generate the documentation.
38 * [Git](https://git-scm.com/) 2.2.0 or newer.
40 * [Python](https://python.org/) 3.6 or newer.
42 * [QtPy](https://github.com/spyder-ide/qtpy) 2.0.0 or newer.
44 Git Cola uses QtPy, so you can choose between PyQt6, PyQt5 and PySide2 by setting
45 the `QT_API` environment variable to `pyqt6`, `pyqt5` or `pyside2` as desired.
46 `qtpy` defaults to `pyqt5` and falls back to `pyqt6` and `pyside2` if `pyqt5`
49 Any of the following Python Qt libraries must be installed:
51 * [PyQt5 / PyQt6](https://www.riverbankcomputing.com/software/pyqt/download5)
52 5.9 or newer is required. Qt 6.2 or newer is also supported via QtPy.
54 * [PySide2](https://github.com/PySide/PySide)
60 Git Cola enables additional features when the following
61 Python modules are installed.
63 [Send2Trash](https://pypi.org/project/Send2Trash/)
64 enables cross-platform "Send to Trash" functionality.
65 ([source](https://github.com/hsoft/send2trash))
67 [notify_py](https://pypi.org/project/notify_py/)
68 enables delivery of desktop notifications.
69 ([source](https://github.com/ms7m/notify-py))
71 [pyobjc](https://pypi.org/project/pyobjc/)
72 enables macOS-specific application themes on macOS.
73 ([source](https://github.com/ronaldoussoren/pyobjc))
78 There are several ways to install Git Cola but you do not need to "install" Git Cola
81 Git Cola is designed to run directly from its source tree. Installation is optional.
86 The recommended approach for running the latest Git Cola version is to install its
87 PyQt dependencies using your distribution's package manager and then run
88 `./bin/git-cola` directly from source.
91 ## Installing PyQt dependencies on Debian / Ubuntu systems
93 Git Cola works with either PyQt5 or PyQt6 because it uses the
94 [qtpy](https://github.com/spyder-ide/qtpy) library for PyQt compatibility.
98 Users on newer Debian/Ubuntu version can install a single package to run from source.
101 sudo apt install python3-qtpy
104 If you are on an older version that does not have `python3-qtpy` available then you can
105 install the following packages directly.
108 sudo apt install python3-pyqt5 python3-pyqt5.qtopengl python3-pyqt5.qtwebengine python3-pyqt5.qtsvg
113 If you'd like to use Git Cola with the newer PyQt6 ecosystem then you can install these
114 packages instead of PyQt5.
117 sudo apt install python3-pyqt6 python3-pyqt6.qtsvg python3-pyqt6.qtwebengine
120 At this point you should be able to launch `./bin/git-cola` from the source tree and
121 there is nothing more to do.
123 The further instructions below detail how to install Git Cola from PyPI or how to
124 install it into a location separate from the source tree.
129 Linux is it! Your distro has probably already packaged `git-cola`.
130 If not, please file a bug against your distribution ;-)
134 Available in the [AUR](https://aur.archlinux.org/packages/git-cola/).
150 zypper install git-cola
154 Available in [SlackBuilds.org](http://slackbuilds.org/result/?search=git-cola).
158 [See here](https://packages.ubuntu.com/search?keywords=git-cola) for the
159 versions that are available in Ubuntu's repositories.
163 # Install from official binary packages
164 pkg install -r FreeBSD devel/git-cola
167 cd /usr/ports/devel/git-cola && make clean install
169 ## Install into a Python Virtualenv from PyPI using pip
171 **IMPORTANT**: never run `pip install` or `garden install` outside of a
172 Python virtualenv or as root!
174 **IMPORTANT**: if you are on Linux distributions where PyQt6 or PyQt5 are available from
175 your package manager then it is highly recommended to install those dependencies using
176 your system's package manager. See the section above for details.
178 One way to install the latest released version is to use `venv` (virtualenv) and `pip`.
179 This installs [git-cola from pypi.org](https://pypi.org/project/git-cola/).
181 python3 -m venv --system-site-packages env3
182 ./env3/bin/pip install git-cola
185 Add the `env3/bin` directory to your `PATH` or symlink to `bin/git-cola` from
186 somewhere in your `PATH` such as `~/.local/bin/git-cola`, and you can launch
187 Git Cola like any other built-in `git` command:
193 ## Install into a Python Virtualenv from Source
195 If you don't have PyQt installed then the easiest way to get it is to use a Python
196 virtualenv and install Git Cola into it in "editable" mode.
198 This install method lets you upgrade Git Cola by running `git pull`.
200 # Create a virtualenv called "env3" and activate it.
201 python3 -m venv --system-site-packages env3
203 # Install PyQt and (optional) extra packages to enable all features.
204 ./env3/bin/pip install --editable '.[extras,pyqt6]'
206 # Run Git Cola via the "git-cola" Git subcommand.
207 source env3/bin/activate
210 If you add `env3/bin` (or symlink to `env3/bin/git-cola` ) somewhere in your `$PATH` then you can
211 run `git cola` as if it were a builtin `git` command from outside of the virtualenv
212 (e.g. after running "deactivate" or when opening a new shell).
215 ## Standalone Installation from Source
217 Running `garden -D prefix=$HOME/.local install` will install Git Cola in your
218 `$HOME/.local` directory (`$HOME/.local/bin/git-cola`, `$HOME/.local/lib`, etc).
220 This installation method assumes that the `qtpy` and `PyQt*` dependencies have
223 The Garden recipe also supports `DESTDIR` to support creating packages for Linux package
226 garden -D DESTDIR=/tmp/stage -D prefix=/usr/local install
228 If you do not have `garden` available then `make` can be used instead.
229 The `Makefile` supports staged installs using the conventional
230 [DESTDIR](https://www.gnu.org/software/make/manual/html_node/DESTDIR.html) and
231 [prefix](https://www.gnu.org/software/make/manual/html_node/Directory-Variables.html)
234 make DESTDIR=/tmp/stage prefix=/usr/local install
239 For most end-users we recommend using either Homebrew or installing into
240 a Python virtualenv as described above.
242 You can install Git Cola from source using the same steps as above.
246 An easy way to install Git Cola is to use [Homebrew](https://brew.sh/) .
247 Use Homebrew to install the git-cola recipe:
249 brew install git-cola
251 If you install using Homebrew you can stop at this step.
252 You don't need to clone the repo or anything.
256 If you have all of the dependencies installed, either via `pip` or `brew` then
257 you can build a shell `git-cola.app` app bundle wrapper for use in `/Applications`.
259 If you'd like to build a `git-cola.app` bundle for `/Applications` run this command:
263 You will need to periodically rebuild the app wrapper whenever Python is upgraded.
265 ### Updating macOS and Homebrew
267 Updating macOS can often break Homebrew-managed software.
269 If you update macOS and Git Cola stops working then then you probably need to re-install
270 Git Cola's dependencies.
272 Re-installing from scratch using the instructions below can get things back in shape.
276 brew uninstall git-cola
278 brew uninstall pyqt@5
281 brew install git-cola
286 IMPORTANT If you have a 64-bit machine, install the 64-bit versions only.
287 Do not mix 32-bit and 64-bit versions.
289 Download and install the following:
291 * [Git for Windows](https://git-for-windows.github.io/)
293 * [Git Cola](https://github.com/git-cola/git-cola/releases)
295 Once these are installed you can run Git Cola from the Start menu.
297 See "Windows (Continued)" below for more details.
299 If you'd like to install Git Cola with
300 [winget](https://github.com/microsoft/winget-cli) run the following command:
302 winget install git-cola.git-cola
304 As there is no dependency resolution yet you have to install Git as well with:
306 winget install Git.Git
310 Git Cola ships with an interactive rebase editor called `git-cola-sequence-editor`.
311 `git-cola-sequence-editor` is used to reorder and choose commits when rebasing.
312 Start an interactive rebase through the "Rebase" menu, or through the
313 `git cola rebase` sub-command to use the `git-cola-sequence-editor`:
315 git cola rebase @{upstream}
317 `git-cola-sequence-editor` can be launched independently of git cola by telling
318 `git rebase` to use it as its editor through the `GIT_SEQUENCE_EDITOR`
319 environment variable:
321 export GIT_SEQUENCE_EDITOR="$HOME/git-cola/bin/git-cola-sequence-editor"
322 git rebase -i @{upstream}
326 Shell completion scripts are available for bash and zsh.
327 Each script contains instructions on how to install and activate the completions.
329 * [bash completion script](contrib/git-cola-completion.bash)
331 * [zsh completion script](contrib/_git-cola)
334 # Git Cola Sub-commands
336 The `git-cola` command exposes various sub-commands that allow you to quickly
337 launch tools that are available from within the git-cola interface.
338 For example, `git cola find` launches the file finder,
339 and `git cola grep` launches the grep tool.
341 See `git cola --help-commands` for the full list of commands.
343 $ git cola --help-commands
346 {cola,am,archive,branch,browse,config,
347 dag,diff,fetch,find,grep,merge,pull,push,
348 rebase,remote,search,stash,tag,version}
352 {cola,am,archive,branch,browse,config,
353 dag,diff,fetch,find,grep,merge,pull,push,
354 rebase,remote,search,stash,tag,version}
357 am apply patches using "git am"
358 archive save an archive
359 branch create a branch
360 browse browse repository
361 config edit configuration
368 pull pull remote branches
369 push push remote branches
370 rebase interactive rebase
372 search search commits
373 stash stash and unstash changes
375 version print the version
379 If you already have Git Cola's dependencies installed then you can
380 start `cola` as a Python module if you have the source code available.
386 The following commands should be run during development:
391 # Run tests and doc checks
394 # Run tests against multiple python interpreters using tox
397 The test suite can be found in the [test](test) directory.
399 Commits and pull requests are automatically tested for code quality
400 using [GitHub Actions](https://github.com/git-cola/git-cola/actions/workflows/main.yml).
402 Auto-format `cola/i18n/*.po` files before committing when updating translations:
406 When submitting patches, consult the
407 [contributing guidelines](CONTRIBUTING.md).
412 Git Cola installs its modules into the default Python site-packages directory
413 (e.g. `lib/python3.7/site-packages`) using setuptools.
415 While end-users can use `pip install git-cola` to install Git Cola, distribution
416 packagers should use the `garden -D prefix=/usr install` process. Git Cola's Garden
417 recipe wraps `pip install --prefix=<prefix>` to provide a packaging-friendly
418 `garden install` target.
421 # Windows (Continued)
423 ## Microsoft Visual C++ 2015 Redistributable
425 Earlier versions of Git Cola may have shipped without `vcruntime140.dll` and may
426 not run on machines that are missing this DLL.
428 To fix this, download the
429 [Microsoft Visual C++ 2015 Redistributable](https://www.microsoft.com/en-us/download/details.aspx?id=52685)
432 Git Cola v4.0.0 and newer include this DLL and do not require this to be installed
437 In order to develop Git Cola on Windows you will need to install
438 Python3 and pip. Install PyQt5 using `pip install PyQt5`
439 to make the PyQt5 bindings available to Python.
441 Once these are installed you can use `python.exe` to run
442 directly from the source tree. For example, from a Git Bash terminal:
444 /c/Python39/python.exe ./bin/git-cola
446 ## Multiple Python versions
448 If you have multiple versions of Python installed, the `contrib/win32/cola`
449 launcher script might choose the newer version instead of the python
450 that has PyQt installed. In order to resolve this, you can set the
451 `cola.pythonlocation` git configuration variable to tell cola where to
452 find python. For example:
454 git config --global cola.pythonlocation /c/Python39
456 ## Building Windows Installers
458 Windows installers are built using
460 * [Pynsist](https://pynsist.readthedocs.io/en/latest/).
462 * [NSIS](http://nsis.sourceforge.net/Main_Page) is also needed.
464 To build the installer using Pynsist run:
466 ./contrib/win32/run-pynsist.sh
468 This will generate an installer in `build/nsis/`.
470 ## Windows "History Browser" Configuration Upgrade
472 You may need to configure your history browser if you are upgrading from an
473 older version of Git Cola on Windows.
475 `gitk` was originally the default history browser, but `gitk` cannot be
476 launched as-is on Windows because `gitk` is a shell script.
478 If you are configured to use `gitk`, then change your configuration to
479 go through Git's `sh.exe` on Windows. Similarly, we must go through
480 `python.exe` if we want to use `git-dag`.
482 If you want to use gitk as your history browser open the
483 Preferences screen and change the history browser command to:
485 "C:/Program Files/Git/bin/sh.exe" --login -i C:/Git/bin/gitk
487 `git-dag` became the default history browser on Windows in `v2.3`, so new
488 users do not need to configure anything.