garden: get rid of unnecessary variables
[git-cola.git] / README.md
blobaeab24b9edfd92f89b2c74f52abbfc8dec56b426
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)
17 # Documentation
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)
30 # Requirements
32 ## Build
34 * [Sphinx](http://sphinx-doc.org/) is used to generate the documentation.
36 ## Runtime
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`
47 is not installed.
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)
55   5.12.0 or newer.
58 ## Optional Features
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 [pyobjc](https://pypi.org/project/pyobjc/)
68 enables macOS-specific application themes on macOS.
69 ([source](https://github.com/ronaldoussoren/pyobjc))
72 # Installation
74 There are several ways to install Git Cola but you do not need to "install" Git Cola
75 in order to run it.
77 Git Cola is designed to run directly from its source tree. Installation is optional.
80 ## From Source
82 The recommended approach for running the latest Git Cola version is to install its
83 PyQt dependencies using your distribution's package manager and then run
84 `./bin/git-cola` directly from source.
87 ## Installing PyQt dependencies on Debian / Ubuntu systems
89 Git Cola works with either PyQt5 or PyQt6 because it uses the
90 [qtpy](https://github.com/spyder-ide/qtpy) library for PyQt compatibility.
92 ### PyQt5
94 Users on newer Debian/Ubuntu version can install a single package to run from source.
96 ```bash
97 sudo apt install python3-qtpy
98 ```
100 If you are on an older version that does not have `python3-qtpy` available then you can
101 install the following packages directly.
103 ```bash
104 sudo apt install python3-pyqt5 python3-pyqt5.qtopengl python3-pyqt5.qtwebengine python3-pyqt5.qtsvg
107 ### PyQt6
109 If you'd like to use Git Cola with the newer PyQt6 ecosystem then you can install these
110 packages instead of PyQt5.
112 ```bash
113 sudo apt install python3-pyqt6 python3-pyqt6.qtsvg python3-pyqt6.qtwebengine
116 At this point you should be able to launch `./bin/git-cola` from the source tree and
117 there is nothing more to do.
119 The further instructions below detail how to install Git Cola from PyPI or how to
120 install it into a location separate from the source tree.
123 ## Linux
125 Linux is it! Your distro has probably already packaged `git-cola`.
126 If not, please file a bug against your distribution ;-)
128 ### Arch
130 Available in the [AUR](https://aur.archlinux.org/packages/git-cola/).
132 ### Debian, Ubuntu
134     apt install git-cola
136 ### Fedora
138     dnf install git-cola
140 ### Gentoo
142     emerge git-cola
144 ### OpenSUSE, SLE
146     zypper install git-cola
148 ### Slackware
150 Available in [SlackBuilds.org](http://slackbuilds.org/result/?search=git-cola).
152 ### Ubuntu
154 [See here](https://packages.ubuntu.com/search?keywords=git-cola) for the
155 versions that are available in Ubuntu's repositories.
157 ## FreeBSD
159     # Install from official binary packages
160     pkg install -r FreeBSD devel/git-cola
162     # Build from source
163     cd /usr/ports/devel/git-cola && make clean install
165 ## Install into a Python Virtualenv from PyPI using pip
167 **IMPORTANT**: never run `pip install` or `garden install` outside of a
168 Python virtualenv or as root!
170 **IMPORTANT**: if you are on Linux distributions where PyQt6 or PyQt5 are available from
171 your package manager then it is highly recommended to install those dependencies using
172 your system's package manager. See the section above for details.
174 One way to install the latest released version is to use `venv` (virtualenv) and `pip`.
175 This installs [git-cola from pypi.org](https://pypi.org/project/git-cola/).
177     python3 -m venv --system-site-packages env3
178     ./env3/bin/pip install git-cola
179     ./env3/bin/git-cola
181 Add the `env3/bin` directory to your `PATH` or symlink to `bin/git-cola` from
182 somewhere in your `PATH` such as `~/.local/bin/git-cola`, and you can launch
183 Git Cola like any other built-in `git` command:
185     git cola
186     git dag
189 ## Install into a Python Virtualenv from Source
191 If you don't have PyQt installed then the easiest way to get it is to use a Python
192 virtualenv and install Git Cola into it in "editable" mode.
194 This install method lets you upgrade Git Cola by running `git pull`.
196     # Create a virtualenv called "env3" and activate it.
197     python3 -m venv --system-site-packages env3
199     # Install PyQt and (optional) extra packages to enable all features.
200     ./env3/bin/pip install --editable '.[extras,pyqt6]'
202     # Run Git Cola via the "git-cola" Git subcommand.
203     source env3/bin/activate
204     git cola
206 If you add `env3/bin` (or symlink to `env3/bin/git-cola` ) somewhere in your `$PATH` then you can
207 run `git cola` as if it were a builtin `git` command from outside of the virtualenv
208 (e.g. after running "deactivate" or when opening a new shell).
211 ## Standalone Installation from Source
213 Running `garden -D prefix=$HOME/.local install` will install Git Cola in your
214 `$HOME/.local` directory (`$HOME/.local/bin/git-cola`, `$HOME/.local/lib`, etc).
216 This installation method assumes that the `qtpy` and `PyQt*` dependencies have
217 been pre-installed.
219 The Garden recipe also supports `DESTDIR` to support creating packages for Linux package
220 managers:
222     garden -D DESTDIR=/tmp/stage -D prefix=/usr/local install
224 If you do not have `garden` available then `make` can be used instead.
225 The `Makefile` supports staged installs using the conventional
226 [DESTDIR](https://www.gnu.org/software/make/manual/html_node/DESTDIR.html) and
227 [prefix](https://www.gnu.org/software/make/manual/html_node/Directory-Variables.html)
228 variables.
230     make DESTDIR=/tmp/stage prefix=/usr/local install
233 ## macOS
235 For most end-users we recommend using either Homebrew or installing into
236 a Python virtualenv as described above.
238 You can install Git Cola from source using the same steps as above.
240 ### Homebrew
242 An easy way to install Git Cola is to use [Homebrew](https://brew.sh/) .
243 Use Homebrew to install the git-cola recipe:
245     brew install git-cola
247 If you install using Homebrew you can stop at this step.
248 You don't need to clone the repo or anything.
250 ### git-cola.app
252 If you have all of the dependencies installed, either via `pip` or `brew` then
253 you can build a shell `git-cola.app` app bundle wrapper for use in `/Applications`.
255 If you'd like to build a `git-cola.app` bundle for `/Applications` run this command:
257     garden macos/app
259 You will need to periodically rebuild the app wrapper whenever Python is upgraded.
261 ### Updating macOS and Homebrew
263 Updating macOS can often break Homebrew-managed software.
265 If you upgrade your macOS version and Git Cola no longer runs then then it is
266 recommended that you re-install Git Cola's dependencies after upgrading.
268 A quick fix when upgrading to newer versions of XCode or macOS is to
269 reinstall PyQt6.
271     brew reinstall pyqt@6
273 You may also need to relink your pyqt installation:
275     brew link pyqt@6
277 This is required when upgrading to a modern (post-10.11 El Capitan) Mac OS X.
278 Homebrew now bundles its own Python3 installation instead of using the
279 system-provided default Python.
281 If the "brew reinstall" command above does not work then re-installing from
282 scratch using the instructions below should get things back in shape.
284     # update homebrew
285     brew update
287     # uninstall git-cola and its dependencies
288     brew uninstall git-cola
289     brew uninstall pyqt5
290     brew uninstall sip
292     # re-install git-cola and its dependencies
293     brew install git-cola
296 ## Windows
298 IMPORTANT If you have a 64-bit machine, install the 64-bit versions only.
299 Do not mix 32-bit and 64-bit versions.
301 Download and install the following:
303 * [Git for Windows](https://git-for-windows.github.io/)
305 * [Git Cola](https://github.com/git-cola/git-cola/releases)
307 Once these are installed you can run Git Cola from the Start menu.
309 See "Windows (Continued)" below for more details.
311 If you'd like to install Git Cola with
312 [winget](https://github.com/microsoft/winget-cli) run the following command:
314     winget install git-cola.git-cola
316 As there is no dependency resolution yet you have to install Git as well with:
318     winget install Git.Git
320 # Goodies
322 Git Cola ships with an interactive rebase editor called `git-cola-sequence-editor`.
323 `git-cola-sequence-editor` is used to reorder and choose commits when rebasing.
324 Start an interactive rebase through the "Rebase" menu, or through the
325 `git cola rebase` sub-command to use the `git-cola-sequence-editor`:
327     git cola rebase @{upstream}
329 `git-cola-sequence-editor` can be launched independently of git cola by telling
330 `git rebase` to use it as its editor through the `GIT_SEQUENCE_EDITOR`
331 environment variable:
333     export GIT_SEQUENCE_EDITOR="$HOME/git-cola/bin/git-cola-sequence-editor"
334     git rebase -i @{upstream}
336 ## Shell Completions
338 Shell completion scripts are available for bash and zsh.
339 Each script contains instructions on how to install and activate the completions.
341 * [bash completion script](contrib/git-cola-completion.bash)
343 * [zsh completion script](contrib/_git-cola)
346 # Git Cola Sub-commands
348 The `git-cola` command exposes various sub-commands that allow you to quickly
349 launch tools that are available from within the git-cola interface.
350 For example, `git cola find` launches the file finder,
351 and `git cola grep` launches the grep tool.
353 See `git cola --help-commands` for the full list of commands.
355     $ git cola --help-commands
356     usage: git-cola [-h]
358                     {cola,am,archive,branch,browse,config,
359                      dag,diff,fetch,find,grep,merge,pull,push,
360                      rebase,remote,search,stash,tag,version}
361                     ...
363     valid commands:
364       {cola,am,archive,branch,browse,config,
365        dag,diff,fetch,find,grep,merge,pull,push,
366        rebase,remote,search,stash,tag,version}
368         cola                start git-cola
369         am                  apply patches using "git am"
370         archive             save an archive
371         branch              create a branch
372         browse              browse repository
373         config              edit configuration
374         dag                 start git-dag
375         diff                view diffs
376         fetch               fetch remotes
377         find                find files
378         grep                grep source
379         merge               merge branches
380         pull                pull remote branches
381         push                push remote branches
382         rebase              interactive rebase
383         remote              edit remotes
384         search              search commits
385         stash               stash and unstash changes
386         tag                 create tags
387         version             print the version
389 ## Development
391 If you already have Git Cola's dependencies installed then you can
392 start `cola` as a Python module if you have the source code available.
394     python -m cola
395     python -m cola dag
398 The following commands should be run during development:
400     # Run the unit tests
401     $ garden test
403     # Run tests and doc checks
404     $ garden check
406     # Run tests against multiple python interpreters using tox
407     $ garden tox
409 The test suite can be found in the [test](test) directory.
411 Commits and pull requests are automatically tested for code quality
412 using [GitHub Actions](https://github.com/git-cola/git-cola/actions/workflows/main.yml).
414 Auto-format `cola/i18n/*.po` files before committing when updating translations:
416     $ garden po
418 When submitting patches, consult the
419 [contributing guidelines](CONTRIBUTING.md).
422 ## Packaging Notes
424 Git Cola installs its modules into the default Python site-packages directory
425 (e.g. `lib/python3.7/site-packages`) using setuptools.
427 While end-users can use `pip install git-cola` to install Git Cola, distribution
428 packagers should use the `garden -D prefix=/usr install` process. Git Cola's Garden
429 recipe wraps `pip install --prefix=<prefix>` to provide a packaging-friendly
430 `garden install` target.
433 # Windows (Continued)
435 ## Microsoft Visual C++ 2015 Redistributable
437 Earlier versions of Git Cola may have shipped without `vcruntime140.dll`  and may
438 not run on machines that are missing this DLL.
440 To fix this, download the
441 [Microsoft Visual C++ 2015 Redistributable](https://www.microsoft.com/en-us/download/details.aspx?id=52685)
442 and install it
444 Git Cola v4.0.0 and newer include this DLL and do not require this to be installed
445 separately.
447 ## Development
449 In order to develop Git Cola on Windows you will need to install
450 Python3 and pip.  Install PyQt5 using `pip install PyQt5`
451 to make the PyQt5 bindings available to Python.
453 Once these are installed you can use `python.exe` to run
454 directly from the source tree.  For example, from a Git Bash terminal:
456     /c/Python39/python.exe ./bin/git-cola
458 ## Multiple Python versions
460 If you have multiple versions of Python installed, the `contrib/win32/cola`
461 launcher script might choose the newer version instead of the python
462 that has PyQt installed.  In order to resolve this, you can set the
463 `cola.pythonlocation` git configuration variable to tell cola where to
464 find python.  For example:
466     git config --global cola.pythonlocation /c/Python39
468 ## Building Windows Installers
470 Windows installers are built using
472 * [Pynsist](https://pynsist.readthedocs.io/en/latest/).
474 * [NSIS](http://nsis.sourceforge.net/Main_Page) is also needed.
476 To build the installer using Pynsist run:
478     ./contrib/win32/run-pynsist.sh
480 This will generate an installer in `build/nsis/`.
482 ## Windows "History Browser" Configuration Upgrade
484 You may need to configure your history browser if you are upgrading from an
485 older version of Git Cola on Windows.
487 `gitk` was originally the default history browser, but `gitk` cannot be
488 launched as-is on Windows because `gitk` is a shell script.
490 If you are configured to use `gitk`, then change your configuration to
491 go through Git's `sh.exe` on Windows.  Similarly, we must go through
492 `python.exe` if we want to use `git-dag`.
494 If you want to use gitk as your history browser open the
495 Preferences screen and change the history browser command to:
497     "C:/Program Files/Git/bin/sh.exe" --login -i C:/Git/bin/gitk
499 `git-dag` became the default history browser on Windows in `v2.3`, so new
500 users do not need to configure anything.