<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Tools — git-cola v1.7.7 documentation</title>
<link rel="stylesheet" href="static/haiku.css" type="text/css" />
<link rel="stylesheet" href="static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/print.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '1.7.7',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="static/jquery.js"></script>
<script type="text/javascript" src="static/underscore.js"></script>
<script type="text/javascript" src="static/doctools.js"></script>
<script type="text/javascript" src="_static/theme_extras.js"></script>
<link rel="top" title="git-cola v1.7.7 documentation" href="index.html" />
<link rel="next" title="Keyboard Shortcuts" href="mainwindow.html" />
<link rel="prev" title="Introduction" href="intro.html" />
</head>
<body>
<div class="header"><h1 class="heading"><a href="index.html">
<span>git-cola v1.7.7 documentation</span></a></h1>
<h2 class="heading"><span>Tools</span></h2>
</div>
<div class="topnav">
<p>
«  <a href="intro.html">Introduction</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
  ::  
<a href="mainwindow.html">Keyboard Shortcuts</a>  »
</p>
</div>
<div class="content">
<div class="section" id="tools">
<h1>Tools<a class="headerlink" href="#tools" title="Permalink to this headline">¶</a></h1>
<p>The <cite>git cola</cite> interface is composed of various cooperating tools.
Double-clicking a tool opens it in its own subwindow.
Dragging it around moves and places it within the window.</p>
<p>Tools can be hidden and rearranged however you like.
<cite>git cola</cite> carefully remembers your window layout and restores
it the next time it is launched.</p>
<p>A hidden tool can be re-opened using the <cite>Tools</cite> menu as well
as the <cite>Alt-1,2,3,...</cite>, shortcut keys.</p>
<div class="section" id="status">
<span id="id1"></span><h2>Status<a class="headerlink" href="#status" title="Permalink to this headline">¶</a></h2>
<p>The <cite>Status</cite> tool provides a visual analog to the
<a class="reference external" href="http://schacon.github.com/git/git-status.html">git status</a> command.</p>
<p><cite>Status</cite> displays files that are <cite>modified</cite> relative to the staging area,
<cite>staged</cite> for the next commit, <cite>unmerged</cite> files from an in-progress merge,
and files that are <cite>untracked</cite> to git.</p>
<p>These are the same categories one sees when running
<a class="reference external" href="http://schacon.github.com/git/git-status.html">git status</a>
on the command line.</p>
<p>You can navigate through the list of files using keyboard arrows as well
as the ergonomical and vim-like <cite>j</cite> and <cite>k</cite> shortcut keys.</p>
<p>There are several convenient ways to interact with files in the <cite>Status</cite> tool.
Selecting a file displays its diff in the <a class="reference internal" href="#diff"><em>Diff</em></a> viewer.
Double-clicking a file stages its contents, as does the
the <cite>Ctrl-s</cite> shortcut key.</p>
<p><cite>Ctrl-e</cite> opens selected files in the conifgured <cite>$EDITOR</cite>, and
<cite>Ctrl-d</cite> opens selected files using
<a class="reference external" href="http://schacon.github.com/git/git-difftool.html">git difftool</a>.</p>
<p>Additional actions can be performed using the right-click context menu.</p>
<div class="section" id="configuring-your-editor">
<h3>Configuring your $EDITOR<a class="headerlink" href="#configuring-your-editor" title="Permalink to this headline">¶</a></h3>
<p>The editor used by <cite>Ctrl-e</cite> is configured from the Preferences screen.
The environment variables <cite>$VISUAL</cite> and <cite>$EDITOR</cite> are used when no editor
has been configured.</p>
<p>The editor preference is saved in the <cite>gui.editor</cite> variable using
<a class="reference external" href="http://schacon.github.com/git/git-config.html">git config</a>.</p>
<p><em>ProTip</em> – Setting <cite>gvim -p</cite> as your configured editor opens
multiple files using tabs (and <cite>gvim -o</cite> uses splits).</p>
<p><cite>git cola</cite> is {vim, emacs, textpad, notepad++}-aware.
When you select a line in the <cite>grep</cite> screen and press any of
<cite>Enter</cite>, <cite>Ctrl-e</cite>, or the “Edit” button, you are taken to that exact line.</p>
</div>
<div class="section" id="actions">
<h3>Actions<a class="headerlink" href="#actions" title="Permalink to this headline">¶</a></h3>
<p>Clicking the <cite>Staged</cite> folder shows a diffstat for the index.</p>
<p>Clicking the <cite>Modified</cite> folder shows a diffstat for the worktree.</p>
<p>Clicking individual files sends diffs to the <cite>Diff Display</cite>.</p>
<p>Double-clicking individual files adds and removes their content from the index.</p>
<p>Various actions that are available through the right-click context menu.
Different actions are available depending a file’s status.</p>
<div class="section" id="staged-files">
<h4>Staged Files<a class="headerlink" href="#staged-files" title="Permalink to this headline">¶</a></h4>
<dl class="docutils">
<dt>Unstage Selected</dt>
<dd>Remove from the index/staging area with
<a class="reference external" href="http://schacon.github.com/git/git-reset.html">git reset</a></dd>
<dt>Launch Editor</dt>
<dd>Launch the configured visual editor</dd>
<dt>Launch Difftool</dt>
<dd>Visualize changes with
<a class="reference external" href="http://schacon.github.com/git/git-difftool.html">git difftool</a></dd>
<dt>Revert Unstaged Edits</dt>
<dd>Throw away unstaged edits.</dd>
</dl>
</div>
<div class="section" id="modified-files">
<h4>Modified Files<a class="headerlink" href="#modified-files" title="Permalink to this headline">¶</a></h4>
<dl class="docutils">
<dt>Stage Selected</dt>
<dd>Add to the staging area with
<a class="reference external" href="http://schacon.github.com/git/git-add.html">git add</a></dd>
<dt>Launch Editor</dt>
<dd>Launches the configured visual text editor</dd>
<dt>Launch Difftool</dt>
<dd>Visualize changes relative to the index with
<a class="reference external" href="http://schacon.github.com/git/git-difftool.html">git difftool</a></dd>
<dt>Revert Unstaged Edits</dt>
<dd>Reverts unstaged content by checking out selected paths
from the index/staging area</dd>
<dt>Revert Uncommited Edits</dt>
<dd>Throws away uncommitted edits</dd>
</dl>
</div>
<div class="section" id="unmerged-files">
<h4>Unmerged Files<a class="headerlink" href="#unmerged-files" title="Permalink to this headline">¶</a></h4>
<dl class="docutils">
<dt>Launch Merge Tool</dt>
<dd>Resolve conflicts using
<a class="reference external" href="http://schacon.github.com/git/git-mergetool.html">git mergetool</a></dd>
<dt>Stage Selected</dt>
<dd>Mark as resolved using
<a class="reference external" href="http://schacon.github.com/git/git-add.html">git add</a></dd>
<dt>Launch Editor</dt>
<dd>Launch the configured visual text editor</dd>
</dl>
</div>
<div class="section" id="untracked-files">
<h4>Untracked Files<a class="headerlink" href="#untracked-files" title="Permalink to this headline">¶</a></h4>
<dl class="docutils">
<dt>Stage Selected</dt>
<dd>Add to the index/staging area with
<a class="reference external" href="http://schacon.github.com/git/git-add.html">git add</a></dd>
<dt>Launch Editor</dt>
<dd>Launch the configured visual text editor</dd>
<dt>Delete File(s)</dt>
<dd>Delete files from the filesystem</dd>
<dt>Add to .gitignore</dt>
<dd>Adds file/files to GIT ignore list for untracked files</dd>
</dl>
</div>
</div>
</div>
<div class="section" id="diff">
<span id="id7"></span><h2>Diff<a class="headerlink" href="#diff" title="Permalink to this headline">¶</a></h2>
<p>The diff viewer/editor displays diffs for selected files.
Additions are shown in green and removals are displayed in light red.
Extraneous whitespace is shown with a pure-red background.</p>
<p>Right-clicking in the diff provides access to additional actions
that use either the cursor location or text selection.</p>
<div class="section" id="staging-content-for-commit">
<h3>Staging content for commit<a class="headerlink" href="#staging-content-for-commit" title="Permalink to this headline">¶</a></h3>
<p>The <tt class="docutils literal"><span class="pre">@@</span></tt> patterns denote a new diff region. Selecting lines of diff
and using the <cite>Stage Selected</cite> command will stage just the selected lines.
Clicking within a diff region and selecting <cite>Stage Section</cite> stages the
entire patch region.</p>
<p>The corresponding opposite commands can be performed on staged files as well,
e.g. staged content can be selectively removed from the index when we are
viewing diffs for staged content.</p>
</div>
</div>
<div class="section" id="commit-message-editor">
<h2>Commit Message Editor<a class="headerlink" href="#commit-message-editor" title="Permalink to this headline">¶</a></h2>
<p>The <cite>git cola</cite> commit message editor is a simple text widget
for entering commit messages.</p>
<p>You can navigate between the <cite>Subject</cite> and <cite>Extended description...</cite>
fields using the keyboard arrow keys.</p>
<p>Pressing enter when inside the <cite>Subject</cite> field jumps down to the
extended description field.</p>
<p>The <cite>Options</cite> button menu to the left of the subject field
provides access to the additional actions.</p>
<p>The <cite>Ctrl+i</cite> keyboard shortcut adds a standard “Signed-off-by: ” line,
and <cite>Ctrl+Enter</cite> creates a new commit using the commit message and
staged content.</p>
<div class="section" id="sign-off">
<h3>Sign Off<a class="headerlink" href="#sign-off" title="Permalink to this headline">¶</a></h3>
<p>The <cite>Sign Off</cite> button adds a standard:</p>
<div class="highlight-python"><pre>Signed-off-by: A. U. Thor <a.u.thor@example.com></pre>
</div>
<p>line to the bottom of the commit message.</p>
<p>Invoking this action is equivalent to passing the <tt class="docutils literal"><span class="pre">-s</span></tt> option
to <a class="reference external" href="http://schacon.github.com/git/git-commit.html">git commit</a>.</p>
</div>
<div class="section" id="commit">
<h3>Commit<a class="headerlink" href="#commit" title="Permalink to this headline">¶</a></h3>
<p>The commit button runs
<a class="reference external" href="http://schacon.github.com/git/git-commit.html">git commit</a>.
The contents of the commit message editor is provided as the commit message.</p>
<p>Only staged files are included in the commit – this is the same behavior
as running <tt class="docutils literal"><span class="pre">git</span> <span class="pre">commit</span></tt> on the command-line.</p>
</div>
<div class="section" id="line-and-column-display">
<h3>Line and Column Display<a class="headerlink" href="#line-and-column-display" title="Permalink to this headline">¶</a></h3>
<p>The current line and column number is displayed by the editor.
E.g. a <tt class="docutils literal"><span class="pre">5,0</span></tt> display means that the cursor is located at
line five, column zero.</p>
<p>The display changes colors when lines get too long.
Yellow indicates the safe boundary for sending patches to a mailing list
while keeping space for inline reply markers.</p>
<p>Orange indicates that the line is starting to run a bit long and should
break soon.</p>
<p>Red indicates that the line is running up against the standard
80-column limit for commit messages.</p>
<p>Keeping commit messages less than 76-characters wide is encouraged.
<a class="reference external" href="http://schacon.github.com/git/git-log.html">git log</a>
is a great tool but long lines mess up its formatting for everyone else,
so please be mindful when writing commit messages.</p>
</div>
<div class="section" id="amend-last-commit">
<h3>Amend Last Commit<a class="headerlink" href="#amend-last-commit" title="Permalink to this headline">¶</a></h3>
<p>Clicking on <cite>Amend Last Commit</cite> makes <cite>git cola</cite> amend the previous commit
instead of creating a new one. <cite>git cola</cite> loads the previous commit message
into the commit message editor when this option is selected.</p>
<p>The <a href="#id9"><span class="problematic" id="id10">:ref:`Status <status>`_</span></a> tool will display all of the changes for the
amended commit.</p>
</div>
</div>
</div>
</div>
<div class="bottomnav">
<p>
«  <a href="intro.html">Introduction</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
  ::  
<a href="mainwindow.html">Keyboard Shortcuts</a>  »
</p>
</div>
<div class="footer">
© Copyright 2007-2012, David Aguilar and contributors.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.
</div>
</body>
</html>
