doc: pickup credential helpers and other updates

Signed-off-by: David Aguilar <davvid@gmail.com>

Author: davvid

share/doc/git-cola/git-cola.rst

@@ -958,6 +958,50 @@ Defaults to "#bbbbbb"::
 
     git config cola.color.header '#bbbbbb'
 
+commit.cleanup
+--------------
+Configure whether commit messages should be stripped of whitespace and comments.
+
+Valid values are ``strip``, ``whitespace``, ``verbatim``, ``scissors`` or ``default``.
+
+The ``default`` mode uses the ``whitespace`` mode when committing through Git Cola
+and the ``strip`` mode when committing using the ``git commit`` command-line.
+
+* ``strip`` - Strip leading and trailing empty lines, trailing whitespace,
+  commentary and collapse consecutive empty lines.
+
+* ``whitespace`` - Same as strip except ``# commentary`` is not removed.
+  This is the ``default`` behavior when committing through `Git Cola`.
+
+* ``verbatim`` - Do not change the message at all.
+
+* ``scissors`` - Same as whitespace except that everything from (and including)
+  the line found below is truncated, if the message is to be edited.
+  "#" can be customized with ``core.commentChar``::
+
+    # ------------------------ >8 ------------------------
+    Scissor-lines and all following lines are removed.
+
+Changing the mode to ``whitespace`` can be useful when you always want to keep
+lines that begin with comment character ``#`` in your log message, even when
+committing using the command-line ``git commit``.
+
+On the contrary, if you always want to always strip comments, even when
+committing through Git Cola, then configure ``commit.cleanup`` to ``strip``.
+
+Please see the `git commit cleanup mode documentation
+<https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---cleanupltmodegt>`_
+for more details.
+
+core.commentChar
+----------------
+Commit messages can contain comments that start with this character.
+Defaults to ``#``.
+
+Please see the `git config documentation
+<https://git-scm.com/docs/git-config#Documentation/git-config.txt-corecommentChar>`_
+for more details.
+
 core.hooksPath
 --------------
 Hooks are programs you can place in a hooks directory to trigger actions at
@@ -1164,6 +1208,15 @@ Avoid creating shortcuts that conflict with existing built-in `git cola`
 shortcuts.  Creating a conflict will result in no action when the shortcut
 is used.
 
+SETTING UP CREDENTIAL HELPERS
+=============================
+Git has robust support for automatically handling credentials.
+
+The recommended approach is to use SSH keys and an SSH agent, but any of the core Git
+Credentials helpers will get used automatically by Git Cola.
+
+See https://git-scm.com/doc/credential-helpers for more details.
+
 SETTING UP GPG FOR SIGNED COMMITS
 =================================
 When creating signed commits, `gpg` will attempt to read your password from the

share/doc/git-cola/hotkeys.html

@@ -80,7 +80,7 @@
     <td>Stage untracked files</td>
 </tr>
 <tr>
-    <td class="shortcut">Ctrl + U</td>
+    <td class="shortcut">Ctrl + U / Alt + Shift + R</td>
     <td>:</td>
     <td>Revert the selected lines, or the diff hunk beneath the text cursor when nothing
         is selected, from the worktree</td>

share/doc/git-cola/hotkeys_de.html

@@ -81,7 +81,7 @@
     <td>Alle neuen Dateien vormerken</td>
 </tr>
 <tr>
-    <td class="shortcut">Ctrl + U</td>
+    <td class="shortcut">Ctrl + U / Alt + Shift + R</td>
     <td>:</td>
     <!-- TODO -->
     <td>Revert the selected lines, or the diff hunk beneath the text cursor when nothing

share/doc/git-cola/hotkeys_zh_CN.html

@@ -81,7 +81,7 @@
     <td>缓存未追踪项目</td>
 </tr>
 <tr>
-    <td class="shortcut">Ctrl + U</td>
+    <td class="shortcut">Ctrl + U / Alt + Shift + R</td>
     <td>:</td>
     <td>还原缓存改动</td>
 </tr>

share/doc/git-cola/hotkeys_zh_TW.html

@@ -81,7 +81,7 @@
     <td>將尚未追蹤其版本的項目移動到版本提交準備區域</td>
 </tr>
 <tr>
-    <td class="shortcut">Ctrl + U</td>
+    <td class="shortcut">Ctrl + U / Alt + Shift + R</td>
     <td>:</td>
     <td>還原尚未移入版本提交準備區域的內容變動</td>
 </tr>

share/doc/git-cola/html/git-cola.html

