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     Copyright (C) 2007-2017, David Aguilar and contributors
   6
   7     This program is free software: you can redistribute it and/or modify
   8     it under the terms of the GNU General Public License as published by
   9     the Free Software Foundation, either version 2 of the License, or
  10     (at your option) any later version.
  11
  12     This program is distributed in the hope that it will be useful,
  13     but WITHOUT ANY WARRANTY; without even the implied warranty of
  14     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15     GNU General Public License for more details.
  16
  17     You should have received a copy of the GNU General Public License
  18     along with this program.  If not, see <http://www.gnu.org/licenses/>.
  19
  20 ## SCREENSHOTS
  21
  22 Screenshots are available on the
  23 [git-cola screenshots page](https://git-cola.github.io/screenshots.html).
  24
  25 ## DOWNLOAD
  26
  27     apt-get install git-cola
  28
  29 New releases are available on the
  30 [git-cola download page](https://git-cola.github.io/downloads.html).
  31
  32 ## FORK
  33
  34     git clone git://github.com/git-cola/git-cola.git
  35
  36 [![git-cola build status](https://api.travis-ci.org/git-cola/git-cola.svg?branch=master)](https://travis-ci.org/git-cola/git-cola)
  37
  38 [git-cola on github](https://github.com/git-cola/git-cola)
  39
  40 [git-cola google group](http://groups.google.com/group/git-cola/)
  41
  42
  43 # NUTRITIONAL FACTS
  44
  45 ## ACTIVE INGREDIENTS
  46
  47 * [git](http://git-scm.com/) 1.6.3 or newer.
  48
  49 * [Python](http://python.org/) 2.6, 2.7, and 3.2 or newer.
  50
  51 * [QtPy](https://github.com/spyder-ide/qtpy) 1.1.0 or newer.
  52
  53 * [argparse](https://pypi.python.org/pypi/argparse) 1.1 or newer.
  54   argparse is part of the stdlib in Python 2.7; install argparse separately if
  55   you are running on Python 2.6.
  56
  57 * [Sphinx](http://sphinx-doc.org/) for building the documentation.
  58
  59 *git-cola* uses *QtPy*, so you can choose between *PyQt4*, *PyQt5*, and
  60 *PySide* by setting the `QT_API` environment variable to `pyqt4`, `pyqt5` or
  61 `pyside` as desired.  `qtpy` defaults to `pyqt5` and falls back to `pyqt4`
  62 if `pyqt5` is not installed.
  63
  64 Any of the following Python Qt libraries must be installed:
  65
  66 * [PyQt4](https://www.riverbankcomputing.com/software/pyqt/download)
  67   4.6 or newer
  68
  69 * [PyQt5](https://www.riverbankcomputing.com/software/pyqt/download5)
  70   5.2 or newer
  71
  72 * [PySide](https://github.com/PySide/PySide)
  73   1.1.0 or newer
  74
  75 *NOTE*: We do not yet recommend using *PyQt5* because there are known
  76 exit-on-segfault bugs in *Qt5* that have not yet been addressed.
  77 *git-cola* is sensitive to this bug and is known to crash on exit
  78 when using `git dag` or the interactive rebase feature on *PyQt5*.
  79
  80 [QTBUG-52988](https://bugreports.qt.io/browse/QTBUG-52988)
  81
  82 *PyQt4* is stable and there are no known issues when using it so we recommend
  83 using *PyQt4* until the *Qt5* bugs have been resolved.
  84
  85 Set `QT_API=pyqt4` in your environment if you have both
  86 versions of *PyQt* installed and want to ensure that PyQt4 is used.
  87
  88 *NOTE*: *git-cola* includes a vendored copy of its *QtPy* dependency.
  89
  90 We provide a copy of the `qtpy` module when installing *git-cola* so that you
  91 are not required to install *QtPy* separately.  If you'd like to provide your
  92 own `qtpy` module, for example from the `python-qtpy` Debian package, then use
  93 `make NO_VENDOR_LIBS=1 ...` when invoking `make`, or export
  94 `GIT_COLA_NO_VENDOR_LIBS=1` into the build environment.
  95
  96
  97 ## ADDITIVES
  98
  99 *git-cola* enables additional features when the following
 100 Python modules are installed.
 101
 102 [send2trash](https://github.com/hsoft/send2trash) enables cross-platform
 103 "Send to Trash" functionality.
 104
 105 # BREWING INSTRUCTIONS
 106
 107 ## RUN FROM SOURCE
 108
 109 You don't need to install *git-cola* to run it.
 110 Running *git-cola* from its source tree is the easiest
 111 way to try the latest version.
 112
 113     git clone git://github.com/git-cola/git-cola.git
 114     cd git-cola
 115     ./bin/git-cola
 116     ./bin/git-dag
 117
 118 Having *git-cola*'s *bin/* directory in your path allows you to run
 119 *git cola* like a regular built-in Git command:
 120
 121     # Replace "$PWD/bin" with the path to git-cola's bin/ directory
 122     PATH="$PWD/bin":"$PATH"
 123     export PATH
 124
 125     git cola
 126     git dag
 127
 128 The instructions below assume that you have *git-cola* present in your
 129 `$PATH`.  Replace "git cola" with "./bin/git-cola" as needed if you'd like to
 130 just run it in-place.
 131
 132 # DOCUMENTATION
 133
 134 * [HTML documentation](https://git-cola.readthedocs.io/en/latest/)
 135
 136 * [git-cola manual](share/doc/git-cola/git-cola.rst)
 137
 138 * [git-dag manual](share/doc/git-cola/git-dag.rst)
 139
 140 * [Keyboard shortcuts](https://git-cola.github.io/share/doc/git-cola/hotkeys.html)
 141
 142 * [Contributing guidelines](CONTRIBUTING.md)
 143
 144 # INSTALLATION
 145
 146 Normally you can just do "make install" to install *git-cola*
 147 in your `$HOME` directory (`$HOME/bin`, `$HOME/share`, etc).
 148 If you want to do a global install you can do
 149
 150     make prefix=/usr install
 151
 152 The platform-specific installation methods below use the native
 153 package manager.  You should use one of these so that all of *git-cola*'s
 154 dependencies are installed.
 155
 156 ## LINUX
 157
 158 Linux is it! Your distro has probably already packaged git-cola.
 159 If not, please file a bug against your distribution ;-)
 160
 161 ### arch
 162
 163     yaourt -S git-cola
 164
 165 ### debian, ubuntu
 166
 167     apt-get install git-cola
 168
 169 ### fedora
 170
 171     dnf install git-cola
 172
 173 ### gentoo
 174
 175     emerge git-cola
 176
 177 ### opensuse
 178
 179 Use the [one-click install link](http://software.opensuse.org/package/git-cola).
 180
 181
 182 ## MAC OS X
 183
 184 [Homebrew](http://brew.sh/) is the easiest way to install
 185 git-cola's *Qt4* and *PyQt4* dependencies.  We will use Homebrew to install
 186 the git-cola recipe, but build our own .app bundle from source.
 187
 188 [Sphinx](http://sphinx-doc.org/latest/install.html) is used to build the
 189 documentation.
 190
 191     brew install sphinx-doc
 192     brew install git-cola
 193
 194 Once brew has installed git-cola you can:
 195
 196 1. Clone git-cola
 197
 198     `git clone git://github.com/git-cola/git-cola.git && cd git-cola`
 199
 200 2. Build the git-cola.app application bundle
 201
 202     ```
 203     make \
 204         PYTHON=$(brew --prefix python3)/bin/python3 \
 205         PYTHON_CONFIG=$(brew --prefix python3)/bin/python3-config \
 206         SPHINXBUILD=$(brew --prefix sphinx-doc)/bin/sphinx-build \
 207         git-cola.app
 208    ```
 209
 210 3. Copy it to _/Applications_
 211
 212     `rm -fr /Applications/git-cola.app && cp -r git-cola.app /Applications`
 213
 214 Newer versions of Homebrew install their own `python3` installation and
 215 provide the `PyQt5` modules for `python3` only.  You have to use
 216 `python3 ./bin/git-cola` when running from the source tree.
 217
 218 ### UPGRADING USING HOMEBREW
 219
 220 If you upgrade using `brew` then it is recommended that you re-install
 221 *git-cola*'s dependencies when upgrading.  Re-installing ensures that the
 222 Python modules provided by Homebrew will be properly setup.
 223
 224 This is required when upgrading to a modern (post-10.11 El Capitan) Mac OS X.
 225 Homebrew now bundles its own Python3 installation instead of using the
 226 system-provided default Python.
 227
 228
 229     # update homebrew
 230     brew update
 231
 232     # uninstall git-cola and its dependencies
 233     brew uninstall git-cola
 234     brew uninstall pyqt5
 235     brew uninstall sip
 236
 237     # re-install git-cola and its dependencies
 238     brew install git-cola
 239
 240 ## WINDOWS INSTALLATION
 241
 242 **IMPORTANT** If you have a 64-bit machine, install the 64-bit versions only.
 243 Do not mix 32-bit and 64-bit versions.
 244
 245 Download and install the following:
 246
 247 * [Git for Windows](https://git-for-windows.github.io/)
 248
 249 * [Python](https://www.python.org/downloads/)
 250   * Python 3.4 is recommended.  Python 2.7 is also supported.
 251   * [64-bit](https://www.python.org/ftp/python/3.4.4/python-3.4.4.amd64.msi)
 252   * [32-bit](https://www.python.org/ftp/python/3.4.4/python-3.4.4.msi)
 253
 254 * [PyQt](https://riverbankcomputing.com/software/pyqt/download/)
 255   * PyQt4 4.11 is recommended.  PyQt4 requires a matching Python version.
 256   * [64-bit](http://sourceforge.net/projects/pyqt/files/PyQt4/PyQt-4.11.4/PyQt4-4.11.4-gpl-Py3.4-Qt4.8.7-x64.exe)
 257   * [32-bit](http://sourceforge.net/projects/pyqt/files/PyQt4/PyQt-4.11.4/PyQt4-4.11.4-gpl-Py3.4-Qt4.8.7-x32.exe)
 258
 259 * [Git Cola](https://github.com/git-cola/git-cola/downloads)
 260
 261 Once these are installed you can run *git cola* from the Start menu or
 262 by double-clicking on the `git-cola.pyw` script.
 263
 264 If you are developing *git cola* on Windows you can use `python.exe` to run
 265 directly from the source tree.  For example, from a Git Bash terminal:
 266
 267     /c/Python34/python.exe ./bin/git-cola
 268
 269 See "WINDOWS (continued)" below for more details.
 270
 271 # GOODIES
 272
 273 *git-cola* ships with an interactive rebase editor called *git-xbase*.
 274 *git-xbase* can be used to reorder and choose commits and is typically
 275 launched through the *git-cola*'s "Rebase" menu.
 276
 277 *git-xbase* can also be launched independently of the main *git-cola* interface
 278 by telling `git rebase` to use it as its editor:
 279
 280     env GIT_SEQUENCE_EDITOR="$PWD/share/git-cola/bin/git-xbase" \
 281     git rebase -i origin/master
 282
 283 The quickest way to launch *git-xbase* is via the *git cola rebase*
 284 sub-command (as well as various other sub-commands):
 285
 286     git cola rebase origin/master
 287
 288 # COMMAND-LINE TOOLS
 289
 290 The *git-cola* command exposes various sub-commands that allow you to quickly
 291 launch tools that are available from within the *git-cola* interface.
 292 For example, `./bin/git-cola find` launches the file finder,
 293 and `./bin/git-cola grep` launches the grep tool.
 294
 295 See `git cola --help-commands` for the full list of commands.
 296
 297     $ git cola --help-commands
 298     usage: git-cola [-h]
 299
 300                     {cola,am,archive,branch,browse,classic,config,
 301                      dag,diff,fetch,find,grep,merge,pull,push,
 302                      rebase,remote,search,stash,tag,version}
 303                     ...
 304
 305     valid commands:
 306       {cola,am,archive,branch,browse,classic,config,
 307        dag,diff,fetch,find,grep,merge,pull,push,
 308        rebase,remote,search,stash,tag,version}
 309
 310         cola                start git-cola
 311         am                  apply patches using "git am"
 312         archive             save an archive
 313         branch              create a branch
 314         browse              browse repository
 315         classic             browse repository
 316         config              edit configuration
 317         dag                 start git-dag
 318         diff                view diffs
 319         fetch               fetch remotes
 320         find                find files
 321         grep                grep source
 322         merge               merge branches
 323         pull                pull remote branches
 324         push                push remote branches
 325         rebase              interactive rebase
 326         remote              edit remotes
 327         search              search commits
 328         stash               stash and unstash changes
 329         tag                 create tags
 330         version             print the version
 331
 332 ## HACKING
 333
 334 The following commands should be run during development:
 335
 336     # Run the unit tests
 337     $ make test
 338
 339     # Check for pylint warnings.  All new code must pass 100%.
 340     $ make pylint
 341
 342 The test suite can be found in the [test](test) directory.
 343
 344 The tests are setup to run automatically when code is pushed using
 345 [Travis CI](https://travis-ci.org/git-cola/git-cola).
 346 Checkout the [Travis config file](.travis.yml) for more details.
 347
 348 When submitting patches, consult the [contributing guidelines](CONTRIBUTING.md).
 349
 350 # WINDOWS (continued)
 351
 352 ## BUILDING WINDOWS INSTALLERS
 353
 354 Windows installers are built using
 355
 356 * [Pynsist](http://pynsist.readthedocs.io/en/latest/).
 357
 358 * [NSIS](http://nsis.sourceforge.net/Main_Page) is also needed.
 359
 360 To build the installer using *Pynsist*:
 361
 362 * If building from a non-Windows platform run
 363   `./contrib/win32/fetch_pyqt_windows.sh`.
 364   This will download a PyQt binary installer for Windows and unpack its files
 365   into `pynsist_pkgs/`.
 366
 367 * Run `pynsist pynsist.cfg`.
 368   The installer will be built in `build/nsis/`.
 369
 370 Before *Pynsist*, installers were built using *InnoSetup*.
 371 The *InnoSetup* scripts are still available:
 372
 373     ./contrib/win32/create-installer.sh
 374
 375 You have to make sure that the file */share/InnoSetup/ISCC.exe* exists.
 376
 377 ## WINDOWS HISTORY BROWSER CONFIGURATION UPGRADE
 378
 379 You may need to configure your history browser if you are upgrading from an
 380 older version of *git-cola*.
 381
 382 `gitk` was originally the default history browser, but `gitk` cannot be
 383 launched as-is on Windows because `gitk` is a shell script.
 384
 385 If you are configured to use `gitk`, then change your configuration to
 386 go through Git's `sh.exe` on Windows.  Similarly,we must go through
 387 `python.exe` if we want to use `git-dag`.
 388
 389 If you want to use *gitk* as your history browser open the
 390 *Preferences* screen and change the history browser command to:
 391
 392     "C:/Program Files/Git/bin/sh.exe" --login -i C:/Git/bin/gitk
 393
 394 Alternatively, if you'd like to use *git-dag* as your history browser, use:
 395
 396     C:/Python34/python.exe C:/git-cola/bin/git-dag
 397
 398 *git-dag* became the default history browser on Windows in `v2.3`, so new
 399 users should not need to configure anything.