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 * [HTML documentation](https://git-cola.readthedocs.io/en/latest/)
  17
  18 * [Git Cola documentation](share/doc/git-cola/git-cola.rst)
  19
  20 * [Git DAG documentation](share/doc/git-cola/git-dag.rst)
  21
  22 * [Keyboard shortcuts](https://git-cola.github.io/share/doc/git-cola/hotkeys.html)
  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 PyQt5 and PySide2 by setting
  42 the `QT_API` environment variable to `pyqt5` or `pyside2` as desired.
  43 `qtpy` defaults to `pyqt5` and falls back to `pyside2` if `pyqt5` is not installed.
  44
  45 Any of the following Python Qt libraries must be installed:
  46
  47 * [PyQt5](https://www.riverbankcomputing.com/software/pyqt/download5)
  48   5.6 or newer.
  49
  50 * [PySide2](https://github.com/PySide/PySide)
  51   5.11.0 or newer.
  52
  53 Set `QT_API=pyqt4` in your environment if you have both
  54 versions of PyQt installed and want to ensure that PyQt4 is used.
  55
  56 ## Optional Features
  57
  58 Git Cola enables additional features when the following
  59 Python modules are installed.
  60
  61 [send2trash](https://github.com/hsoft/send2trash) enables cross-platform
  62 "Send to Trash" functionality.
  63
  64
  65 # How to Install Git Cola
  66
  67 ## Run from Source
  68
  69 You can run Git Cola directly from its source tree and try the latest version
  70 without needing to `make install` it.
  71
  72     git clone https://github.com/git-cola/git-cola
  73     cd git-cola
  74     ./bin/git-cola
  75     ./bin/git-dag
  76
  77 You can also start `cola` as a Python module if Python can find it.
  78
  79     cd git-cola
  80     python -m cola
  81     python -m cola dag
  82
  83 Having git-cola's `bin/` directory in your path allows you to run
  84 `git cola` like a regular built-in Git command:
  85
  86     # Replace "$HOME/git-cola/bin" with the path to git-cola's bin/ directory
  87     PATH="$HOME/git-cola/bin":"$PATH"
  88     export PATH
  89
  90     git cola
  91     git dag
  92
  93 The instructions below assume that you have git-cola present in your
  94 `$PATH`.  Replace `git cola` with `./bin/git-cola` to run it in-place.
  95
  96 ## Python Virtual Environments
  97
  98 If you don't have PyQt installed then the easiest way to get it is to use a Python
  99 virtualenv and install PyQt5 inside of it.
 100
 101     python3 -m venv env3
 102     ./env3/bin/pip install -r requirements/requirements.txt
 103
 104 You can then run Git Cola using the `env3` virtualenv.
 105
 106     ./env3/bin/python ./bin/git-cola
 107
 108 ## Standalone Installation
 109
 110 Running `make install` will install Git Cola in your `$HOME` directory
 111 (`$HOME/bin/git-cola`, `$HOME/share/git-cola`, etc).
 112
 113 If you want to do a global install you can do
 114
 115     make prefix=/usr install
 116
 117 Distutils is used by the `Makefile` via `setup.py` to install git-cola and
 118 its launcher scripts.  distutils replaces the `#!/usr/bin/env python` lines in
 119 scripts with the full path to python at build time, which can be undesirable
 120 when the runtime python is not the same as the build-time python.
 121
 122 To disable the replacement of the `#!/usr/bin/env python` lines, pass `USE_ENV_PYTHON=1`
 123 to `make`.
 124
 125 ## Linux
 126
 127 Linux is it! Your distro has probably already packaged git-cola.
 128 If not, please file a bug against your distribution ;-)
 129
 130 ### Arch
 131
 132 Available in the [AUR](https://aur.archlinux.org/packages/git-cola/).
 133
 134 ### Debian, Ubuntu
 135
 136     apt install git-cola
 137
 138 ### Fedora
 139
 140     dnf install git-cola
 141
 142 ### Gentoo
 143
 144     emerge git-cola
 145
 146 ### OpenSUSE, SLE
 147
 148     zypper install git-cola
 149
 150 ### Slackware
 151
 152 Available in [SlackBuilds.org](http://slackbuilds.org/result/?search=git-cola).
 153
 154 ### Ubuntu
 155
 156 [See here](https://packages.ubuntu.com/search?keywords=git-cola) for the
 157 versions that are available in Ubuntu's repositories.
 158
 159 There was a [PPA by @pavreh](https://launchpad.net/~pavreh/+archive/ubuntu/git-cola)
 160 but it has not been updated for a while.
 161
 162
 163 ## FreeBSD
 164
 165     # install from official binary packages
 166     pkg install -r FreeBSD devel/git-cola
 167
 168     # build from source
 169     cd /usr/ports/devel/git-cola && make clean install
 170
 171 ## macOS
 172
 173 [Homebrew](https://brew.sh/) is the easiest way to install
 174 Git Cola's PyQt5 dependencies.  We will use Homebrew to install
 175 the git-cola recipe, but build our own .app bundle from source.
 176
 177 [Sphinx](http://sphinx-doc.org/latest/install.html) is used to build the
 178 documentation.
 179
 180     brew install sphinx-doc
 181     brew install git-cola
 182
 183 Once brew has installed `git-cola` you can:
 184
 185 1. Clone the git-cola repositroy
 186
 187     git clone https://github.com/git-cola/git-cola
 188     cd git-cola
 189
 190 2. Build the git-cola.app application bundle
 191
 192     make \
 193         PYTHON=$(brew --prefix python3)/bin/python3 \
 194         PYTHON_CONFIG=$(brew --prefix python3)/bin/python3-config \
 195         SPHINXBUILD=$(brew --prefix sphinx-doc)/bin/sphinx-build \
 196         git-cola.app
 197
 198 3. Copy it to /Applications
 199
 200     rsync -ar --delete git-cola.app/ /Applications/git-cola.app/
 201
 202 Newer versions of Homebrew install their own `python3` installation and
 203 provide the `PyQt5` modules for `python3` only.  You have to use
 204 `python3 ./bin/git-cola` when running from the source tree.
 205
 206 ### Upgrading using Homebrew
 207
 208 If you upgrade using `brew` then it is recommended that you re-install
 209 Git Colaa's dependencies when upgrading.  Re-installing ensures that the
 210 Python modules provided by Homebrew will be properly set up.
 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 ## Windows
 240
 241 IMPORTANT If you have a 64-bit machine, install the 64-bit versions only.
 242 Do not mix 32-bit and 64-bit versions.
 243
 244 Download and install the following:
 245
 246 * [Git for Windows](https://git-for-windows.github.io/)
 247
 248 * [Git Cola](https://github.com/git-cola/git-cola/releases)
 249
 250 Once these are installed you can run Git Cola from the Start menu.
 251
 252 See "Windows (Continued)" below for more details.
 253
 254
 255 # Goodies
 256
 257 Git Cola ships with an interactive rebase editor called `git-cola-sequence-editor`.
 258 `git-cola-sequence-editor` is used to reorder and choose commits when rebasing.
 259 Start an interactive rebase through the "Rebase" menu, or through the
 260 `git cola rebase` sub-command to use the `git-cola-sequence-editor`:
 261
 262     git cola rebase @{upstream}
 263
 264 `git-cola-sequence-editor` can be launched independently of git cola by telling
 265 `git rebase` to use it as its editor through the `GIT_SEQUENCE_EDITOR`
 266 environment variable:
 267
 268     export GIT_SEQUENCE_EDITOR="$HOME/git-cola/bin/git-cola-sequence-editor"
 269     git rebase -i @{upstream}
 270
 271
 272 # Git Cola Sub-commands
 273
 274 The `git-cola` command exposes various sub-commands that allow you to quickly
 275 launch tools that are available from within the git-cola interface.
 276 For example, `git cola find` launches the file finder,
 277 and `git cola grep` launches the grep tool.
 278
 279 See `git cola --help-commands` for the full list of commands.
 280
 281     $ git cola --help-commands
 282     usage: git-cola [-h]
 283
 284                     {cola,am,archive,branch,browse,config,
 285                      dag,diff,fetch,find,grep,merge,pull,push,
 286                      rebase,remote,search,stash,tag,version}
 287                     ...
 288
 289     valid commands:
 290       {cola,am,archive,branch,browse,config,
 291        dag,diff,fetch,find,grep,merge,pull,push,
 292        rebase,remote,search,stash,tag,version}
 293
 294         cola                start git-cola
 295         am                  apply patches using "git am"
 296         archive             save an archive
 297         branch              create a branch
 298         browse              browse repository
 299         config              edit configuration
 300         dag                 start git-dag
 301         diff                view diffs
 302         fetch               fetch remotes
 303         find                find files
 304         grep                grep source
 305         merge               merge branches
 306         pull                pull remote branches
 307         push                push remote branches
 308         rebase              interactive rebase
 309         remote              edit remotes
 310         search              search commits
 311         stash               stash and unstash changes
 312         tag                 create tags
 313         version             print the version
 314
 315 ## Development
 316
 317 The following commands should be run during development:
 318
 319     # Run the unit tests
 320     $ make test
 321
 322     # Run tests and longer-running pylint and flake8 checks
 323     $ make check
 324
 325     # Run tests against multiple python interpreters using tox
 326     $ make tox
 327
 328 The test suite can be found in the [test](test) directory.
 329
 330 Commits and pull requests are automatically tested for code quality
 331 using [GitHub Actions](https://github.com/git-cola/git-cola/actions/workflows/main.yml).
 332
 333 Auto-format `po/*.po` files before committing when updating translations:
 334
 335     $ make po
 336
 337 When submitting patches, consult the
 338 [contributing guidelines](CONTRIBUTING.md).
 339
 340
 341 ## Packaging Notes
 342
 343 Git Cola installs its modules into the default Python site-packages directory
 344 (eg. `lib/python3.7/site-packages`), and in its own private `share/git-cola/lib`
 345 area by default.  The private modules are redundant and not needed when cola's modules
 346 have been installed into the site-packages directory.
 347
 348 Git Cola will prefer its private modules when the `share/git-cola/lib` directory
 349 exists, but they are not required to exist.  This directory is optional, and can
 350 be safely removed if the cola modules have been installed into site-packages
 351 and are importable through the default `sys.path`.
 352
 353 To suppress the installation of the private (redundant) `share/git-cola/lib/cola`
 354 package, specify `make NO_PRIVATE_LIBS=1 ...` when invoking `make`,
 355 or export `GIT_COLA_NO_PRIVATE_LIBS=1` into the build environment.
 356
 357     make NO_PRIVATE_LIBS=1 ...
 358
 359 Git Cola installs a vendored copy of its QtPy dependency by default.
 360 Git Cola provides a copy of the `qtpy` module in its private modules area
 361 when installing Git Cola so that you are not required to install QtPy separately.
 362 If you'd like to provide your own `qtpy` module, for example from the `python-qtpy`
 363 Debian package, then specify `make NO_VENDOR_LIBS=1 ...` when invoking `make`,
 364 or export `GIT_COLA_NO_VENDOR_LIBS=1` into the build environment.
 365
 366     make NO_VENDOR_LIBS=1 ...
 367
 368 Python3 users on debian will need to install `python3-distutils` in order
 369 to run the Makefile's installation steps.  `distutils` is a Python build
 370 requirement, but not needed at runtime.
 371
 372 # Windows (Continued)
 373
 374 ## Development
 375
 376 In order to develop Git Cola on Windows you will need to install
 377 Python3 and pip.  Install PyQt5 using `pip install PyQt5`
 378 to make the PyQt5 bindings available to Python.
 379
 380 Once these are installed you can use `python.exe` to run
 381 directly from the source tree.  For example, from a Git Bash terminal:
 382
 383     /c/Python36/python.exe ./bin/git-cola
 384
 385 ## Multiple Python versions
 386
 387 If you have multiple versions of Python installed, the `contrib/win32/cola`
 388 launcher script might choose the newer version instead of the python
 389 that has PyQt installed.  In order to resolve this, you can set the
 390 `cola.pythonlocation` git configuration variable to tell cola where to
 391 find python.  For example:
 392
 393     git config --global cola.pythonlocation /c/Python36
 394
 395 ## Building Windows Installers
 396
 397 Windows installers are built using
 398
 399 * [Pynsist](https://pynsist.readthedocs.io/en/latest/).
 400
 401 * [NSIS](http://nsis.sourceforge.net/Main_Page) is also needed.
 402
 403 To build the installer using Pynsist run:
 404
 405     ./contrib/win32/run-pynsist.sh
 406
 407 This will generate an installer in `build/nsis/`.
 408
 409 ## Windows "History Browser" Configuration Upgrade
 410
 411 You may need to configure your history browser if you are upgrading from an
 412 older version of Git Cola on Windows.
 413
 414 `gitk` was originally the default history browser, but `gitk` cannot be
 415 launched as-is on Windows because `gitk` is a shell script.
 416
 417 If you are configured to use `gitk`, then change your configuration to
 418 go through Git's `sh.exe` on Windows.  Similarly, we must go through
 419 `python.exe` if we want to use `git-dag`.
 420
 421 If you want to use gitk as your history browser open the
 422 Preferences screen and change the history browser command to:
 423
 424     "C:/Program Files/Git/bin/sh.exe" --login -i C:/Git/bin/gitk
 425
 426 `git-dag` became the default history browser on Windows in `v2.3`, so new
 427 users do not need to configure anything.