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