1 # git-cola: The highly caffeinated Git GUI
3 git-cola is a powerful Git GUI with a slick and intuitive user interface.
5 Copyright (C) 2007-2016, David Aguilar and contributors
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.
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.
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/>.
22 Screenshots are available on the
23 [git-cola screenshots page](https://git-cola.github.io/screenshots.html).
27 apt-get install git-cola
29 New releases are available on the
30 [git-cola download page](https://git-cola.github.io/downloads.html).
34 git clone git://github.com/git-cola/git-cola.git
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)
38 [git-cola on github](https://github.com/git-cola/git-cola)
40 [git-cola google group](http://groups.google.com/group/git-cola/)
47 * [git](http://git-scm.com/) 1.6.3 or newer.
49 * [Python](http://python.org/) 2.6, 2.7, and 3.2 or newer.
51 * [QtPy](https://github.com/spyder-ide/qtpy) 1.0.2 or newer.
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.
57 * [Sphinx](http://sphinx-doc.org/) for building the documentation.
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.
64 Any of the following Python Qt libraries must be installed:
66 * [PyQt4](http://www.riverbankcomputing.co.uk/software/pyqt/download) 4.6 or newer
68 * [PyQt5](http://www.riverbankcomputing.co.uk/software/pyqt/download5) 5.2 or newer
70 * [PySide](https://github.com/PySide/PySide) 1.1.0 or newer
72 *NOTE*: *git-cola* includes a vendored copy of its *QtPy* dependency.
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.
83 *git-cola* enables additional features when the following
84 Python modules are installed.
86 [send2trash](https://github.com/hsoft/send2trash) enables cross-platform
87 "Send to Trash" functionality.
89 # BREWING INSTRUCTIONS
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.
97 git clone git://github.com/git-cola/git-cola.git
102 Having *git-cola*'s *bin/* directory in your path allows you to run
103 *git cola* like a regular built-in Git command:
105 # Replace "$PWD/bin" with the path to git-cola's bin/ directory
106 PATH="$PWD/bin":"$PATH"
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.
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
122 make prefix=/usr install
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.
130 Linux is it! Your distro has probably already packaged git-cola.
131 If not, please file a bug against your distribution ;-)
139 apt-get install git-cola
151 Use the [one-click install link](http://software.opensuse.org/package/git-cola).
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).
160 Sphinx is used to build the documentation.
162 sudo pip install --requirement requirements.txt
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.
168 brew install git-cola
170 Once brew has installed git-cola you can:
174 `git clone git://github.com/git-cola/git-cola.git && cd git-cola`
176 2. Build the git-cola.app application bundle
180 3. Copy it to _/Applications_
182 `rm -fr /Applications/git-cola.app && cp -r git-cola.app /Applications`
184 ## WINDOWS INSTALLATION
186 Download the latest stable Git, Python 2.x, and Py2x-PyQt4 installers
188 * [msysGit](http://msysgit.github.com/)
190 * [Python](http://python.org/download/)
192 * [PyQt](http://www.riverbankcomputing.co.uk/software/pyqt/download/)
194 * [git-cola Installer](https://github.com/git-cola/git-cola/downloads)
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.
199 If you are developing *git-cola* on Windows you can use `python.exe` to run
200 *git-cola* directly from source.
202 python.exe ./bin/git-cola
204 See "WINDOWS (continued)" below for more details.
208 * [HTML documentation](https://git-cola.readthedocs.io/en/latest/)
210 * [git-cola manual](share/doc/git-cola/git-cola.rst)
212 * [git-dag manual](share/doc/git-cola/git-dag.rst)
214 * [Keyboard shortcuts](https://git-cola.github.io/share/doc/git-cola/hotkeys.html)
216 * [Contributing guidelines](CONTRIBUTING.md)
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.
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:
227 env GIT_SEQUENCE_EDITOR="$PWD/share/git-cola/bin/git-xbase" \
228 git rebase -i origin/master
230 The quickest way to launch *git-xbase* is via the *git cola rebase*
231 sub-command (as well as various other sub-commands):
233 git cola rebase origin/master
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.
242 See `git cola --help-commands` for the full list of commands.
244 $ git cola --help-commands
247 {cola,am,archive,branch,browse,classic,config,
248 dag,diff,fetch,find,grep,merge,pull,push,
249 rebase,remote,search,stash,tag,version}
253 {cola,am,archive,branch,browse,classic,config,
254 dag,diff,fetch,find,grep,merge,pull,push,
255 rebase,remote,search,stash,tag,version}
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
270 pull pull remote branches
271 push push remote branches
272 rebase interactive rebase
274 search search commits
275 stash stash and unstash changes
277 version print the version
281 The following commands should be run during development:
286 # Check for pylint warnings. All new code must pass 100%.
289 The test suite can be found in the [test](test) directory.
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.
295 When submitting patches, consult the [contributing guidelines](CONTRIBUTING.md).
297 # WINDOWS (continued)
299 ## WINDOWS-ONLY HISTORY BROWSER CONFIGURATION UPGRADE
301 You may need to configure your history browser if you are upgrading from an
302 older version of *git-cola*.
304 `gitk` was originally the default history browser, but `gitk` cannot be
305 launched as-is on Windows because `gitk` is a shell script.
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`.
311 If you want to use *gitk* as your history browser open the
312 *Preferences* screen and change the history browser command to:
314 C:/Git/bin/sh.exe --login -i C:/Git/bin/gitk
316 Alternatively, if you'd like to use *git-dag* as your history browser, use:
318 C:/Python27/python.exe C:/git-cola/bin/git-dag
320 *git-dag* became the default history browser on Windows in `v2.3`, so new
321 users should not need to configure anything.
323 # BUILDING WINDOWS INSTALLERS
325 Windows installers are built using
327 * [Pynsist](http://pynsist.readthedocs.io/en/latest/).
329 * [NSIS](http://nsis.sourceforge.net/Main_Page) is also needed.
331 To build the installer using *Pynsist*:
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/`.
338 * Run `pynsist pynsist.cfg`.
339 The installer will be built in `build/nsis/`.
341 Before *Pynsist*, installers were built using *InnoSetup*.
342 The *InnoSetup* scripts are still available:
344 ./contrib/win32/create-installer.sh
346 You have to make sure that the file */share/InnoSetup/ISCC.exe* exists.