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 `pyqt6` 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     python3 -m venv --system-site-packages env3
 129     ./env3/bin/pip install git-cola
 130     ./env3/bin/git-cola
 131
 132 Add the `env3/bin` directory to your `$PATH`, or symlink to `bin/git-cola` from
 133 somewhere in your `$PATH` such as `~/.local/bin/git-cola`, and you can launch
 134 Git Cola like any other built-in `git` command:
 135
 136     git cola
 137     git dag
 138
 139
 140 ## Install into a Python Virtualenv from Source
 141
 142 If you don't have PyQt installed then the easiest way to get it is to use a Python
 143 virtualenv and install Git Cola into it in "editable" mode. This install method
 144 lets you upgrade Git Cola by running `git pull`.
 145
 146     # Create a virtualenv called "env3" and activate it.
 147     python3 -m venv --system-site-packages env3
 148     source env3/bin/activate
 149
 150     # One-time setup: install optional requirements for development.
 151     make requirements-dev requirements-optional
 152
 153     # Install git-cola in "editable" mode so that it uses the source tree.
 154     make develop
 155
 156     # Run Git Cola via the "git-cola" Git subcommand.
 157     git cola
 158
 159
 160 If you add `env3/bin` (or symlink to `bin/git-cola` ) to your `$PATH` then you can
 161 run `git cola` as if it were a builtin `git` command from outside of the virtualenv
 162 (eg. after running "deactivate" or when opening a new shell).
 163
 164
 165 ## Standalone Installation from Source
 166
 167 Running `make install prefix=$HOME/.local` will install Git Cola in your
 168 `$HOME/.local` directory (`$HOME/.local/bin/git-cola`, `$HOME/.local/lib`, etc).
 169
 170 This installation method assumes that the `qtpy` and `PyQt*` dependencies have
 171 been pre-installed.
 172
 173 The `Makefile` also supports `DESTDIR` to support creating packages for Linux package
 174 managers:
 175
 176     make DESTDIR=/tmp/stage prefix=/usr/local install
 177
 178
 179 ## macOS
 180
 181 For most end-users we recommend using either Homebrew or installing into
 182 a Python virtualenv as described above.
 183
 184 You can install Git Cola from source using the same steps as above.
 185
 186 ### Homebrew
 187
 188 An easy way to install Git Cola is to use [Homebrew](https://brew.sh/) .
 189 Use Homebrew to install the git-cola recipe:
 190
 191     brew install git-cola
 192
 193 If you install using Homebrew you can stop at this step.
 194 You don't need to clone the repo or anything.
 195
 196 ### git-cola.app
 197
 198 If you have all of the dependencies installed, either via `pip` or `brew` then
 199 you can build a shell `git-cola.app` app bundle wrapper for use in `/Applications`.
 200
 201 If you'd like to build a `git-cola.app` bundle for `/Applications` run this command:
 202
 203     make git-cola.app
 204
 205 You will need to periodically rebuild the app wrapper whenever Python is upgraded.
 206
 207 ### Updating macOS and Homebrew
 208
 209 Updating macOS can often break Homebrew-managed software.
 210
 211 If you upgrade your macOS version and Git Cola no longer runs then then it is
 212 recommended that you re-install Git Cola's dependencies after upgrading.
 213
 214 A quick fix when upgrading to newer versions of XCode or macOS is to
 215 reinstall pyqt5.
 216
 217     brew reinstall pyqt@5
 218
 219 You may also need to relink your pyqt installation:
 220
 221     brew link pyqt@5
 222
 223 This is required when upgrading to a modern (post-10.11 El Capitan) Mac OS X.
 224 Homebrew now bundles its own Python3 installation instead of using the
 225 system-provided default Python.
 226
 227 If the "brew reinstall" command above does not work then re-installing from
 228 scratch using the instructions below should get things back in shape.
 229
 230     # update homebrew
 231     brew update
 232
 233     # uninstall git-cola and its dependencies
 234     brew uninstall git-cola
 235     brew uninstall pyqt5
 236     brew uninstall sip
 237
 238     # re-install git-cola and its dependencies
 239     brew install git-cola
 240
 241
 242 ## Windows
 243
 244 IMPORTANT If you have a 64-bit machine, install the 64-bit versions only.
 245 Do not mix 32-bit and 64-bit versions.
 246
 247 Download and install the following:
 248
 249 * [Git for Windows](https://git-for-windows.github.io/)
 250
 251 * [Git Cola](https://github.com/git-cola/git-cola/releases)
 252
 253 Once these are installed you can run Git Cola from the Start menu.
 254
 255 See "Windows (Continued)" below for more details.
 256
 257
 258 # Goodies
 259
 260 Git Cola ships with an interactive rebase editor called `git-cola-sequence-editor`.
 261 `git-cola-sequence-editor` is used to reorder and choose commits when rebasing.
 262 Start an interactive rebase through the "Rebase" menu, or through the
 263 `git cola rebase` sub-command to use the `git-cola-sequence-editor`:
 264
 265     git cola rebase @{upstream}
 266
 267 `git-cola-sequence-editor` can be launched independently of git cola by telling
 268 `git rebase` to use it as its editor through the `GIT_SEQUENCE_EDITOR`
 269 environment variable:
 270
 271     export GIT_SEQUENCE_EDITOR="$HOME/git-cola/bin/git-cola-sequence-editor"
 272     git rebase -i @{upstream}
 273
 274
 275 # Git Cola Sub-commands
 276
 277 The `git-cola` command exposes various sub-commands that allow you to quickly
 278 launch tools that are available from within the git-cola interface.
 279 For example, `git cola find` launches the file finder,
 280 and `git cola grep` launches the grep tool.
 281
 282 See `git cola --help-commands` for the full list of commands.
 283
 284     $ git cola --help-commands
 285     usage: git-cola [-h]
 286
 287                     {cola,am,archive,branch,browse,config,
 288                      dag,diff,fetch,find,grep,merge,pull,push,
 289                      rebase,remote,search,stash,tag,version}
 290                     ...
 291
 292     valid commands:
 293       {cola,am,archive,branch,browse,config,
 294        dag,diff,fetch,find,grep,merge,pull,push,
 295        rebase,remote,search,stash,tag,version}
 296
 297         cola                start git-cola
 298         am                  apply patches using "git am"
 299         archive             save an archive
 300         branch              create a branch
 301         browse              browse repository
 302         config              edit configuration
 303         dag                 start git-dag
 304         diff                view diffs
 305         fetch               fetch remotes
 306         find                find files
 307         grep                grep source
 308         merge               merge branches
 309         pull                pull remote branches
 310         push                push remote branches
 311         rebase              interactive rebase
 312         remote              edit remotes
 313         search              search commits
 314         stash               stash and unstash changes
 315         tag                 create tags
 316         version             print the version
 317
 318 ## Development
 319
 320 If you already have Git Cola's dependencies installed then you can
 321 start `cola` as a Python module if you have the source code available.
 322
 323     python -m cola
 324     python -m cola dag
 325
 326
 327 The following commands should be run during development:
 328
 329     # Run the unit tests
 330     $ make test
 331
 332     # Run tests and longer-running pylint and flake8 checks
 333     $ make check
 334
 335     # Run tests against multiple python interpreters using tox
 336     $ make tox
 337
 338 The test suite can be found in the [test](test) directory.
 339
 340 Commits and pull requests are automatically tested for code quality
 341 using [GitHub Actions](https://github.com/git-cola/git-cola/actions/workflows/main.yml).
 342
 343 Auto-format `cola/i18n/*.po` files before committing when updating translations:
 344
 345     $ make po
 346
 347 When submitting patches, consult the
 348 [contributing guidelines](CONTRIBUTING.md).
 349
 350
 351 ## Packaging Notes
 352
 353 Git Cola installs its modules into the default Python site-packages directory
 354 (eg. `lib/python3.7/site-packages`) using setuptools.
 355
 356 While end-users can use `pip install git-cola` to install Git Cola, distribution
 357 packagers should use the `make prefix=/usr` install process. Git Cola's `Makefile` wraps
 358 `pip install --prefix=<prefix>` to provide a packaging-friendly `make install` target.
 359
 360
 361 # Windows (Continued)
 362
 363 ## Microsoft Visual C++ 2015 Redistributable
 364
 365 Earlier versions of Git Cola may have shipped without `vcruntime140.dll`  and may
 366 not run on machines that are missing this DLL.
 367
 368 To fix this, download the
 369 [Microsoft Visual C++ 2015 Redistributable](https://www.microsoft.com/en-us/download/details.aspx?id=52685)
 370 and install it
 371
 372 Git Cola v4.0.0 and newer include this DLL and do not require this to be installed
 373 separately.
 374
 375 ## Development
 376
 377 In order to develop Git Cola on Windows you will need to install
 378 Python3 and pip.  Install PyQt5 using `pip install PyQt5`
 379 to make the PyQt5 bindings available to Python.
 380
 381 Once these are installed you can use `python.exe` to run
 382 directly from the source tree.  For example, from a Git Bash terminal:
 383
 384     /c/Python36/python.exe ./bin/git-cola
 385
 386 ## Multiple Python versions
 387
 388 If you have multiple versions of Python installed, the `contrib/win32/cola`
 389 launcher script might choose the newer version instead of the python
 390 that has PyQt installed.  In order to resolve this, you can set the
 391 `cola.pythonlocation` git configuration variable to tell cola where to
 392 find python.  For example:
 393
 394     git config --global cola.pythonlocation /c/Python39
 395
 396 ## Building Windows Installers
 397
 398 Windows installers are built using
 399
 400 * [Pynsist](https://pynsist.readthedocs.io/en/latest/).
 401
 402 * [NSIS](http://nsis.sourceforge.net/Main_Page) is also needed.
 403
 404 To build the installer using Pynsist run:
 405
 406     ./contrib/win32/run-pynsist.sh
 407
 408 This will generate an installer in `build/nsis/`.
 409
 410 ## Windows "History Browser" Configuration Upgrade
 411
 412 You may need to configure your history browser if you are upgrading from an
 413 older version of Git Cola on Windows.
 414
 415 `gitk` was originally the default history browser, but `gitk` cannot be
 416 launched as-is on Windows because `gitk` is a shell script.
 417
 418 If you are configured to use `gitk`, then change your configuration to
 419 go through Git's `sh.exe` on Windows.  Similarly, we must go through
 420 `python.exe` if we want to use `git-dag`.
 421
 422 If you want to use gitk as your history browser open the
 423 Preferences screen and change the history browser command to:
 424
 425     "C:/Program Files/Git/bin/sh.exe" --login -i C:/Git/bin/gitk
 426
 427 `git-dag` became the default history browser on Windows in `v2.3`, so new
 428 users do not need to configure anything.