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