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