i18n: update translations for upcoming v3.9
[git-cola.git] / share / doc / git-cola / git-cola.rst
blob7c7ece8949408f6f6b69b718cdd3c7259c9378ff
1 ===========
2 git-cola(1)
3 ===========
5 SYNOPSIS
6 ========
7 git cola [options] [sub-command]
9 DESCRIPTION
10 ===========
11 Git Cola is a sleek and powerful Git GUI.
13 OPTIONS
14 =======
16 --amend
17 -------
18 Start `git cola` in amend mode.
20 --prompt
21 --------
22 Prompt for a Git repository.  Defaults to the current directory.
24 -r, --repo <path>
25 -----------------
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.
32 --version
33 ---------
34 Print the `git cola` version and exit.
36 -h, --help
37 ----------
38 Show usage and optional arguments.
40 --help-commands
41 ---------------
42 Show available sub-commands.
44 SUB-COMMANDS
45 ============
49 Apply patches.
51 archive
52 -------
53 Export tarballs from Git.
55 branch
56 ------
57 Create branches.
59 browse
60 ------
61 Browse tracked files.
63 config
64 ------
65 Configure settings.
67 dag
68 ---
69 Start the `git dag` Git history browser.
71 diff
72 ----
73 Diff changed files.
75 fetch
76 -----
77 Fetch history from remote repositories.
79 grep
80 ----
81 Use `git grep` to search for content.
83 merge
84 -----
85 Merge branches.
87 pull
88 ----
89 Fetch and merge remote branches.
91 push
92 ----
93 Push branches to remotes.
95 rebase
96 ------
97 Start an interactive rebase.
99 remote
100 ------
101 Create and edit remotes.
103 search
104 ------
105 Search for commits.
107 stash
108 -----
109 Stash uncommitted modifications.
113 Create tags.
115 version
116 -------
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
123 configured.
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>`_.
135 KEYBOARD SHORTCUTS
136 ==================
137 `git cola` has many useful keyboard shortcuts.
139 Many of `git cola`'s editors understand vim-style hotkeys, eg. `{h,j,k,l}`
140 for navigating in the diff, status, grep, and file browser widgets.
142 `{d,u}` move down/up one half page at a time (similar to vim's `ctrl-{d,u}`).
143 The `space` and `shift-space` hotkeys are mapped to the same operations.
145 `Shift-{j,k,d,u,f,b,page-up,page-down,left,right,up,down}` can be be used in
146 the diff editor to select lines while navigating.
148 `s` is a useful hotkey in the diff editor.  It stages/unstages the current
149 selection when a selection is present.  When nothing is selected, the
150 diff hunk at the current text cursor position is staged.  This makes it very
151 easy to review changes by selecting good hunks with `s` while navigating down
152 and over hunks that are not going to be staged.
154 `Ctrl-u` in the diff editor reverts unstaged edits, and respects the
155 selection.  This is useful for selectively reverted edits from the worktree.
156 This same hotkey reverts the entire file when used from the status tool.
158 `Ctrl-s` in the diff editor and status tools stages/unstages the entire file.
160 You can see the available shortcuts by pressing pressing the ``?`` key,
161 choosing ``Help -> Keyboard shortcuts`` from the main menu,
162 or by consulting the `git cola keyboard shortcuts reference <https://git-cola.github.io/share/doc/git-cola/hotkeys.html>`_.
164 TOOLS
165 =====
166 The `git cola` interface is composed of various cooperating tools.
167 Double-clicking a tool opens it in its own subwindow.
168 Dragging it around moves and places it within the main window.
170 Tools can be hidden and rearranged however you like.
171 `git cola` carefully remembers your window layout and restores
172 it the next time it is launched.
174 The `Control-{1, 2, 3, ...}` hotkey gives focus to a specific tool.
175 A hidden tool can be re-opened using the `Tools` menu or
176 the `Shift+Control-{1, 2, 3, ...}` shortcut keys.
178 The Diff editor can be focused with `Ctrl-j`.
179 the Status tool can be focused with `Ctrl-k`.
180 the Commit tool can be focused with `Ctrl-l`.
182 .. _status:
184 STATUS
185 ======
186 The `Status` tool provides a visual analog to the
187 `git status <http://git-scm.com/docs/git-status>`_ command.
189 `Status` displays files that are `modified` relative to the staging area,
190 `staged` for the next commit, `unmerged` files from an in-progress merge,
191 and files that are `untracked` to git.
193 These are the same categories one sees when running
194 `git status <http://git-scm.com/docs/git-status>`_
195 on the command line.
197 You can navigate through the list of files using keyboard arrows as well
198 as the ergonomical and vim-like `j` and `k` shortcut keys.
200 There are several convenient ways to interact with files in the `Status` tool.
202 Selecting a file displays its diff in the :ref:`Diff` viewer.
203 Double-clicking a file stages its contents, as does the
204 the `Ctrl-s` shortcut key.
206 `Ctrl-e` opens selected files in the conifgured editor, and
207 `Ctrl-d` opens selected files using `git difftool <http://git-scm.com/docs/git-difftool>`_
209 Additional actions can be performed using the right-click context menu.
211 Actions
212 -------
213 Clicking the `Staged` folder shows a diffstat for the index.
215 Clicking the `Modified` folder shows a diffstat for the worktree.
217 Clicking individual files sends diffs to the `Diff Display`.
219 Double-clicking individual files adds and removes their content from the index.
221 Various actions are available through the right-click context menu.
222 Different actions are available depending a file's status.
224 Stage Selected
225 ~~~~~~~~~~~~~~
226 Add to the staging area using `git add <http://git-scm.com/docs/git-add>`_
227 Marks unmerged files as resolved.
229 Launch Editor
230 ~~~~~~~~~~~~~
231 Launches the configured visual text editor
233 Launch Difftool
234 ~~~~~~~~~~~~~~~
235 Visualize changes using `git difftool`.
237 Revert Unstaged Edits
238 ~~~~~~~~~~~~~~~~~~~~~
239 Reverts unstaged content by checking out selected paths
240 from the index/staging area
242 Revert Uncommitted Edits
243 ~~~~~~~~~~~~~~~~~~~~~~~~
244 Throws away uncommitted edits
246 Unstage Selected
247 ~~~~~~~~~~~~~~~~
248 Remove from the index/staging area with
249 `git reset <http://git-scm.com/docs/git-reset>`_
251 Launch Merge Tool
252 ~~~~~~~~~~~~~~~~~
253 Resolve conflicts using `git mergetool <http://git-scm.com/docs/git-mergetool>`_.
255 Delete File(s)
256 ~~~~~~~~~~~~~~
257 Delete untracked files from the filesystem.
259 Add to .gitignore
260 ~~~~~~~~~~~~~~~~~
261 Adds untracked files to to the .gitignore file.
263 .. _diff:
265 DIFF
266 ====
267 The diff viewer/editor displays diffs for selected files.
268 Additions are shown in green and removals are displayed in light red.
269 Extraneous whitespace is shown with a pure-red background.
271 Right-clicking in the diff provides access to additional actions
272 that use either the cursor location or text selection.
274 Staging content for commit
275 --------------------------
276 The ``@@`` patterns denote a new diff hunk.  Selecting lines of diff
277 and using the `Stage Selected Lines` command will stage just the selected
278 lines.  Clicking within a diff hunk and selecting `Stage Diff Hunk` stages the
279 entire patch diff hunk.
281 The corresponding opposite commands can be performed on staged files as well,
282 e.g. staged content can be selectively removed from the index when we are
283 viewing diffs for staged content.
285 COMMIT MESSAGE EDITOR
286 =====================
288 The commit message editor is a simple text widget
289 for entering commit messages.
291 You can navigate between the `Subject` and `Extended description...`
292 fields using the keyboard arrow keys.
294 Pressing enter when inside the `Subject` field jumps down to the
295 extended description field.
297 The `Options` button menu to the left of the subject field
298 provides access to the additional actions.
300 The `Ctrl+i` keyboard shortcut adds a standard "Signed-off-by: " line,
301 and `Ctrl+Enter` creates a new commit using the commit message and
302 staged content.
304 Sign Off
305 --------
306 The `Sign Off` button adds a standard::
308     Signed-off-by: A. U. Thor <a.u.thor@example.com>
310 line to the bottom of the commit message.
312 Invoking this action is equivalent to passing the ``-s`` option
313 to `git commit <http://git-scm.com/docs/git-commit>`_.
315 Commit
316 ------
317 The commit button runs
318 `git commit <http://git-scm.com/docs/git-commit>`_.
319 The contents of the commit message editor is provided as the commit message.
321 Only staged files are included in the commit -- this is the same behavior
322 as running ``git commit`` on the command-line.
324 Line and Column Display
325 -----------------------
326 The current line and column number is displayed by the editor.
327 E.g. a ``5,0`` display means that the cursor is located at
328 line five, column zero.
330 The display changes colors when lines get too long.
331 Yellow indicates the safe boundary for sending patches to a mailing list
332 while keeping space for inline reply markers.
334 Orange indicates that the line is starting to run a bit long and should
335 break soon.
337 Red indicates that the line is running up against the standard
338 80-column limit for commit messages.
340 Keeping commit messages less than 76-characters wide is encouraged.
341 `git log <http://git-scm.com/docs/git-log>`_
342 is a great tool but long lines mess up its formatting for everyone else,
343 so please be mindful when writing commit messages.
346 Amend Last Commit
347 -----------------
348 Clicking on `Amend Last Commit` makes `git cola` amend the previous commit
349 instead of creating a new one.  `git cola` loads the previous commit message
350 into the commit message editor when this option is selected.
352 The `Status` tool will display all of the changes for the amended commit.
354 Create Signed Commit
355 --------------------
356 Tell `git commit` and `git merge` to sign commits using GPG.
358 Using this option is equivalent to passing the ``--gpg-sign`` option to
359 `git commit <http://git-scm.com/docs/git-commit>`_ and
360 `git merge <http://git-scm.com/docs/git-merge>`_.
362 This option's default value can be configured using the `cola.signcommits`
363 configuration variable.
365 Prepare Commit Message
366 ----------------------
367 The ``Commit -> Prepare Commit Message`` action or `Ctrl-Shift-Return` keyboard shortcut
368 runs the `cola-prepare-commit-msg` hook if it is available in `.git/hooks/`.
369 This is a `git cola`-specific hook that takes the same parameters
370 as Git's `prepare-commit-msg hook <https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks>`_
372 The hook is passed the path to `.git/GIT_COLA_MSG` as the first argument and the hook is expected to write
373 an updated commit message to specified path.  After running this action, the
374 commit message editor is updated with the new commit message.
376 To override the default path to this hook set the
377 `cola.prepareCommitMessageHook` `git config` variable to the path to the
378 hook script.  This is useful if you would like to use a common hook
379 across all repositories.
381 BRANCHES
382 ========
384 The `Branches` tool provides a visual tree to navigate through the branches.
385 The tree has three main nodes `Local Branch`, `Remote Branch` and `Tags`.
386 Branches are grouped by their name divided by the character '/'.Ex::
388     branch/feature/foo
389     branch/feature/bar
390     branch/doe
392 Will produce::
394     branch
395         - doe
396         + feature
397             - bar
398             - foo
400 Current branch will display a star icon. If current branch has commits
401 ahead/behind it will display an up/down arrow with its number.
403 Actions
404 -------
405 Various actions are available through the right-click context menu.
406 Different actions are available depending of selected branch status.
408 Checkout
409 ~~~~~~~~
410 The checkout action runs
411 `git checkout [<branchname>] <https://git-scm.com/docs/git-checkout>`_.
413 Merge in current branch
414 ~~~~~~~~~~~~~~~~~~~~~~~
415 The merge action runs
416 `git merge --no-commit [<branchname>] <https://git-scm.com/docs/git-merge>`_.
418 Pull
419 ~~~~
420 The pull action runs
421 `git pull --no-ff [<remote>] [<branchname>] <https://git-scm.com/docs/git-pull>`_.
423 Push
424 ~~~~
425 The push action runs
426 `git push [<remote>] [<branchname>] <https://git-scm.com/docs/git-push>`_.
428 Rename Branch
429 ~~~~~~~~~~~~~
430 The rename branch action runs
431 `git branch -M [<branchname>] <https://git-scm.com/docs/git-push>`_.
433 Delete Branch
434 ~~~~~~~~~~~~~
435 The delete branch branch action runs
436 `git branch -D [<branchname>] <https://git-scm.com/docs/git-branch>`_.
438 Delete Remote Branch
439 ~~~~~~~~~~~~~~~~~~~~
440 The remote branch action runs
441 `git push --delete [<remote>] [<branchname>] <https://git-scm.com/docs/git-push>`_.
444 APPLY PATCHES
445 =============
446 Use the ``File -> Apply Patches`` menu item to begin applying patches.
448 Dragging and dropping patches onto the `git cola` interface
449 adds the patches to the list of patches to apply using
450 `git am <http://git-scm.com/docs/git-am>`_.
452 You can drag either a set of patches or a directory containing patches.
453 Patches can be sorted using in the interface and are applied in the
454 same order as is listed in the list.
456 When a directory is dropped `git cola` walks the directory
457 tree in search of patches.  `git cola` sorts the list of
458 patches after they have all been found.  This allows you
459 to control the order in which patchs are applied by placing
460 patchsets into alphanumerically-sorted directories.
462 CUSTOM WINDOW SETTINGS
463 ======================
464 `git cola` remembers modifications to the layout and arrangement
465 of tools within the `git cola` interface.  Changes are saved
466 and restored at application shutdown/startup.
468 `git cola` can be configured to not save custom layouts by unsetting
469 the `Save Window Settings` option in the `git cola` preferences.
471 DARK MODE AND WINDOW MANAGER THEMES
472 ===================================
473 Git Cola contains a ``default`` theme which follows the current Qt style and a
474 handful of built-in color themes.  See :ref:`cola_theme` for more details.
476 To use icons appropriate for a dark application theme, configure
477 ``git config --global cola.icontheme dark`` to use the dark icon theme.
478 See :ref:`cola_icontheme` for more details.
480 On Linux, you may want Qt to follow the Window manager theme by configuring it
481 to do so using the ``qt5ct`` Qt5 configuration tool.  Install ``qt5ct`` on
482 Debian/Ubuntu systems to make this work.::
484     sudo apt install qt5ct
486 Once installed, update your `~/.bash_profile` to activate ``qt5ct``::
488     # Use the style configured using the qt5ct tool
489     QT_QPA_PLATFORMTHEME=qt5ct
490     export QT_QPA_PLATFORMTHEME
492 This only work with the `default` theme.  The other themes replace the color
493 palette with theme-specific colors.
495 On macOS, using the ``default`` theme will automatically inherit "Dark Mode"
496 color themes when configured via System Preferences.  You will need to
497 configure the dark icon theme as noted above when dark mode is enabled.
499 CONFIGURATION VARIABLES
500 =======================
501 These variables can be set using `git config` or from the settings.
503 cola.autocompletepaths
504 ----------------------
505 Set to `false` to disable auto-completion of filenames in completion widgets.
506 This can speed up operations when working in large repositories.
507 Defaults to `true`.
509 cola.autoloadCommitTemplate
510 ---------------------------
511 Set to `true` to automatically load the commit template in the commit message
512 editor If the commit.template variable has not been configured, raise the
513 corresponding error.
514 Defaults to `false`.
516 cola.blameviewer
517 ----------------
518 The command used to blame files.  Defaults to `git gui blame`.
520 cola.browserdockable
521 --------------------
522 Whether to create a dock widget with the `Browser` tool.
523 Defaults to `false` to speedup startup time.
525 cola.checkconflicts
526 -------------------
527 Inspect unmerged files for conflict markers before staging them.
528 This feature helps prevent accidental staging of unresolved merge conflicts.
529 Defaults to `true`.
531 cola.defaultrepo
532 ----------------
533 `git cola`, when run outside of a Git repository, prompts the user for a
534 repository.  Set `cola.defaultrepo` to the path of a Git repository to make
535 `git cola` attempt to use that repository before falling back to prompting
536 the user for a repository.
538 cola.dictionary
539 ---------------
540 Specifies an additional dictionary for `git cola` to use in its spell checker.
541 This should be configured to the path of a newline-separated list of words.
543 cola.expandtab
544 --------------
545 Expand tabs into spaces in the commit message editor.  When set to `true`,
546 `git cola` will insert a configurable number of spaces when tab is pressed.
547 The number of spaces is determined by `cola.tabwidth`.
548 Defaults to `false`.
550 cola.fileattributes
551 -------------------
552 Enables per-file gitattributes encoding support when set to `true`.
553 This tells `git cola` to honor the configured encoding when displaying
554 and applying diffs.
556 cola.fontdiff
557 -------------
558 Specifies the font to use for `git cola`'s diff display.
560 cola.hidpi
561 -------------
562 Specifies the High DPI displays scale factor. Set `0` to automatically scaled.
563 Setting value between 0 and 1 is undefined.
564 This option requires at least Qt 5.6 to work.
565 See `Qt QT_SCALE_FACTOR documentation <https://doc.qt.io/qt-5/highdpi.html>`_
566 for more information.
568 .. _cola_icontheme:
570 cola.icontheme
571 --------------
572 Specifies the icon themes to use throughout `git cola`. The theme specified
573 must be the name of the subdirectory containing the icons, which in turn must
574 be placed in the inside the main "icons" directory in `git cola`'s
575 installation prefix.
577 If unset, or set either "light" or "default", then the default style will be
578 used.  If set to "dark" then the built-in "dark" icon theme, which is
579 suitable for a dark window manager theme, will be used.
581 If set to an absolute directory path then icons in that directory will be used.
582 This value can be set to multiple values using,
583 ``git config --add cola.icontheme $theme``.
585 This setting can be overridden by the `GIT_COLA_ICON_THEME` environment
586 variable, which can specify multiple themes using a colon-separated value.
588 The icon theme can also be specified by passing ``--icon-theme=<theme>`` on the
589 command line, once for each icon theme, in the order that they should be
590 searched.  This can be used to override a subset of the icons, and fallback
591 to the built-in icons for the remainder.
593 cola.imagediff.<extension>
594 --------------------------
595 Enable image diffs for the specified file extension.  For example, configuring
596 `git config --global cola.imagediff.svg false` will disable use of the visual
597 image diff for `.svg` files in all repos until is is explicitly toggled on.
598 Defaults to `true`.
600 cola.inotify
601 ------------
602 Set to `false` to disable file system change monitoring.  Defaults to `true`,
603 but also requires either Linux with inotify support or Windows with `pywin32`
604 installed for file system change monitoring to actually function.
606 cola.refreshonfocus
607 -------------------
608 Set to `true` to automatically refresh when `git cola` gains focus.  Defaults
609 to `false` because this can cause a pause whenever switching to `git cola` from
610 another application.
612 cola.linebreak
613 --------------
614 Whether to automatically break long lines while editing commit messages.
615 Defaults to `true`.  This setting is configured using the `Preferences`
616 dialog, but it can be toggled for one-off usage using the commit message
617 editor's options sub-menu.
619 cola.maxrecent
620 --------------
621 `git cola` caps the number of recent repositories to avoid cluttering
622 the start and recent repositories menu.  The maximum number of repositories to
623 remember is controlled by `cola.maxrecent` and defaults to `8`.
625 cola.dragencoding
626 -----------------
627 `git cola` encodes paths dragged from its widgets into `utf-16` when adding
628 them to the drag-and-drop mime data (specifically, the `text/x-moz-url` entry).
629 `utf-16` is used to make `gnome-terminal` see the right paths, but other
630 terminals may expect a different encoding.  If you are using a terminal that
631 expects a modern encoding, e.g. `terminator`, then set this value to `utf-8`.
633 cola.readsize
634 -------------
635 `git cola` avoids reading large binary untracked files.
636 The maximum size to read is controlled by `cola.readsize`
637 and defaults to `2048`.
639 cola.safemode
640 -------------
641 The "Stage" button in the `git cola` Actions panel stages all files when it is
642 activated and no files are selected.  This can be problematic if it is
643 accidentally triggered after carefully preparing the index with staged
644 changes.  "Safe Mode" is enabled by setting `cola.safemode` to `true`.
645 When enabled, `git cola` will do nothing when "Stage" is activated without a
646 selection.  Defaults to `false`.
648 cola.savewindowsettings
649 -----------------------
650 `git cola` will remember its window settings when set to `true`.
651 Window settings and X11 sessions are saved in `$HOME/.config/git-cola`.
653 cola.showpath
654 -------------
655 `git cola` displays the absolute path of the repository in the window title.
656 This can be disabled by setting `cola.showpath` to `false`.
657 Defaults to `true`.
659 cola.signcommits
660 ----------------
661 `git cola` will sign commits by default when set `true`. Defaults to `false`.
662 See the section below on setting up GPG for more details.
664 cola.startupmode
665 ----------------
666 Control how the list of repositories is displayed in the startup dialog.
667 Set to `list` to view the list of repositories as a list, or `folder` to view
668 the list of repositories as a collection of folder icons.
669 Defaults to `list`.
671 cola.statusindent
672 -----------------
673 Set to `true` to indent files in the Status widget.  Files in the `Staged`,
674 `Modified`, etc. categories will be grouped in a tree-like structure.
675 Defaults to `false`.
677 cola.statusshowtotals
678 ---------------------
679 Set to `true` to display files counts in the Status widget's category titles.
680 Defaults to `false`.
682 cola.tabwidth
683 -------------
684 The number of columns occupied by a tab character.  Defaults to 8.
686 cola.terminal
687 -------------
688 The command to use when launching commands within a graphical terminal.
690 `cola.terminal` defaults to `xterm -e` when unset.
691 e.g. when opening a shell, `git cola` will run `xterm -e $SHELL`.
693 `git cola` has built-in support for `xterm`, `gnome-terminal`, `konsole`.
694 If either `gnome-terminal`, `xfce4-terminal`, or `konsole` are installed
695 then they will be preferred over `xterm` when `cola.terminal` is unset.
697 The table below shows the built-in values that are used for the respective
698 terminal.  You can force the use of a specific terminal by configuring cola
699 accordingly.
701 cola.terminalshellquote
702 -----------------------
703 Some terminal require that the command string get passed as a string.
704 For example, ``xfce4-terminal -e "git difftool"`` requires shellquoting,
705 whereas ``gnome-terminal -- git difftool`` does not.
707 You should not need to set this variable for the built-in terminals
708 cola knows about -- it will behave correctly without configuration.
709 For example, when unconfigured, cola already knows that xfce4-terminal
710 requires shellquoting.
712 This configuration variable is for custom terminals outside of the builtin set.
713 The table below shows the builtin configuration.
715     Terminal            cola.terminal           cola.terminalshellquote
716     --------            -------------           -----------------------
717     gnome-terminal      gnome-terminal --       false
718     konsole             konsole -e              false
719     xfce4-terminal      xfce4-terminal -e       true
720     xterm               xterm -e                false
722 cola.textwidth
723 --------------
724 The number of columns used for line wrapping.
725 Tabs are counted according to `cola.tabwidth`.
727 .. _cola_theme:
729 cola.theme
730 ----------
731 Specifies the GUI theme to use throughout `git cola`. The theme specified
732 must be one of the following values:
734 * `default` â€“ default Qt theme, may appear different on various systems
735 * `flat-dark-blue`
736 * `flat-dark-green`
737 * `flat-dark-grey`
738 * `flat-dark-red`
739 * `flat-light-blue`
740 * `flat-light-green`
741 * `flat-light-grey`
742 * `flat-light-red`
744 If unset, or set to an invalid value, then the default style will be
745 used. The `default` theme is generated by Qt internal engine and should look
746 native but may look noticeably different on different platforms. The flat
747 themes on the other hand should look similar (but not identical) on various
748 systems.
750 The GUI theme can also be specified by passing ``--theme=<name>`` on the
751 command line.
753 cola.turbo
754 ----------
755 Set to `true` to enable "turbo" mode.  "Turbo" mode disables some
756 features that can slow things down when operating on huge repositories.
757 "Turbo" mode will skip loading Git commit messages, author details, status
758 information, and commit date details in the `File Browser` tool.
759 Defaults to `false`.
761 cola.color.text
762 ---------------
763 The default diff text color, in hexadecimal #RRGGBB notation.
764 Defaults to "#030303"::
766     git config cola.color.text '#030303'
768 cola.color.add
769 --------------
770 The default diff "add" background color, in hexadecimal #RRGGBB notation.
771 Defaults to "#d2ffe4"::
773     git config cola.color.add '#d2ffe4'
775 cola.color.remove
776 -----------------
777 The default diff "remove" background color, in hexadecimal #RRGGBB notation.
778 Defaults to "#fee0e4"::
780     git config cola.color.remove '#fee0e4'
782 cola.color.header
783 -----------------
784 The default diff header text color, in hexadecimal #RRGGBB notation.
785 Defaults to "#bbbbbb"::
787     git config cola.color.header '#bbbbbb'
789 gui.diffcontext
790 ---------------
791 The number of diff context lines to display.
793 gui.displayuntracked
794 --------------------
795 `git cola` avoids showing untracked files when set to `false`.
797 gui.editor
798 ----------
799 The default text editor to use is defined in `gui.editor`.
800 The config variable overrides the VISUAL environment variable.
801 e.g. `gvim -f -p`.
803 gui.historybrowser
804 ------------------
805 The history browser to use when visualizing history.
806 Defaults to `gitk`.
808 diff.tool
809 ---------
810 The default diff tool to use.
812 merge.tool
813 ----------
814 The default merge tool to use.
816 user.email
817 ----------
818 Your email address to be recorded in any newly created commits.
819 Can be overridden by the 'GIT_AUTHOR_EMAIL', 'GIT_COMMITTER_EMAIL', and
820 'EMAIL' environment variables.
822 user.name
823 ---------
824 Your full name to be recorded in any newly created commits.
825 Can be overridden by the 'GIT_AUTHOR_NAME' and 'GIT_COMMITTER_NAME'
826 environment variables.
828 ENVIRONMENT VARIABLES
829 =====================
831 GIT_COLA_ICON_THEME
832 -------------------
833 When set in the environment, `GIT_COLA_ICON_THEME` overrides the
834 theme specified in the `cola.icontheme` configuration.
835 Read :ref:`cola_icontheme` for more details.
837 GIT_COLA_SCALE
838 --------------
839 .. Important:: `GIT_COLA_SCALE` should not be used with newer versions of Qt.
841     Set `QT_AUTO_SCREEN_SCALE_FACTOR` to `1` and Qt will automatically
842     scale the interface to the correct size based on the display DPI.
843     This option is also available by setting `cola.hidpi` configuration.
845     See the `Qt High DPI documentation <https://doc.qt.io/qt-5/highdpi.html>`_
846     for more details.
848 `git cola` can be made to scale its interface for HiDPI displays.
849 When defined, `git cola` will scale icons, radioboxes, and checkboxes
850 according to the scale factor.  The default value is `1`.
851 A good value is `2` for high-resolution displays.
853 Fonts are not scaled, as their size can already be set in the settings.
855 GIT_COLA_TRACE
856 --------------
857 When defined, `git cola` logs `git` commands to stdout.
858 When set to `full`, `git cola` also logs the exit status and output.
859 When set to `trace`, `git cola` logs to the `Console` widget.
861 VISUAL
862 ------
863 Specifies the default editor to use.
864 This is ignored when the `gui.editor` configuration variable is defined.
866 LANGUAGE SETTINGS
867 =================
868 `git cola` automatically detects your language and presents some
869 translations when available.  This may not be desired, or you
870 may want `git cola` to use a specific language.
872 You can make `git cola` use an alternative language by creating a
873 `~/.config/git-cola/language` file containing the standard two-letter
874 gettext language code, e.g. "en", "de", "ja", "zh", etc.::
876     mkdir -p ~/.config/git-cola &&
877     echo en >~/.config/git-cola/language
879 Alternatively you may also use LANGUAGE environmental variable to temporarily
880 change `git cola`'s language just like any other gettext-based program.  For
881 example to temporarily change `git cola`'s language to English::
883     LANGUAGE=en git cola
885 To make `git cola` use the zh_TW translation with zh_HK, zh, and en as a
886 fallback.::
888     LANGUAGE=zh_TW:zh_HK:zh:en git cola
891 CUSTOM GUI ACTIONS
892 ==================
893 `git cola` allows you to define custom GUI actions by setting `git config`
894 variables.  The "name" of the command appears in the "Actions" menu.
896 guitool.<name>.cmd
897 ------------------
898 Specifies the shell command line to execute when the corresponding item of the
899 Tools menu is invoked. This option is mandatory for every tool. The command is
900 executed from the root of the working directory, and in the environment it
901 receives the name of the tool as GIT_GUITOOL, the name of the currently
902 selected file as FILENAME, and the name of the current branch as CUR_BRANCH
903 (if the head is detached, CUR_BRANCH is empty).
905 guitool.<name>.background
906 -------------------------
907 Run the command in the background (similar to editing and difftool actions).
908 This avoids blocking the GUI.  Setting `background` to `true` implies
909 `noconsole` and `norescan`.
911 guitool.<name>.needsfile
912 ------------------------
913 Run the tool only if a diff is selected in the GUI. It guarantees that
914 FILENAME is not empty.
916 guitool.<name>.noconsole
917 ------------------------
918 Run the command silently, without creating a window to display its output.
920 guitool.<name>.norescan
921 -----------------------
922 Don’t rescan the working directory for changes after the tool finishes
923 execution.
925 guitool.<name>.confirm
926 ----------------------
927 Show a confirmation dialog before actually running the tool.
929 guitool.<name>.argprompt
930 ------------------------
931 Request a string argument from the user, and pass it to the tool through the
932 ARGS environment variable. Since requesting an argument implies confirmation,
933 the confirm option has no effect if this is enabled. If the option is set to
934 true, yes, or 1, the dialog uses a built-in generic prompt; otherwise the
935 exact value of the variable is used.
937 guitool.<name>.revprompt
938 ------------------------
939 Request a single valid revision from the user, and set the REVISION
940 environment variable. In other aspects this option is similar to argprompt,
941 and can be used together with it.
943 guitool.<name>.revunmerged
944 --------------------------
945 Show only unmerged branches in the revprompt subdialog. This is useful for
946 tools similar to merge or rebase, but not for things like checkout or reset.
948 guitool.<name>.title
949 --------------------
950 Specifies the title to use for the prompt dialog.
951 Defaults to the tool name.
953 guitool.<name>.prompt
954 ---------------------
955 Specifies the general prompt string to display at the top of the dialog,
956 before subsections for argprompt and revprompt.
957 The default value includes the actual command.
959 guitool.<name>.shortcut
960 -----------------------
961 Specifies a keyboard shortcut for the custom tool.
963 The value must be a valid string understood by the `QAction::setShortcut()` API.
964 See http://qt-project.org/doc/qt-4.8/qkeysequence.html#QKeySequence-2
965 for more details about the supported values.
967 Avoid creating shortcuts that conflict with existing built-in `git cola`
968 shortcuts.  Creating a conflict will result in no action when the shortcut
969 is used.
971 SETTING UP GPG FOR SIGNED COMMITS
972 =================================
973 When creating signed commits, `gpg` will attempt to read your password from the
974 terminal from which `git cola` was launched.
975 The way to make this work smoothly is to use a GPG agent so that you can avoid
976 needing to re-enter your password every time you commit.
978 This also gets you a graphical passphrase prompt instead of getting prompted
979 for your password in the terminal.
981 Install gpg-agent and friends
982 -----------------------------
983 On Mac OS X, you may need to `brew install gpg-agent` and install the
984 `Mac GPG Suite <https://gpgtools.org/macgpg2/>`_.
986 On Linux use your package manager to install gnupg2,
987 gnupg-agent and pinentry-qt, e.g.::
989     sudo apt-get install gnupg2 gnupg-agent pinentry-qt
991 On Linux, you should also configure Git so that it uses gpg2 (gnupg2),
992 otherwise you will get errors mentioning, "unable to open /dev/tty".
993 Set Git's `gpg.program` to `gpg2`::
995     git config --global gpg.program gpg2
997 Configure gpg-agent and a pin-entry program
998 -------------------------------------------
999 On Mac OS X, edit `~/.gnupg/gpg.conf` to include the line,::
1001     use-agent
1003 This is typically not needed on Linux, where `gpg2` is used, as
1004 this is the default value when using `gpg2`.
1006 Next, edit `~/.gnupg/gpg-agent.conf` to contain a pinentry-program line
1007 pointing to the pinentry program for your platform.
1009 The following example `~/.gnupg/gpg-agent.conf` shows how to use
1010 pinentry-gtk-2 on Linux::
1012     pinentry-program /usr/bin/pinentry-gtk-2
1013     default-cache-ttl 3600
1015 This following example `.gnupg/gpg-agent.conf` shows how to use MacGPG2's
1016 pinentry app on On Mac OS X::
1018     pinentry-program /usr/local/MacGPG2/libexec/pinentry-mac.app/Contents/MacOS/pinentry-mac
1019     default-cache-ttl 3600
1020     enable-ssh-support
1021     use-standard-socket
1023 Once this has been set up then you will need to reload your gpg-agent config::
1025     echo RELOADAGENT | gpg-connect-agent
1027 If you see the following output::
1029     OK
1031 Then the daemon is already running, and you do not need to start it yourself.
1033 If it is not running, eval the output of ``gpg-agent --daemon`` in your shell
1034 prior to launching `git cola`.::
1036     eval $(gpg-agent --daemon)
1037     git cola
1039 WINDOWS NOTES
1040 =============
1042 Git Installation
1043 ----------------
1044 If Git is installed in a custom location, e.g. not installed in `C:/Git` or
1045 Program Files, then the path to Git must be configured by creating a file in
1046 your home directory `~/.config/git-cola/git-bindir` that points to your git
1047 installation.  e.g.::
1049     C:/Tools/Git/bin
1051 LINKS
1052 =====
1054 Git Cola's Git Repository
1055 -------------------------
1056 https://github.com/git-cola/git-cola/
1058 Git Cola Homepage
1059 -----------------
1060 https://git-cola.github.io/
1062 Mailing List
1063 ------------
1064 https://groups.google.com/group/git-cola