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