[PATCH 0/6] minor documentation improvements

[PATCH 0/6] minor documentation improvements

[Eric Sunshine]

This is a set of minor documentation improvements, prompted by
suggestions from Junio and Michael Haggerty, plus a few things I
discovered in the process. It is built atop 'es/worktree-add' in
'next' in order to avoid conflicts with changes in that series (but
is otherwise not related to those patches).

Eric Sunshine (6):
  Documentation/git-worktree: fix broken 'linkgit' invocation
  Documentation/config: mention "now" and "never" for 'expire' settings
  Documentation/git: drop outdated Cogito reference
  Documentation/git-tools: improve discoverability of Git wiki
  Documentation/git-tools: fix item text formatting
  Documentation/git-tools: drop references to defunct tools

 Documentation/config.txt       |  13 +++--
 Documentation/git-tools.txt    | 124 +++++++++++++++--------------------------
 Documentation/git-worktree.txt |   2 +-
 Documentation/git.txt          |   2 +-
 4 files changed, 55 insertions(+), 86 deletions(-)

-- 
2.5.0.rc3.407.g68aafd0

[PATCH 1/6] Documentation/git-worktree: fix broken 'linkgit' invocation

[Eric Sunshine]

Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
---
 Documentation/git-worktree.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index 332dd77..400b313 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt
@@ -27,7 +27,7 @@ bare repository) and zero or more linked working trees.
 When you are done with a linked working tree you can simply delete it.
 The working tree's administrative files in the repository (see
 "DETAILS" below) will eventually be removed automatically (see
-`gc.worktreePruneExpire` in linkgit::git-config[1]), or you can run
+`gc.worktreePruneExpire` in linkgit:git-config[1]), or you can run
 `git worktree prune` in the main or any linked working tree to
 clean up any stale administrative files.
 
-- 
2.5.0.rc3.407.g68aafd0

[PATCH 2/6] Documentation/config: mention "now" and "never" for 'expire' settings

[Eric Sunshine]

