From: Eric Sunshine <hidden> Date: 2016-06-15 23:05:52
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
From: Eric Sunshine <hidden> Date: 2016-06-15 23:05:52
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 <redacted>
Signed-off-by: Eric Sunshine <redacted>
---
Reference: http://article.gmane.org/gmane.comp.version-control.git/274084
Documentation/git.txt | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
@@ -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
From: Eric Sunshine <hidden> Date: 2016-06-15 23:05:52
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 <redacted>
Signed-off-by: Eric Sunshine <redacted>
---
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(-)
@@ -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>.
From: Eric Sunshine <hidden> Date: 2016-06-15 23:05:52
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 <redacted>
---
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(-)
@@ -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
@@ -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.
From: Eric Sunshine <hidden> Date: 2016-06-15 23:05:52
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 <redacted>
---
I sneaked in a minor grammatical fix.
Documentation/git-tools.txt | 9 +++------
1 file changed, 3 insertions(+), 6 deletions(-)
@@ -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.
From: Eric Sunshine <hidden> Date: 2016-06-15 23:05:52
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 <redacted>
---
Documentation/git-tools.txt | 134 ++++++++++++++++++++++----------------------
1 file changed, 67 insertions(+), 67 deletions(-)
@@ -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.
From: Michael Haggerty <hidden> Date: 2016-06-15 23:05:53
On 07/23/2015 09:00 PM, Eric Sunshine wrote:
quoted hunk
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 <redacted>
Signed-off-by: Eric Sunshine <redacted>
---
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(-)
@@ -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. [...]
quoted hunk
@@ -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
From: Eric Sunshine <hidden> Date: 2016-06-15 23:05:55
[+cc:Paul Tan]
On Sun, Jul 26, 2015 at 9:41 PM, Michael Haggerty [off-list ref] wrote:
On 07/23/2015 09:00 PM, Eric Sunshine wrote:
quoted
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 <redacted>
Signed-off-by: Eric Sunshine <redacted>
---
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
From: Eric Sunshine <hidden> Date: 2016-06-15 23:05:55
On Sun, Jul 26, 2015 at 9:41 PM, Michael Haggerty [off-list ref] wrote:
On 07/23/2015 09:00 PM, Eric Sunshine wrote:
quoted
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 <redacted>
Signed-off-by: Eric Sunshine <redacted>
---
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...
quoted
@@ -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