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