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