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