README.md

   1 # git-cola: The highly caffeinated Git GUI
   2
   3 Git Cola is a powerful Git GUI with a slick and intuitive user interface.
   4
   5     git clone https://github.com/git-cola/git-cola.git
   6
   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)
  11
  12 * [Screenshots](https://git-cola.github.io/screenshots.html)
  13
  14 * [Downloads](https://git-cola.github.io/downloads.html)
  15
  16
  17 # Documentation
  18
  19 * [Keyboard shortcuts](https://git-cola.github.io/share/doc/git-cola/hotkeys.html)
  20
  21 * [HTML documentation](https://git-cola.readthedocs.io/en/latest/)
  22
  23 * [Git Cola documentation](docs/git-cola.rst)
  24
  25 * [Git DAG documentation](docs/git-dag.rst)
  26
  27 * [Contributing guidelines](CONTRIBUTING.md)
  28
  29
  30 # Requirements
  31
  32 ## Build
  33
  34 * [Sphinx](http://sphinx-doc.org/) is used to generate the documentation.
  35
  36 ## Runtime
  37
  38 * [Git](https://git-scm.com/) 2.2.0 or newer.
  39
  40 * [Python](https://python.org/) 3.6 or newer.
  41
  42 * [QtPy](https://github.com/spyder-ide/qtpy) 1.1.0 or newer.
  43
  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.
  48
  49 Any of the following Python Qt libraries must be installed:
  50
  51 * [PyQt5 / PyQt6](https://www.riverbankcomputing.com/software/pyqt/download5)
  52   5.6 or newer is required. Qt 6.0 is also supported via QtPy.
  53
  54 * [PySide2](https://github.com/PySide/PySide)
  55   5.11.0 or newer.
  56
  57
  58 ## Optional Features
  59
  60 Git Cola enables additional features when the following
  61 Python modules are installed.
  62
  63 [Send2Trash](https://pypi.org/project/Send2Trash/)
  64 enables cross-platform "Send to Trash" functionality.
  65 ([source](https://github.com/hsoft/send2trash))
  66
  67 [pyobjc](https://pypi.org/project/pyobjc/)
  68 enables macOS-specific application themes on macOS.
  69 ([source](https://github.com/ronaldoussoren/pyobjc))
  70
  71
  72 # Installation
  73
  74 **IMPORTANT**: never run `pip install` or `garden install` outside of a
  75 Python virtualenv or as root!
  76
  77 There are several ways to install Git Cola.
  78
  79 ## Linux
  80
  81 Linux is it! Your distro has probably already packaged `git-cola`.
  82 If not, please file a bug against your distribution ;-)
  83
  84 ### Arch
  85
  86 Available in the [AUR](https://aur.archlinux.org/packages/git-cola/).
  87
  88 ### Debian, Ubuntu
  89
  90     apt install git-cola
  91
  92 ### Fedora
  93
  94     dnf install git-cola
  95
  96 ### Gentoo
  97
  98     emerge git-cola
  99
 100 ### OpenSUSE, SLE
 101
 102     zypper install git-cola
 103
 104 ### Slackware
 105
 106 Available in [SlackBuilds.org](http://slackbuilds.org/result/?search=git-cola).
 107
 108 ### Ubuntu
 109
 110 [See here](https://packages.ubuntu.com/search?keywords=git-cola) for the
 111 versions that are available in Ubuntu's repositories.
 112
 113 There was a [PPA by @pavreh](https://launchpad.net/~pavreh/+archive/ubuntu/git-cola)
 114 but it has not been updated for a while.
 115
 116
 117 ## FreeBSD
 118
 119     # Install from official binary packages
 120     pkg install -r FreeBSD devel/git-cola
 121
 122     # Build from source
 123     cd /usr/ports/devel/git-cola && make clean install
 124
 125
 126 ## Installing PyQt dependencies on Debian / Ubuntu systems
 127
 128 If you are on an older version of Debian or Ubuntu then you may have a rather old
 129 version of `git-cola` available from `apt`.
 130
 131 The recommended approach to running the latest Git Cola version is to install its
 132 dependencies using `apt` and then run `./bin/git-cola` directly from the Git sources.
 133
 134 No installation is required. Git Cola is designed to run directly from its source tree.
 135
 136 For newer Debian/Ubuntu versions you may need to use the *Qt6* dependencies.
 137 For older Debian/Ubuntu versions you may need to use the *Qt5* dependencies.
 138
 139 Git Cola runs fine with either version and only one of these two sets of packages are
 140 required.
 141
 142 * Qt6 / PyQt6
 143
 144 ```bash
 145 sudo apt install python3-pyqt6 python3-pyqt6.qtsvg python3-pyqt6.qtwebengine
 146 ```
 147
 148 * Qt5 / PyQt5
 149
 150 ```bash
 151 sudo apt install python3-pyqt5 python3-pyqt5.qtopengl python3-pyqt5.qtwebengine python3-pyqt5.qtsvg
 152 ```
 153
 154 At this point you should be able to launch `./bin/git-cola` from the source tree and
 155 there is nothing more to do.
 156
 157 The further instructions below detail how to install Git Cola from PyPI or how to
 158 install it into a location separate from the source tree.
 159
 160
 161 ## Install into a Python Virtualenv from PyPI using pip
 162
 163 **IMPORTANT**: never run `pip install` or `garden install` outside of a
 164 Python virtualenv or as root!
 165
 166 **IMPORTANT**: if you are on Linux distributions where PyQt6 or PyQt5 are available from
 167 your package manager then it is highly recommended to install those dependencies using
 168 your system's package manager. See the section above for details.
 169
 170 One way to install the latest released version is to use `venv` (virtualenv) and `pip`.
 171 This installs [git-cola from pypi.org](https://pypi.org/project/git-cola/).
 172
 173     python3 -m venv --system-site-packages env3
 174     ./env3/bin/pip install git-cola
 175     ./env3/bin/git-cola
 176
 177 Add the `env3/bin` directory to your `PATH` or symlink to `bin/git-cola` from
 178 somewhere in your `PATH` such as `~/.local/bin/git-cola`, and you can launch
 179 Git Cola like any other built-in `git` command:
 180
 181     git cola
 182     git dag
 183
 184
 185 ## Install into a Python Virtualenv from Source
 186
 187 If you don't have PyQt installed then the easiest way to get it is to use a Python
 188 virtualenv and install Git Cola into it in "editable" mode. This install method
 189 lets you upgrade Git Cola by running `git pull`.
 190
 191     # Create a virtualenv called "env3" and activate it.
 192     python3 -m venv --system-site-packages env3
 193     source env3/bin/activate
 194
 195     # One-time setup: install dev and optional runtime requirements
 196     garden requirements/dev
 197     garden requirements/opt
 198
 199     # Install git-cola in "editable" mode so that it uses the source tree.
 200     garden develop
 201
 202     # Run Git Cola via the "git-cola" Git subcommand.
 203     git cola
 204
 205
 206 If you add `env3/bin` (or symlink to `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 (eg. after running "deactivate" or when opening a new shell).
 209
 210
 211 ## Standalone Installation from Source
 212
 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).
 215
 216 This installation method assumes that the `qtpy` and `PyQt*` dependencies have
 217 been pre-installed.
 218
 219 The Garden recipe also supports `DESTDIR` to support creating packages for Linux package
 220 managers:
 221
 222     garden -D DESTDIR=/tmp/stage -D prefix=/usr/local install
 223
 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.
 229
 230     make DESTDIR=/tmp/stage prefix=/usr/local install
 231
 232
 233 ## macOS
 234
 235 For most end-users we recommend using either Homebrew or installing into
 236 a Python virtualenv as described above.
 237
 238 You can install Git Cola from source using the same steps as above.
 239
 240 ### Homebrew
 241
 242 An easy way to install Git Cola is to use [Homebrew](https://brew.sh/) .
 243 Use Homebrew to install the git-cola recipe:
 244
 245     brew install git-cola
 246
 247 If you install using Homebrew you can stop at this step.
 248 You don't need to clone the repo or anything.
 249
 250 ### git-cola.app
 251
 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`.
 254
 255 If you'd like to build a `git-cola.app` bundle for `/Applications` run this command:
 256
 257     garden macos/app
 258
 259 You will need to periodically rebuild the app wrapper whenever Python is upgraded.
 260
 261 ### Updating macOS and Homebrew
 262
 263 Updating macOS can often break Homebrew-managed software.
 264
 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.
 267
 268 A quick fix when upgrading to newer versions of XCode or macOS is to
 269 reinstall pyqt5.
 270
 271     brew reinstall pyqt@5
 272
 273 You may also need to relink your pyqt installation:
 274
 275     brew link pyqt@5
 276
 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.
 280
 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.
 283
 284     # update homebrew
 285     brew update
 286
 287     # uninstall git-cola and its dependencies
 288     brew uninstall git-cola
 289     brew uninstall pyqt5
 290     brew uninstall sip
 291
 292     # re-install git-cola and its dependencies
 293     brew install git-cola
 294
 295
 296 ## Windows
 297
 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.
 300
 301 Download and install the following:
 302
 303 * [Git for Windows](https://git-for-windows.github.io/)
 304
 305 * [Git Cola](https://github.com/git-cola/git-cola/releases)
 306
 307 Once these are installed you can run Git Cola from the Start menu.
 308
 309 See "Windows (Continued)" below for more details.
 310
 311 If you'd like to install Git Cola with
 312 [winget](https://github.com/microsoft/winget-cli) run the following command:
 313
 314     winget install git-cola.git-cola
 315
 316 As there is no dependency resolution yet you have to install Git as well with:
 317
 318     winget install Git.Git
 319
 320 # Goodies
 321
 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`:
 326
 327     git cola rebase @{upstream}
 328
 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:
 332
 333     export GIT_SEQUENCE_EDITOR="$HOME/git-cola/bin/git-cola-sequence-editor"
 334     git rebase -i @{upstream}
 335
 336 ## Shell Completions
 337
 338 Shell completion scripts are available for bash and zsh.
 339 Each script contains instructions on how to install and activate the completions.
 340
 341 * [bash completion script](contrib/git-cola-completion.bash)
 342
 343 * [zsh completion script](contrib/_git-cola)
 344
 345
 346 # Git Cola Sub-commands
 347
 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.
 352
 353 See `git cola --help-commands` for the full list of commands.
 354
 355     $ git cola --help-commands
 356     usage: git-cola [-h]
 357
 358                     {cola,am,archive,branch,browse,config,
 359                      dag,diff,fetch,find,grep,merge,pull,push,
 360                      rebase,remote,search,stash,tag,version}
 361                     ...
 362
 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}
 367
 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
 388
 389 ## Development
 390
 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.
 393
 394     python -m cola
 395     python -m cola dag
 396
 397
 398 The following commands should be run during development:
 399
 400     # Run the unit tests
 401     $ garden test
 402
 403     # Run tests and longer-running pylint checks
 404     $ garden check
 405
 406     # Run tests against multiple python interpreters using tox
 407     $ garden tox
 408
 409 The test suite can be found in the [test](test) directory.
 410
 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).
 413
 414 Auto-format `cola/i18n/*.po` files before committing when updating translations:
 415
 416     $ garden po
 417
 418 When submitting patches, consult the
 419 [contributing guidelines](CONTRIBUTING.md).
 420
 421
 422 ## Packaging Notes
 423
 424 Git Cola installs its modules into the default Python site-packages directory
 425 (eg. `lib/python3.7/site-packages`) using setuptools.
 426
 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.
 431
 432
 433 # Windows (Continued)
 434
 435 ## Microsoft Visual C++ 2015 Redistributable
 436
 437 Earlier versions of Git Cola may have shipped without `vcruntime140.dll`  and may
 438 not run on machines that are missing this DLL.
 439
 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
 443
 444 Git Cola v4.0.0 and newer include this DLL and do not require this to be installed
 445 separately.
 446
 447 ## Development
 448
 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.
 452
 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:
 455
 456     /c/Python39/python.exe ./bin/git-cola
 457
 458 ## Multiple Python versions
 459
 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:
 465
 466     git config --global cola.pythonlocation /c/Python39
 467
 468 ## Building Windows Installers
 469
 470 Windows installers are built using
 471
 472 * [Pynsist](https://pynsist.readthedocs.io/en/latest/).
 473
 474 * [NSIS](http://nsis.sourceforge.net/Main_Page) is also needed.
 475
 476 To build the installer using Pynsist run:
 477
 478     ./contrib/win32/run-pynsist.sh
 479
 480 This will generate an installer in `build/nsis/`.
 481
 482 ## Windows "History Browser" Configuration Upgrade
 483
 484 You may need to configure your history browser if you are upgrading from an
 485 older version of Git Cola on Windows.
 486
 487 `gitk` was originally the default history browser, but `gitk` cannot be
 488 launched as-is on Windows because `gitk` is a shell script.
 489
 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`.
 493
 494 If you want to use gitk as your history browser open the
 495 Preferences screen and change the history browser command to:
 496
 497     "C:/Program Files/Git/bin/sh.exe" --login -i C:/Git/bin/gitk
 498
 499 `git-dag` became the default history browser on Windows in `v2.3`, so new
 500 users do not need to configure anything.