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