In addition to approxidate-style values ("2.months.ago", "yesterday"),
consumers of 'gc.*expire*' configuration variables also accept and
respect 'now'/'all' ("do it immediately") and 'never'/'false' ("suppress
entirely").

Suggested-by: Michael Haggerty <mhagger@alum.mit.edu>
Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
---

Reference: http://article.gmane.org/gmane.comp.version-control.git/274325

I sneaked in a minor whitespace fix.

 Documentation/config.txt | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 1a8a399..cc920c0 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -1307,20 +1307,22 @@ gc.packRefs::
 gc.pruneExpire::
 	When 'git gc' is run, it will call 'prune --expire 2.weeks.ago'.
 	Override the grace period with this config variable.  The value
-	"now" may be used to disable this  grace period and always prune
-	unreachable objects immediately.
+	"now" may be used to disable this grace period and always prune
+	unreachable objects immediately; or "never" to suppress pruning.
 
 gc.worktreePruneExpire::
 	When 'git gc' is run, it calls
 	'git worktree prune --expire 3.months.ago'.
 	This config variable can be used to set a different grace
 	period. The value "now" may be used to disable the grace
-	period and prune $GIT_DIR/worktrees immediately.
+	period and prune $GIT_DIR/worktrees immediately; or "never" to
+	suppress pruning.
 
 gc.reflogExpire::
 gc.<pattern>.reflogExpire::
 	'git reflog expire' removes reflog entries older than
-	this time; defaults to 90 days.  With "<pattern>" (e.g.
+	this time; defaults to 90 days. The value "all" expires all
+	entries; and "false" disables expiration. With "<pattern>" (e.g.
 	"refs/stash") in the middle the setting applies only to
 	the refs that match the <pattern>.
 
@@ -1328,7 +1330,8 @@ gc.reflogExpireUnreachable::
 gc.<ref>.reflogExpireUnreachable::
 	'git reflog expire' removes reflog entries older than
 	this time and are not reachable from the current tip;
-	defaults to 30 days.  With "<pattern>" (e.g. "refs/stash")
+	defaults to 30 days. The value "all" expires all entries; and
+	"false" disables expiration. With "<pattern>" (e.g. "refs/stash")
 	in the middle, the setting applies only to the refs that
 	match the <pattern>.
 
-- 
2.5.0.rc3.407.g68aafd0

[PATCH 3/6] Documentation/git: drop outdated Cogito reference

[Eric Sunshine]

Cogito hasn't been maintained since late 2006, so drop the reference
to it. The warning that SCMS front-ends might override listed
environment variables, however, may still be valuable, so keep it but
generalize the wording.

Suggested-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
---

Reference: http://article.gmane.org/gmane.comp.version-control.git/274084

 Documentation/git.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git.txt b/Documentation/git.txt
index 1e8a569..ef774be 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -774,7 +774,7 @@ The Git Repository
 ~~~~~~~~~~~~~~~~~~
 These environment variables apply to 'all' core Git commands. Nb: it
 is worth noting that they may be used/overridden by SCMS sitting above
-Git so take care if using Cogito etc.
+Git so take care if using a foreign front-end.
 
 'GIT_INDEX_FILE'::
 	This environment allows the specification of an alternate
-- 
2.5.0.rc3.407.g68aafd0

[PATCH 4/6] Documentation/git-tools: improve discoverability of Git wiki

[Eric Sunshine]

These days, the best way to find Git-related tools is via a search
engine. Second best may be the Git wiki. git-tools.txt falls in last
place. Therefore, promote the Git wiki reference to the top of
git-tools.txt so the reader will encounter it first, rather than
hiding it away at the very bottom.

Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
---

I sneaked in a minor grammatical fix.

 Documentation/git-tools.txt | 9 +++------
 1 file changed, 3 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-tools.txt b/Documentation/git-tools.txt
index 78a0d95..129b8c0 100644
--- a/Documentation/git-tools.txt
+++ b/Documentation/git-tools.txt
@@ -6,10 +6,11 @@ Introduction
 ------------
 
 Apart from Git contrib/ area there are some others third-party tools
-you may want to look.
-
+you may want to look at.
 This document presents a brief summary of each tool and the corresponding
 link.
+For a more comprehensive list, see:
+http://git.or.cz/gitwiki/InterfacesFrontendsAndTools
 
 
 Alternative/Augmentative Porcelains
@@ -112,7 +113,3 @@ Others
    This is an Emacs interface for Git. The user interface is modelled on
    pcl-cvs. It has been developed on Emacs 21 and will probably need some
    tweaking to work on XEmacs.
-
-
-http://git.or.cz/gitwiki/InterfacesFrontendsAndTools has more
-comprehensive list.
-- 
2.5.0.rc3.407.g68aafd0

[PATCH 5/6] Documentation/git-tools: fix item text formatting

[Eric Sunshine]

Descriptive text for each tool item is incorrectly formatted using a
fixed width font. Fix formatting to use a variable width font by
unindenting the item text.

Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
---
 Documentation/git-tools.txt | 134 ++++++++++++++++++++++----------------------
 1 file changed, 67 insertions(+), 67 deletions(-)

diff --git a/Documentation/git-tools.txt b/Documentation/git-tools.txt
index 129b8c0..ab4aab9 100644
--- a/Documentation/git-tools.txt
+++ b/Documentation/git-tools.txt
@@ -16,100 +16,100 @@ http://git.or.cz/gitwiki/InterfacesFrontendsAndTools
 Alternative/Augmentative Porcelains
 -----------------------------------
 
-   - *Cogito* (http://www.kernel.org/pub/software/scm/cogito/)
+- *Cogito* (http://www.kernel.org/pub/software/scm/cogito/)
++
+Cogito is a version control system layered on top of the Git tree history
+storage system. It aims at seamless user interface and ease of use,
+providing generally smoother user experience than the "raw" Core Git
+itself and indeed many other version control systems.
++
+Cogito is no longer maintained as most of its functionality
+is now in core Git.
 
-   Cogito is a version control system layered on top of the Git tree history
-   storage system. It aims at seamless user interface and ease of use,
-   providing generally smoother user experience than the "raw" Core Git
-   itself and indeed many other version control systems.
 
-   Cogito is no longer maintained as most of its functionality
-   is now in core Git.
+- *pg* (http://www.spearce.org/category/projects/scm/pg/)
++
+pg is a shell script wrapper around Git to help the user manage a set of
+patches to files. pg is somewhat like quilt or StGit, but it does have a
+slightly different feature set.
 
 
-   - *pg* (http://www.spearce.org/category/projects/scm/pg/)
-
-   pg is a shell script wrapper around Git to help the user manage a set of
-   patches to files. pg is somewhat like quilt or StGit, but it does have a
-   slightly different feature set.
-
-
-   - *StGit* (http://www.procode.org/stgit/)
-
-   Stacked Git provides a quilt-like patch management functionality in the
-   Git environment. You can easily manage your patches in the scope of Git
-   until they get merged upstream.
+- *StGit* (http://www.procode.org/stgit/)
++
+Stacked Git provides a quilt-like patch management functionality in the
+Git environment. You can easily manage your patches in the scope of Git
+until they get merged upstream.
 
 
 History Viewers
 ---------------
 
-   - *gitk* (shipped with git-core)
-
-   gitk is a simple Tk GUI for browsing history of Git repositories easily.
-
-
-   - *gitview*  (contrib/)
-
-   gitview is a GTK based repository browser for Git
+- *gitk* (shipped with git-core)
++
+gitk is a simple Tk GUI for browsing history of Git repositories easily.
 
 
-   - *gitweb* (shipped with git-core)
+- *gitview*  (contrib/)
++
+gitview is a GTK based repository browser for Git
 
-   Gitweb provides full-fledged web interface for Git repositories.
 
+- *gitweb* (shipped with git-core)
++
+Gitweb provides full-fledged web interface for Git repositories.
 
-   - *qgit* (http://digilander.libero.it/mcostalba/)
 
-   QGit is a git/StGit GUI viewer built on Qt/C++. QGit could be used
-   to browse history and directory tree, view annotated files, commit
-   changes cherry picking single files or applying patches.
-   Currently it is the fastest and most feature rich among the Git
-   viewers and commit tools.
+- *qgit* (http://digilander.libero.it/mcostalba/)
++
+QGit is a git/StGit GUI viewer built on Qt/C++. QGit could be used
+to browse history and directory tree, view annotated files, commit
+changes cherry picking single files or applying patches.
+Currently it is the fastest and most feature rich among the Git
+viewers and commit tools.
 
-   - *tig* (http://jonas.nitro.dk/tig/)
-
-   tig by Jonas Fonseca is a simple Git repository browser
-   written using ncurses. Basically, it just acts as a front-end
-   for git-log and git-show/git-diff. Additionally, you can also
-   use it as a pager for Git commands.
+- *tig* (http://jonas.nitro.dk/tig/)
++
+tig by Jonas Fonseca is a simple Git repository browser
+written using ncurses. Basically, it just acts as a front-end
+for git-log and git-show/git-diff. Additionally, you can also
+use it as a pager for Git commands.
 
 
 Foreign SCM interface
 ---------------------
 
-   - *git-svn* (shipped with git-core)
-
-   git-svn is a simple conduit for changesets between a single Subversion
-   branch and Git.
-
-
-   - *quilt2git / git2quilt* (http://home-tj.org/wiki/index.php/Misc)
+- *git-svn* (shipped with git-core)
++
+git-svn is a simple conduit for changesets between a single Subversion
+branch and Git.
 
-   These utilities convert patch series in a quilt repository and commit
-   series in Git back and forth.
 
+- *quilt2git / git2quilt* (http://home-tj.org/wiki/index.php/Misc)
++
+These utilities convert patch series in a quilt repository and commit
+series in Git back and forth.
 
-   - *hg-to-git* (contrib/)
 
-   hg-to-git converts a Mercurial repository into a Git one, and
-   preserves the full branch history in the process. hg-to-git can
-   also be used in an incremental way to keep the Git repository
-   in sync with the master Mercurial repository.
+- *hg-to-git* (contrib/)
++
+hg-to-git converts a Mercurial repository into a Git one, and
+preserves the full branch history in the process. hg-to-git can
+also be used in an incremental way to keep the Git repository
+in sync with the master Mercurial repository.
 
 
 Others
 ------
 
-   - *(h)gct* (http://www.cyd.liu.se/users/~freku045/gct/)
-
-   Commit Tool or (h)gct is a GUI enabled commit tool for Git and
-   Mercurial (hg). It allows the user to view diffs, select which files
-   to committed (or ignored / reverted) write commit messages and
-   perform the commit itself.
-
-   - *git.el* (contrib/)
-
-   This is an Emacs interface for Git. The user interface is modelled on
-   pcl-cvs. It has been developed on Emacs 21 and will probably need some
-   tweaking to work on XEmacs.
+- *(h)gct* (http://www.cyd.liu.se/users/~freku045/gct/)
++
+Commit Tool or (h)gct is a GUI enabled commit tool for Git and
+Mercurial (hg). It allows the user to view diffs, select which files
+to committed (or ignored / reverted) write commit messages and
+perform the commit itself.
+
+- *git.el* (contrib/)
++
+This is an Emacs interface for Git. The user interface is modelled on
+pcl-cvs. It has been developed on Emacs 21 and will probably need some
+tweaking to work on XEmacs.
-- 
2.5.0.rc3.407.g68aafd0

[PATCH 6/6] Documentation/git-tools: drop references to defunct tools

[Eric Sunshine]

Cogito -- unmaintained since late 2006[1]
pg -- URL dead; web searches reveal no information
quilt2git -- URL dead; web searches reveal no information
(h)gct -- URL dead; no repository activity since 2007[2]

[1]: http://git.or.cz/cogito/
[2]: http://repo.or.cz/w/hgct.git

Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
---

Perhaps it would be better to drop all items, and retain only the link
to the Git wiki?

 Documentation/git-tools.txt | 31 -------------------------------
 1 file changed, 31 deletions(-)

diff --git a/Documentation/git-tools.txt b/Documentation/git-tools.txt
index ab4aab9..48a3595 100644
--- a/Documentation/git-tools.txt
+++ b/Documentation/git-tools.txt
@@ -16,24 +16,6 @@ http://git.or.cz/gitwiki/InterfacesFrontendsAndTools
 Alternative/Augmentative Porcelains
 -----------------------------------
 
-- *Cogito* (http://www.kernel.org/pub/software/scm/cogito/)
-+
-Cogito is a version control system layered on top of the Git tree history
-storage system. It aims at seamless user interface and ease of use,
-providing generally smoother user experience than the "raw" Core Git
-itself and indeed many other version control systems.
-+
-Cogito is no longer maintained as most of its functionality
-is now in core Git.
-
-
-- *pg* (http://www.spearce.org/category/projects/scm/pg/)
-+
-pg is a shell script wrapper around Git to help the user manage a set of
-patches to files. pg is somewhat like quilt or StGit, but it does have a
-slightly different feature set.
-
-
 - *StGit* (http://www.procode.org/stgit/)
 +
 Stacked Git provides a quilt-like patch management functionality in the
@@ -84,12 +66,6 @@ git-svn is a simple conduit for changesets between a single Subversion
 branch and Git.
 
 
-- *quilt2git / git2quilt* (http://home-tj.org/wiki/index.php/Misc)
-+
-These utilities convert patch series in a quilt repository and commit
-series in Git back and forth.
-
-
 - *hg-to-git* (contrib/)
 +
 hg-to-git converts a Mercurial repository into a Git one, and
@@ -101,13 +77,6 @@ in sync with the master Mercurial repository.
 Others
 ------
 
-- *(h)gct* (http://www.cyd.liu.se/users/~freku045/gct/)
-+
-Commit Tool or (h)gct is a GUI enabled commit tool for Git and
-Mercurial (hg). It allows the user to view diffs, select which files
-to committed (or ignored / reverted) write commit messages and
-perform the commit itself.
-
 - *git.el* (contrib/)
 +
 This is an Emacs interface for Git. The user interface is modelled on
-- 
2.5.0.rc3.407.g68aafd0

Re: [PATCH 6/6] Documentation/git-tools: drop references to defunct tools

[Junio C Hamano]

Eric Sunshine <sunshine@sunshineco.com> writes:

> Cogito -- unmaintained since late 2006[1]
> pg -- URL dead; web searches reveal no information
> quilt2git -- URL dead; web searches reveal no information
> (h)gct -- URL dead; no repository activity since 2007[2]
>
> [1]: http://git.or.cz/cogito/
> [2]: http://repo.or.cz/w/hgct.git
>
> Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
> ---
>
> Perhaps it would be better to drop all items, and retain only the link
> to the Git wiki?

Hmmm, that's a very tempting thought.

Re: [PATCH 6/6] Documentation/git-tools: drop references to defunct tools

[Eric Sunshine]

On Fri, Jul 24, 2015 at 11:03:54AM -0700, Junio C Hamano wrote:
> Eric Sunshine <sunshine@sunshineco.com> writes:
> > Cogito -- unmaintained since late 2006[1]
> > pg -- URL dead; web searches reveal no information
> > quilt2git -- URL dead; web searches reveal no information
> > (h)gct -- URL dead; no repository activity since 2007[2]
> >
> > [1]: http://git.or.cz/cogito/
> > [2]: http://repo.or.cz/w/hgct.git
> >
> > Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
> > ---
> > Perhaps it would be better to drop all items, and retain only the link
> > to the Git wiki?
> 
> Hmmm, that's a very tempting thought.

Here it is in patch form atop the present series[1]. By plopping this
change atop the other patches, the decision to retire or keep the list
of tools becomes as easy as either retaining or dropping this one patch
(as opposed to re-rolling the entire series).

[1]: http://thread.gmane.org/gmane.comp.version-control.git/274537


---- 8< ----
From: Eric Sunshine <sunshine@sunshineco.com>
Subject: [PATCH 7/6] Documentation/git-tools: retire manually maintained list; keep only wiki

When Git was young, people looking for third-party Git-related tools
came to the Git project itself to find them, so it made sense to
maintain a list of tools here. These days, however, search engines fill
that role much more efficiently, so retire this manually-maintained
list.

The list of front-ends and tools on the Git wiki rates perhaps a distant
second to search engines, and may still have value, so retain a
reference to it.

Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
---
 Documentation/git-tools.txt | 88 ++++-----------------------------------------
 1 file changed, 7 insertions(+), 81 deletions(-)

diff --git a/Documentation/git-tools.txt b/Documentation/git-tools.txt
index 48a3595..2f4ff50 100644
--- a/Documentation/git-tools.txt
+++ b/Documentation/git-tools.txt
@@ -1,84 +1,10 @@
-A short Git tools survey
-========================
+Git Tools
+=========
 
+When Git was young, people looking for third-party Git-related tools came
+to the Git project itself to find them, thus a list of such tools was
+maintained here. These days, however, search engines fill that role much
+more efficiently, so this manually-maintained list has been retired.
 
-Introduction
-------------
-
-Apart from Git contrib/ area there are some others third-party tools
-you may want to look at.
-This document presents a brief summary of each tool and the corresponding
-link.
-For a more comprehensive list, see:
+See also the `contrib/` area, and the Git wiki:
 http://git.or.cz/gitwiki/InterfacesFrontendsAndTools
-
-
-Alternative/Augmentative Porcelains
------------------------------------
-
-- *StGit* (http://www.procode.org/stgit/)
-+
-Stacked Git provides a quilt-like patch management functionality in the
-Git environment. You can easily manage your patches in the scope of Git
-until they get merged upstream.
-
-
-History Viewers
----------------
-
-- *gitk* (shipped with git-core)
-+
-gitk is a simple Tk GUI for browsing history of Git repositories easily.
-
-
-- *gitview*  (contrib/)
-+
-gitview is a GTK based repository browser for Git
-
-
-- *gitweb* (shipped with git-core)
-+
-Gitweb provides full-fledged web interface for Git repositories.
-
-
-- *qgit* (http://digilander.libero.it/mcostalba/)
-+
-QGit is a git/StGit GUI viewer built on Qt/C++. QGit could be used
-to browse history and directory tree, view annotated files, commit
-changes cherry picking single files or applying patches.
-Currently it is the fastest and most feature rich among the Git
-viewers and commit tools.
-
-- *tig* (http://jonas.nitro.dk/tig/)
-+
-tig by Jonas Fonseca is a simple Git repository browser
-written using ncurses. Basically, it just acts as a front-end
-for git-log and git-show/git-diff. Additionally, you can also
-use it as a pager for Git commands.
-
-
-Foreign SCM interface
----------------------
-
-- *git-svn* (shipped with git-core)
-+
-git-svn is a simple conduit for changesets between a single Subversion
-branch and Git.
-
-
-- *hg-to-git* (contrib/)
-+
-hg-to-git converts a Mercurial repository into a Git one, and
-preserves the full branch history in the process. hg-to-git can
-also be used in an incremental way to keep the Git repository
-in sync with the master Mercurial repository.
-
-
-Others
-------
-
-- *git.el* (contrib/)
-+
-This is an Emacs interface for Git. The user interface is modelled on
-pcl-cvs. It has been developed on Emacs 21 and will probably need some
-tweaking to work on XEmacs.
-- 
2.5.0.rc3.407.g68aafd0

Re: [PATCH 2/6] Documentation/config: mention "now" and "never" for 'expire' settings

[Michael Haggerty]

On 07/23/2015 09:00 PM, Eric Sunshine wrote:
> In addition to approxidate-style values ("2.months.ago", "yesterday"),
> consumers of 'gc.*expire*' configuration variables also accept and
> respect 'now'/'all' ("do it immediately") and 'never'/'false' ("suppress
> entirely").
> 
> Suggested-by: Michael Haggerty <mhagger@alum.mit.edu>
> Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
> ---
> 
> Reference: http://article.gmane.org/gmane.comp.version-control.git/274325
> 
> I sneaked in a minor whitespace fix.
> 
>  Documentation/config.txt | 13 ++++++++-----
>  1 file changed, 8 insertions(+), 5 deletions(-)
> 
> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index 1a8a399..cc920c0 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -1307,20 +1307,22 @@ gc.packRefs::
>  gc.pruneExpire::
>  	When 'git gc' is run, it will call 'prune --expire 2.weeks.ago'.
>  	Override the grace period with this config variable.  The value
> -	"now" may be used to disable this  grace period and always prune
> -	unreachable objects immediately.
> +	"now" may be used to disable this grace period and always prune
> +	unreachable objects immediately; or "never" to suppress pruning.

A semicolon should be used without a conjunction, and the parts of a
sentence joined by a semicolon should be independent clauses. So this
should probably be

                                                     [...] The value
    "now" may be used to disable this grace period and always prune
    unreachable objects immediately, or "never" may be used to
    suppress pruning.

>  gc.worktreePruneExpire::
>  	When 'git gc' is run, it calls
>  	'git worktree prune --expire 3.months.ago'.
>  	This config variable can be used to set a different grace
>  	period. The value "now" may be used to disable the grace
> -	period and prune $GIT_DIR/worktrees immediately.
> +	period and prune $GIT_DIR/worktrees immediately; or "never" to
> +	suppress pruning.

The same here.

>  gc.reflogExpire::
>  gc.<pattern>.reflogExpire::
>  	'git reflog expire' removes reflog entries older than
> -	this time; defaults to 90 days.  With "<pattern>" (e.g.
> +	this time; defaults to 90 days. The value "all" expires all
> +	entries; and "false" disables expiration. With "<pattern>" (e.g.
>  	"refs/stash") in the middle the setting applies only to
>  	the refs that match the <pattern>.

Similarly, this could be fixed to

                               [...] The value "all" expires all
    entries; "false" disables expiration. [...]


> @@ -1328,7 +1330,8 @@ gc.reflogExpireUnreachable::
>  gc.<ref>.reflogExpireUnreachable::
>  	'git reflog expire' removes reflog entries older than
>  	this time and are not reachable from the current tip;
> -	defaults to 30 days.  With "<pattern>" (e.g. "refs/stash")
> +	defaults to 30 days. The value "all" expires all entries; and
> +	"false" disables expiration. With "<pattern>" (e.g. "refs/stash")
>  	in the middle, the setting applies only to the refs that
>  	match the <pattern>.

The same here.

Also, I wonder why you suggest "now"/"never" for the first two settings,
but "all"/"false" for the second two. Wouldn't it be less confusing to
be consistent?

Michael

-- 
Michael Haggerty
mhagger@alum.mit.edu

Re: [PATCH 2/6] Documentation/config: mention "now" and "never" for 'expire' settings

[Eric Sunshine]

[+cc:Paul Tan]

On Sun, Jul 26, 2015 at 9:41 PM, Michael Haggerty <mhagger@alum.mit.edu> wrote:
> On 07/23/2015 09:00 PM, Eric Sunshine wrote:
>> In addition to approxidate-style values ("2.months.ago", "yesterday"),
>> consumers of 'gc.*expire*' configuration variables also accept and
>> respect 'now'/'all' ("do it immediately") and 'never'/'false' ("suppress
>> entirely").
>>
>> Suggested-by: Michael Haggerty <mhagger@alum.mit.edu>
>> Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
>> ---
>>  gc.pruneExpire::
>>       When 'git gc' is run, it will call 'prune --expire 2.weeks.ago'.
>>       Override the grace period with this config variable.  The value
>> -     "now" may be used to disable this  grace period and always prune
>> -     unreachable objects immediately.
>> +     "now" may be used to disable this grace period and always prune
>> +     unreachable objects immediately; or "never" to suppress pruning.
>
> A semicolon should be used without a conjunction, and the parts of a
> sentence joined by a semicolon should be independent clauses. So this
> should probably be

I was just getting ready to re-roll this series[1] to address
Michael's comments[2] and noticed that the add-on patch 7/6 which I
sent later[3] seems to have been botched when Junio applied it to
'pu'. It's currently at 36598db (Documentation/git-tools: drop
references to defunct tools, 2015-07-24) in
es/doc-clean-outdated-tools and it appears that the --scissors option
didn't cut off the leading cruft from the email conversation, thus the
commit has the wrong "subject" plus a bunch of email conversation gunk
in the commit message which doesn't belong. I understand that Junio
uses a relatively bleeding-edge version of Git for his day-to-day work
and was wondering if this is possible fallout from the git-am rewrite
in C?

[1]: http://thread.gmane.org/gmane.comp.version-control.git/274537
[2]: http://article.gmane.org/gmane.comp.version-control.git/274647
[3]: http://article.gmane.org/gmane.comp.version-control.git/274602

Re: [PATCH 2/6] Documentation/config: mention "now" and "never" for 'expire' settings

[Junio C Hamano]

Eric Sunshine <sunshine@sunshineco.com> writes:

> I was just getting ready to re-roll this series[1] to address
> Michael's comments[2] and noticed that the add-on patch 7/6 which I
> sent later[3] seems to have been botched when Junio applied it to
> 'pu'. It's currently at 36598db (Documentation/git-tools: drop
> references to defunct tools, 2015-07-24) in
> es/doc-clean-outdated-tools and it appears that the --scissors option
> didn't cut off the leading cruft from the email conversation, thus the
> commit has the wrong "subject" plus a bunch of email conversation gunk
> in the commit message which doesn't belong. I understand that Junio
> uses a relatively bleeding-edge version of Git for his day-to-day work
> and was wondering if this is possible fallout from the git-am rewrite
> in C?

It is more likely that I was just lazy, knowing that the patch [3]
would not hit "next" and I'll have a more relaxed time to amend it
after the release was done, and let "am -s" without "-c" take it.

I just tried to re-apply the patch with "am -sc" on
es/doc-clean-outdated-tools^ and the built-in one takes it just
fine, so we should be OK.

Thanks.

Re: [PATCH 2/6] Documentation/config: mention "now" and "never" for 'expire' settings

[Eric Sunshine]

On Sun, Jul 26, 2015 at 9:41 PM, Michael Haggerty <mhagger@alum.mit.edu> wrote:
> On 07/23/2015 09:00 PM, Eric Sunshine wrote:
>> In addition to approxidate-style values ("2.months.ago", "yesterday"),
>> consumers of 'gc.*expire*' configuration variables also accept and
>> respect 'now'/'all' ("do it immediately") and 'never'/'false' ("suppress
>> entirely").
>>
>> Suggested-by: Michael Haggerty <mhagger@alum.mit.edu>
>> Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
>> ---
>>  gc.pruneExpire::
>>       When 'git gc' is run, it will call 'prune --expire 2.weeks.ago'.
>>       Override the grace period with this config variable.  The value
>> -     "now" may be used to disable this  grace period and always prune
>> -     unreachable objects immediately.
>> +     "now" may be used to disable this grace period and always prune
>> +     unreachable objects immediately; or "never" to suppress pruning.
>
> A semicolon should be used without a conjunction, and the parts of a
> sentence joined by a semicolon should be independent clauses. So this
> should probably be
>
>                                                      [...] The value
>     "now" may be used to disable this grace period and always prune
>     unreachable objects immediately, or "never" may be used to
>     suppress pruning.

I was absent from school that day...

>> @@ -1328,7 +1330,8 @@ gc.reflogExpireUnreachable::
>>  gc.<ref>.reflogExpireUnreachable::
>>       'git reflog expire' removes reflog entries older than
>>       this time and are not reachable from the current tip;
>> -     defaults to 30 days.  With "<pattern>" (e.g. "refs/stash")
>> +     defaults to 30 days. The value "all" expires all entries; and
>> +     "false" disables expiration. With "<pattern>" (e.g. "refs/stash")
>>       in the middle, the setting applies only to the refs that
>>       match the <pattern>.
>
> Also, I wonder why you suggest "now"/"never" for the first two settings,
> but "all"/"false" for the second two. Wouldn't it be less confusing to
> be consistent?

It was intentional due to the way I worded the sentence. It sounded
slightly strange to my ear to say:

    The value "now" expires all entries; and "never"
    disables expiration.

whereas:

    The value "all" expires all entries; ...

sounded nice. But, upon reflection, with a slight re-wording[1], "all"
and "never" work, as well.

[1]: http://article.gmane.org/gmane.comp.version-control.git/274828