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