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 regular built-in Git command:
  82
  83     # Replace "$PWD/bin" with the path to git-cola's bin/ directory
  84     PATH="$PWD/bin":"$PATH"
  85     export PATH
  86
  87     git cola
  88     git dag
  89
  90 The instructions below assume that you have *git-cola* present in your
  91 `$PATH`.  Replace "git cola" with "./bin/git-cola" as needed if you'd like to
  92 just run it in-place.
  93
  94 # INSTALLATION
  95
  96 Normally you can just do "make install" to install *git-cola*
  97 in your `$HOME` directory (`$HOME/bin`, `$HOME/share`, etc).
  98 If you want to do a global install you can do
  99
 100     make prefix=/usr install
 101
 102 There are also platform-specific installation methods.
 103 You'll probably want to use one of these anyways since they
 104 have a nice side-effect of installing *git-cola*'s PyQt4
 105 and argparse dependencies.
 106
 107 ## LINUX
 108
 109 Linux is it! Your distro has probably already packaged git-cola.
 110 If not, please file a bug against your distribution ;-)
 111
 112 ### arch
 113
 114     yaourt -S git-cola
 115
 116 ### debian, ubuntu
 117
 118     apt-get install git-cola
 119
 120 ### fedora
 121
 122     yum install git-cola
 123
 124 ### gentoo
 125
 126     emerge git-cola
 127
 128 ### opensuse
 129
 130 Use the [one-click install link](http://software.opensuse.org/package/git-cola).
 131
 132 ## MAC OS X
 133
 134 [Homebrew](http://mxcl.github.com/homebrew/) is the easiest way to install
 135 git-cola, *Qt4* and *PyQt4*.
 136
 137     brew install git-cola
 138
 139 Once brew has installed git-cola you can:
 140
 141 1. Clone git-cola
 142
 143     `git clone git://github.com/git-cola/git-cola.git && cd git-cola`
 144
 145 2. Build the git-cola.app application bundle
 146
 147     `make git-cola.app`
 148
 149 3. Copy it to _/Applications_
 150
 151     `rm -fr /Applications/git-cola.app && cp -r git-cola.app /Applications`
 152
 153 ## WINDOWS INSTALLATION
 154
 155 Download the latest stable Git, Python 2.x, and Py2x-PyQt4 installers
 156
 157 * [msysGit](http://msysgit.github.com/)
 158
 159 * [Python](http://python.org/download/)
 160
 161 * [PyQt](http://www.riverbankcomputing.co.uk/software/pyqt/download/)
 162
 163 * [git-cola Installer](https://github.com/git-cola/git-cola/downloads)
 164
 165 Once these are installed you can run *git-cola* from the Start menu or
 166 by double-clicking on the `git-cola.pyw` script.
 167
 168 If you are developing *git-cola* on Windows you can use `python.exe` to run
 169 *git-cola* directly from source.
 170
 171     python.exe ./bin/git-cola
 172
 173 See "WINDOWS (continued)" below for more details.
 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     env GIT_SEQUENCE_EDITOR="$PWD/share/git-cola/bin/git-xbase" \
 197     git rebase -i origin/master
 198
 199 The quickest way to launch *git-xbase* is via the *git cola rebase*
 200 sub-command (as well as various other sub-commands):
 201
 202     git cola rebase origin/master
 203
 204 # COMMAND-LINE TOOLS
 205
 206 The *git-cola* command exposes various sub-commands that allow you to quickly
 207 launch tools that are available from within the *git-cola* interface.
 208 For example, `./bin/git-cola find` launches the file finder,
 209 and `./bin/git-cola grep` launches the grep tool.
 210
 211 See `git cola --help-commands` for the full list of commands.
 212
 213     $ git cola --help-commands
 214     usage: git-cola [-h]
 215
 216                     {cola,am,archive,branch,browse,classic,config,
 217                      dag,diff,fetch,find,grep,merge,pull,push,
 218                      rebase,remote,search,stash,tag,version}
 219                     ...
 220
 221     valid commands:
 222       {cola,am,archive,branch,browse,classic,config,
 223        dag,diff,fetch,find,grep,merge,pull,push,
 224        rebase,remote,search,stash,tag,version}
 225
 226         cola                start git-cola
 227         am                  apply patches using "git am"
 228         archive             save an archive
 229         branch              create a branch
 230         browse              browse repository
 231         classic             browse repository
 232         config              edit configuration
 233         dag                 start git-dag
 234         diff                view diffs
 235         fetch               fetch remotes
 236         find                find files
 237         grep                grep source
 238         merge               merge branches
 239         pull                pull remote branches
 240         push                push remote branches
 241         rebase              interactive rebase
 242         remote              edit remotes
 243         search              search commits
 244         stash               stash and unstash changes
 245         tag                 create tags
 246         version             print the version
 247
 248
 249 ## WINDOWS (continued)
 250
 251 # WINDOWS-ONLY HISTORY BROWSER CONFIGURATION UPGRADE
 252
 253 You may need to configure your history browser if you are upgrading from an
 254 older version of *git-cola*.
 255
 256 `gitk` was originally the default history browser, but `gitk` cannot be
 257 launched as-is on Windows because `gitk` is a shell script.
 258
 259 If you are configured to use `gitk`, then change your configuration to
 260 go through Git's `sh.exe` on Windows.  Similarly,we must go through
 261 `python.exe` if we want to use `git-dag`.
 262
 263 If you want to use *gitk* as your history browser open the
 264 *Preferences* screen and change the history browser command to:
 265
 266     C:/Git/bin/sh.exe --login -i C:/Git/bin/gitk
 267
 268 Alternatively, if you'd like to use *git-dag* as your history browser, use:
 269
 270     C:/Python27/python.exe C:/git-cola/bin/git-dag
 271
 272 *git-dag* became the default history browser on Windows in `v2.3`, so new
 273 users should not need to configure anything.
 274
 275 # BUILDING WINDOWS INSTALLERS
 276
 277 Windows installers are built using
 278 [Pynsist](http://pynsist.readthedocs.org/en/latest/).
 279 [NSIS](http://nsis.sourceforge.net/Main_Page) is also needed.
 280
 281 To build the installer using *Pynsist*:
 282
 283 1. (If building from a non-Windows platform), run
 284    `./contrib/win32/fetch_pyqt_windows.sh`.
 285    This will download a PyQt binary installer for Windows and unpack its files
 286    into `pynsist_pkgs/`.
 287 2. Run `pynsist pynsist.cfg`.
 288    The installer will be built in `build/nsis/`.
 289
 290
 291 Before *Pynsist*, installers were built using *InnoSetup*.
 292 The *InnoSetup* scripts are still available:
 293
 294     ./contrib/win32/create-installer.sh
 295
 296 You have to make sure that the file */share/InnoSetup/ISCC.exe* exists.
 297 That is normally the case when you run the *msysGit bash* and not the
 298 *Git for Windows bash* (look [here](http://msysgit.github.com/)
 299 for the differences).