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