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
 162 ## macOS
 163
 164 You can install Git Cola using the same `Makefile` steps above to install from source.
 165
 166 ### git-cola.app
 167
 168 If you'd like to build a `git-cola.app` bundle for `/Applications` run this command:
 169
 170     make git-cola.app
 171
 172 ### Homebrew
 173
 174 An easy way to install Git Cola is to use [Homebrew](https://brew.sh/) .
 175 Use Homebrew to install the git-cola recipe:
 176
 177     brew install git-cola
 178
 179 ### Updating macOS and Homebrew
 180
 181 Updating macOS can often break Homebrew-managed software.
 182
 183 If you upgrade your macOS version and Git Cola no longer runs then then it is
 184 recommended that you re-install Git Cola's dependencies after upgrading.
 185
 186 A quick fix when upgrading to newer versions of XCode or macOS is to
 187 reinstall pyqt5.
 188
 189     brew reinstall pyqt@5
 190
 191 You may also need to relink your pyqt installation:
 192
 193     brew link pyqt@5
 194
 195 This is required when upgrading to a modern (post-10.11 El Capitan) Mac OS X.
 196 Homebrew now bundles its own Python3 installation instead of using the
 197 system-provided default Python.
 198
 199 If the "brew reinstall" command above does not work then re-installing from
 200 scratch using the instructions below should get things back in shape.
 201
 202     # update homebrew
 203     brew update
 204
 205     # uninstall git-cola and its dependencies
 206     brew uninstall git-cola
 207     brew uninstall pyqt5
 208     brew uninstall sip
 209
 210     # re-install git-cola and its dependencies
 211     brew install git-cola
 212
 213
 214 ## Windows
 215
 216 IMPORTANT If you have a 64-bit machine, install the 64-bit versions only.
 217 Do not mix 32-bit and 64-bit versions.
 218
 219 Download and install the following:
 220
 221 * [Git for Windows](https://git-for-windows.github.io/)
 222
 223 * [Git Cola](https://github.com/git-cola/git-cola/releases)
 224
 225 Once these are installed you can run Git Cola from the Start menu.
 226
 227 See "Windows (Continued)" below for more details.
 228
 229
 230 # Goodies
 231
 232 Git Cola ships with an interactive rebase editor called `git-cola-sequence-editor`.
 233 `git-cola-sequence-editor` is used to reorder and choose commits when rebasing.
 234 Start an interactive rebase through the "Rebase" menu, or through the
 235 `git cola rebase` sub-command to use the `git-cola-sequence-editor`:
 236
 237     git cola rebase @{upstream}
 238
 239 `git-cola-sequence-editor` can be launched independently of git cola by telling
 240 `git rebase` to use it as its editor through the `GIT_SEQUENCE_EDITOR`
 241 environment variable:
 242
 243     export GIT_SEQUENCE_EDITOR="$HOME/git-cola/bin/git-cola-sequence-editor"
 244     git rebase -i @{upstream}
 245
 246
 247 # Git Cola Sub-commands
 248
 249 The `git-cola` command exposes various sub-commands that allow you to quickly
 250 launch tools that are available from within the git-cola interface.
 251 For example, `git cola find` launches the file finder,
 252 and `git cola grep` launches the grep tool.
 253
 254 See `git cola --help-commands` for the full list of commands.
 255
 256     $ git cola --help-commands
 257     usage: git-cola [-h]
 258
 259                     {cola,am,archive,branch,browse,config,
 260                      dag,diff,fetch,find,grep,merge,pull,push,
 261                      rebase,remote,search,stash,tag,version}
 262                     ...
 263
 264     valid commands:
 265       {cola,am,archive,branch,browse,config,
 266        dag,diff,fetch,find,grep,merge,pull,push,
 267        rebase,remote,search,stash,tag,version}
 268
 269         cola                start git-cola
 270         am                  apply patches using "git am"
 271         archive             save an archive
 272         branch              create a branch
 273         browse              browse repository
 274         config              edit configuration
 275         dag                 start git-dag
 276         diff                view diffs
 277         fetch               fetch remotes
 278         find                find files
 279         grep                grep source
 280         merge               merge branches
 281         pull                pull remote branches
 282         push                push remote branches
 283         rebase              interactive rebase
 284         remote              edit remotes
 285         search              search commits
 286         stash               stash and unstash changes
 287         tag                 create tags
 288         version             print the version
 289
 290 ## Development
 291
 292 If you already have Git Cola's dependencies installed then you can
 293 start `cola` as a Python module if you have the source code available.
 294
 295     python -m cola
 296     python -m cola dag
 297
 298
 299 The following commands should be run during development:
 300
 301     # Run the unit tests
 302     $ make test
 303
 304     # Run tests and longer-running pylint and flake8 checks
 305     $ make check
 306
 307     # Run tests against multiple python interpreters using tox
 308     $ make tox
 309
 310 The test suite can be found in the [test](test) directory.
 311
 312 Commits and pull requests are automatically tested for code quality
 313 using [GitHub Actions](https://github.com/git-cola/git-cola/actions/workflows/main.yml).
 314
 315 Auto-format `cola/i18n/*.po` files before committing when updating translations:
 316
 317     $ make po
 318
 319 When submitting patches, consult the
 320 [contributing guidelines](CONTRIBUTING.md).
 321
 322
 323 ## Packaging Notes
 324
 325 Git Cola installs its modules into the default Python site-packages directory
 326 (eg. `lib/python3.7/site-packages`) using setuptools.
 327
 328 While end-users can use `pip install git-cola` to install Git Cola, distribution
 329 packagers should use the `make prefix=/usr` install process. Git Cola's `Makefile` wraps
 330 `pip install --prefix=<prefix>` to provide a packaging-friendly `make install` target.
 331
 332
 333 # Windows (Continued)
 334
 335 ## Microsoft Visual C++ 2015 Redistributable
 336
 337 Earlier versions of Git Cola may have shipped without `vcruntime140.dll`  and may
 338 not run on machines that are missing this DLL.
 339
 340 To fix this, download the
 341 [Microsoft Visual C++ 2015 Redistributable](https://www.microsoft.com/en-us/download/details.aspx?id=52685)
 342 and install it
 343
 344 Git Cola v4.0.0 and newer include this DLL and do not require this to be installed
 345 separately.
 346
 347 ## Development
 348
 349 In order to develop Git Cola on Windows you will need to install
 350 Python3 and pip.  Install PyQt5 using `pip install PyQt5`
 351 to make the PyQt5 bindings available to Python.
 352
 353 Once these are installed you can use `python.exe` to run
 354 directly from the source tree.  For example, from a Git Bash terminal:
 355
 356     /c/Python36/python.exe ./bin/git-cola
 357
 358 ## Multiple Python versions
 359
 360 If you have multiple versions of Python installed, the `contrib/win32/cola`
 361 launcher script might choose the newer version instead of the python
 362 that has PyQt installed.  In order to resolve this, you can set the
 363 `cola.pythonlocation` git configuration variable to tell cola where to
 364 find python.  For example:
 365
 366     git config --global cola.pythonlocation /c/Python39
 367
 368 ## Building Windows Installers
 369
 370 Windows installers are built using
 371
 372 * [Pynsist](https://pynsist.readthedocs.io/en/latest/).
 373
 374 * [NSIS](http://nsis.sourceforge.net/Main_Page) is also needed.
 375
 376 To build the installer using Pynsist run:
 377
 378     ./contrib/win32/run-pynsist.sh
 379
 380 This will generate an installer in `build/nsis/`.
 381
 382 ## Windows "History Browser" Configuration Upgrade
 383
 384 You may need to configure your history browser if you are upgrading from an
 385 older version of Git Cola on Windows.
 386
 387 `gitk` was originally the default history browser, but `gitk` cannot be
 388 launched as-is on Windows because `gitk` is a shell script.
 389
 390 If you are configured to use `gitk`, then change your configuration to
 391 go through Git's `sh.exe` on Windows.  Similarly, we must go through
 392 `python.exe` if we want to use `git-dag`.
 393
 394 If you want to use gitk as your history browser open the
 395 Preferences screen and change the history browser command to:
 396
 397     "C:/Program Files/Git/bin/sh.exe" --login -i C:/Git/bin/gitk
 398
 399 `git-dag` became the default history browser on Windows in `v2.3`, so new
 400 users do not need to configure anything.