@@ -176,6 +176,8 @@
 <li class="toctree-l3"><a class="reference internal" href="#cola-color-add">cola.color.add</a></li>
 <li class="toctree-l3"><a class="reference internal" href="#cola-color-remove">cola.color.remove</a></li>
 <li class="toctree-l3"><a class="reference internal" href="#cola-color-header">cola.color.header</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#commit-cleanup">commit.cleanup</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#core-commentchar">core.commentChar</a></li>
 <li class="toctree-l3"><a class="reference internal" href="#core-hookspath">core.hooksPath</a></li>
 <li class="toctree-l3"><a class="reference internal" href="#gui-diffcontext">gui.diffcontext</a></li>
 <li class="toctree-l3"><a class="reference internal" href="#gui-displayuntracked">gui.displayuntracked</a></li>
@@ -210,6 +212,7 @@
 <li class="toctree-l3"><a class="reference internal" href="#guitool-name-shortcut">guitool.&lt;name&gt;.shortcut</a></li>
 </ul>
 </li>
+<li class="toctree-l2"><a class="reference internal" href="#setting-up-credential-helpers">SETTING UP CREDENTIAL HELPERS</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#setting-up-gpg-for-signed-commits">SETTING UP GPG FOR SIGNED COMMITS</a><ul>
 <li class="toctree-l3"><a class="reference internal" href="#install-gpg-agent-and-friends">Install gpg-agent and friends</a></li>
 <li class="toctree-l3"><a class="reference internal" href="#configure-gpg-agent-and-a-pin-entry-program">Configure gpg-agent and a pin-entry program</a></li>
@@ -1148,6 +1151,42 @@ <h3>cola.color.header<a class="headerlink" href="#cola-color-header" title="Perm
 </pre></div>
 </div>
 </section>
+<section id="commit-cleanup">
+<h3>commit.cleanup<a class="headerlink" href="#commit-cleanup" title="Permalink to this heading"></a></h3>
+<p>Configure whether commit messages should be stripped of whitespace and comments.</p>
+<p>Valid values are <code class="docutils literal notranslate"><span class="pre">strip</span></code>, <code class="docutils literal notranslate"><span class="pre">whitespace</span></code>, <code class="docutils literal notranslate"><span class="pre">verbatim</span></code>, <code class="docutils literal notranslate"><span class="pre">scissors</span></code> or <code class="docutils literal notranslate"><span class="pre">default</span></code>.</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">default</span></code> mode uses the <code class="docutils literal notranslate"><span class="pre">whitespace</span></code> mode when committing through Git Cola
+and the <code class="docutils literal notranslate"><span class="pre">strip</span></code> mode when committing using the <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">commit</span></code> command-line.</p>
+<ul>
+<li><p><code class="docutils literal notranslate"><span class="pre">strip</span></code> - Strip leading and trailing empty lines, trailing whitespace,
+commentary and collapse consecutive empty lines.</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">whitespace</span></code> - Same as strip except <code class="docutils literal notranslate"><span class="pre">#</span> <span class="pre">commentary</span></code> is not removed.
+This is the <code class="docutils literal notranslate"><span class="pre">default</span></code> behavior when committing through <cite>Git Cola</cite>.</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">verbatim</span></code> - Do not change the message at all.</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">scissors</span></code> - Same as whitespace except that everything from (and including)
+the line found below is truncated, if the message is to be edited.
+“#” can be customized with <code class="docutils literal notranslate"><span class="pre">core.commentChar</span></code>:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># ------------------------ &gt;8 ------------------------</span>
+<span class="n">Scissor</span><span class="o">-</span><span class="n">lines</span> <span class="ow">and</span> <span class="nb">all</span> <span class="n">following</span> <span class="n">lines</span> <span class="n">are</span> <span class="n">removed</span><span class="o">.</span>
+</pre></div>
+</div>
+</li>
+</ul>
+<p>Changing the mode to <code class="docutils literal notranslate"><span class="pre">whitespace</span></code> can be useful when you always want to keep
+lines that begin with comment character <code class="docutils literal notranslate"><span class="pre">#</span></code> in your log message, even when
+committing using the command-line <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">commit</span></code>.</p>
+<p>On the contrary, if you always want to always strip comments, even when
+committing through Git Cola, then configure <code class="docutils literal notranslate"><span class="pre">commit.cleanup</span></code> to <code class="docutils literal notranslate"><span class="pre">strip</span></code>.</p>
+<p>Please see the <a class="reference external" href="https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---cleanupltmodegt">git commit cleanup mode documentation</a>
+for more details.</p>
+</section>
+<section id="core-commentchar">
+<h3>core.commentChar<a class="headerlink" href="#core-commentchar" title="Permalink to this heading"></a></h3>
+<p>Commit messages can contain comments that start with this character.
+Defaults to <code class="docutils literal notranslate"><span class="pre">#</span></code>.</p>
+<p>Please see the <a class="reference external" href="https://git-scm.com/docs/git-config#Documentation/git-config.txt-corecommentChar">git config documentation</a>
+for more details.</p>
+</section>
 <section id="core-hookspath">
 <h3>core.hooksPath<a class="headerlink" href="#core-hookspath" title="Permalink to this heading"></a></h3>
 <p>Hooks are programs you can place in a hooks directory to trigger actions at
