git-cola v4.2.1
[git-cola.git] / README.md
blob9eb2ee68541e47a4cdb363ad9dbb7d7983b2ff8a
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/main.yml/badge.svg?branch=main&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)
11 * [Screenshots](https://git-cola.github.io/screenshots.html)
13 * [Downloads](https://git-cola.github.io/downloads.html)
16 # Documentation
18 * [Keyboard shortcuts](https://git-cola.github.io/share/doc/git-cola/hotkeys.html)
20 * [HTML documentation](https://git-cola.readthedocs.io/en/latest/)
22 * [Git Cola documentation](docs/git-cola.rst)
24 * [Git DAG documentation](docs/git-dag.rst)
26 * [Contributing guidelines](CONTRIBUTING.md)
29 # Requirements
31 ## Build
33 * [Sphinx](http://sphinx-doc.org/) is used to generate the documentation.
35 ## Runtime
37 * [Git](https://git-scm.com/) 2.2.0 or newer.
39 * [Python](https://python.org/) 3.6 or newer.
41 * [QtPy](https://github.com/spyder-ide/qtpy) 1.1.0 or newer.
43 Git Cola uses QtPy, so you can choose between PyQt6, PyQt5 and PySide2 by setting
44 the `QT_API` environment variable to `pyqt6`, `pyqt5` or `pyside2` as desired.
45 `qtpy` defaults to `pyqt5` and falls back to `pyqt6` and `pyside2` if `pyqt5`
46 is not installed.
48 Any of the following Python Qt libraries must be installed:
50 * [PyQt5 / PyQt6](https://www.riverbankcomputing.com/software/pyqt/download5)
51   5.6 or newer is required. Qt 6.0 is also supported via QtPy.
53 * [PySide2](https://github.com/PySide/PySide)
54   5.11.0 or newer.
57 ## Optional Features
59 Git Cola enables additional features when the following
60 Python modules are installed.
62 [send2trash](https://github.com/hsoft/send2trash) enables cross-platform
63 "Send to Trash" functionality.
66 # Installation
68 **IMPORTANT**: never run `pip install` or `make install` as root or outside of a
69 Python virtualenv!
71 There are several ways to install Git Cola.
73 ## Linux
75 Linux is it! Your distro has probably already packaged `git-cola`.
76 If not, please file a bug against your distribution ;-)
78 ### Arch
80 Available in the [AUR](https://aur.archlinux.org/packages/git-cola/).
82 ### Debian, Ubuntu
84     apt install git-cola
86 ### Fedora
88     dnf install git-cola
90 ### Gentoo
92     emerge git-cola
94 ### OpenSUSE, SLE
96     zypper install git-cola
98 ### Slackware
100 Available in [SlackBuilds.org](http://slackbuilds.org/result/?search=git-cola).
102 ### Ubuntu
104 [See here](https://packages.ubuntu.com/search?keywords=git-cola) for the
105 versions that are available in Ubuntu's repositories.
107 There was a [PPA by @pavreh](https://launchpad.net/~pavreh/+archive/ubuntu/git-cola)
108 but it has not been updated for a while.
111 ## FreeBSD
113     # Install from official binary packages
114     pkg install -r FreeBSD devel/git-cola
116     # Build from source
117     cd /usr/ports/devel/git-cola && make clean install
120 ## Install into a Python Virtualenv from PyPI using pip
122 **IMPORTANT**: never run `pip install` or `make install` as root or outside of a
123 Python virtualenv!
125 One way to install the latest released version is to use `venv` (virtualenv) and `pip`.
126 This installs [git-cola from pypi.org](https://pypi.org/project/git-cola/).
128 If you already have `PyQt5` installed from your distribution's package manager
129 then you should skip the `pip install PyQt` steps.
131 If you already have the `qt5-devel` package installed then you can lookup its version so
132 that your virtualenv can install a compatible version of PyQt using `qmake`:
134     QT_VERSION=$(qmake -query QT_VERSION)
135     QT_VERSION_MAJOR=$(qmake -query QT_VERSION | head -c 1)
136     echo PyQt${QT_VERSION_MAJOR}==${QT_VERSION}
138 Take note of the `PyQtX==A.B.C` value so that you can specify it when installing
139 PyQt below if, and only if, you have `qmake` installed and want to interoperate
140 with its corresponding Qt installation.
142     python3 -m venv --system-site-packages env3
144     # Skip this command if you already have PyQt installed or if you do not have qmake
145     ./env3/bin/pip install PyQt${QT_VERSION_MAJOR}==${QT_VERSION}
147     ./env3/bin/pip install git-cola
148     ./env3/bin/git-cola
150 Add the `env3/bin` directory to your `PATH` or symlink to `bin/git-cola` from
151 somewhere in your `PATH` such as `~/.local/bin/git-cola`, and you can launch
152 Git Cola like any other built-in `git` command:
154     git cola
155     git dag
158 ## Install into a Python Virtualenv from Source
160 If you don't have PyQt installed then the easiest way to get it is to use a Python
161 virtualenv and install Git Cola into it in "editable" mode. This install method
162 lets you upgrade Git Cola by running `git pull`.
164     # Create a virtualenv called "env3" and activate it.
165     python3 -m venv --system-site-packages env3
166     source env3/bin/activate
168     # One-time setup: install optional requirements for development.
169     make requirements-dev requirements-optional
171     # Install git-cola in "editable" mode so that it uses the source tree.
172     make develop
174     # Run Git Cola via the "git-cola" Git subcommand.
175     git cola
178 If you add `env3/bin` (or symlink to `bin/git-cola` ) to your `$PATH` then you can
179 run `git cola` as if it were a builtin `git` command from outside of the virtualenv
180 (eg. after running "deactivate" or when opening a new shell).
183 ## Standalone Installation from Source
185 Running `make install prefix=$HOME/.local` will install Git Cola in your
186 `$HOME/.local` directory (`$HOME/.local/bin/git-cola`, `$HOME/.local/lib`, etc).
188 This installation method assumes that the `qtpy` and `PyQt*` dependencies have
189 been pre-installed.
191 The `Makefile` also supports `DESTDIR` to support creating packages for Linux package
192 managers:
194     make DESTDIR=/tmp/stage prefix=/usr/local install
197 ## macOS
199 For most end-users we recommend using either Homebrew or installing into
200 a Python virtualenv as described above.
202 You can install Git Cola from source using the same steps as above.
204 ### Homebrew
206 An easy way to install Git Cola is to use [Homebrew](https://brew.sh/) .
207 Use Homebrew to install the git-cola recipe:
209     brew install git-cola
211 If you install using Homebrew you can stop at this step.
212 You don't need to clone the repo or anything.
214 ### git-cola.app
216 If you have all of the dependencies installed, either via `pip` or `brew` then
217 you can build a shell `git-cola.app` app bundle wrapper for use in `/Applications`.
219 If you'd like to build a `git-cola.app` bundle for `/Applications` run this command:
221     make git-cola.app
223 You will need to periodically rebuild the app wrapper whenever Python is upgraded.
225 ### Updating macOS and Homebrew
227 Updating macOS can often break Homebrew-managed software.
229 If you upgrade your macOS version and Git Cola no longer runs then then it is
230 recommended that you re-install Git Cola's dependencies after upgrading.
232 A quick fix when upgrading to newer versions of XCode or macOS is to
233 reinstall pyqt5.
235     brew reinstall pyqt@5
237 You may also need to relink your pyqt installation:
239     brew link pyqt@5
241 This is required when upgrading to a modern (post-10.11 El Capitan) Mac OS X.
242 Homebrew now bundles its own Python3 installation instead of using the
243 system-provided default Python.
245 If the "brew reinstall" command above does not work then re-installing from
246 scratch using the instructions below should get things back in shape.
248     # update homebrew
249     brew update
251     # uninstall git-cola and its dependencies
252     brew uninstall git-cola
253     brew uninstall pyqt5
254     brew uninstall sip
256     # re-install git-cola and its dependencies
257     brew install git-cola
260 ## Windows
262 IMPORTANT If you have a 64-bit machine, install the 64-bit versions only.
263 Do not mix 32-bit and 64-bit versions.
265 Download and install the following:
267 * [Git for Windows](https://git-for-windows.github.io/)
269 * [Git Cola](https://github.com/git-cola/git-cola/releases)
271 Once these are installed you can run Git Cola from the Start menu.
273 See "Windows (Continued)" below for more details.
276 # Goodies
278 Git Cola ships with an interactive rebase editor called `git-cola-sequence-editor`.
279 `git-cola-sequence-editor` is used to reorder and choose commits when rebasing.
280 Start an interactive rebase through the "Rebase" menu, or through the
281 `git cola rebase` sub-command to use the `git-cola-sequence-editor`:
283     git cola rebase @{upstream}
285 `git-cola-sequence-editor` can be launched independently of git cola by telling
286 `git rebase` to use it as its editor through the `GIT_SEQUENCE_EDITOR`
287 environment variable:
289     export GIT_SEQUENCE_EDITOR="$HOME/git-cola/bin/git-cola-sequence-editor"
290     git rebase -i @{upstream}
293 # Git Cola Sub-commands
295 The `git-cola` command exposes various sub-commands that allow you to quickly
296 launch tools that are available from within the git-cola interface.
297 For example, `git cola find` launches the file finder,
298 and `git cola grep` launches the grep tool.
300 See `git cola --help-commands` for the full list of commands.
302     $ git cola --help-commands
303     usage: git-cola [-h]
304     
305                     {cola,am,archive,branch,browse,config,
306                      dag,diff,fetch,find,grep,merge,pull,push,
307                      rebase,remote,search,stash,tag,version}
308                     ...
309     
310     valid commands:
311       {cola,am,archive,branch,browse,config,
312        dag,diff,fetch,find,grep,merge,pull,push,
313        rebase,remote,search,stash,tag,version}
315         cola                start git-cola
316         am                  apply patches using "git am"
317         archive             save an archive
318         branch              create a branch
319         browse              browse repository
320         config              edit configuration
321         dag                 start git-dag
322         diff                view diffs
323         fetch               fetch remotes
324         find                find files
325         grep                grep source
326         merge               merge branches
327         pull                pull remote branches
328         push                push remote branches
329         rebase              interactive rebase
330         remote              edit remotes
331         search              search commits
332         stash               stash and unstash changes
333         tag                 create tags
334         version             print the version
336 ## Development
338 If you already have Git Cola's dependencies installed then you can 
339 start `cola` as a Python module if you have the source code available.
341     python -m cola
342     python -m cola dag
345 The following commands should be run during development:
347     # Run the unit tests
348     $ make test
350     # Run tests and longer-running pylint and flake8 checks
351     $ make check
353     # Run tests against multiple python interpreters using tox
354     $ make tox
356 The test suite can be found in the [test](test) directory.
358 Commits and pull requests are automatically tested for code quality
359 using [GitHub Actions](https://github.com/git-cola/git-cola/actions/workflows/main.yml).
361 Auto-format `cola/i18n/*.po` files before committing when updating translations:
363     $ make po
365 When submitting patches, consult the
366 [contributing guidelines](CONTRIBUTING.md).
369 ## Packaging Notes
371 Git Cola installs its modules into the default Python site-packages directory
372 (eg. `lib/python3.7/site-packages`) using setuptools.
374 While end-users can use `pip install git-cola` to install Git Cola, distribution
375 packagers should use the `make prefix=/usr` install process. Git Cola's `Makefile` wraps
376 `pip install --prefix=<prefix>` to provide a packaging-friendly `make install` target.
379 # Windows (Continued)
381 ## Microsoft Visual C++ 2015 Redistributable
383 Earlier versions of Git Cola may have shipped without `vcruntime140.dll`  and may
384 not run on machines that are missing this DLL.
386 To fix this, download the
387 [Microsoft Visual C++ 2015 Redistributable](https://www.microsoft.com/en-us/download/details.aspx?id=52685)
388 and install it
390 Git Cola v4.0.0 and newer include this DLL and do not require this to be installed
391 separately.
393 ## Development
395 In order to develop Git Cola on Windows you will need to install
396 Python3 and pip.  Install PyQt5 using `pip install PyQt5`
397 to make the PyQt5 bindings available to Python.
399 Once these are installed you can use `python.exe` to run
400 directly from the source tree.  For example, from a Git Bash terminal:
402     /c/Python36/python.exe ./bin/git-cola
404 ## Multiple Python versions
406 If you have multiple versions of Python installed, the `contrib/win32/cola`
407 launcher script might choose the newer version instead of the python
408 that has PyQt installed.  In order to resolve this, you can set the
409 `cola.pythonlocation` git configuration variable to tell cola where to
410 find python.  For example:
412     git config --global cola.pythonlocation /c/Python39
414 ## Building Windows Installers
416 Windows installers are built using
418 * [Pynsist](https://pynsist.readthedocs.io/en/latest/).
420 * [NSIS](http://nsis.sourceforge.net/Main_Page) is also needed.
422 To build the installer using Pynsist run:
424     ./contrib/win32/run-pynsist.sh
426 This will generate an installer in `build/nsis/`.
428 ## Windows "History Browser" Configuration Upgrade
430 You may need to configure your history browser if you are upgrading from an
431 older version of Git Cola on Windows.
433 `gitk` was originally the default history browser, but `gitk` cannot be
434 launched as-is on Windows because `gitk` is a shell script.
436 If you are configured to use `gitk`, then change your configuration to
437 go through Git's `sh.exe` on Windows.  Similarly, we must go through
438 `python.exe` if we want to use `git-dag`.
440 If you want to use gitk as your history browser open the
441 Preferences screen and change the history browser command to:
443     "C:/Program Files/Git/bin/sh.exe" --login -i C:/Git/bin/gitk
445 `git-dag` became the default history browser on Windows in `v2.3`, so new
446 users do not need to configure anything.