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