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 diff or grep screens 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 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>`_.
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`.
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>`_
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.
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.
226 Add to the staging area using `git add <http://git-scm.com/docs/git-add>`_
227 Marks unmerged files as resolved.
231 Launches the configured visual text editor
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
248 Remove from the index/staging area with
249 `git reset <http://git-scm.com/docs/git-reset>`_
253 Resolve conflicts using `git mergetool <http://git-scm.com/docs/git-mergetool>`_.
257 Delete untracked files from the filesystem.
261 Adds untracked files to to the .gitignore file.
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
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>`_.
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
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.
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.
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.
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::
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.
405 Various actions are available through the right-click context menu.
406 Different actions are available depending of selected branch status.
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>`_.
421 `git pull --no-ff [<remote>] [<branchname>] <https://git-scm.com/docs/git-pull>`_.
426 `git push [<remote>] [<branchname>] <https://git-scm.com/docs/git-push>`_.
430 The rename branch action runs
431 `git branch -M [<branchname>] <https://git-scm.com/docs/git-push>`_.
435 The delete branch branch action runs
436 `git branch -D [<branchname>] <https://git-scm.com/docs/git-branch>`_.
440 The remote branch action runs
441 `git push --delete [<remote>] [<branchname>] <https://git-scm.com/docs/git-push>`_.
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 patches 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 macOS, using the ``default`` theme will automatically inherit "Dark Mode"
481 color themes when configured via System Preferences. You will need to
482 configure the dark icon theme as noted above when dark mode is enabled.
484 On Linux, you may want Qt to follow the Window manager theme by configuring it
485 to do so using the ``qt5ct`` Qt5 configuration tool. Install ``qt5ct`` on
486 Debian/Ubuntu systems to make this work.::
488 sudo apt install qt5ct
490 Once installed, update your `~/.bash_profile` to activate ``qt5ct``::
492 # Use the style configured using the qt5ct tool
493 export QT_QPA_PLATFORMTHEME=qt5ct
495 This only work with the `default` theme. The other themes replace the color
496 palette with theme-specific colors.
498 Some systems may require that you override `QT_STYLE_OVERRIDE` in order to
499 use a dark theme or to better interact with the Desktop environment.
500 Some systems provide a theme that you can install::
502 sudo apt-get install adwaita-qt
504 You can activate the theme using the following enviornment variable::
506 # Override the default theme to adwait-dark
507 export QT_STYLE_OVERRIDE=adwaita-dark
509 `QT_STYLE_OVERRIDE` may already be set in your Desktop Environment, so check that
510 variable for reference if you get unexpected hangs when launching `git-cola` or
511 when the default theme does not follow the desktop's theme on Linux.
513 If you don't want to set this variable globally then you can set it when launching
514 cola from the command-line::
516 QT_STYLE_OVERRIDE=adwaita-dark git cola
518 The following is a user-contributed custom `git-cola.desktop` file that can be used to
519 launch Git Cola with these settings preset for you::
523 Comment=The highly caffeinated Git GUI
525 Exec=env QT_STYLE_OVERRIDE=adwaita-dark git-cola --prompt --icon-theme dark
530 Categories=Development;RevisionControl;
531 X-KDE-SubstituteUID=false
533 You may also want to customize the diff colors when using a dark theme::
535 git config --global cola.color.add 86c19f
536 git config --global cola.color.remove c07067
538 Please see `#760 <https://github.com/git-cola/git-cola/issues/760>`_ for more details.
542 To create your own custom theme for Git Cola just create a QSS file and put it in
543 ``~/.config/themes/``. You can add as many files as you want. Each file will become
544 an option in ``Menu -> File -> Preferences -> Appearance -> GUI theme``.
546 Some examples can be found here `Qt Style Sheets Examples <https://doc.qt.io/qt-5/stylesheet-examples.html>`_.
549 CONFIGURATION VARIABLES
550 =======================
551 These variables can be set using `git config` or from the settings.
553 cola.autocompletepaths
554 ----------------------
555 Set to `false` to disable auto-completion of filenames in completion widgets.
556 This can speed up operations when working in large repositories.
559 cola.autoloadCommitTemplate
560 ---------------------------
561 Set to `true` to automatically load the commit template in the commit message
562 editor If the commit.template variable has not been configured, raise the
568 The command used to blame files. Defaults to `git gui blame`.
572 Whether to create a dock widget with the `Browser` tool.
573 Defaults to `false` to speedup startup time.
577 Inspect unmerged files for conflict markers before staging them.
578 This feature helps prevent accidental staging of unresolved merge conflicts.
583 `git cola`, when run outside of a Git repository, prompts the user for a
584 repository. Set `cola.defaultrepo` to the path of a Git repository to make
585 `git cola` attempt to use that repository before falling back to prompting
586 the user for a repository.
590 Specifies an additional dictionary for `git cola` to use in its spell checker.
591 This should be configured to the path of a newline-separated list of words.
595 Expand tabs into spaces in the commit message editor. When set to `true`,
596 `git cola` will insert a configurable number of spaces when tab is pressed.
597 The number of spaces is determined by `cola.tabwidth`.
602 Enables per-file gitattributes encoding and binary file support.
603 This tells `git cola` to honor the configured encoding when displaying
606 A `.gitattributes` file can set the ``binary`` attribute in order to force
607 specific untracked paths to be treated as binary files when diffing.
608 Binary files are displayed using a hexdump display.
612 # Treat *.exr files as binary files.
617 Specifies the font to use for `git cola`'s diff display.
621 Specifies the High DPI displays scale factor. Set `0` to automatically scaled.
622 Setting value between 0 and 1 is undefined.
623 This option requires at least Qt 5.6 to work.
624 See `Qt QT_SCALE_FACTOR documentation <https://doc.qt.io/qt-5/highdpi.html>`_
625 for more information.
631 Specifies the icon themes to use throughout `git cola`. The theme specified
632 must be the name of the subdirectory containing the icons, which in turn must
633 be placed in the inside the main "icons" directory in `git cola`'s
636 If unset, or set either "light" or "default", then the default style will be
637 used. If set to "dark" then the built-in "dark" icon theme, which is
638 suitable for a dark window manager theme, will be used.
640 If set to an absolute directory path then icons in that directory will be used.
641 This value can be set to multiple values using,
642 ``git config --add cola.icontheme $theme``.
644 This setting can be overridden by the `GIT_COLA_ICON_THEME` environment
645 variable, which can specify multiple themes using a colon-separated value.
647 The icon theme can also be specified by passing ``--icon-theme=<theme>`` on the
648 command line, once for each icon theme, in the order that they should be
649 searched. This can be used to override a subset of the icons, and fallback
650 to the built-in icons for the remainder.
652 cola.imagediff.<extension>
653 --------------------------
654 Enable image diffs for the specified file extension. For example, configuring
655 `git config --global cola.imagediff.svg false` will disable use of the visual
656 image diff for `.svg` files in all repos until is is explicitly toggled on.
661 Set to `false` to disable file system change monitoring. Defaults to `true`,
662 but also requires either Linux with inotify support or Windows with `pywin32`
663 installed for file system change monitoring to actually function.
667 Set to `true` to automatically refresh when `git cola` gains focus. Defaults
668 to `false` because this can cause a pause whenever switching to `git cola` from
673 Whether to automatically break long lines while editing commit messages.
674 Defaults to `true`. This setting is configured using the `Preferences`
675 dialog, but it can be toggled for one-off usage using the commit message
676 editor's options sub-menu.
680 `git cola` caps the number of recent repositories to avoid cluttering
681 the start and recent repositories menu. The maximum number of repositories to
682 remember is controlled by `cola.maxrecent` and defaults to `8`.
686 `git cola` encodes paths dragged from its widgets into `utf-16` when adding
687 them to the drag-and-drop mime data (specifically, the `text/x-moz-url` entry).
688 `utf-16` is used to make `gnome-terminal` see the right paths, but other
689 terminals may expect a different encoding. If you are using a terminal that
690 expects a modern encoding, e.g. `terminator`, then set this value to `utf-8`.
694 `git cola` avoids reading large binary untracked files.
695 The maximum size to read is controlled by `cola.readsize`
696 and defaults to `2048`.
698 cola.resizebrowsercolumns
699 -------------------------
700 `git cola` will automatically resize the file browser columns as folders are
701 expanded/collapsed when ``cola.resizebrowsercolumns`` is set to `true`.
705 The "Stage" button in the `git cola` Actions panel stages all files when it is
706 activated and no files are selected. This can be problematic if it is
707 accidentally triggered after carefully preparing the index with staged
708 changes. "Safe Mode" is enabled by setting `cola.safemode` to `true`.
709 When enabled, `git cola` will do nothing when "Stage" is activated without a
710 selection. Defaults to `false`.
712 cola.savewindowsettings
713 -----------------------
714 `git cola` will remember its window settings when set to `true`.
715 Window settings and X11 sessions are saved in `$HOME/.config/git-cola`.
719 `git cola` displays the absolute path of the repository in the window title.
720 This can be disabled by setting `cola.showpath` to `false`.
725 `git cola` will sign commits by default when set `true`. Defaults to `false`.
726 See the section below on setting up GPG for more details.
730 Control how the list of repositories is displayed in the startup dialog.
731 Set to `list` to view the list of repositories as a list, or `folder` to view
732 the list of repositories as a collection of folder icons.
737 Set to `true` to indent files in the Status widget. Files in the `Staged`,
738 `Modified`, etc. categories will be grouped in a tree-like structure.
741 cola.statusshowtotals
742 ---------------------
743 Set to `true` to display files counts in the Status widget's category titles.
748 The number of columns occupied by a tab character. Defaults to 8.
752 The command to use when launching commands within a graphical terminal.
754 `cola.terminal` defaults to `xterm -e` when unset.
755 e.g. when opening a shell, `git cola` will run `xterm -e $SHELL`.
757 `git cola` has built-in support for `xterm`, `gnome-terminal`, `konsole`.
758 If either `gnome-terminal`, `xfce4-terminal`, or `konsole` are installed
759 then they will be preferred over `xterm` when `cola.terminal` is unset.
761 The table below shows the built-in values that are used for the respective
762 terminal. You can force the use of a specific terminal by configuring cola
765 cola.terminalshellquote
766 -----------------------
767 Some terminal require that the command string get passed as a string.
768 For example, ``xfce4-terminal -e "git difftool"`` requires shellquoting,
769 whereas ``gnome-terminal -- git difftool`` does not.
771 You should not need to set this variable for the built-in terminals
772 cola knows about -- it will behave correctly without configuration.
773 For example, when unconfigured, cola already knows that xfce4-terminal
774 requires shellquoting.
776 This configuration variable is for custom terminals outside of the builtin set.
777 The table below shows the builtin configuration.
779 Terminal cola.terminal cola.terminalshellquote
780 -------- ------------- -----------------------
781 gnome-terminal gnome-terminal -- false
782 konsole konsole -e false
783 xfce4-terminal xfce4-terminal -e true
788 The number of columns used for line wrapping.
789 Tabs are counted according to `cola.tabwidth`.
795 Specifies the GUI theme to use throughout `git cola`. The theme specified
796 must be one of the following values:
798 * `default` – default Qt theme, may appear different on various systems
808 If unset, or set to an invalid value, then the default style will be
809 used. The `default` theme is generated by Qt internal engine and should look
810 native but may look noticeably different on different platforms. The flat
811 themes on the other hand should look similar (but not identical) on various
814 The GUI theme can also be specified by passing ``--theme=<name>`` on the
819 Set to `true` to enable "turbo" mode. "Turbo" mode disables some
820 features that can slow things down when operating on huge repositories.
821 "Turbo" mode will skip loading Git commit messages, author details, status
822 information, and commit date details in the `File Browser` tool.
827 The default diff text color, in hexadecimal #RRGGBB notation.
828 Defaults to "#030303"::
830 git config cola.color.text '#030303'
834 The default diff "add" background color, in hexadecimal #RRGGBB notation.
835 Defaults to "#d2ffe4"::
837 git config cola.color.add '#d2ffe4'
841 The default diff "remove" background color, in hexadecimal #RRGGBB notation.
842 Defaults to "#fee0e4"::
844 git config cola.color.remove '#fee0e4'
848 The default diff header text color, in hexadecimal #RRGGBB notation.
849 Defaults to "#bbbbbb"::
851 git config cola.color.header '#bbbbbb'
855 Hooks are programs you can place in a hooks directory to trigger actions at
856 certain points in git’s execution. Hooks that don’t have the executable bit
859 By default the hooks directory is ``$GIT_DIR/hooks``, but that can
860 be changed via the ``core.hooksPath`` configuration variable
862 The ``cola-prepare-commit-msg`` hook functionality and Cola's Git LFS
863 detection honors this configuration.
865 Please see the `git hooks documentation <https://git-scm.com/docs/githooks>`_
870 The number of diff context lines to display.
874 `git cola` avoids showing untracked files when set to `false`.
878 The default text editor to use is defined in `gui.editor`.
879 The config variable overrides the VISUAL environment variable.
884 The history browser to use when visualizing history.
889 The default diff tool to use.
893 The default merge tool to use.
897 Your email address to be recorded in any newly created commits.
898 Can be overridden by the 'GIT_AUTHOR_EMAIL', 'GIT_COMMITTER_EMAIL', and
899 'EMAIL' environment variables.
903 Your full name to be recorded in any newly created commits.
904 Can be overridden by the 'GIT_AUTHOR_NAME' and 'GIT_COMMITTER_NAME'
905 environment variables.
907 ENVIRONMENT VARIABLES
908 =====================
912 When set in the environment, `GIT_COLA_ICON_THEME` overrides the
913 theme specified in the `cola.icontheme` configuration.
914 Read :ref:`cola_icontheme` for more details.
918 .. Important:: `GIT_COLA_SCALE` should not be used with newer versions of Qt.
920 Set `QT_AUTO_SCREEN_SCALE_FACTOR` to `1` and Qt will automatically
921 scale the interface to the correct size based on the display DPI.
922 This option is also available by setting `cola.hidpi` configuration.
924 See the `Qt High DPI documentation <https://doc.qt.io/qt-5/highdpi.html>`_
927 `git cola` can be made to scale its interface for HiDPI displays.
928 When defined, `git cola` will scale icons, radioboxes, and checkboxes
929 according to the scale factor. The default value is `1`.
930 A good value is `2` for high-resolution displays.
932 Fonts are not scaled, as their size can already be set in the settings.
936 When defined, `git cola` logs `git` commands to stdout.
937 When set to `full`, `git cola` also logs the exit status and output.
938 When set to `trace`, `git cola` logs to the `Console` widget.
942 Specifies the default editor to use.
943 This is ignored when the `gui.editor` configuration variable is defined.
947 `git cola` automatically detects your language and presents some
948 translations when available. This may not be desired, or you
949 may want `git cola` to use a specific language.
951 You can make `git cola` use an alternative language by creating a
952 `~/.config/git-cola/language` file containing the standard two-letter
953 gettext language code, e.g. "en", "de", "ja", "zh", etc.::
955 mkdir -p ~/.config/git-cola &&
956 echo en >~/.config/git-cola/language
958 Alternatively you may also use LANGUAGE environmental variable to temporarily
959 change `git cola`'s language just like any other gettext-based program. For
960 example to temporarily change `git cola`'s language to English::
964 To make `git cola` use the zh_TW translation with zh_HK, zh, and en as a
967 LANGUAGE=zh_TW:zh_HK:zh:en git cola
972 `git cola` allows you to define custom GUI actions by setting `git config`
973 variables. The "name" of the command appears in the "Actions" menu.
977 Specifies the shell command line to execute when the corresponding item of the
978 Tools menu is invoked. This option is mandatory for every tool. The command is
979 executed from the root of the working directory, and in the environment it
980 receives the name of the tool as GIT_GUITOOL, the name of the currently
981 selected file as FILENAME, and the name of the current branch as CUR_BRANCH
982 (if the head is detached, CUR_BRANCH is empty).
984 If ``<name>`` contains slashes (``/``) then the leading part of the name,
985 up until the final slash, is treated like a path of submenus under which the
986 actions will be created.
988 For example, configuring ``guitool.Commands/Util/echo.cmd`` creates a
989 ``Commands`` menu inside the top-level ``Actions`` menu, a ``Util`` menu
990 inside the ``Commands`` menu and an ``echo`` action inside the ``Commands``
993 guitool.<name>.background
994 -------------------------
995 Run the command in the background (similar to editing and difftool actions).
996 This avoids blocking the GUI. Setting `background` to `true` implies
997 `noconsole` and `norescan`.
999 guitool.<name>.needsfile
1000 ------------------------
1001 Run the tool only if a diff is selected in the GUI. It guarantees that
1002 FILENAME is not empty.
1004 guitool.<name>.noconsole
1005 ------------------------
1006 Run the command silently, without creating a window to display its output.
1008 guitool.<name>.norescan
1009 -----------------------
1010 Don’t rescan the working directory for changes after the tool finishes
1013 guitool.<name>.confirm
1014 ----------------------
1015 Show a confirmation dialog before actually running the tool.
1017 guitool.<name>.argprompt
1018 ------------------------
1019 Request a string argument from the user, and pass it to the tool through the
1020 ARGS environment variable. Since requesting an argument implies confirmation,
1021 the confirm option has no effect if this is enabled. If the option is set to
1022 true, yes, or 1, the dialog uses a built-in generic prompt; otherwise the
1023 exact value of the variable is used.
1025 guitool.<name>.revprompt
1026 ------------------------
1027 Request a single valid revision from the user, and set the REVISION
1028 environment variable. In other aspects this option is similar to argprompt,
1029 and can be used together with it.
1031 guitool.<name>.revunmerged
1032 --------------------------
1033 Show only unmerged branches in the revprompt subdialog. This is useful for
1034 tools similar to merge or rebase, but not for things like checkout or reset.
1036 guitool.<name>.title
1037 --------------------
1038 Specifies the title to use for the prompt dialog.
1039 Defaults to the tool name.
1041 guitool.<name>.prompt
1042 ---------------------
1043 Specifies the general prompt string to display at the top of the dialog,
1044 before subsections for argprompt and revprompt.
1045 The default value includes the actual command.
1047 guitool.<name>.shortcut
1048 -----------------------
1049 Specifies a keyboard shortcut for the custom tool.
1051 The value must be a valid string understood by the `QAction::setShortcut()` API.
1052 See http://qt-project.org/doc/qt-4.8/qkeysequence.html#QKeySequence-2
1053 for more details about the supported values.
1055 Avoid creating shortcuts that conflict with existing built-in `git cola`
1056 shortcuts. Creating a conflict will result in no action when the shortcut
1059 SETTING UP GPG FOR SIGNED COMMITS
1060 =================================
1061 When creating signed commits, `gpg` will attempt to read your password from the
1062 terminal from which `git cola` was launched.
1063 The way to make this work smoothly is to use a GPG agent so that you can avoid
1064 needing to re-enter your password every time you commit.
1066 This also gets you a graphical passphrase prompt instead of getting prompted
1067 for your password in the terminal.
1069 Install gpg-agent and friends
1070 -----------------------------
1071 On Mac OS X, you may need to `brew install gpg-agent` and install the
1072 `Mac GPG Suite <https://gpgtools.org/macgpg2/>`_.
1074 On Linux use your package manager to install gnupg2,
1075 gnupg-agent and pinentry-qt, e.g.::
1077 sudo apt-get install gnupg2 gnupg-agent pinentry-qt
1079 On Linux, you should also configure Git so that it uses gpg2 (gnupg2),
1080 otherwise you will get errors mentioning, "unable to open /dev/tty".
1081 Set Git's `gpg.program` to `gpg2`::
1083 git config --global gpg.program gpg2
1085 Configure gpg-agent and a pin-entry program
1086 -------------------------------------------
1087 On Mac OS X, edit `~/.gnupg/gpg.conf` to include the line,::
1091 This is typically not needed on Linux, where `gpg2` is used, as
1092 this is the default value when using `gpg2`.
1094 Next, edit `~/.gnupg/gpg-agent.conf` to contain a pinentry-program line
1095 pointing to the pinentry program for your platform.
1097 The following example `~/.gnupg/gpg-agent.conf` shows how to use
1098 pinentry-gtk-2 on Linux::
1100 pinentry-program /usr/bin/pinentry-gtk-2
1101 default-cache-ttl 3600
1103 This following example `.gnupg/gpg-agent.conf` shows how to use MacGPG2's
1104 pinentry app on On Mac OS X::
1106 pinentry-program /usr/local/MacGPG2/libexec/pinentry-mac.app/Contents/MacOS/pinentry-mac
1107 default-cache-ttl 3600
1111 Once this has been set up then you will need to reload your gpg-agent config::
1113 echo RELOADAGENT | gpg-connect-agent
1115 If you see the following output::
1119 Then the daemon is already running, and you do not need to start it yourself.
1121 If it is not running, eval the output of ``gpg-agent --daemon`` in your shell
1122 prior to launching `git cola`.::
1124 eval $(gpg-agent --daemon)
1132 If Git is installed in a custom location, e.g. not installed in `C:/Git` or
1133 Program Files, then the path to Git must be configured by creating a file in
1134 your home directory `~/.config/git-cola/git-bindir` that points to your git
1135 installation. e.g.::
1139 SSH Agents for Key-based Authentication
1140 ---------------------------------------
1141 You may need to setup ssh-agent in order to use SSH key-based authentication
1142 on Windows. It has been reported that starting OpenSSH agent in
1143 Windows Services and adding the key using Powershell are necessary in order
1144 to get things working.
1146 Please see the following links for more details.
1148 https://stackoverflow.com/questions/18683092/how-to-run-ssh-add-on-windows
1152 `FIPS Security Mode <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/FIPS_Mode_-_an_explanation>`_
1153 is available in newer versions of Python. These include Python 3.9+ and the
1154 patched Python 3.6 used by CentOS8/RHEL8 (and possibly others).
1156 Git Cola uses the ``hashlib.md5`` function and adheres to the FIPS security
1157 mode when available. Git Cola does not use the MD5 value for security purposes.
1158 MD% is used only for the purposes of implementing the ``cola/gravatar.py``
1164 Git Cola's Git Repository
1165 -------------------------
1166 https://github.com/git-cola/git-cola/
1170 https://git-cola.github.io/
1174 https://groups.google.com/group/git-cola