share/doc/git-cola/userguide.rst

   1 User Guide
   2 ==========
   3
   4 * :ref:`Introduction <intro>`
   5 * :ref:`Main Window <mainwindow>`
   6 * :ref:`Shortcut Keys <shortcuts>`
   7
   8 .. _intro:
   9
  10 Introduction
  11 ----------------------------------------------------------------
  12 `git-cola` is a powerful GUI for git that gives you an easy way to
  13 interact with git repositories.
  14
  15 .. _mainwindow:
  16
  17 Main Window
  18 ----------------------------------------------------------------
  19 This image shows the main `git-cola` interface.
  20
  21 .. figure:: images/cola-macosx.png
  22
  23     git-cola running on Mac OSX
  24
  25 1. Repository Status
  26
  27    The repository status view displays paths that git detects as either
  28    staged for the next commit (`Staged`),
  29    modified relative to the staging area (`Modified`), or
  30    an unresolved file from a merge (`Unmerged`).
  31
  32    A file can be staged or unstaged by either double-clicking on its name or
  33    single-clicking on its icon.  Right-clicking on an entry displays additional
  34    actions that can be performed such as launching `git-difftool` or `git-mergetool`.
  35
  36 2. Diff View
  37
  38    The diff view displays diffs for selected files.
  39    Additions are shown in green and removals are displayed in light red.
  40    Extraneous whitespace is shown in a pure red background.
  41
  42    Right-clicking in the diff view provides access to additional actions
  43    that can operate on the cursor location or selection.
  44
  45 3. Diff Hunks
  46
  47    The `@@` diff headers divide each diff region.  Selecting specific lines
  48    and using the 'Stage/Unstage Selected' actions will operate on that
  49    subset of the diff.  Clicking within a diff region and selecting
  50    the 'Stage/Unstage Hunk' action will operate on the entire region
  51    within the diff header.
  52
  53 .. _shortcuts:
  54
  55 Shortcut Keys
  56 ----------------------------------------------------------------
  57 * :command:`h` -- Stage/unstage hunk at text cursor position
  58 * :command:`s` -- Stage/unstage selection
  59 * :command:`ctrl-b` -- Create branch
  60 * :command:`alt-b` -- Checkout branch
  61 * :command:`ctrl-d` -- Diffstat the most recent commit
  62 * :command:`ctrl-e` -- Export patches
  63 * :command:`ctrl-p` -- Cherry-pick
  64 * :command:`ctrl-r` -- Rescan/refresh repository status
  65 * :command:`alt-a` -- Stage all modified files
  66 * :command:`alt-u` -- Stage all untracked files
  67 * :command:`alt-t` -- Stage selected files
  68 * :command:`shift-alt-s` -- Stash dialog
  69
  70 Classic View Shortcut Keys
  71 ----------------------------------------------------------------
  72 * :command:`h` -- Move to parent/collapse
  73 * :command:`j` -- Move down
  74 * :command:`k` -- Move up
  75 * :command:`l` -- Expand directory
  76 * :command:`ctrl-e` -- Launch Editor
  77 * :command:`ctrl-s` -- Stage Selected
  78 * :command:`ctrl-u` -- Unstage Selected
  79 * :command:`shift-ctrl-h` -- View History
  80 * :command:`ctrl-d` -- View Diff (`git difftool <path>`)
  81 * :command:`shift-ctrl-d` -- Diff Against Predecessor
  82 * :command:`ctrl-z` -- Revert uncommitted changes (`git checkout HEAD <path>...`)