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