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) 2.0.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.9 or newer is required. Qt 6.2 or newer is also supported via QtPy.
  53
  54 * [PySide2](https://github.com/PySide/PySide)
  55   5.12.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 [notify_py](https://pypi.org/project/notify_py/)
  68 enables delivery of desktop notifications.
  69 ([source](https://github.com/ms7m/notify-py))
  70
  71 [pyobjc](https://pypi.org/project/pyobjc/)
  72 enables macOS-specific application themes on macOS.
  73 ([source](https://github.com/ronaldoussoren/pyobjc))
  74
  75
  76 # Installation
  77
  78 There are several ways to install Git Cola but you do not need to "install" Git Cola
  79 in order to run it.
  80
  81 Git Cola is designed to run directly from its source tree. Installation is optional.
  82
  83
  84 ## From Source
  85
  86 The recommended approach for running the latest Git Cola version is to install its
  87 PyQt dependencies using your distribution's package manager and then run
  88 `./bin/git-cola` directly from source.
  89
  90
  91 ## Installing PyQt dependencies on Debian / Ubuntu systems
  92
  93 Git Cola works with either PyQt5 or PyQt6 because it uses the
  94 [qtpy](https://github.com/spyder-ide/qtpy) library for PyQt compatibility.
  95
  96 ### PyQt5
  97
  98 Users on newer Debian/Ubuntu version can install a single package to run from source.
  99
 100 ```bash
 101 sudo apt install python3-qtpy
 102 ```
 103
 104 If you are on an older version that does not have `python3-qtpy` available then you can
 105 install the following packages directly.
 106
 107 ```bash
 108 sudo apt install python3-pyqt5 python3-pyqt5.qtopengl python3-pyqt5.qtwebengine python3-pyqt5.qtsvg
 109 ```
 110
 111 ### PyQt6
 112
 113 If you'd like to use Git Cola with the newer PyQt6 ecosystem then you can install these
 114 packages instead of PyQt5.
 115
 116 ```bash
 117 sudo apt install python3-pyqt6 python3-pyqt6.qtsvg python3-pyqt6.qtwebengine
 118 ```
 119
 120 At this point you should be able to launch `./bin/git-cola` from the source tree and
 121 there is nothing more to do.
 122
 123 The further instructions below detail how to install Git Cola from PyPI or how to
 124 install it into a location separate from the source tree.
 125
 126
 127 ## Linux
 128
 129 Linux is it! Your distro has probably already packaged `git-cola`.
 130 If not, please file a bug against your distribution ;-)
 131
 132 ### Arch
 133
 134 Available in the [AUR](https://aur.archlinux.org/packages/git-cola/).
 135
 136 ### Debian, Ubuntu
 137
 138     apt install git-cola
 139
 140 ### Fedora
 141
 142     dnf install git-cola
 143
 144 ### Gentoo
 145
 146     emerge git-cola
 147
 148 ### OpenSUSE, SLE
 149
 150     zypper install git-cola
 151
 152 ### Slackware
 153
 154 Available in [SlackBuilds.org](http://slackbuilds.org/result/?search=git-cola).
 155
 156 ### Ubuntu
 157
 158 [See here](https://packages.ubuntu.com/search?keywords=git-cola) for the
 159 versions that are available in Ubuntu's repositories.
 160
 161 ## FreeBSD
 162
 163     # Install from official binary packages
 164     pkg install -r FreeBSD devel/git-cola
 165
 166     # Build from source
 167     cd /usr/ports/devel/git-cola && make clean install
 168
 169 ## Install into a Python Virtualenv from PyPI using pip
 170
 171 **IMPORTANT**: never run `pip install` or `garden install` outside of a
 172 Python virtualenv or as root!
 173
 174 **IMPORTANT**: if you are on Linux distributions where PyQt6 or PyQt5 are available from
 175 your package manager then it is highly recommended to install those dependencies using
 176 your system's package manager. See the section above for details.
 177
 178 One way to install the latest released version is to use `venv` (virtualenv) and `pip`.
 179 This installs [git-cola from pypi.org](https://pypi.org/project/git-cola/).
 180
 181     python3 -m venv --system-site-packages env3
 182     ./env3/bin/pip install git-cola
 183     ./env3/bin/git-cola
 184
 185 Add the `env3/bin` directory to your `PATH` or symlink to `bin/git-cola` from
 186 somewhere in your `PATH` such as `~/.local/bin/git-cola`, and you can launch
 187 Git Cola like any other built-in `git` command:
 188
 189     git cola
 190     git dag
 191
 192
 193 ## Install into a Python Virtualenv from Source
 194
 195 If you don't have PyQt installed then the easiest way to get it is to use a Python
 196 virtualenv and install Git Cola into it in "editable" mode.
 197
 198 This install method lets you upgrade Git Cola by running `git pull`.
 199
 200     # Create a virtualenv called "env3" and activate it.
 201     python3 -m venv --system-site-packages env3
 202
 203     # Install PyQt and (optional) extra packages to enable all features.
 204     ./env3/bin/pip install --editable '.[extras,pyqt6]'
 205
 206     # Run Git Cola via the "git-cola" Git subcommand.
 207     source env3/bin/activate
 208     git cola
 209
 210 If you add `env3/bin` (or symlink to `env3/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 (e.g. 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 update macOS and Git Cola stops working then then you probably need to re-install
 270 Git Cola's dependencies.
 271
 272 Re-installing from scratch using the instructions below can get things back in shape.
 273
 274     brew update
 275
 276     brew uninstall git-cola
 277     brew uninstall pyqt
 278     brew uninstall pyqt@5
 279     brew autoremove
 280
 281     brew install git-cola
 282
 283
 284 ## Windows
 285
 286 IMPORTANT If you have a 64-bit machine, install the 64-bit versions only.
 287 Do not mix 32-bit and 64-bit versions.
 288
 289 Download and install the following:
 290
 291 * [Git for Windows](https://git-for-windows.github.io/)
 292
 293 * [Git Cola](https://github.com/git-cola/git-cola/releases)
 294
 295 Once these are installed you can run Git Cola from the Start menu.
 296
 297 See "Windows (Continued)" below for more details.
 298
 299 If you'd like to install Git Cola with
 300 [winget](https://github.com/microsoft/winget-cli) run the following command:
 301
 302     winget install git-cola.git-cola
 303
 304 As there is no dependency resolution yet you have to install Git as well with:
 305
 306     winget install Git.Git
 307
 308 # Goodies
 309
 310 Git Cola ships with an interactive rebase editor called `git-cola-sequence-editor`.
 311 `git-cola-sequence-editor` is used to reorder and choose commits when rebasing.
 312 Start an interactive rebase through the "Rebase" menu, or through the
 313 `git cola rebase` sub-command to use the `git-cola-sequence-editor`:
 314
 315     git cola rebase @{upstream}
 316
 317 `git-cola-sequence-editor` can be launched independently of git cola by telling
 318 `git rebase` to use it as its editor through the `GIT_SEQUENCE_EDITOR`
 319 environment variable:
 320
 321     export GIT_SEQUENCE_EDITOR="$HOME/git-cola/bin/git-cola-sequence-editor"
 322     git rebase -i @{upstream}
 323
 324 ## Shell Completions
 325
 326 Shell completion scripts are available for bash and zsh.
 327 Each script contains instructions on how to install and activate the completions.
 328
 329 * [bash completion script](contrib/git-cola-completion.bash)
 330
 331 * [zsh completion script](contrib/_git-cola)
 332
 333
 334 # Git Cola Sub-commands
 335
 336 The `git-cola` command exposes various sub-commands that allow you to quickly
 337 launch tools that are available from within the git-cola interface.
 338 For example, `git cola find` launches the file finder,
 339 and `git cola grep` launches the grep tool.
 340
 341 See `git cola --help-commands` for the full list of commands.
 342
 343     $ git cola --help-commands
 344     usage: git-cola [-h]
 345
 346                     {cola,am,archive,branch,browse,config,
 347                      dag,diff,fetch,find,grep,merge,pull,push,
 348                      rebase,remote,search,stash,tag,version}
 349                     ...
 350
 351     valid commands:
 352       {cola,am,archive,branch,browse,config,
 353        dag,diff,fetch,find,grep,merge,pull,push,
 354        rebase,remote,search,stash,tag,version}
 355
 356         cola                start git-cola
 357         am                  apply patches using "git am"
 358         archive             save an archive
 359         branch              create a branch
 360         browse              browse repository
 361         config              edit configuration
 362         dag                 start git-dag
 363         diff                view diffs
 364         fetch               fetch remotes
 365         find                find files
 366         grep                grep source
 367         merge               merge branches
 368         pull                pull remote branches
 369         push                push remote branches
 370         rebase              interactive rebase
 371         remote              edit remotes
 372         search              search commits
 373         stash               stash and unstash changes
 374         tag                 create tags
 375         version             print the version
 376
 377 ## Development
 378
 379 If you already have Git Cola's dependencies installed then you can
 380 start `cola` as a Python module if you have the source code available.
 381
 382     python -m cola
 383     python -m cola dag
 384
 385
 386 The following commands should be run during development:
 387
 388     # Run the unit tests
 389     $ garden test
 390
 391     # Run tests and doc checks
 392     $ garden check
 393
 394     # Run tests against multiple python interpreters using tox
 395     $ garden tox
 396
 397 The test suite can be found in the [test](test) directory.
 398
 399 Commits and pull requests are automatically tested for code quality
 400 using [GitHub Actions](https://github.com/git-cola/git-cola/actions/workflows/main.yml).
 401
 402 Auto-format `cola/i18n/*.po` files before committing when updating translations:
 403
 404     $ garden po
 405
 406 When submitting patches, consult the
 407 [contributing guidelines](CONTRIBUTING.md).
 408
 409
 410 ## Packaging Notes
 411
 412 Git Cola installs its modules into the default Python site-packages directory
 413 (e.g. `lib/python3.7/site-packages`) using setuptools.
 414
 415 While end-users can use `pip install git-cola` to install Git Cola, distribution
 416 packagers should use the `garden -D prefix=/usr install` process. Git Cola's Garden
 417 recipe wraps `pip install --prefix=<prefix>` to provide a packaging-friendly
 418 `garden install` target.
 419
 420
 421 # Windows (Continued)
 422
 423 ## Microsoft Visual C++ 2015 Redistributable
 424
 425 Earlier versions of Git Cola may have shipped without `vcruntime140.dll`  and may
 426 not run on machines that are missing this DLL.
 427
 428 To fix this, download the
 429 [Microsoft Visual C++ 2015 Redistributable](https://www.microsoft.com/en-us/download/details.aspx?id=52685)
 430 and install it
 431
 432 Git Cola v4.0.0 and newer include this DLL and do not require this to be installed
 433 separately.
 434
 435 ## Development
 436
 437 In order to develop Git Cola on Windows you will need to install
 438 Python3 and pip.  Install PyQt5 using `pip install PyQt5`
 439 to make the PyQt5 bindings available to Python.
 440
 441 Once these are installed you can use `python.exe` to run
 442 directly from the source tree.  For example, from a Git Bash terminal:
 443
 444     /c/Python39/python.exe ./bin/git-cola
 445
 446 ## Multiple Python versions
 447
 448 If you have multiple versions of Python installed, the `contrib/win32/cola`
 449 launcher script might choose the newer version instead of the python
 450 that has PyQt installed.  In order to resolve this, you can set the
 451 `cola.pythonlocation` git configuration variable to tell cola where to
 452 find python.  For example:
 453
 454     git config --global cola.pythonlocation /c/Python39
 455
 456 ## Building Windows Installers
 457
 458 Windows installers are built using
 459
 460 * [Pynsist](https://pynsist.readthedocs.io/en/latest/).
 461
 462 * [NSIS](http://nsis.sourceforge.net/Main_Page) is also needed.
 463
 464 To build the installer using Pynsist run:
 465
 466     ./contrib/win32/run-pynsist.sh
 467
 468 This will generate an installer in `build/nsis/`.
 469
 470 ## Windows "History Browser" Configuration Upgrade
 471
 472 You may need to configure your history browser if you are upgrading from an
 473 older version of Git Cola on Windows.
 474
 475 `gitk` was originally the default history browser, but `gitk` cannot be
 476 launched as-is on Windows because `gitk` is a shell script.
 477
 478 If you are configured to use `gitk`, then change your configuration to
 479 go through Git's `sh.exe` on Windows.  Similarly, we must go through
 480 `python.exe` if we want to use `git-dag`.
 481
 482 If you want to use gitk as your history browser open the
 483 Preferences screen and change the history browser command to:
 484
 485     "C:/Program Files/Git/bin/sh.exe" --login -i C:/Git/bin/gitk
 486
 487 `git-dag` became the default history browser on Windows in `v2.3`, so new
 488 users do not need to configure anything.