@@ -1346,6 +1385,13 @@ <h3>guitool.&lt;name&gt;.shortcut<a class="headerlink" href="#guitool-name-short
 is used.</p>
 </section>
 </section>
+<section id="setting-up-credential-helpers">
+<h2>SETTING UP CREDENTIAL HELPERS<a class="headerlink" href="#setting-up-credential-helpers" title="Permalink to this heading"></a></h2>
+<p>Git has robust support for automatically handling credentials.</p>
+<p>The recommended approach is to use SSH keys and an SSH agent, but any of the core Git
+Credentials helpers will get used automatically by Git Cola.</p>
+<p>See <a class="reference external" href="https://git-scm.com/doc/credential-helpers">https://git-scm.com/doc/credential-helpers</a> for more details.</p>
+</section>
 <section id="setting-up-gpg-for-signed-commits">
 <h2>SETTING UP GPG FOR SIGNED COMMITS<a class="headerlink" href="#setting-up-gpg-for-signed-commits" title="Permalink to this heading"></a></h2>
 <p>When creating signed commits, <cite>gpg</cite> will attempt to read your password from the

share/doc/git-cola/html/index.html

@@ -191,6 +191,8 @@ <h1>Git Cola Documentation<a class="headerlink" href="#git-cola-documentation" t
 <li class="toctree-l3"><a class="reference internal" href="git-cola.html#cola-color-add">cola.color.add</a></li>
 <li class="toctree-l3"><a class="reference internal" href="git-cola.html#cola-color-remove">cola.color.remove</a></li>
 <li class="toctree-l3"><a class="reference internal" href="git-cola.html#cola-color-header">cola.color.header</a></li>
+<li class="toctree-l3"><a class="reference internal" href="git-cola.html#commit-cleanup">commit.cleanup</a></li>
+<li class="toctree-l3"><a class="reference internal" href="git-cola.html#core-commentchar">core.commentChar</a></li>
 <li class="toctree-l3"><a class="reference internal" href="git-cola.html#core-hookspath">core.hooksPath</a></li>
 <li class="toctree-l3"><a class="reference internal" href="git-cola.html#gui-diffcontext">gui.diffcontext</a></li>
 <li class="toctree-l3"><a class="reference internal" href="git-cola.html#gui-displayuntracked">gui.displayuntracked</a></li>
@@ -225,6 +227,7 @@ <h1>Git Cola Documentation<a class="headerlink" href="#git-cola-documentation" t
 <li class="toctree-l3"><a class="reference internal" href="git-cola.html#guitool-name-shortcut">guitool.&lt;name&gt;.shortcut</a></li>
 </ul>
 </li>
+<li class="toctree-l2"><a class="reference internal" href="git-cola.html#setting-up-credential-helpers">SETTING UP CREDENTIAL HELPERS</a></li>
 <li class="toctree-l2"><a class="reference internal" href="git-cola.html#setting-up-gpg-for-signed-commits">SETTING UP GPG FOR SIGNED COMMITS</a><ul>
 <li class="toctree-l3"><a class="reference internal" href="git-cola.html#install-gpg-agent-and-friends">Install gpg-agent and friends</a></li>
 <li class="toctree-l3"><a class="reference internal" href="git-cola.html#configure-gpg-agent-and-a-pin-entry-program">Configure gpg-agent and a pin-entry program</a></li>
@@ -275,6 +278,7 @@ <h2>Release Notes<a class="headerlink" href="#release-notes" title="Permalink to
 <li class="toctree-l1"><a class="reference internal" href="relnotes.html">Releases</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="relnotes.html#latest-release">Latest Release</a></li>
 <li class="toctree-l2"><a class="reference internal" href="relnotes.html#development-version">Development version</a></li>
+<li class="toctree-l2"><a class="reference internal" href="relnotes.html#v4-4-0">v4.4.0</a></li>
 <li class="toctree-l2"><a class="reference internal" href="relnotes.html#v4-3-2">v4.3.2</a></li>
 <li class="toctree-l2"><a class="reference internal" href="relnotes.html#v4-3-1">v4.3.1</a></li>
 <li class="toctree-l2"><a class="reference internal" href="relnotes.html#v4-3-0">v4.3.0</a></li>