7 git cola [options] [sub-command]
11 git cola is a sleek and powerful Git GUI.
18 Start `git cola` in amend mode.
22 Prompt for a Git repository. Defaults to the current directory.
26 Open the Git repository at `<path>`. Defaults to the current directory.
28 -s, --status-filter <filter>
29 ----------------------------
30 Apply the path filter to the status widget.
34 Print the `git cola` version and exit.
38 Show usage and optional arguments.
42 Show available sub-commands.
53 Export tarballs from Git.
69 Start the `git dag` Git history browser.
77 Fetch history from remote repositories.
81 Use `git grep` to search for content.
89 Fetch and merge remote branches.
93 Push branches to remotes.
97 Start an interactive rebase.
101 Create and edit remotes.
109 Stash uncommitted modifications.
117 Print the `git cola` version.
119 CONFIGURE YOUR EDITOR
120 =====================
121 The editor used by `Ctrl-e` is configured from the Preferences screen.
122 The environment variable `$VISUAL` is consulted when no editor has been
125 *ProTip*: Configuring your editor to `gvim -f -p` will open multiple tabs
126 when editing files. `gvim -f -o` uses splits.
128 `git cola` is {vim, emacs, textpad, notepad++}-aware.
129 When you select a line in the `grep` screen and press any of
130 `Enter`, `Ctrl-e`, or the `Edit` button, you are taken to that exact line.
132 The editor preference is saved in the `gui.editor` variable using
133 `git config <http://git-scm.com/docs/git-config>`_.
137 `git cola` has many useful keyboard shortcuts.
139 You can see the available shortcuts by pressing the ``?`` key,
140 choosing ``Help -> Keyboard shortcuts`` from the main menu,
141 or by consulting the `git cola keyboard shortcuts reference <https://git-cola.github.io/share/doc/git-cola/hotkeys.html>`_.
145 The `git cola` interface is composed of various cooperating tools.
146 Double-clicking a tool opens it in its own subwindow.
147 Dragging it around moves and places it within the window.
149 Tools can be hidden and rearranged however you like.
150 `git cola` carefully remembers your window layout and restores
151 it the next time it is launched.
153 The `Control-{1, 2, 3, ...}` hotkey gives focus to a specific tool.
154 A hidden tool can be re-opened using the `Tools` menu or
155 the `Shift+Control-{1, 2, 3, ...}` shortcut keys.
161 The `Status` tool provides a visual analog to the
162 `git status <http://git-scm.com/docs/git-status>`_ command.
164 `Status` displays files that are `modified` relative to the staging area,
165 `staged` for the next commit, `unmerged` files from an in-progress merge,
166 and files that are `untracked` to git.
168 These are the same categories one sees when running
169 `git status <http://git-scm.com/docs/git-status>`_
172 You can navigate through the list of files using keyboard arrows as well
173 as the ergonomical and vim-like `j` and `k` shortcut keys.
175 There are several convenient ways to interact with files in the `Status` tool.
177 Selecting a file displays its diff in the :ref:`Diff` viewer.
178 Double-clicking a file stages its contents, as does the
179 the `Ctrl-s` shortcut key.
181 `Ctrl-e` opens selected files in the conifgured editor, and
182 `Ctrl-d` opens selected files using `git difftool <http://git-scm.com/docs/git-difftool>`_
184 Additional actions can be performed using the right-click context menu.
188 Clicking the `Staged` folder shows a diffstat for the index.
190 Clicking the `Modified` folder shows a diffstat for the worktree.
192 Clicking individual files sends diffs to the `Diff Display`.
194 Double-clicking individual files adds and removes their content from the index.
196 Various actions are available through the right-click context menu.
197 Different actions are available depending a file's status.
201 Add to the staging area using `git add <http://git-scm.com/docs/git-add>`_
202 Marks unmerged files as resolved.
206 Launches the configured visual text editor
210 Visualize changes using `git difftool`.
212 Revert Unstaged Edits
213 ~~~~~~~~~~~~~~~~~~~~~
214 Reverts unstaged content by checking out selected paths
215 from the index/staging area
217 Revert Uncommited Edits
218 ~~~~~~~~~~~~~~~~~~~~~~~
219 Throws away uncommitted edits
223 Remove from the index/staging area with
224 `git reset <http://git-scm.com/docs/git-reset>`_
228 Resolve conflicts using `git mergetool <http://git-scm.com/docs/git-mergetool>`_.
232 Delete untracked files from the filesystem.
236 Adds untracked files to to the .gitignore file.
242 The diff viewer/editor displays diffs for selected files.
243 Additions are shown in green and removals are displayed in light red.
244 Extraneous whitespace is shown with a pure-red background.
246 Right-clicking in the diff provides access to additional actions
247 that use either the cursor location or text selection.
249 Staging content for commit
250 --------------------------
251 The ``@@`` patterns denote a new diff hunk. Selecting lines of diff
252 and using the `Stage Selected Lines` command will stage just the selected
253 lines. Clicking within a diff hunk and selecting `Stage Diff Hunk` stages the
254 entire patch diff hunk.
256 The corresponding opposite commands can be performed on staged files as well,
257 e.g. staged content can be selectively removed from the index when we are
258 viewing diffs for staged content.
260 COMMIT MESSAGE EDITOR
261 =====================
263 The commit message editor is a simple text widget
264 for entering commit messages.
266 You can navigate between the `Subject` and `Extended description...`
267 fields using the keyboard arrow keys.
269 Pressing enter when inside the `Subject` field jumps down to the
270 extended description field.
272 The `Options` button menu to the left of the subject field
273 provides access to the additional actions.
275 The `Ctrl+i` keyboard shortcut adds a standard "Signed-off-by: " line,
276 and `Ctrl+Enter` creates a new commit using the commit message and
281 The `Sign Off` button adds a standard::
283 Signed-off-by: A. U. Thor <a.u.thor@example.com>
285 line to the bottom of the commit message.
287 Invoking this action is equivalent to passing the ``-s`` option
288 to `git commit <http://git-scm.com/docs/git-commit>`_.
292 The commit button runs
293 `git commit <http://git-scm.com/docs/git-commit>`_.
294 The contents of the commit message editor is provided as the commit message.
296 Only staged files are included in the commit -- this is the same behavior
297 as running ``git commit`` on the command-line.
299 Line and Column Display
300 -----------------------
301 The current line and column number is displayed by the editor.
302 E.g. a ``5,0`` display means that the cursor is located at
303 line five, column zero.
305 The display changes colors when lines get too long.
306 Yellow indicates the safe boundary for sending patches to a mailing list
307 while keeping space for inline reply markers.
309 Orange indicates that the line is starting to run a bit long and should
312 Red indicates that the line is running up against the standard
313 80-column limit for commit messages.
315 Keeping commit messages less than 76-characters wide is encouraged.
316 `git log <http://git-scm.com/docs/git-log>`_
317 is a great tool but long lines mess up its formatting for everyone else,
318 so please be mindful when writing commit messages.
323 Clicking on `Amend Last Commit` makes `git cola` amend the previous commit
324 instead of creating a new one. `git cola` loads the previous commit message
325 into the commit message editor when this option is selected.
327 The `Status` tool will display all of the changes for the amended commit.
331 Tell `git commit` and `git merge` to sign commits using GPG.
333 Using this option is equivalent to passing the ``--gpg-sign`` option to
334 `git commit <http://git-scm.com/docs/git-commit>`_ and
335 `git merge <http://git-scm.com/docs/git-merge>`_.
337 This option's default value can be configured using the `cola.signcommits`
338 configuration variable.
342 Use the ``File -> Apply Patches`` menu item to begin applying patches.
344 Dragging and dropping patches onto the `git cola` interface
345 adds the patches to the list of patches to apply using
346 `git am <http://git-scm.com/docs/git-am>`_.
348 You can drag either a set of patches or a directory containing patches.
349 Patches can be sorted using in the interface and are applied in the
350 same order as is listed in the list.
352 When a directory is dropped `git cola` walks the directory
353 tree in search of patches. `git cola` sorts the list of
354 patches after they have all been found. This allows you
355 to control the order in which patchs are applied by placing
356 patchsets into alphanumerically-sorted directories.
358 CUSTOM WINDOW SETTINGS
359 ======================
360 `git cola` remembers modifications to the layout and arrangement
361 of tools within the `git cola` interface. Changes are saved
362 and restored at application shutdown/startup.
364 `git cola` can be configured to not save custom layouts by unsetting
365 the `Save Window Settings` option in the `git cola` preferences.
367 CONFIGURATION VARIABLES
368 =======================
369 These variables can be set using `git config` or from the settings.
373 The command used to blame files. Defaults to `git gui blame`.
377 Whether to create a dock widget with the `Browser` tool.
378 Defaults to `false` to speedup startup time.
382 Inspect unmerged files for conflict markers before staging them.
383 This feature helps prevent accidental staging of unresolved merge conflicts.
388 `git cola`, when run outside of a Git repository, prompts the user for a
389 repository. Set `cola.defaultrepo` to the path of a Git repostiory to make
390 `git cola` attempt to use that repository before falling back to prompting
391 the user for a repository.
395 Enables per-file gitattributes encoding support when set to `true`.
396 This tells `git cola` to honor the configured encoding when displaying
401 Specifies the font to use for `git cola`'s diff display.
405 Set to `false` to disable file system change monitoring. Defaults to `true`,
406 but also requires either Linux with inotify support or Windows with `pywin32`
407 installed for file system change monitoring to actually function.
410 ----------------------
411 Set to `true` to automatically refresh when `git cola` gains focus. Defaults
412 to `false` because this can cause a pause whenever switching to `git cola` from
417 Whether to automatically break long lines while editing commit messages.
418 Defaults to `true`. This setting is configured using the `Preferences`
419 dialog, but it can be toggled for one-off usage using the commit message
420 editor's options sub-menu.
424 `git cola` encodes paths dragged from its widgets into `utf-16` when adding
425 them to the drag-and-drop mime data (specifically, the `text/x-moz-url` entry).
426 `utf-16` is used to make `gnome-terminal` see the right paths, but other
427 terminals may expect a different encoding. If you are using a terminal that
428 expects a modern encoding, e.g. `terminator`, then set this value to `utf-8`.
432 `git cola` avoids reading large binary untracked files.
433 The maximum size to read is controlled by `cola.readsize`
434 and defaults to `2048`.
436 cola.savewindowsettings
437 -----------------------
438 `git cola` will remember its window settings when set to `true`.
439 Window settings and X11 sessions are saved in `$HOME/.config/git-cola`.
443 `git cola` will sign commits by default when set `true`. Defaults to `false`.
444 See the section below on setting up GPG for more details.
448 The number of columns occupied by a tab character. Defaults to 8.
452 The command to use when launching commands within a graphical terminal.
454 `cola.terminal` defaults to `xterm -e` when unset.
455 e.g. when opening a shell, `git cola` will run `xterm -e $SHELL`.
457 If either `gnome-terminal`, `xfce4-terminal`, or `konsole` are installed
458 then they will be preferred over `xterm` when `cola.terminal` is unset.
462 The number of columns used for line wrapping.
463 Tabs are counted according to `cola.tabwidth`.
467 The default diff text color, in hexadecimal RRGGBB notation.
468 Defaults to "030303".
472 The default diff "add" background color, in hexadecimal RRGGBB notation.
473 Defaults to "d2ffe4".
477 The default diff "remove" background color, in hexadecimal RRGGBB notation.
478 Defaults to "fee0e4".
482 The default diff header text color, in hexadecimal RRGGBB notation.
483 Defaults to "bbbbbb".
487 The number of diff context lines to display.
491 `git cola` avoids showing untracked files when set to `false`.
495 The default text editor to use is defined in `gui.editor`.
496 The config variable overrides the VISUAL environment variable.
501 The history browser to use when visualizing history.
506 The default diff tool to use.
510 The default merge tool to use.
514 Your email address to be recorded in any newly created commits.
515 Can be overridden by the 'GIT_AUTHOR_EMAIL', 'GIT_COMMITTER_EMAIL', and
516 'EMAIL' environment variables.
520 Your full name to be recorded in any newly created commits.
521 Can be overridden by the 'GIT_AUTHOR_NAME' and 'GIT_COMMITTER_NAME'
522 environment variables.
525 ENVIRONMENT VARIABLES
526 =====================
530 `git cola` can be made to scale its interface for HiDPI displays.
531 When defined, `git cola` will scale icons, radioboxes, and checkboxes
532 according to the scale factor. The default value is `1`.
533 A good value is `2` for high-resolution displays.
535 Fonts are not scaled, as their size can already be set in the settings.
539 When defined, `git cola` logs `git` commands to stdout.
540 When set to `full`, `git cola` also logs the exit status and output.
541 When set to `trace`, `git cola` logs to the `Console` widget.
545 Specifies the default editor to use.
546 This is ignored when the `gui.editor` configuration variable is defined.
550 `git cola` automatically detects your language and presents some
551 translations when available. This may not be desired, or you
552 may want `git cola` to use a specific language.
554 You can make `git cola` use an alternative language by creating a
555 `~/.config/git-cola/language` file containing the standard two-letter
556 gettext language code, e.g. "en", "de", "ja", "zh", etc.::
558 mkdir -p ~/.config/git-cola &&
559 echo en >~/.config/git-cola/language
561 Alternatively you may also use LANGAUGE environmental variable to temporarily
562 change `git cola`'s language just like any other gettext-based program. For
563 example to temporarily change `git cola`'s language to English::
567 To make `git cola` use the zh_TW translation with zh_HK, zh, and en as a
570 LANGUAGE=zh_TW:zh_HK:zh:en git cola
575 `git cola` allows you to define custom GUI actions by setting `git config`
576 variables. The "name" of the command appears in the "Actions" menu.
580 Specifies the shell command line to execute when the corresponding item of the
581 Tools menu is invoked. This option is mandatory for every tool. The command is
582 executed from the root of the working directory, and in the environment it
583 receives the name of the tool as GIT_GUITOOL, the name of the currently
584 selected file as FILENAME, and the name of the current branch as CUR_BRANCH
585 (if the head is detached, CUR_BRANCH is empty).
587 guitool.<name>.background
588 -------------------------
589 Run the command in the background (similar to editing and difftool actions).
590 This avoids blocking the GUI. Setting `background` to `true` implies
591 `noconsole` and `norescan`.
593 guitool.<name>.needsfile
594 ------------------------
595 Run the tool only if a diff is selected in the GUI. It guarantees that
596 FILENAME is not empty.
598 guitool.<name>.noconsole
599 ------------------------
600 Run the command silently, without creating a window to display its output.
602 guitool.<name>.norescan
603 -----------------------
604 Don’t rescan the working directory for changes after the tool finishes
607 guitool.<name>.confirm
608 ----------------------
609 Show a confirmation dialog before actually running the tool.
611 guitool.<name>.argprompt
612 ------------------------
613 Request a string argument from the user, and pass it to the tool through the
614 ARGS environment variable. Since requesting an argument implies confirmation,
615 the confirm option has no effect if this is enabled. If the option is set to
616 true, yes, or 1, the dialog uses a built-in generic prompt; otherwise the
617 exact value of the variable is used.
619 guitool.<name>.revprompt
620 ------------------------
621 Request a single valid revision from the user, and set the REVISION
622 environment variable. In other aspects this option is similar to argprompt,
623 and can be used together with it.
625 guitool.<name>.revunmerged
626 --------------------------
627 Show only unmerged branches in the revprompt subdialog. This is useful for
628 tools similar to merge or rebase, but not for things like checkout or reset.
632 Specifies the title to use for the prompt dialog.
633 Defaults to the tool name.
635 guitool.<name>.prompt
636 ---------------------
637 Specifies the general prompt string to display at the top of the dialog,
638 before subsections for argprompt and revprompt.
639 The default value includes the actual command.
641 guitool.<name>.shortcut
642 -----------------------
643 Specifies a keyboard shortcut for the custom tool.
645 The value must be a valid string understood by the `QAction::setShortcut()` API.
646 See http://qt-project.org/doc/qt-4.8/qkeysequence.html#QKeySequence-2
647 for more details about the supported values.
649 Avoid creating shortcuts that conflict with existing built-in `git cola`
650 shortcuts. Creating a conflict will result in no action when the shortcut
653 SETTING UP GPG FOR SIGNED COMMITS
654 =================================
655 When creating signed commits `gpg` will attempt to read your password from the
656 terminal from which `git cola` was launched.
657 The way to make this work smoothly is to use a GPG agent so that you can avoid
658 needing to re-enter your password every time you commit.
660 This also gets you a graphical passphrase prompt instead of getting prompted
661 for your password in the terminal.
663 Install gpg-agent and friends
664 -----------------------------
665 On Mac OS X, you may need to `brew install gpg-agent` and install the
666 `Mac GPG Suite <https://gpgtools.org/macgpg2/>`_.
668 On Linux use your package manager to install gnupg2,
669 gnupg-agent and pinentry-qt, e.g.::
671 sudo apt-get install gnupg2 gnupg-agent pinentry-qt
673 On Linux, you should also configure Git so that it uses gpg2 (gnupg2),
674 otherwise you will get errors mentioning, "unable to open /dev/tty".
675 Set Git's `gpg.program` to `gpg2`::
677 git config --global gpg.program gpg2
679 Configure gpg-agent and a pin-entry program
680 -------------------------------------------
681 On Mac OS X, edit `~/.gnupg/gpg.conf` to include the line,::
685 This is typically not needed on Linux, where `gpg2` is used, as
686 this is the default value when using `gpg2`.
688 Next, edit `~/.gnupg/gpg-agent.conf` to contain a pinentry-program line
689 pointing to the pinentry program for your platform.
691 The following example `~/.gnupg/gpg-agent.conf` shows how to use pinentry-qt on Linux::
693 pinentry-program /usr/bin/pinentry-qt
694 default-cache-ttl 3600
698 This following example `.gnupg/gpg-agent.conf` shows how to use MacGPG2's
699 pinentry app on On Mac OS X::
701 pinentry-program /usr/local/MacGPG2/libexec/pinentry-mac.app/Contents/MacOS/pinentry-mac
702 default-cache-ttl 3600
706 Once this has been setup then you will need to start the gpg-agent daemon.
707 First, check if it is already running.::
709 env | grep GPG_AGENT_INFO
710 echo bye | gpg-connect-agent
712 If you see the following output::
715 OK closing connection
717 Then the daemon is already running, and you do not need to start it yourself.
719 If it is not running, eval the output of `gpg-agent --daemon` in your shell
720 prior to launching `git cola`.::
722 eval $(gpg-agent --daemon)
730 If Git is installed in a custom location, e.g. not installed in `C:/Git` or
731 Program Files, then the path to Git must be configured by creating a file in
732 your home directory `~/.config/git-cola/git-bindir` that points to your git
740 Git Cola's Git Repository
741 -------------------------
742 https://github.com/git-cola/git-cola/
746 https://git-cola.github.io/
750 https://groups.google.com/group/git-cola