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