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 There are several ways to install Git Cola but you do not need to "install" Git Cola
  75 in order to run it.
  76
  77 Git Cola is designed to run directly from its source tree. Installation is optional.
  78
  79
  80 ## From Source
  81
  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.
  85
  86
  87 ## Installing PyQt dependencies on Debian / Ubuntu systems
  88
  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.
  91
  92 ### PyQt5
  93
  94 Users on newer Debian/Ubuntu version can install a single package to run from source.
  95
  96 ```bash
  97 sudo apt install python3-qtpy
  98 ```
  99
 100 If you are on an older version that does not have `python3-qtpy` available then you can
 101 install the following packages directly.
 102
 103 ```bash
 104 sudo apt install python3-pyqt5 python3-pyqt5.qtopengl python3-pyqt5.qtwebengine python3-pyqt5.qtsvg
 105 ```
 106
 107 ### PyQt6
 108
 109 If you'd like to use Git Cola with the newer PyQt6 ecosystem then you can install these
 110 packages instead of PyQt5.
 111
 112 ```bash
 113 sudo apt install python3-pyqt6 python3-pyqt6.qtsvg python3-pyqt6.qtwebengine
 114 ```
 115
 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.
 118
 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.
 121
 122
 123 ## Linux
 124
 125 Linux is it! Your distro has probably already packaged `git-cola`.
 126 If not, please file a bug against your distribution ;-)
 127
 128 ### Arch
 129
 130 Available in the [AUR](https://aur.archlinux.org/packages/git-cola/).
 131
 132 ### Debian, Ubuntu
 133
 134     apt install git-cola
 135
 136 ### Fedora
 137
 138     dnf install git-cola
 139
 140 ### Gentoo
 141
 142     emerge git-cola
 143
 144 ### OpenSUSE, SLE
 145
 146     zypper install git-cola
 147
 148 ### Slackware
 149
 150 Available in [SlackBuilds.org](http://slackbuilds.org/result/?search=git-cola).
 151
 152 ### Ubuntu
 153
 154 [See here](https://packages.ubuntu.com/search?keywords=git-cola) for the
 155 versions that are available in Ubuntu's repositories.
 156
 157 ## FreeBSD
 158
 159     # Install from official binary packages
 160     pkg install -r FreeBSD devel/git-cola
 161
 162     # Build from source
 163     cd /usr/ports/devel/git-cola && make clean install
 164
 165 ## Install into a Python Virtualenv from PyPI using pip
 166
 167 **IMPORTANT**: never run `pip install` or `garden install` outside of a
 168 Python virtualenv or as root!
 169
 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.
 173
 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/).
 176
 177     python3 -m venv --system-site-packages env3
 178     ./env3/bin/pip install git-cola
 179     ./env3/bin/git-cola
 180
 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:
 184
 185     git cola
 186     git dag
 187
 188
 189 ## Install into a Python Virtualenv from Source
 190
 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. This install method
 193 lets you upgrade Git Cola by running `git pull`.
 194
 195     # Create a virtualenv called "env3" and activate it.
 196     python3 -m venv --system-site-packages env3
 197     source env3/bin/activate
 198
 199     # One-time setup: install dev and optional runtime requirements
 200     garden requirements/dev
 201     garden requirements/opt
 202
 203     # Install git-cola in "editable" mode so that it uses the source tree.
 204     garden develop
 205
 206     # Run Git Cola via the "git-cola" Git subcommand.
 207     git cola
 208
 209
 210 If you add `env3/bin` (or symlink to `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 (eg. after running "deactivate" or when opening a new shell).
 213
 214
 215 ## Standalone Installation from Source
 216
 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).
 219
 220 This installation method assumes that the `qtpy` and `PyQt*` dependencies have
 221 been pre-installed.
 222
 223 The Garden recipe also supports `DESTDIR` to support creating packages for Linux package
 224 managers:
 225
 226     garden -D DESTDIR=/tmp/stage -D prefix=/usr/local install
 227
 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)
 232 variables.
 233
 234     make DESTDIR=/tmp/stage prefix=/usr/local install
 235
 236
 237 ## macOS
 238
 239 For most end-users we recommend using either Homebrew or installing into
 240 a Python virtualenv as described above.
 241
 242 You can install Git Cola from source using the same steps as above.
 243
 244 ### Homebrew
 245
 246 An easy way to install Git Cola is to use [Homebrew](https://brew.sh/) .
 247 Use Homebrew to install the git-cola recipe:
 248
 249     brew install git-cola
 250
 251 If you install using Homebrew you can stop at this step.
 252 You don't need to clone the repo or anything.
 253
 254 ### git-cola.app
 255
 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`.
 258
 259 If you'd like to build a `git-cola.app` bundle for `/Applications` run this command:
 260
 261     garden macos/app
 262
 263 You will need to periodically rebuild the app wrapper whenever Python is upgraded.
 264
 265 ### Updating macOS and Homebrew
 266
 267 Updating macOS can often break Homebrew-managed software.
 268
 269 If you upgrade your macOS version and Git Cola no longer runs then then it is
 270 recommended that you re-install Git Cola's dependencies after upgrading.
 271
 272 A quick fix when upgrading to newer versions of XCode or macOS is to
 273 reinstall pyqt5.
 274
 275     brew reinstall pyqt@5
 276
 277 You may also need to relink your pyqt installation:
 278
 279     brew link pyqt@5
 280
 281 This is required when upgrading to a modern (post-10.11 El Capitan) Mac OS X.
 282 Homebrew now bundles its own Python3 installation instead of using the
 283 system-provided default Python.
 284
 285 If the "brew reinstall" command above does not work then re-installing from
 286 scratch using the instructions below should get things back in shape.
 287
 288     # update homebrew
 289     brew update
 290
 291     # uninstall git-cola and its dependencies
 292     brew uninstall git-cola
 293     brew uninstall pyqt5
 294     brew uninstall sip
 295
 296     # re-install git-cola and its dependencies
 297     brew install git-cola
 298
 299
 300 ## Windows
 301
 302 IMPORTANT If you have a 64-bit machine, install the 64-bit versions only.
 303 Do not mix 32-bit and 64-bit versions.
 304
 305 Download and install the following:
 306
 307 * [Git for Windows](https://git-for-windows.github.io/)
 308
 309 * [Git Cola](https://github.com/git-cola/git-cola/releases)
 310
 311 Once these are installed you can run Git Cola from the Start menu.
 312
 313 See "Windows (Continued)" below for more details.
 314
 315 If you'd like to install Git Cola with
 316 [winget](https://github.com/microsoft/winget-cli) run the following command:
 317
 318     winget install git-cola.git-cola
 319
 320 As there is no dependency resolution yet you have to install Git as well with:
 321
 322     winget install Git.Git
 323
 324 # Goodies
 325
 326 Git Cola ships with an interactive rebase editor called `git-cola-sequence-editor`.
 327 `git-cola-sequence-editor` is used to reorder and choose commits when rebasing.
 328 Start an interactive rebase through the "Rebase" menu, or through the
 329 `git cola rebase` sub-command to use the `git-cola-sequence-editor`:
 330
 331     git cola rebase @{upstream}
 332
 333 `git-cola-sequence-editor` can be launched independently of git cola by telling
 334 `git rebase` to use it as its editor through the `GIT_SEQUENCE_EDITOR`
 335 environment variable:
 336
 337     export GIT_SEQUENCE_EDITOR="$HOME/git-cola/bin/git-cola-sequence-editor"
 338     git rebase -i @{upstream}
 339
 340 ## Shell Completions
 341
 342 Shell completion scripts are available for bash and zsh.
 343 Each script contains instructions on how to install and activate the completions.
 344
 345 * [bash completion script](contrib/git-cola-completion.bash)
 346
 347 * [zsh completion script](contrib/_git-cola)
 348
 349
 350 # Git Cola Sub-commands
 351
 352 The `git-cola` command exposes various sub-commands that allow you to quickly
 353 launch tools that are available from within the git-cola interface.
 354 For example, `git cola find` launches the file finder,
 355 and `git cola grep` launches the grep tool.
 356
 357 See `git cola --help-commands` for the full list of commands.
 358
 359     $ git cola --help-commands
 360     usage: git-cola [-h]
 361
 362                     {cola,am,archive,branch,browse,config,
 363                      dag,diff,fetch,find,grep,merge,pull,push,
 364                      rebase,remote,search,stash,tag,version}
 365                     ...
 366
 367     valid commands:
 368       {cola,am,archive,branch,browse,config,
 369        dag,diff,fetch,find,grep,merge,pull,push,
 370        rebase,remote,search,stash,tag,version}
 371
 372         cola                start git-cola
 373         am                  apply patches using "git am"
 374         archive             save an archive
 375         branch              create a branch
 376         browse              browse repository
 377         config              edit configuration
 378         dag                 start git-dag
 379         diff                view diffs
 380         fetch               fetch remotes
 381         find                find files
 382         grep                grep source
 383         merge               merge branches
 384         pull                pull remote branches
 385         push                push remote branches
 386         rebase              interactive rebase
 387         remote              edit remotes
 388         search              search commits
 389         stash               stash and unstash changes
 390         tag                 create tags
 391         version             print the version
 392
 393 ## Development
 394
 395 If you already have Git Cola's dependencies installed then you can
 396 start `cola` as a Python module if you have the source code available.
 397
 398     python -m cola
 399     python -m cola dag
 400
 401
 402 The following commands should be run during development:
 403
 404     # Run the unit tests
 405     $ garden test
 406
 407     # Run tests and longer-running pylint checks
 408     $ garden check
 409
 410     # Run tests against multiple python interpreters using tox
 411     $ garden tox
 412
 413 The test suite can be found in the [test](test) directory.
 414
 415 Commits and pull requests are automatically tested for code quality
 416 using [GitHub Actions](https://github.com/git-cola/git-cola/actions/workflows/main.yml).
 417
 418 Auto-format `cola/i18n/*.po` files before committing when updating translations:
 419
 420     $ garden po
 421
 422 When submitting patches, consult the
 423 [contributing guidelines](CONTRIBUTING.md).
 424
 425
 426 ## Packaging Notes
 427
 428 Git Cola installs its modules into the default Python site-packages directory
 429 (eg. `lib/python3.7/site-packages`) using setuptools.
 430
 431 While end-users can use `pip install git-cola` to install Git Cola, distribution
 432 packagers should use the `garden -D prefix=/usr install` process. Git Cola's Garden
 433 recipe wraps `pip install --prefix=<prefix>` to provide a packaging-friendly
 434 `garden install` target.
 435
 436
 437 # Windows (Continued)
 438
 439 ## Microsoft Visual C++ 2015 Redistributable
 440
 441 Earlier versions of Git Cola may have shipped without `vcruntime140.dll`  and may
 442 not run on machines that are missing this DLL.
 443
 444 To fix this, download the
 445 [Microsoft Visual C++ 2015 Redistributable](https://www.microsoft.com/en-us/download/details.aspx?id=52685)
 446 and install it
 447
 448 Git Cola v4.0.0 and newer include this DLL and do not require this to be installed
 449 separately.
 450
 451 ## Development
 452
 453 In order to develop Git Cola on Windows you will need to install
 454 Python3 and pip.  Install PyQt5 using `pip install PyQt5`
 455 to make the PyQt5 bindings available to Python.
 456
 457 Once these are installed you can use `python.exe` to run
 458 directly from the source tree.  For example, from a Git Bash terminal:
 459
 460     /c/Python39/python.exe ./bin/git-cola
 461
 462 ## Multiple Python versions
 463
 464 If you have multiple versions of Python installed, the `contrib/win32/cola`
 465 launcher script might choose the newer version instead of the python
 466 that has PyQt installed.  In order to resolve this, you can set the
 467 `cola.pythonlocation` git configuration variable to tell cola where to
 468 find python.  For example:
 469
 470     git config --global cola.pythonlocation /c/Python39
 471
 472 ## Building Windows Installers
 473
 474 Windows installers are built using
 475
 476 * [Pynsist](https://pynsist.readthedocs.io/en/latest/).
 477
 478 * [NSIS](http://nsis.sourceforge.net/Main_Page) is also needed.
 479
 480 To build the installer using Pynsist run:
 481
 482     ./contrib/win32/run-pynsist.sh
 483
 484 This will generate an installer in `build/nsis/`.
 485
 486 ## Windows "History Browser" Configuration Upgrade
 487
 488 You may need to configure your history browser if you are upgrading from an
 489 older version of Git Cola on Windows.
 490
 491 `gitk` was originally the default history browser, but `gitk` cannot be
 492 launched as-is on Windows because `gitk` is a shell script.
 493
 494 If you are configured to use `gitk`, then change your configuration to
 495 go through Git's `sh.exe` on Windows.  Similarly, we must go through
 496 `python.exe` if we want to use `git-dag`.
 497
 498 If you want to use gitk as your history browser open the
 499 Preferences screen and change the history browser command to:
 500
 501     "C:/Program Files/Git/bin/sh.exe" --login -i C:/Git/bin/gitk
 502
 503 `git-dag` became the default history browser on Windows in `v2.3`, so new
 504 users do not need to configure anything.