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-2016, 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](http://www.riverbankcomputing.co.uk/software/pyqt/download)
  67   4.6 or newer
  68
  69 * [PyQt5](http://www.riverbankcomputing.co.uk/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 # INSTALLATION
 133
 134 Normally you can just do "make install" to install *git-cola*
 135 in your `$HOME` directory (`$HOME/bin`, `$HOME/share`, etc).
 136 If you want to do a global install you can do
 137
 138     make prefix=/usr install
 139
 140 The platform-specific installation methods below use the native
 141 package manager.  You should use one of these so that all of *git-cola*'s
 142 dependencies are installed.
 143
 144 ## LINUX
 145
 146 Linux is it! Your distro has probably already packaged git-cola.
 147 If not, please file a bug against your distribution ;-)
 148
 149 ### arch
 150
 151     yaourt -S git-cola
 152
 153 ### debian, ubuntu
 154
 155     apt-get install git-cola
 156
 157 ### fedora
 158
 159     dnf install git-cola
 160
 161 ### gentoo
 162
 163     emerge git-cola
 164
 165 ### opensuse
 166
 167 Use the [one-click install link](http://software.opensuse.org/package/git-cola).
 168
 169
 170 ## MAC OS X
 171
 172 Before setting up homebrew, use
 173 [pip](https://pip.readthedocs.io/en/latest/installing.html) to install
 174 [sphinx](http://sphinx-doc.org/latest/install.html).
 175
 176 Sphinx is used to build the documentation.
 177
 178     sudo pip install --requirement requirements.txt
 179
 180 [Homebrew](http://mxcl.github.com/homebrew/) is the easiest way to install
 181 git-cola's *Qt4* and *PyQt4* dependencies.  We will use homebrew to install
 182 the git-cola recipe, but build our own .app bundle from source.
 183
 184     brew install git-cola
 185
 186 Once brew has installed git-cola you can:
 187
 188 1. Clone git-cola
 189
 190     `git clone git://github.com/git-cola/git-cola.git && cd git-cola`
 191
 192 2. Build the git-cola.app application bundle
 193
 194     `make git-cola.app`
 195
 196 3. Copy it to _/Applications_
 197
 198     `rm -fr /Applications/git-cola.app && cp -r git-cola.app /Applications`
 199
 200 ## WINDOWS INSTALLATION
 201
 202 Download the latest stable Git, Python 2.x, and Py2x-PyQt4 installers
 203
 204 * [msysGit](http://msysgit.github.com/)
 205
 206 * [Python](http://python.org/download/)
 207
 208 * [PyQt](http://www.riverbankcomputing.co.uk/software/pyqt/download/)
 209
 210 * [git-cola Installer](https://github.com/git-cola/git-cola/downloads)
 211
 212 Once these are installed you can run *git-cola* from the Start menu or
 213 by double-clicking on the `git-cola.pyw` script.
 214
 215 If you are developing *git-cola* on Windows you can use `python.exe` to run
 216 *git-cola* directly from source.
 217
 218     python.exe ./bin/git-cola
 219
 220 See "WINDOWS (continued)" below for more details.
 221
 222 # DOCUMENTATION
 223
 224 * [HTML documentation](https://git-cola.readthedocs.io/en/latest/)
 225
 226 * [git-cola manual](share/doc/git-cola/git-cola.rst)
 227
 228 * [git-dag manual](share/doc/git-cola/git-dag.rst)
 229
 230 * [Keyboard shortcuts](https://git-cola.github.io/share/doc/git-cola/hotkeys.html)
 231
 232 * [Contributing guidelines](CONTRIBUTING.md)
 233
 234 # GOODIES
 235
 236 *git-cola* ships with an interactive rebase editor called *git-xbase*.
 237 *git-xbase* can be used to reorder and choose commits and is typically
 238 launched through the *git-cola*'s "Rebase" menu.
 239
 240 *git-xbase* can also be launched independently of the main *git-cola* interface
 241 by telling `git rebase` to use it as its editor:
 242
 243     env GIT_SEQUENCE_EDITOR="$PWD/share/git-cola/bin/git-xbase" \
 244     git rebase -i origin/master
 245
 246 The quickest way to launch *git-xbase* is via the *git cola rebase*
 247 sub-command (as well as various other sub-commands):
 248
 249     git cola rebase origin/master
 250
 251 # COMMAND-LINE TOOLS
 252
 253 The *git-cola* command exposes various sub-commands that allow you to quickly
 254 launch tools that are available from within the *git-cola* interface.
 255 For example, `./bin/git-cola find` launches the file finder,
 256 and `./bin/git-cola grep` launches the grep tool.
 257
 258 See `git cola --help-commands` for the full list of commands.
 259
 260     $ git cola --help-commands
 261     usage: git-cola [-h]
 262
 263                     {cola,am,archive,branch,browse,classic,config,
 264                      dag,diff,fetch,find,grep,merge,pull,push,
 265                      rebase,remote,search,stash,tag,version}
 266                     ...
 267
 268     valid commands:
 269       {cola,am,archive,branch,browse,classic,config,
 270        dag,diff,fetch,find,grep,merge,pull,push,
 271        rebase,remote,search,stash,tag,version}
 272
 273         cola                start git-cola
 274         am                  apply patches using "git am"
 275         archive             save an archive
 276         branch              create a branch
 277         browse              browse repository
 278         classic             browse repository
 279         config              edit configuration
 280         dag                 start git-dag
 281         diff                view diffs
 282         fetch               fetch remotes
 283         find                find files
 284         grep                grep source
 285         merge               merge branches
 286         pull                pull remote branches
 287         push                push remote branches
 288         rebase              interactive rebase
 289         remote              edit remotes
 290         search              search commits
 291         stash               stash and unstash changes
 292         tag                 create tags
 293         version             print the version
 294
 295 ## HACKING
 296
 297 The following commands should be run during development:
 298
 299     # Run the unit tests
 300     $ make test
 301
 302     # Check for pylint warnings.  All new code must pass 100%.
 303     $ make pylint
 304
 305 The test suite can be found in the [test](test) directory.
 306
 307 The tests are setup to run automatically when code is pushed using
 308 [Travis CI](https://travis-ci.org/git-cola/git-cola).
 309 Checkout the [Travis config file](.travis.yml) for more details.
 310
 311 When submitting patches, consult the [contributing guidelines](CONTRIBUTING.md).
 312
 313 # WINDOWS (continued)
 314
 315 ## WINDOWS-ONLY HISTORY BROWSER CONFIGURATION UPGRADE
 316
 317 You may need to configure your history browser if you are upgrading from an
 318 older version of *git-cola*.
 319
 320 `gitk` was originally the default history browser, but `gitk` cannot be
 321 launched as-is on Windows because `gitk` is a shell script.
 322
 323 If you are configured to use `gitk`, then change your configuration to
 324 go through Git's `sh.exe` on Windows.  Similarly,we must go through
 325 `python.exe` if we want to use `git-dag`.
 326
 327 If you want to use *gitk* as your history browser open the
 328 *Preferences* screen and change the history browser command to:
 329
 330     C:/Git/bin/sh.exe --login -i C:/Git/bin/gitk
 331
 332 Alternatively, if you'd like to use *git-dag* as your history browser, use:
 333
 334     C:/Python27/python.exe C:/git-cola/bin/git-dag
 335
 336 *git-dag* became the default history browser on Windows in `v2.3`, so new
 337 users should not need to configure anything.
 338
 339 # BUILDING WINDOWS INSTALLERS
 340
 341 Windows installers are built using
 342
 343 * [Pynsist](http://pynsist.readthedocs.io/en/latest/).
 344
 345 * [NSIS](http://nsis.sourceforge.net/Main_Page) is also needed.
 346
 347 To build the installer using *Pynsist*:
 348
 349 * If building from a non-Windows platform run
 350   `./contrib/win32/fetch_pyqt_windows.sh`.
 351   This will download a PyQt binary installer for Windows and unpack its files
 352   into `pynsist_pkgs/`.
 353
 354 * Run `pynsist pynsist.cfg`.
 355   The installer will be built in `build/nsis/`.
 356
 357 Before *Pynsist*, installers were built using *InnoSetup*.
 358 The *InnoSetup* scripts are still available:
 359
 360     ./contrib/win32/create-installer.sh
 361
 362 You have to make sure that the file */share/InnoSetup/ISCC.exe* exists.