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