[PATCH 00/13] Git help option to list user guides

[PATCH 00/13] Git help option to list user guides

[Philip Oakley]

The git help system will list common commands, and all commands
if asked. However it is difficult for newer users to discover the
guides that are available. This series seeks to add such an option
to 'git help', and allow the user-manual and [git]everyday to be
accessed in the same way.

Patch 1 to 7 update the codebase and look to work correctly.
Patch 1 & 3 are tidy ups. 
The code is very strongly based on the existing common-commands
list so could be refactored and joined if the series is accepted.

Patch 8 onward get into areas of the documentation Makefile that I
need help on so that the user-manual and [git]everyday can 
follow the naming convention for guides and be picked up by the code.
The intent is shown, but the Documentation/Makefile fails for the
renamed gituser-manual and giteveryday - advice needed.

I'm minded to make them have a man page format to simplify changes to
the make file but haven't managed to get that format right. The
alternative is to tweak the make file to cope with these 'pretty'
documents yet still move them to their new names. (I'm unfamiliar
with make files)

Holding pages have been created for the vacated page locations in
the same vein as used for Rename {git- => git}remote-helpers.txt

The patches are built upon V1.8.2-rc0 which includes the recent
user-manual changes.

Initial discussion was at $gmane/215814/focus=216146

Philip Oakley (13):
  Use 'Git' in help messages
  Show 'git help <guide>' usage, with examples
  Help.c use OPT_COUNTUP
  Help.c add --guide option
  Help.c: add list_common_guides_help() function
  Add guide-list.txt and extraction shell
  Extend name string for longer names
  Rename user-manual to gituser-manual
  Rename everyday to giteveryday
  Update Git(1) links to guides
  Add missing guides to list and regenerate
  Documentation/Makefile: update git guide links
  Fixup! doc: giteveryday and user-manual man format

 Documentation/Makefile           |    4 +
 Documentation/everyday.txt       |  424 +---
 Documentation/git.txt            |   12 +-
 Documentation/giteveryday.txt    |  419 ++++
 Documentation/gituser-manual.txt | 4639 +++++++++++++++++++++++++++++++++++++
 Documentation/user-manual.txt    | 4643 +-------------------------------------
 builtin/help.c                   |   11 +-
 common-guides.h                  |   15 +
 generate-cmdlist.sh              |    2 +-
 generate-guidelist.sh            |   23 +
 git.c                            |    4 +-
 guide-list.txt                   |   30 +
 help.c                           |   30 +-
 help.h                           |    1 +
 14 files changed, 5208 insertions(+), 5049 deletions(-)
 create mode 100644 Documentation/giteveryday.txt
 create mode 100644 Documentation/gituser-manual.txt
 create mode 100644 common-guides.h
 create mode 100644 generate-guidelist.sh
 create mode 100644 guide-list.txt

-- 
1.8.1.msysgit.1

[PATCH 01/13] Use 'Git' in help messages

[Philip Oakley]

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 help.c | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/help.c b/help.c
index 1dfa0b0..1c0e17d 100644
--- a/help.c
+++ b/help.c
@@ -209,14 +209,14 @@ void list_commands(unsigned int colopts,
 {
 	if (main_cmds->cnt) {
 		const char *exec_path = git_exec_path();
-		printf_ln(_("available git commands in '%s'"), exec_path);
+		printf_ln(_("available Git commands in '%s'"), exec_path);
 		putchar('\n');
 		pretty_print_string_list(main_cmds, colopts);
 		putchar('\n');
 	}
 
 	if (other_cmds->cnt) {
-		printf_ln(_("git commands available from elsewhere on your $PATH"));
+		printf_ln(_("Git commands available from elsewhere on your $PATH"));
 		putchar('\n');
 		pretty_print_string_list(other_cmds, colopts);
 		putchar('\n');
@@ -232,7 +232,7 @@ void list_common_cmds_help(void)
 			longest = strlen(common_cmds[i].name);
 	}
 
-	puts(_("The most commonly used git commands are:"));
+	puts(_("The most commonly used Git commands are:"));
 	for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
 		printf("   %s   ", common_cmds[i].name);
 		mput_char(' ', longest - strlen(common_cmds[i].name));
@@ -289,7 +289,7 @@ static void add_cmd_list(struct cmdnames *cmds, struct cmdnames *old)
 #define SIMILAR_ENOUGH(x) ((x) < SIMILARITY_FLOOR)
 
 static const char bad_interpreter_advice[] =
-	N_("'%s' appears to be a git command, but we were not\n"
+	N_("'%s' appears to be a Git command, but we were not\n"
 	"able to execute it. Maybe git-%s is broken?");
 
 const char *help_unknown_cmd(const char *cmd)
@@ -380,7 +380,7 @@ const char *help_unknown_cmd(const char *cmd)
 		return assumed;
 	}
 
-	fprintf_ln(stderr, _("git: '%s' is not a git command. See 'git --help'."), cmd);
+	fprintf_ln(stderr, _("git: '%s' is not a Git command. See 'git --help'."), cmd);
 
 	if (SIMILAR_ENOUGH(best_similarity)) {
 		fprintf_ln(stderr,
@@ -397,6 +397,6 @@ const char *help_unknown_cmd(const char *cmd)
 
 int cmd_version(int argc, const char **argv, const char *prefix)
 {
-	printf("git version %s\n", git_version_string);
+	printf("Git version %s\n", git_version_string);
 	return 0;
 }
-- 
1.8.1.msysgit.1

[PATCH 02/13] Show 'git help <guide>' usage, with examples

[Philip Oakley]

The git(1) man page must be accessed via 'git help git' on Git for Windows
as it has no 'man' command. And it prompts users to read the git(1) page,
rather than hoping they follow a subsidiary link within another documentation
page. The 'tutorial' is an obvious guide to suggest.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 git.c | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/git.c b/git.c
index b10c18b..bf0e0de 100644
--- a/git.c
+++ b/git.c
@@ -13,7 +13,9 @@ const char git_usage_string[] =
 	"           <command> [<args>]";
 
 const char git_more_info_string[] =
-	N_("See 'git help <command>' for more information on a specific command.");
+	N_("See 'git help <command>' for more information on a specific command.\n"
+	   "While 'git help <guide>', will show the selected Git concept guide.\n"
+	   "Examples: 'git help git', 'git help branch', 'git help tutorial'..");
 
 static struct startup_info git_startup_info;
 static int use_pager = -1;
-- 
1.8.1.msysgit.1

[PATCH 03/13] Help.c use OPT_COUNTUP

[Philip Oakley]

rename deprecated option in preparation for 'git help --guides'.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 builtin/help.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/builtin/help.c b/builtin/help.c
index d1d7181..d10cbed 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -39,7 +39,7 @@ static int show_all = 0;
 static unsigned int colopts;
 static enum help_format help_format = HELP_FORMAT_NONE;
 static struct option builtin_help_options[] = {
-	OPT_BOOLEAN('a', "all", &show_all, N_("print all available commands")),
+	OPT_COUNTUP('a', "all", &show_all, N_("print all available commands")),
 	OPT_SET_INT('m', "man", &help_format, N_("show man page"), HELP_FORMAT_MAN),
 	OPT_SET_INT('w', "web", &help_format, N_("show manual in web browser"),
 			HELP_FORMAT_WEB),
-- 
1.8.1.msysgit.1

[PATCH 04/13] Help.c add --guide option

[Philip Oakley]

Logic, but no actions, included.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 builtin/help.c | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/builtin/help.c b/builtin/help.c
index d10cbed..699e679 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -36,10 +36,12 @@ enum help_format {
 static const char *html_path;
 
 static int show_all = 0;
+static int show_guides = 0;
 static unsigned int colopts;
 static enum help_format help_format = HELP_FORMAT_NONE;
 static struct option builtin_help_options[] = {
 	OPT_COUNTUP('a', "all", &show_all, N_("print all available commands")),
+	OPT_COUNTUP('g', "guides", &show_guides, N_("print all available guides")),
 	OPT_SET_INT('m', "man", &help_format, N_("show man page"), HELP_FORMAT_MAN),
 	OPT_SET_INT('w', "web", &help_format, N_("show manual in web browser"),
 			HELP_FORMAT_WEB),
@@ -49,7 +51,7 @@ static struct option builtin_help_options[] = {
 };
 
 static const char * const builtin_help_usage[] = {
-	N_("git help [--all] [--man|--web|--info] [command]"),
+	N_("git help [--all] [--guides] [--man|--web|--info] [command]"),
 	NULL
 };
 
@@ -429,9 +431,11 @@ int cmd_help(int argc, const char **argv, const char *prefix)
 		printf(_("usage: %s%s"), _(git_usage_string), "\n\n");
 		list_commands(colopts, &main_cmds, &other_cmds);
 		printf("%s\n", _(git_more_info_string));
+		if (!show_guides) return 0;
+	}
+	if (show_guides) {
 		return 0;
 	}
-
 	if (!argv[0]) {
 		printf(_("usage: %s%s"), _(git_usage_string), "\n\n");
 		list_common_cmds_help();
-- 
1.8.1.msysgit.1

[PATCH 05/13] Help.c: add list_common_guides_help() function

[Philip Oakley]

Re-use list_common_cmds_help but simply change the array name.
Candidate for future refactoring to pass a pointer to the array.

Do not list User-manual and Everday Git which not follow the naming
convention, nor gitrepository-layout which doesn't fit within the name field size

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 builtin/help.c  |  1 +
 common-guides.h | 12 ++++++++++++
 help.c          | 18 ++++++++++++++++++
 help.h          |  1 +
 4 files changed, 32 insertions(+)
 create mode 100644 common-guides.h

diff --git a/builtin/help.c b/builtin/help.c
index 699e679..b0746af 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -434,6 +434,7 @@ int cmd_help(int argc, const char **argv, const char *prefix)
 		if (!show_guides) return 0;
 	}
 	if (show_guides) {
+		list_common_guides_help();
 		return 0;
 	}
 	if (!argv[0]) {
diff --git a/common-guides.h b/common-guides.h
new file mode 100644
index 0000000..a8ad8d1
--- /dev/null
+++ b/common-guides.h
@@ -0,0 +1,12 @@
+/* Automatically generated by ./generate-guidelist.sh */
+/* re-use struct cmdname_help in common-commands.h */
+
+static struct cmdname_help common_guides[] = {
+  {"attributes", "defining attributes per path"},
+  {"glossary", "A GIT Glossary"},
+  {"ignore", "Specifies intentionally untracked files to ignore"},
+  {"modules", "defining submodule properties"},
+  {"revisions", "specifying revisions and ranges for git"},
+  {"tutorial", "A tutorial introduction to git (for version 1.5.1 or newer)"},
+  {"workflows", "An overview of recommended workflows with git"},
+};
diff --git a/help.c b/help.c
index 1c0e17d..94df446 100644
--- a/help.c
+++ b/help.c
@@ -4,6 +4,7 @@
 #include "levenshtein.h"
 #include "help.h"
 #include "common-cmds.h"
+#include "common-guides.h"
 #include "string-list.h"
 #include "column.h"
 #include "version.h"
@@ -240,6 +241,23 @@ void list_common_cmds_help(void)
 	}
 }
 
+void list_common_guides_help(void)
+{
+	int i, longest = 0;
+
+	for (i = 0; i < ARRAY_SIZE(common_guides); i++) {
+		if (longest < strlen(common_guides[i].name))
+			longest = strlen(common_guides[i].name);
+	}
+
+	puts(_("The common Git guides are:"));
+	for (i = 0; i < ARRAY_SIZE(common_guides); i++) {
+		printf("   %s   ", common_guides[i].name);
+		mput_char(' ', longest - strlen(common_guides[i].name));
+		puts(_(common_guides[i].help));
+	}
+}
+
 int is_in_cmdlist(struct cmdnames *c, const char *s)
 {
 	int i;
diff --git a/help.h b/help.h
index 0ae5a12..4ae1fd7 100644
--- a/help.h
+++ b/help.h
@@ -17,6 +17,7 @@ static inline void mput_char(char c, unsigned int num)
 }
 
 extern void list_common_cmds_help(void);
+extern void list_common_guides_help(void);
 extern const char *help_unknown_cmd(const char *cmd);
 extern void load_command_list(const char *prefix,
 			      struct cmdnames *main_cmds,
-- 
1.8.1.msysgit.1

[PATCH 06/13] Add guide-list.txt and extraction shell

[Philip Oakley]

The guide-list.txt uses exactly the same format as command-list.txt
so could be merged as part of a refactoring.

The category naming for each guide is an initial suggestion and
is not yet used. Only those with the 'guide' prefix are copied
by the generate-guidelist.sh into the common-guides.h file.

The user-manual.txt and everyday.txt do not have the correct filename
format yet. And gitrepository-layout.txt name is too long to include.
So comment them out.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
The shell script function N_() does not appear to work correctly on my
Ubuntu lash-up, so an simpler script line is used with the original
commented out.
---
 generate-guidelist.sh | 23 +++++++++++++++++++++++
 guide-list.txt        | 29 +++++++++++++++++++++++++++++
 2 files changed, 52 insertions(+)
 create mode 100644 generate-guidelist.sh
 create mode 100644 guide-list.txt

diff --git a/generate-guidelist.sh b/generate-guidelist.sh
new file mode 100644
index 0000000..c0c98eb
--- /dev/null
+++ b/generate-guidelist.sh
@@ -0,0 +1,23 @@
+#!/bin/sh
+# Usage: ./generate-guidelist.sh  >>common-guides.h
+# based on generate-cmdlist.sh
+echo "/* Automatically generated by $0 */
+/* re-use struct cmdname_help in common-commands.h */
+
+static struct cmdname_help common_guides[] = {"
+
+sed -n -e 's/^git\([^ 	]*\)[ 	].* guide.*/\1/p' guide-list.txt |
+sort |
+while read guide
+do
+     sed -n '
+     /^NAME/,/git'"$guide"'/H
+     ${
+	    x
+#	    s/.*git'"$guide"' - \(.*\)/  {"'"$guide"'", N_("\1")},/
+	    s/.*git'"$guide"' - \(.*\)/  {"'"$guide"'", "\1"},/
+	    p
+     }' "Documentation/git$guide.txt"
+done
+echo "};"
+
diff --git a/guide-list.txt b/guide-list.txt
new file mode 100644
index 0000000..a419ac4
--- /dev/null
+++ b/guide-list.txt
@@ -0,0 +1,29 @@
+# List of known git guides.
+# guide name				category [deprecated] [common] [guide]
+gitattributes                           concept	 guide
+gitcore-tutorial                        specialist
+gitcredentials                          specialist
+gitcvs-migration                        specialist
+gitdiffcore                             specialist
+gitglossary                             reference	 guide
+githooks                                specialist
+gitignore                               concept	 guide
+gitmodules                              concept	 guide
+gitnamespaces                           specialist
+#gitrepository-layout                    reference guide
+gitrevisions                            concept	 guide
+gittutorial                             user	 guide
+gittutorial-2                           user
+gitweb.conf                             specialist
+gitweb                                  specialist
+gitworkflows                            user	 guide
+
+#giteveryday                             user	 guide
+#gituser-manual                          user	 guide
+
+# could embed inside common-cmds.h with [guide] as the second thing,
+# making the sed's in generate-cmdlist.sh more obvious
+# but drop the dash in 's/^git-\
+
+#gitrepository-layout is too long for the current char[16]
+#
-- 
1.8.1.msysgit.1

[PATCH 07/13] Extend name string for longer names

[Philip Oakley]

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 generate-cmdlist.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh
index 9a4c9b9..c25561f 100755
--- a/generate-cmdlist.sh
+++ b/generate-cmdlist.sh
@@ -2,7 +2,7 @@
 
 echo "/* Automatically generated by $0 */
 struct cmdname_help {
-    char name[16];
+    char name[20];
     char help[80];
 };
 
-- 
1.8.1.msysgit.1

[PATCH 09/13] Rename everyday to giteveryday

[Philip Oakley]

and leave a 'page has moved' page.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 Documentation/everyday.txt    | 424 ++----------------------------------------
 Documentation/giteveryday.txt | 413 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 431 insertions(+), 406 deletions(-)
 create mode 100644 Documentation/giteveryday.txt

diff --git a/Documentation/everyday.txt b/Documentation/everyday.txt
index e1fba85..3fc69f6 100644
--- a/Documentation/everyday.txt
+++ b/Documentation/everyday.txt
@@ -1,413 +1,25 @@
-Everyday Git With 20 Commands Or So
+Everyday GIT With 20 Commands Or So
 ===================================
 
-<<Individual Developer (Standalone)>> commands are essential for
-anybody who makes a commit, even for somebody who works alone.
+NAME
+----
+everyday - obsoleted page
 
-If you work with other people, you will need commands listed in
-the <<Individual Developer (Participant)>> section as well.
+SYNOPSIS
+--------
+See linkgit:giteveryday.
 
-People who play the <<Integrator>> role need to learn some more
-commands in addition to the above.
+DESCRIPTION
+-----------
+This document has been moved to linkgit:giteveryday.
 
-<<Repository Administration>> commands are for system
-administrators who are responsible for the care and feeding
-of Git repositories.
+Please let the owners of the referring site know so that they can update the
+link you clicked to get here.
 
+SEE ALSO
+--------
+linkgit:giteveryday
 
-Individual Developer (Standalone)[[Individual Developer (Standalone)]]
-----------------------------------------------------------------------
-
-A standalone individual developer does not exchange patches with
-other people, and works alone in a single repository, using the
-following commands.
-
-  * linkgit:git-init[1] to create a new repository.
-
-  * linkgit:git-show-branch[1] to see where you are.
-
-  * linkgit:git-log[1] to see what happened.
-
-  * linkgit:git-checkout[1] and linkgit:git-branch[1] to switch
-    branches.
-
-  * linkgit:git-add[1] to manage the index file.
-
-  * linkgit:git-diff[1] and linkgit:git-status[1] to see what
-    you are in the middle of doing.
-
-  * linkgit:git-commit[1] to advance the current branch.
-
-  * linkgit:git-reset[1] and linkgit:git-checkout[1] (with
-    pathname parameters) to undo changes.
-
-  * linkgit:git-merge[1] to merge between local branches.
-
-  * linkgit:git-rebase[1] to maintain topic branches.
-
-  * linkgit:git-tag[1] to mark known point.
-
-Examples
-~~~~~~~~
-
-Use a tarball as a starting point for a new repository.::
-+
-------------
-$ tar zxf frotz.tar.gz
-$ cd frotz
-$ git init
-$ git add . <1>
-$ git commit -m "import of frotz source tree."
-$ git tag v2.43 <2>
-------------
-+
-<1> add everything under the current directory.
-<2> make a lightweight, unannotated tag.
-
-Create a topic branch and develop.::
-+
-------------
-$ git checkout -b alsa-audio <1>
-$ edit/compile/test
-$ git checkout -- curses/ux_audio_oss.c <2>
-$ git add curses/ux_audio_alsa.c <3>
-$ edit/compile/test
-$ git diff HEAD <4>
-$ git commit -a -s <5>
-$ edit/compile/test
-$ git reset --soft HEAD^ <6>
-$ edit/compile/test
-$ git diff ORIG_HEAD <7>
-$ git commit -a -c ORIG_HEAD <8>
-$ git checkout master <9>
-$ git merge alsa-audio <10>
-$ git log --since='3 days ago' <11>
-$ git log v2.43.. curses/ <12>
-------------
-+
-<1> create a new topic branch.
-<2> revert your botched changes in `curses/ux_audio_oss.c`.
-<3> you need to tell Git if you added a new file; removal and
-modification will be caught if you do `git commit -a` later.
-<4> to see what changes you are committing.
-<5> commit everything as you have tested, with your sign-off.
-<6> take the last commit back, keeping what is in the working tree.
-<7> look at the changes since the premature commit we took back.
-<8> redo the commit undone in the previous step, using the message
-you originally wrote.
-<9> switch to the master branch.
-<10> merge a topic branch into your master branch.
-<11> review commit logs; other forms to limit output can be
-combined and include `--max-count=10` (show 10 commits),
-`--until=2005-12-10`, etc.
-<12> view only the changes that touch what's in `curses/`
-directory, since `v2.43` tag.
-
-
-Individual Developer (Participant)[[Individual Developer (Participant)]]
-------------------------------------------------------------------------
-
-A developer working as a participant in a group project needs to
-learn how to communicate with others, and uses these commands in
-addition to the ones needed by a standalone developer.
-
-  * linkgit:git-clone[1] from the upstream to prime your local
-    repository.
-
-  * linkgit:git-pull[1] and linkgit:git-fetch[1] from "origin"
-    to keep up-to-date with the upstream.
-
-  * linkgit:git-push[1] to shared repository, if you adopt CVS
-    style shared repository workflow.
-
-  * linkgit:git-format-patch[1] to prepare e-mail submission, if
-    you adopt Linux kernel-style public forum workflow.
-
-Examples
-~~~~~~~~
-
-Clone the upstream and work on it.  Feed changes to upstream.::
-+
-------------
-$ git clone git://git.kernel.org/pub/scm/.../torvalds/linux-2.6 my2.6
-$ cd my2.6
-$ edit/compile/test; git commit -a -s <1>
-$ git format-patch origin <2>
-$ git pull <3>
-$ git log -p ORIG_HEAD.. arch/i386 include/asm-i386 <4>
-$ git pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL <5>
-$ git reset --hard ORIG_HEAD <6>
-$ git gc <7>
-$ git fetch --tags <8>
-------------
-+
-<1> repeat as needed.
-<2> extract patches from your branch for e-mail submission.
-<3> `git pull` fetches from `origin` by default and merges into the
-current branch.
-<4> immediately after pulling, look at the changes done upstream
-since last time we checked, only in the
-area we are interested in.
-<5> fetch from a specific branch from a specific repository and merge.
-<6> revert the pull.
-<7> garbage collect leftover objects from reverted pull.
-<8> from time to time, obtain official tags from the `origin`
-and store them under `.git/refs/tags/`.
-
-
-Push into another repository.::
-+
-------------
-satellite$ git clone mothership:frotz frotz <1>
-satellite$ cd frotz
-satellite$ git config --get-regexp '^(remote|branch)\.' <2>
-remote.origin.url mothership:frotz
-remote.origin.fetch refs/heads/*:refs/remotes/origin/*
-branch.master.remote origin
-branch.master.merge refs/heads/master
-satellite$ git config remote.origin.push \
-           master:refs/remotes/satellite/master <3>
-satellite$ edit/compile/test/commit
-satellite$ git push origin <4>
-
-mothership$ cd frotz
-mothership$ git checkout master
-mothership$ git merge satellite/master <5>
-------------
-+
-<1> mothership machine has a frotz repository under your home
-directory; clone from it to start a repository on the satellite
-machine.
-<2> clone sets these configuration variables by default.
-It arranges `git pull` to fetch and store the branches of mothership
-machine to local `remotes/origin/*` remote-tracking branches.
-<3> arrange `git push` to push local `master` branch to
-`remotes/satellite/master` branch of the mothership machine.
-<4> push will stash our work away on `remotes/satellite/master`
-remote-tracking branch on the mothership machine.  You could use this
-as a back-up method.
-<5> on mothership machine, merge the work done on the satellite
-machine into the master branch.
-
-Branch off of a specific tag.::
-+
-------------
-$ git checkout -b private2.6.14 v2.6.14 <1>
-$ edit/compile/test; git commit -a
-$ git checkout master
-$ git format-patch -k -m --stdout v2.6.14..private2.6.14 |
-  git am -3 -k <2>
-------------
-+
-<1> create a private branch based on a well known (but somewhat behind)
-tag.
-<2> forward port all changes in `private2.6.14` branch to `master` branch
-without a formal "merging".
-
-
-Integrator[[Integrator]]
-------------------------
-
-A fairly central person acting as the integrator in a group
-project receives changes made by others, reviews and integrates
-them and publishes the result for others to use, using these
-commands in addition to the ones needed by participants.
-
-  * linkgit:git-am[1] to apply patches e-mailed in from your
-    contributors.
-
-  * linkgit:git-pull[1] to merge from your trusted lieutenants.
-
-  * linkgit:git-format-patch[1] to prepare and send suggested
-    alternative to contributors.
-
-  * linkgit:git-revert[1] to undo botched commits.
-
-  * linkgit:git-push[1] to publish the bleeding edge.
-
-
-Examples
-~~~~~~~~
-
-My typical Git day.::
-+
-------------
-$ git status <1>
-$ git show-branch <2>
-$ mailx <3>
-& s 2 3 4 5 ./+to-apply
-& s 7 8 ./+hold-linus
-& q
-$ git checkout -b topic/one master
-$ git am -3 -i -s -u ./+to-apply <4>
-$ compile/test
-$ git checkout -b hold/linus && git am -3 -i -s -u ./+hold-linus <5>
-$ git checkout topic/one && git rebase master <6>
-$ git checkout pu && git reset --hard next <7>
-$ git merge topic/one topic/two && git merge hold/linus <8>
-$ git checkout maint
-$ git cherry-pick master~4 <9>
-$ compile/test
-$ git tag -s -m "GIT 0.99.9x" v0.99.9x <10>
-$ git fetch ko && git show-branch master maint 'tags/ko-*' <11>
-$ git push ko <12>
-$ git push ko v0.99.9x <13>
-------------
-+
-<1> see what I was in the middle of doing, if any.
-<2> see what topic branches I have and think about how ready
-they are.
-<3> read mails, save ones that are applicable, and save others
-that are not quite ready.
-<4> apply them, interactively, with my sign-offs.
-<5> create topic branch as needed and apply, again with my
-sign-offs.
-<6> rebase internal topic branch that has not been merged to the
-master, nor exposed as a part of a stable branch.
-<7> restart `pu` every time from the next.
-<8> and bundle topic branches still cooking.
-<9> backport a critical fix.
-<10> create a signed tag.
-<11> make sure I did not accidentally rewind master beyond what I
-already pushed out.  `ko` shorthand points at the repository I have
-at kernel.org, and looks like this:
-+
-------------
-$ cat .git/remotes/ko
-URL: kernel.org:/pub/scm/git/git.git
-Pull: master:refs/tags/ko-master
-Pull: next:refs/tags/ko-next
-Pull: maint:refs/tags/ko-maint
-Push: master
-Push: next
-Push: +pu
-Push: maint
-------------
-+
-In the output from `git show-branch`, `master` should have
-everything `ko-master` has, and `next` should have
-everything `ko-next` has.
-
-<12> push out the bleeding edge.
-<13> push the tag out, too.
-
-
-Repository Administration[[Repository Administration]]
-------------------------------------------------------
-
-A repository administrator uses the following tools to set up
-and maintain access to the repository by developers.
-
-  * linkgit:git-daemon[1] to allow anonymous download from
-    repository.
-
-  * linkgit:git-shell[1] can be used as a 'restricted login shell'
-    for shared central repository users.
-
-link:howto/update-hook-example.txt[update hook howto] has a good
-example of managing a shared central repository.
-
-
-Examples
-~~~~~~~~
-We assume the following in /etc/services::
-+
-------------
-$ grep 9418 /etc/services
-git		9418/tcp		# Git Version Control System
-------------
-
-Run git-daemon to serve /pub/scm from inetd.::
-+
-------------
-$ grep git /etc/inetd.conf
-git	stream	tcp	nowait	nobody \
-  /usr/bin/git-daemon git-daemon --inetd --export-all /pub/scm
-------------
-+
-The actual configuration line should be on one line.
-
-Run git-daemon to serve /pub/scm from xinetd.::
-+
-------------
-$ cat /etc/xinetd.d/git-daemon
-# default: off
-# description: The Git server offers access to Git repositories
-service git
-{
-        disable = no
-        type            = UNLISTED
-        port            = 9418
-        socket_type     = stream
-        wait            = no
-        user            = nobody
-        server          = /usr/bin/git-daemon
-        server_args     = --inetd --export-all --base-path=/pub/scm
-        log_on_failure  += USERID
-}
-------------
-+
-Check your xinetd(8) documentation and setup, this is from a Fedora system.
-Others might be different.
-
-Give push/pull only access to developers.::
-+
-------------
-$ grep git /etc/passwd <1>
-alice:x:1000:1000::/home/alice:/usr/bin/git-shell
-bob:x:1001:1001::/home/bob:/usr/bin/git-shell
-cindy:x:1002:1002::/home/cindy:/usr/bin/git-shell
-david:x:1003:1003::/home/david:/usr/bin/git-shell
-$ grep git /etc/shells <2>
-/usr/bin/git-shell
-------------
-+
-<1> log-in shell is set to /usr/bin/git-shell, which does not
-allow anything but `git push` and `git pull`.  The users should
-get an ssh access to the machine.
-<2> in many distributions /etc/shells needs to list what is used
-as the login shell.
-
-CVS-style shared repository.::
-+
-------------
-$ grep git /etc/group <1>
-git:x:9418:alice,bob,cindy,david
-$ cd /home/devo.git
-$ ls -l <2>
-  lrwxrwxrwx   1 david git    17 Dec  4 22:40 HEAD -> refs/heads/master
-  drwxrwsr-x   2 david git  4096 Dec  4 22:40 branches
-  -rw-rw-r--   1 david git    84 Dec  4 22:40 config
-  -rw-rw-r--   1 david git    58 Dec  4 22:40 description
-  drwxrwsr-x   2 david git  4096 Dec  4 22:40 hooks
-  -rw-rw-r--   1 david git 37504 Dec  4 22:40 index
-  drwxrwsr-x   2 david git  4096 Dec  4 22:40 info
-  drwxrwsr-x   4 david git  4096 Dec  4 22:40 objects
-  drwxrwsr-x   4 david git  4096 Nov  7 14:58 refs
-  drwxrwsr-x   2 david git  4096 Dec  4 22:40 remotes
-$ ls -l hooks/update <3>
-  -r-xr-xr-x   1 david git  3536 Dec  4 22:40 update
-$ cat info/allowed-users <4>
-refs/heads/master	alice\|cindy
-refs/heads/doc-update	bob
-refs/tags/v[0-9]*	david
-------------
-+
-<1> place the developers into the same git group.
-<2> and make the shared repository writable by the group.
-<3> use update-hook example by Carl from Documentation/howto/
-for branch policy control.
-<4> alice and cindy can push into master, only bob can push into doc-update.
-david is the release manager and is the only person who can
-create and push version tags.
-
-HTTP server to support dumb protocol transfer.::
-+
-------------
-dev$ git update-server-info <1>
-dev$ ftp user@isp.example.com <2>
-ftp> cp -r .git /home/user/myproject.git
-------------
-+
-<1> make sure your info/refs and objects/info/packs are up-to-date
-<2> upload to public HTTP server hosted by your ISP.
+GIT
+---
+This page location is no longer a part of the linkgit:git[1] suite
diff --git a/Documentation/giteveryday.txt b/Documentation/giteveryday.txt
new file mode 100644
index 0000000..e1fba85
--- /dev/null
+++ b/Documentation/giteveryday.txt
@@ -0,0 +1,413 @@
+Everyday Git With 20 Commands Or So
+===================================
+
+<<Individual Developer (Standalone)>> commands are essential for
+anybody who makes a commit, even for somebody who works alone.
+
+If you work with other people, you will need commands listed in
+the <<Individual Developer (Participant)>> section as well.
+
+People who play the <<Integrator>> role need to learn some more
+commands in addition to the above.
+
+<<Repository Administration>> commands are for system
+administrators who are responsible for the care and feeding
+of Git repositories.
+
+
+Individual Developer (Standalone)[[Individual Developer (Standalone)]]
+----------------------------------------------------------------------
+
+A standalone individual developer does not exchange patches with
+other people, and works alone in a single repository, using the
+following commands.
+
+  * linkgit:git-init[1] to create a new repository.
+
+  * linkgit:git-show-branch[1] to see where you are.
+
+  * linkgit:git-log[1] to see what happened.
+
+  * linkgit:git-checkout[1] and linkgit:git-branch[1] to switch
+    branches.
+
+  * linkgit:git-add[1] to manage the index file.
+
+  * linkgit:git-diff[1] and linkgit:git-status[1] to see what
+    you are in the middle of doing.
+
+  * linkgit:git-commit[1] to advance the current branch.
+
+  * linkgit:git-reset[1] and linkgit:git-checkout[1] (with
+    pathname parameters) to undo changes.
+
+  * linkgit:git-merge[1] to merge between local branches.
+
+  * linkgit:git-rebase[1] to maintain topic branches.
+
+  * linkgit:git-tag[1] to mark known point.
+
+Examples
+~~~~~~~~
+
+Use a tarball as a starting point for a new repository.::
++
+------------
+$ tar zxf frotz.tar.gz
+$ cd frotz
+$ git init
+$ git add . <1>
+$ git commit -m "import of frotz source tree."
+$ git tag v2.43 <2>
+------------
++
+<1> add everything under the current directory.
+<2> make a lightweight, unannotated tag.
+
+Create a topic branch and develop.::
++
+------------
+$ git checkout -b alsa-audio <1>
+$ edit/compile/test
+$ git checkout -- curses/ux_audio_oss.c <2>
+$ git add curses/ux_audio_alsa.c <3>
+$ edit/compile/test
+$ git diff HEAD <4>
+$ git commit -a -s <5>
+$ edit/compile/test
+$ git reset --soft HEAD^ <6>
+$ edit/compile/test
+$ git diff ORIG_HEAD <7>
+$ git commit -a -c ORIG_HEAD <8>
+$ git checkout master <9>
+$ git merge alsa-audio <10>
+$ git log --since='3 days ago' <11>
+$ git log v2.43.. curses/ <12>
+------------
++
+<1> create a new topic branch.
+<2> revert your botched changes in `curses/ux_audio_oss.c`.
+<3> you need to tell Git if you added a new file; removal and
+modification will be caught if you do `git commit -a` later.
+<4> to see what changes you are committing.
+<5> commit everything as you have tested, with your sign-off.
+<6> take the last commit back, keeping what is in the working tree.
+<7> look at the changes since the premature commit we took back.
+<8> redo the commit undone in the previous step, using the message
+you originally wrote.
+<9> switch to the master branch.
+<10> merge a topic branch into your master branch.
+<11> review commit logs; other forms to limit output can be
+combined and include `--max-count=10` (show 10 commits),
+`--until=2005-12-10`, etc.
+<12> view only the changes that touch what's in `curses/`
+directory, since `v2.43` tag.
+
+
+Individual Developer (Participant)[[Individual Developer (Participant)]]
+------------------------------------------------------------------------
+
+A developer working as a participant in a group project needs to
+learn how to communicate with others, and uses these commands in
+addition to the ones needed by a standalone developer.
+
+  * linkgit:git-clone[1] from the upstream to prime your local
+    repository.
+
+  * linkgit:git-pull[1] and linkgit:git-fetch[1] from "origin"
+    to keep up-to-date with the upstream.
+
+  * linkgit:git-push[1] to shared repository, if you adopt CVS
+    style shared repository workflow.
+
+  * linkgit:git-format-patch[1] to prepare e-mail submission, if
+    you adopt Linux kernel-style public forum workflow.
+
+Examples
+~~~~~~~~
+
+Clone the upstream and work on it.  Feed changes to upstream.::
++
+------------
+$ git clone git://git.kernel.org/pub/scm/.../torvalds/linux-2.6 my2.6
+$ cd my2.6
+$ edit/compile/test; git commit -a -s <1>
+$ git format-patch origin <2>
+$ git pull <3>
+$ git log -p ORIG_HEAD.. arch/i386 include/asm-i386 <4>
+$ git pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL <5>
+$ git reset --hard ORIG_HEAD <6>
+$ git gc <7>
+$ git fetch --tags <8>
+------------
++
+<1> repeat as needed.
+<2> extract patches from your branch for e-mail submission.
+<3> `git pull` fetches from `origin` by default and merges into the
+current branch.
+<4> immediately after pulling, look at the changes done upstream
+since last time we checked, only in the
+area we are interested in.
+<5> fetch from a specific branch from a specific repository and merge.
+<6> revert the pull.
+<7> garbage collect leftover objects from reverted pull.
+<8> from time to time, obtain official tags from the `origin`
+and store them under `.git/refs/tags/`.
+
+
+Push into another repository.::
++
+------------
+satellite$ git clone mothership:frotz frotz <1>
+satellite$ cd frotz
+satellite$ git config --get-regexp '^(remote|branch)\.' <2>
+remote.origin.url mothership:frotz
+remote.origin.fetch refs/heads/*:refs/remotes/origin/*
+branch.master.remote origin
+branch.master.merge refs/heads/master
+satellite$ git config remote.origin.push \
+           master:refs/remotes/satellite/master <3>
+satellite$ edit/compile/test/commit
+satellite$ git push origin <4>
+
+mothership$ cd frotz
+mothership$ git checkout master
+mothership$ git merge satellite/master <5>
+------------
++
+<1> mothership machine has a frotz repository under your home
+directory; clone from it to start a repository on the satellite
+machine.
+<2> clone sets these configuration variables by default.
+It arranges `git pull` to fetch and store the branches of mothership
+machine to local `remotes/origin/*` remote-tracking branches.
+<3> arrange `git push` to push local `master` branch to
+`remotes/satellite/master` branch of the mothership machine.
+<4> push will stash our work away on `remotes/satellite/master`
+remote-tracking branch on the mothership machine.  You could use this
+as a back-up method.
+<5> on mothership machine, merge the work done on the satellite
+machine into the master branch.
+
+Branch off of a specific tag.::
++
+------------
+$ git checkout -b private2.6.14 v2.6.14 <1>
+$ edit/compile/test; git commit -a
+$ git checkout master
+$ git format-patch -k -m --stdout v2.6.14..private2.6.14 |
+  git am -3 -k <2>
+------------
++
+<1> create a private branch based on a well known (but somewhat behind)
+tag.
+<2> forward port all changes in `private2.6.14` branch to `master` branch
+without a formal "merging".
+
+
+Integrator[[Integrator]]
+------------------------
+
+A fairly central person acting as the integrator in a group
+project receives changes made by others, reviews and integrates
+them and publishes the result for others to use, using these
+commands in addition to the ones needed by participants.
+
+  * linkgit:git-am[1] to apply patches e-mailed in from your
+    contributors.
+
+  * linkgit:git-pull[1] to merge from your trusted lieutenants.
+
+  * linkgit:git-format-patch[1] to prepare and send suggested
+    alternative to contributors.
+
+  * linkgit:git-revert[1] to undo botched commits.
+
+  * linkgit:git-push[1] to publish the bleeding edge.
+
+
+Examples
+~~~~~~~~
+
+My typical Git day.::
++
+------------
+$ git status <1>
+$ git show-branch <2>
+$ mailx <3>
+& s 2 3 4 5 ./+to-apply
+& s 7 8 ./+hold-linus
+& q
+$ git checkout -b topic/one master
+$ git am -3 -i -s -u ./+to-apply <4>
+$ compile/test
+$ git checkout -b hold/linus && git am -3 -i -s -u ./+hold-linus <5>
+$ git checkout topic/one && git rebase master <6>
+$ git checkout pu && git reset --hard next <7>
+$ git merge topic/one topic/two && git merge hold/linus <8>
+$ git checkout maint
+$ git cherry-pick master~4 <9>
+$ compile/test
+$ git tag -s -m "GIT 0.99.9x" v0.99.9x <10>
+$ git fetch ko && git show-branch master maint 'tags/ko-*' <11>
+$ git push ko <12>
+$ git push ko v0.99.9x <13>
+------------
++
+<1> see what I was in the middle of doing, if any.
+<2> see what topic branches I have and think about how ready
+they are.
+<3> read mails, save ones that are applicable, and save others
+that are not quite ready.
+<4> apply them, interactively, with my sign-offs.
+<5> create topic branch as needed and apply, again with my
+sign-offs.
+<6> rebase internal topic branch that has not been merged to the
+master, nor exposed as a part of a stable branch.
+<7> restart `pu` every time from the next.
+<8> and bundle topic branches still cooking.
+<9> backport a critical fix.
+<10> create a signed tag.
+<11> make sure I did not accidentally rewind master beyond what I
+already pushed out.  `ko` shorthand points at the repository I have
+at kernel.org, and looks like this:
++
+------------
+$ cat .git/remotes/ko
+URL: kernel.org:/pub/scm/git/git.git
+Pull: master:refs/tags/ko-master
+Pull: next:refs/tags/ko-next
+Pull: maint:refs/tags/ko-maint
+Push: master
+Push: next
+Push: +pu
+Push: maint
+------------
++
+In the output from `git show-branch`, `master` should have
+everything `ko-master` has, and `next` should have
+everything `ko-next` has.
+
+<12> push out the bleeding edge.
+<13> push the tag out, too.
+
+
+Repository Administration[[Repository Administration]]
+------------------------------------------------------
+
+A repository administrator uses the following tools to set up
+and maintain access to the repository by developers.
+
+  * linkgit:git-daemon[1] to allow anonymous download from
+    repository.
+
+  * linkgit:git-shell[1] can be used as a 'restricted login shell'
+    for shared central repository users.
+
+link:howto/update-hook-example.txt[update hook howto] has a good
+example of managing a shared central repository.
+
+
+Examples
+~~~~~~~~
+We assume the following in /etc/services::
++
+------------
+$ grep 9418 /etc/services
+git		9418/tcp		# Git Version Control System
+------------
+
+Run git-daemon to serve /pub/scm from inetd.::
++
+------------
+$ grep git /etc/inetd.conf
+git	stream	tcp	nowait	nobody \
+  /usr/bin/git-daemon git-daemon --inetd --export-all /pub/scm
+------------
++
+The actual configuration line should be on one line.
+
+Run git-daemon to serve /pub/scm from xinetd.::
++
+------------
+$ cat /etc/xinetd.d/git-daemon
+# default: off
+# description: The Git server offers access to Git repositories
+service git
+{
+        disable = no
+        type            = UNLISTED
+        port            = 9418
+        socket_type     = stream
+        wait            = no
+        user            = nobody
+        server          = /usr/bin/git-daemon
+        server_args     = --inetd --export-all --base-path=/pub/scm
+        log_on_failure  += USERID
+}
+------------
++
+Check your xinetd(8) documentation and setup, this is from a Fedora system.
+Others might be different.
+
+Give push/pull only access to developers.::
++
+------------
+$ grep git /etc/passwd <1>
+alice:x:1000:1000::/home/alice:/usr/bin/git-shell
+bob:x:1001:1001::/home/bob:/usr/bin/git-shell
+cindy:x:1002:1002::/home/cindy:/usr/bin/git-shell
+david:x:1003:1003::/home/david:/usr/bin/git-shell
+$ grep git /etc/shells <2>
+/usr/bin/git-shell
+------------
++
+<1> log-in shell is set to /usr/bin/git-shell, which does not
+allow anything but `git push` and `git pull`.  The users should
+get an ssh access to the machine.
+<2> in many distributions /etc/shells needs to list what is used
+as the login shell.
+
+CVS-style shared repository.::
++
+------------
+$ grep git /etc/group <1>
+git:x:9418:alice,bob,cindy,david
+$ cd /home/devo.git
+$ ls -l <2>
+  lrwxrwxrwx   1 david git    17 Dec  4 22:40 HEAD -> refs/heads/master
+  drwxrwsr-x   2 david git  4096 Dec  4 22:40 branches
+  -rw-rw-r--   1 david git    84 Dec  4 22:40 config
+  -rw-rw-r--   1 david git    58 Dec  4 22:40 description
+  drwxrwsr-x   2 david git  4096 Dec  4 22:40 hooks
+  -rw-rw-r--   1 david git 37504 Dec  4 22:40 index
+  drwxrwsr-x   2 david git  4096 Dec  4 22:40 info
+  drwxrwsr-x   4 david git  4096 Dec  4 22:40 objects
+  drwxrwsr-x   4 david git  4096 Nov  7 14:58 refs
+  drwxrwsr-x   2 david git  4096 Dec  4 22:40 remotes
+$ ls -l hooks/update <3>
+  -r-xr-xr-x   1 david git  3536 Dec  4 22:40 update
+$ cat info/allowed-users <4>
+refs/heads/master	alice\|cindy
+refs/heads/doc-update	bob
+refs/tags/v[0-9]*	david
+------------
++
+<1> place the developers into the same git group.
+<2> and make the shared repository writable by the group.
+<3> use update-hook example by Carl from Documentation/howto/
+for branch policy control.
+<4> alice and cindy can push into master, only bob can push into doc-update.
+david is the release manager and is the only person who can
+create and push version tags.
+
+HTTP server to support dumb protocol transfer.::
++
+------------
+dev$ git update-server-info <1>
+dev$ ftp user@isp.example.com <2>
+ftp> cp -r .git /home/user/myproject.git
+------------
++
+<1> make sure your info/refs and objects/info/packs are up-to-date
+<2> upload to public HTTP server hosted by your ISP.
-- 
1.8.1.msysgit.1

[PATCH 10/13] Update Git(1) links to guides

[Philip Oakley]

to giteverday and gituser-manual

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 Documentation/git.txt | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/git.txt b/Documentation/git.txt
index 0b681d9..1830245 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -22,8 +22,8 @@ unusually rich command set that provides both high-level operations
 and full access to internals.
 
 See linkgit:gittutorial[7] to get started, then see
-link:everyday.html[Everyday Git] for a useful minimum set of
-commands.  The link:user-manual.html[Git User's Manual] has a more
+linkgit:giteveryday[Everyday Git] for a useful minimum set of
+commands.  The linkgit:gituser-manual[Git User's Manual] has a more
 in-depth introduction.
 
 After you mastered the basic concepts, you can come back to this
@@ -826,7 +826,7 @@ Discussion[[Discussion]]
 ------------------------
 
 More detail on the following is available from the
-link:user-manual.html#git-concepts[Git concepts chapter of the
+linkgit:gituser-manual#git-concepts[git concepts chapter of the
 user-manual] and linkgit:gitcore-tutorial[7].
 
 A Git project normally consists of a working directory with a ".git"
@@ -882,7 +882,7 @@ See the references in the "description" section to get started
 using Git.  The following is probably more detail than necessary
 for a first-time user.
 
-The link:user-manual.html#git-concepts[Git concepts chapter of the
+The linkgit:gituser-manual#git-concepts[git concepts chapter of the
 user-manual] and linkgit:gitcore-tutorial[7] both provide
 introductions to the underlying Git architecture.
 
@@ -919,9 +919,9 @@ subscribed to the list to send a message there.
 SEE ALSO
 --------
 linkgit:gittutorial[7], linkgit:gittutorial-2[7],
-link:everyday.html[Everyday Git], linkgit:gitcvs-migration[7],
+linkgit:giteveryday[Everyday Git], linkgit:gitcvs-migration[7],
 linkgit:gitglossary[7], linkgit:gitcore-tutorial[7],
-linkgit:gitcli[7], link:user-manual.html[The Git User's Manual],
+linkgit:gitcli[7], linkgit:gituser-manual[The Git User's Manual],
 linkgit:gitworkflows[7]
 
 GIT
-- 
1.8.1.msysgit.1

[PATCH 11/13] Add missing guides to list and regenerate

[Philip Oakley]

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 common-guides.h |  3 +++
 guide-list.txt  | 17 +++++++++--------
 2 files changed, 12 insertions(+), 8 deletions(-)

diff --git a/common-guides.h b/common-guides.h
index a8ad8d1..ae57d75 100644
--- a/common-guides.h
+++ b/common-guides.h
@@ -3,10 +3,13 @@
 
 static struct cmdname_help common_guides[] = {
   {"attributes", "defining attributes per path"},
+  {"everyday", "Everyday GIT With 20 Commands Or So"},
   {"glossary", "A GIT Glossary"},
   {"ignore", "Specifies intentionally untracked files to ignore"},
   {"modules", "defining submodule properties"},
+  {"repository-layout", "Git Repository Layout"},
   {"revisions", "specifying revisions and ranges for git"},
   {"tutorial", "A tutorial introduction to git (for version 1.5.1 or newer)"},
+  {"user-manual", "Git User's Manual (for version 1.5.3 or newer)"},
   {"workflows", "An overview of recommended workflows with git"},
 };
diff --git a/guide-list.txt b/guide-list.txt
index a419ac4..9ba1b5b 100644
--- a/guide-list.txt
+++ b/guide-list.txt
@@ -10,7 +10,7 @@ githooks                                specialist
 gitignore                               concept	 guide
 gitmodules                              concept	 guide
 gitnamespaces                           specialist
-#gitrepository-layout                    reference guide
+gitrepository-layout                    reference guide
 gitrevisions                            concept	 guide
 gittutorial                             user	 guide
 gittutorial-2                           user
@@ -18,12 +18,13 @@ gitweb.conf                             specialist
 gitweb                                  specialist
 gitworkflows                            user	 guide
 
-#giteveryday                             user	 guide
-#gituser-manual                          user	 guide
+giteveryday                             user	 guide
+gituser-manual                          user	 guide
 
-# could embed inside common-cmds.h with [guide] as the second thing,
-# making the sed's in generate-cmdlist.sh more obvious
-# but drop the dash in 's/^git-\
+# Could embed inside common-cmds.h and move generate-guidelist.sh
+# into generate-cmdlist.sh 
 
-#gitrepository-layout is too long for the current char[16]
-#
+# Could also extend generate-guidelist.sh to create a second, complete
+# list of guides should -gg option be applied twice (It's a countup option)
+
+# use './generate-guidelist.sh >common-guides.h' to re-generate.
-- 
1.8.1.msysgit.1

[PATCH 12/13] Documentation/Makefile: update git guide links

[Philip Oakley]

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 Documentation/Makefile | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 62dbd9a..dc759a2 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -23,11 +23,13 @@ MAN7_TXT += gitcore-tutorial.txt
 MAN7_TXT += gitcredentials.txt
 MAN7_TXT += gitcvs-migration.txt
 MAN7_TXT += gitdiffcore.txt
+MAN7_TXT += giteveryday.txt
 MAN7_TXT += gitglossary.txt
 MAN7_TXT += gitnamespaces.txt
 MAN7_TXT += gitrevisions.txt
 MAN7_TXT += gittutorial-2.txt
 MAN7_TXT += gittutorial.txt
+MAN7_TXT += gituser-manual.txt
 MAN7_TXT += gitworkflows.txt
 
 MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
@@ -35,6 +37,8 @@ MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT))
 MAN_HTML=$(patsubst %.txt,%.html,$(MAN_TXT))
 
 OBSOLETE_HTML = git-remote-helpers.html
+OBSOLETE_HTML = everyday.html
+OBSOLETE_HTML = user-manual.html
 DOC_HTML=$(MAN_HTML) $(OBSOLETE_HTML)
 
 ARTICLES = howto-index
-- 
1.8.1.msysgit.1

[PATCH 13/13] Fixup! doc: giteveryday and user-manual man format

[Philip Oakley]

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 Documentation/giteveryday.txt    | 10 ++++++++--
 Documentation/gituser-manual.txt |  7 ++++++-
 2 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/Documentation/giteveryday.txt b/Documentation/giteveryday.txt
index e1fba85..3f11787 100644
--- a/Documentation/giteveryday.txt
+++ b/Documentation/giteveryday.txt
@@ -1,6 +1,12 @@
-Everyday Git With 20 Commands Or So
-===================================
+Everyday-Git(7)
+===============
 
+NAME
+----
+giteveryday - A useful minimum set of commands for Everyday Git 
+
+SYNOPSIS
+--------
 <<Individual Developer (Standalone)>> commands are essential for
 anybody who makes a commit, even for somebody who works alone.
 
diff --git a/Documentation/gituser-manual.txt b/Documentation/gituser-manual.txt
index a4778d7..e991b11 100644
--- a/Documentation/gituser-manual.txt
+++ b/Documentation/gituser-manual.txt
@@ -1,7 +1,12 @@
 Git User's Manual (for version 1.5.3 or newer)
-______________________________________________
+==============================================
 
+NAME
+----
+gituser-manual - User Manual for Git, the stupid content tracker
 
+SYNOPSIS
+--------
 Git is a fast distributed revision control system.
 
 This manual is designed to be readable by someone with basic UNIX
-- 
1.8.1.msysgit.1

Re: [PATCH 01/13] Use 'Git' in help messages

[David Aguilar]

On Sat, Feb 23, 2013 at 3:05 PM, Philip Oakley <philipoakley@iee.org> wrote:
> Signed-off-by: Philip Oakley <philipoakley@iee.org>
> ---
>  help.c | 12 ++++++------
>  1 file changed, 6 insertions(+), 6 deletions(-)
>
> diff --git a/help.c b/help.c
> index 1dfa0b0..1c0e17d 100644
> --- a/help.c
> +++ b/help.c
> @@ -209,14 +209,14 @@ void list_commands(unsigned int colopts,
>  {
>         if (main_cmds->cnt) {
>                 const char *exec_path = git_exec_path();
> -               printf_ln(_("available git commands in '%s'"), exec_path);
> +               printf_ln(_("available Git commands in '%s'"), exec_path);
>                 putchar('\n');
>                 pretty_print_string_list(main_cmds, colopts);
>                 putchar('\n');
>         }
>
>         if (other_cmds->cnt) {
> -               printf_ln(_("git commands available from elsewhere on your $PATH"));
> +               printf_ln(_("Git commands available from elsewhere on your $PATH"));
>                 putchar('\n');
>                 pretty_print_string_list(other_cmds, colopts);
>                 putchar('\n');
> @@ -232,7 +232,7 @@ void list_common_cmds_help(void)
>                         longest = strlen(common_cmds[i].name);
>         }
>
> -       puts(_("The most commonly used git commands are:"));
> +       puts(_("The most commonly used Git commands are:"));
>         for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
>                 printf("   %s   ", common_cmds[i].name);
>                 mput_char(' ', longest - strlen(common_cmds[i].name));
> @@ -289,7 +289,7 @@ static void add_cmd_list(struct cmdnames *cmds, struct cmdnames *old)
>  #define SIMILAR_ENOUGH(x) ((x) < SIMILARITY_FLOOR)
>
>  static const char bad_interpreter_advice[] =
> -       N_("'%s' appears to be a git command, but we were not\n"
> +       N_("'%s' appears to be a Git command, but we were not\n"
>         "able to execute it. Maybe git-%s is broken?");
>
>  const char *help_unknown_cmd(const char *cmd)
> @@ -380,7 +380,7 @@ const char *help_unknown_cmd(const char *cmd)
>                 return assumed;
>         }
>
> -       fprintf_ln(stderr, _("git: '%s' is not a git command. See 'git --help'."), cmd);
> +       fprintf_ln(stderr, _("git: '%s' is not a Git command. See 'git --help'."), cmd);
>
>         if (SIMILAR_ENOUGH(best_similarity)) {
>                 fprintf_ln(stderr,
> @@ -397,6 +397,6 @@ const char *help_unknown_cmd(const char *cmd)
>
>  int cmd_version(int argc, const char **argv, const char *prefix)
>  {
> -       printf("git version %s\n", git_version_string);
> +       printf("Git version %s\n", git_version_string);
>         return 0;
>  }

This is referring to "git the command", not "git the system",
so it should not be changed according to the rule that was
applied when many "git" strings were changed to "Git".

There are scripts, etc. in the wild that parse this output.
which is another reason we would not want to change this.

Does the build system use this output somewhere?

The other strings in this patch mention "git commands" which
the user is expected to type, so it might make sense to leave
them as-is as well.
-- 
David

Re: [PATCH 01/13] Use 'Git' in help messages

[Philip Oakley]

On 23/02/13 23:41, David Aguilar wrote:
> On Sat, Feb 23, 2013 at 3:05 PM, Philip Oakley <philipoakley@iee.org> wrote:
>> Signed-off-by: Philip Oakley <philipoakley@iee.org>
>> ---
>>   help.c | 12 ++++++------
>>   1 file changed, 6 insertions(+), 6 deletions(-)
>>
>> diff --git a/help.c b/help.c
>> index 1dfa0b0..1c0e17d 100644
>> --- a/help.c
>> +++ b/help.c
>> @@ -209,14 +209,14 @@ void list_commands(unsigned int colopts,
>>   {
>>          if (main_cmds->cnt) {
>>                  const char *exec_path = git_exec_path();
>> -               printf_ln(_("available git commands in '%s'"), exec_path);
>> +               printf_ln(_("available Git commands in '%s'"), exec_path);
>>                  putchar('\n');
>>                  pretty_print_string_list(main_cmds, colopts);
>>                  putchar('\n');
>>          }
>>
>>          if (other_cmds->cnt) {
>> -               printf_ln(_("git commands available from elsewhere on your $PATH"));
>> +               printf_ln(_("Git commands available from elsewhere on your $PATH"));
>>                  putchar('\n');
>>                  pretty_print_string_list(other_cmds, colopts);
>>                  putchar('\n');
>> @@ -232,7 +232,7 @@ void list_common_cmds_help(void)
>>                          longest = strlen(common_cmds[i].name);
>>          }
>>
>> -       puts(_("The most commonly used git commands are:"));
>> +       puts(_("The most commonly used Git commands are:"));
>>          for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
>>                  printf("   %s   ", common_cmds[i].name);
>>                  mput_char(' ', longest - strlen(common_cmds[i].name));
>> @@ -289,7 +289,7 @@ static void add_cmd_list(struct cmdnames *cmds, struct cmdnames *old)
>>   #define SIMILAR_ENOUGH(x) ((x) < SIMILARITY_FLOOR)
>>
>>   static const char bad_interpreter_advice[] =
>> -       N_("'%s' appears to be a git command, but we were not\n"
>> +       N_("'%s' appears to be a Git command, but we were not\n"
>>          "able to execute it. Maybe git-%s is broken?");
>>
>>   const char *help_unknown_cmd(const char *cmd)
>> @@ -380,7 +380,7 @@ const char *help_unknown_cmd(const char *cmd)
>>                  return assumed;
>>          }
>>
>> -       fprintf_ln(stderr, _("git: '%s' is not a git command. See 'git --help'."), cmd);
>> +       fprintf_ln(stderr, _("git: '%s' is not a Git command. See 'git --help'."), cmd);
>>
>>          if (SIMILAR_ENOUGH(best_similarity)) {
>>                  fprintf_ln(stderr,
>> @@ -397,6 +397,6 @@ const char *help_unknown_cmd(const char *cmd)
>>
>>   int cmd_version(int argc, const char **argv, const char *prefix)
>>   {
>> -       printf("git version %s\n", git_version_string);
>> +       printf("Git version %s\n", git_version_string);
>>          return 0;
>>   }
>
> This is referring to "git the command", not "git the system",
> so it should not be changed according to the rule that was
> applied when many "git" strings were changed to "Git".

I'd felt that they were referring to 'Git the system', hence the changes.
>
> There are scripts, etc. in the wild that parse this output.

My first pass avoided the 'git --version' response on the basis
that it might be used in the tests or elsewhere, but I didn't
find an occurrence of it's use (in Git), so I thought 'why not'.
However I'm not wedded to it. If the exact phrase 'git version'
is parsed in the wild it then we should let it be.

> which is another reason we would not want to change this.
>
> Does the build system use this output somewhere?
>
> The other strings in this patch mention "git commands" which
> the user is expected to type, so it might make sense to leave
> them as-is as well.
>

Re: [PATCH 01/13] Use 'Git' in help messages

[Junio C Hamano]

David Aguilar <davvid@gmail.com> writes:

> This is referring to "git the command", not "git the system",
> so it should not be changed according to the rule that was
> applied when many "git" strings were changed to "Git".

That sounds like a sensible objection.

> There are scripts, etc. in the wild that parse this output.
> which is another reason we would not want to change this.

Are there?  For what purpose?

Especially when these are all _("l10n ready"), I find that somewhat
unlikely.

The bash completion (in contrib/) does read from the command list
IIRC.  I do not think it relies on the messages, though.

Re: [PATCH 05/13] Help.c: add list_common_guides_help() function

[Junio C Hamano]

Philip Oakley <philipoakley@iee.org> writes:

> diff --git a/common-guides.h b/common-guides.h
> new file mode 100644
> index 0000000..a8ad8d1
> --- /dev/null
> +++ b/common-guides.h
> @@ -0,0 +1,12 @@
> +/* Automatically generated by ./generate-guidelist.sh */
> +/* re-use struct cmdname_help in common-commands.h */

Huh?

Re: [PATCH 02/13] Show 'git help <guide>' usage, with examples

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 365 bytes --]

On Sat, Feb 23, 2013 at 11:05:50PM +0000, Philip Oakley wrote:
> +	   "Examples: 'git help git', 'git help branch', 'git help tutorial'..");

This sentence should end in '.', not '..'.

Cheers,
Trevor

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [PATCH 06/13] Add guide-list.txt and extraction shell

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 782 bytes --]

On Sat, Feb 23, 2013 at 11:05:54PM +0000, Philip Oakley wrote:
> +# Usage: ./generate-guidelist.sh  >>common-guides.h

Following David's recent series, it's probably better to use a
lowercase 'usage' [1].  Also, I'd expect '>common-guides.h' would make
more sense than appending with '>>'.

> +/* re-use struct cmdname_help in common-commands.h */
> +
> +static struct cmdname_help common_guides[] = {"

This is probably just copied from generate-cmdlist.sh, but maybe it
would be a good idea to #include "common-commands.h" here?

Trevor

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

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [PATCH 09/13] Rename everyday to giteveryday

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 947 bytes --]

On Sat, Feb 23, 2013 at 11:05:57PM +0000, Philip Oakley wrote:
> diff --git a/Documentation/everyday.txt b/Documentation/everyday.txt
> index e1fba85..3fc69f6 100644
> --- a/Documentation/everyday.txt
> +++ b/Documentation/everyday.txt
> @@ -1,413 +1,25 @@
> -Everyday Git With 20 Commands Or So
> +Everyday GIT With 20 Commands Or So
>  ===================================

This looks like it's opposing 48a8c26 (Documentation: avoid poor-man's
small caps GIT, 2013-01-21).  Another reason to use 'Git' over 'GIT'
is to match the page we're redirecting to:

> new file mode 100644
> index 0000000..e1fba85
> --- /dev/null
> +++ b/Documentation/giteveryday.txt
> @@ -0,0 +1,413 @@
> +Everyday Git With 20 Commands Or So
> +===================================

Trevor

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [PATCH 12/13] Documentation/Makefile: update git guide links

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 412 bytes --]

On Sat, Feb 23, 2013 at 11:06:00PM +0000, Philip Oakley wrote:
>  OBSOLETE_HTML = git-remote-helpers.html
> +OBSOLETE_HTML = everyday.html
> +OBSOLETE_HTML = user-manual.html
>  DOC_HTML=$(MAN_HTML) $(OBSOLETE_HTML)

Should be '+=' instead of '='.

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [PATCH 13/13] Fixup! doc: giteveryday and user-manual man format

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 830 bytes --]

On Sat, Feb 23, 2013 at 11:06:01PM +0000, Philip Oakley wrote:
> diff --git a/Documentation/gituser-manual.txt b/Documentation/gituser-manual.txt
> index a4778d7..e991b11 100644
> --- a/Documentation/gituser-manual.txt
> +++ b/Documentation/gituser-manual.txt
> @@ -1,7 +1,12 @@
>  Git User's Manual (for version 1.5.3 or newer)
> -______________________________________________
> +==============================================

I'd be happy dropping the parenthetical bit here.  It's hard to
imagine someone still running something earlier than 1.5.3.  It's even
harder to imagine them installing a modern user manual man page for
their old Git version ;).

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [PATCH 01/13] Use 'Git' in help messages

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
Sent: Sunday, February 24, 2013 8:59 AM
> David Aguilar <davvid@gmail.com> writes:
>
>> This is referring to "git the command", not "git the system",
>> so it should not be changed according to the rule that was
>> applied when many "git" strings were changed to "Git".
>
> That sounds like a sensible objection.
>

I'd read the messages in the tone 'commands of the Git system', but I 
can see that both views are equally plausible. Though the final _("git: 
'%s' is not a Git command. See 'git --help'.") can't be referring to a 
'git-<cmd>', obviously ;-)

>> There are scripts, etc. in the wild that parse this output.
>> which is another reason we would not want to change this.
>
> Are there?  For what purpose?
>
> Especially when these are all _("l10n ready"), I find that somewhat
> unlikely.
>
> The bash completion (in contrib/) does read from the command list
> IIRC.  I do not think it relies on the messages, though.

I was aware of that bash completion used 'git help -a' so I avoided 
changing the response to that option. Initially I'd thought of making 
'-a' provide both commands and guides but knew I'd need to ensure the 
completion would still be sensible. I'd taken Juio's earlier advice to 
keep '-a' unchanged and simply add the -g|--guides option as a 
supplemental 'git help' response..

Philip 

Re: [PATCH 05/13] Help.c: add list_common_guides_help() function

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
Sent: Sunday, February 24, 2013 9:01 AM
> Philip Oakley <philipoakley@iee.org> writes:
>
>> diff --git a/common-guides.h b/common-guides.h
>> new file mode 100644
>> index 0000000..a8ad8d1
>> --- /dev/null
>> +++ b/common-guides.h
>> @@ -0,0 +1,12 @@
>> +/* Automatically generated by ./generate-guidelist.sh */
>> +/* re-use struct cmdname_help in common-commands.h */
>
> Huh?
The first comment line fortells of patch 6 which can generate this .h 
file.
The second comment line notes that I re-use cmdname_help, rather than 
creating another struct with a similar name.

I should probably have noted these points in the commit message. (or 
waited until patch 6 to add the comment).

Philip 

Re: [PATCH 02/13] Show 'git help <guide>' usage, with examples

[Philip Oakley]

On 24/02/13 14:39, W. Trevor King wrote:
> On Sat, Feb 23, 2013 at 11:05:50PM +0000, Philip Oakley wrote:
>> +	   "Examples: 'git help git', 'git help branch', 'git help tutorial'..");
>
> This sentence should end in '.', not '..'.
>
> Cheers,
> Trevor
>
I should have used three as ellipsis ... to suggest 'more', which was my 
intent, but ended up neither here, nor there.
Philip

Re: [PATCH 01/13] Use 'Git' in help messages

[David Aguilar]

On Sun, Feb 24, 2013 at 12:59 AM, Junio C Hamano <gitster@pobox.com> wrote:
> David Aguilar <davvid@gmail.com> writes:
>
>> This is referring to "git the command", not "git the system",
>> so it should not be changed according to the rule that was
>> applied when many "git" strings were changed to "Git".
>
> That sounds like a sensible objection.
>
>> There are scripts, etc. in the wild that parse this output.
>> which is another reason we would not want to change this.
>
> Are there?  For what purpose?
>
> Especially when these are all _("l10n ready"), I find that somewhat
> unlikely.

A script might conditionally use new git behavior and parse the
output of "git version" to determine whether or not it can use it.
oh-my-zsh does this, for example [*].

Changing the git to Git is probably fine for some scripts that
do something interesting based on the git version since they
might be doing something simple like splitting the string on
whitespace and taking the last element as the version number.

These won't be broken by this change, but this approach is
already broken for a different reason. Apple's build of git
prints "git version 1.7.12.4 (Apple Git-37)" so they would
need to account for the last parens section optionally
being there.  Changing "git" to "Git" only breaks anyone that
has assumed that they could get the version by doing
s/git version// on the string.

I think being able to find the version at runtime is something
that is typically used by packagers and folks that want to be
portable across git versions.  For these, it would be helpful
to have a consistent and stable output that can be easily parsed.

By deciding to not mark these l10n ready and keeping the output
consistent we could help that use case.

[*] I'm not saying this is a good idea or something that scripts
should do, I'm just pointing out that it is done in practice,
so it is worth considering their use cases.
-- 
David

Re: [PATCH 06/13] Add guide-list.txt and extraction shell

[Philip Oakley]

On 24/02/13 14:51, W. Trevor King wrote:
> On Sat, Feb 23, 2013 at 11:05:54PM +0000, Philip Oakley wrote:
>> +# Usage: ./generate-guidelist.sh  >>common-guides.h
>
> Following David's recent series, it's probably better to use a
> lowercase 'usage' [1].
I prefer the Initial capital version to suggest the start of a sentence, 
but I can go with either way.

>                     Also, I'd expect '>common-guides.h' would make
> more sense than appending with '>>'.

My mistake. Will correct.

>
>> +/* re-use struct cmdname_help in common-commands.h */
>> +
>> +static struct cmdname_help common_guides[] = {"
>
> This is probably just copied from generate-cmdlist.sh, but maybe it
> would be a good idea to #include "common-commands.h" here?

I was trying to avoid nested includes. Eventually, if the series is 
accepted, I'd want to refactor the guide generation into the existing 
command generation so that .h file would then disappear.
>
> Trevor
>
> [1]: http://article.gmane.org/gmane.comp.version-control.git/216961
>
Philip

Re: [PATCH 09/13] Rename everyday to giteveryday

[Philip Oakley]

On 24/02/13 14:55, W. Trevor King wrote:
> On Sat, Feb 23, 2013 at 11:05:57PM +0000, Philip Oakley wrote:
>> diff --git a/Documentation/everyday.txt b/Documentation/everyday.txt
>> index e1fba85..3fc69f6 100644
>> --- a/Documentation/everyday.txt
>> +++ b/Documentation/everyday.txt
>> @@ -1,413 +1,25 @@
>> -Everyday Git With 20 Commands Or So
>> +Everyday GIT With 20 Commands Or So
>>   ===================================
>
> This looks like it's opposing 48a8c26 (Documentation: avoid poor-man's
> small caps GIT, 2013-01-21).  Another reason to use 'Git' over 'GIT'
> is to match the page we're redirecting to:

My mistake. When I was separating out the changes into separate patches 
I incorrectly restored/copied an old version of the title.

Will correct.

>
>> new file mode 100644
>> index 0000000..e1fba85
>> --- /dev/null
>> +++ b/Documentation/giteveryday.txt
>> @@ -0,0 +1,413 @@
>> +Everyday Git With 20 Commands Or So
>> +===================================
>
> Trevor
>
Philip

Re: [PATCH 12/13] Documentation/Makefile: update git guide links

[Philip Oakley]

On 24/02/13 14:58, W. Trevor King wrote:
> On Sat, Feb 23, 2013 at 11:06:00PM +0000, Philip Oakley wrote:
>>   OBSOLETE_HTML = git-remote-helpers.html
>> +OBSOLETE_HTML = everyday.html
>> +OBSOLETE_HTML = user-manual.html
>>   DOC_HTML=$(MAN_HTML) $(OBSOLETE_HTML)
>
> Should be '+=' instead of '='.
>
Well spotted. That maybe part of why my make of the documentation failed.

Though the 'new' giteveryday gituser-manual don't build as man pages, so 
I may simply leave them with their old make process - If I understand 
correctly they are in the right place and just need the 'git' prefix.

However I'm biased by my Msysgit/G4W experience which always assumes 
--web and fires up the HTML version so there may be issues with the 
plain .txt version attempting to be displayed as a man page if it 
doesn't follow the format. (my linux laptop was a repair of a 'scrapper')

Philip

Re: [PATCH 13/13] Fixup! doc: giteveryday and user-manual man format

[Philip Oakley]

On 24/02/13 15:01, W. Trevor King wrote:
> On Sat, Feb 23, 2013 at 11:06:01PM +0000, Philip Oakley wrote:
>> diff --git a/Documentation/gituser-manual.txt b/Documentation/gituser-manual.txt
>> index a4778d7..e991b11 100644
>> --- a/Documentation/gituser-manual.txt
>> +++ b/Documentation/gituser-manual.txt
>> @@ -1,7 +1,12 @@
>>   Git User's Manual (for version 1.5.3 or newer)
>> -______________________________________________
>> +==============================================
>
> I'd be happy dropping the parenthetical bit here.  It's hard to
> imagine someone still running something earlier than 1.5.3.  It's even
> harder to imagine them installing a modern user manual man page for
> their old Git version ;).
>
Sensible. Will do.

Philip

Re: [PATCH 05/13] Help.c: add list_common_guides_help() function

[Junio C Hamano]

"Philip Oakley" <philipoakley@iee.org> writes:

> From: "Junio C Hamano" <gitster@pobox.com>
> Sent: Sunday, February 24, 2013 9:01 AM
>> Philip Oakley <philipoakley@iee.org> writes:
>>
>>> diff --git a/common-guides.h b/common-guides.h
>>> new file mode 100644
>>> index 0000000..a8ad8d1
>>> --- /dev/null
>>> +++ b/common-guides.h
>>> @@ -0,0 +1,12 @@
>>> +/* Automatically generated by ./generate-guidelist.sh */
>>> +/* re-use struct cmdname_help in common-commands.h */
>>
>> Huh?
> The first comment line fortells of patch 6 which can generate this .h
> file.

The Huh? was about that one, not about reuse.  I do not want to see
a build artifact kept in the history without a good reason.

Re: [PATCH 12/13] Documentation/Makefile: update git guide links

[Junio C Hamano]

Philip Oakley <philipoakley@iee.org> writes:

> @@ -35,6 +37,8 @@ MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT))
>  MAN_HTML=$(patsubst %.txt,%.html,$(MAN_TXT))
>  
>  OBSOLETE_HTML = git-remote-helpers.html
> +OBSOLETE_HTML = everyday.html
> +OBSOLETE_HTML = user-manual.html
>  DOC_HTML=$(MAN_HTML) $(OBSOLETE_HTML)

If you are keeping track of inventory of "guides" in a new static
array, do you still need to look up "giteveryday" or "gituser-manual"
when the user asks for guide documents?

In other words, can't you change the side that launches the document
viewer so that we do not have to rename anything in the first place?

Re: [PATCH 12/13] Documentation/Makefile: update git guide links

[Philip Oakley]

On 25/02/13 05:29, Junio C Hamano wrote:
> Philip Oakley <philipoakley@iee.org> writes:
>
>> @@ -35,6 +37,8 @@ MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT))
>>   MAN_HTML=$(patsubst %.txt,%.html,$(MAN_TXT))
>>
>>   OBSOLETE_HTML = git-remote-helpers.html
>> +OBSOLETE_HTML = everyday.html
>> +OBSOLETE_HTML = user-manual.html
>>   DOC_HTML=$(MAN_HTML) $(OBSOLETE_HTML)
>
> If you are keeping track of inventory of "guides" in a new static
> array, do you still need to look up "giteveryday" or "gituser-manual"
> when the user asks for guide documents?

I'm only keeping track in the new static array of the 'common guides' 
and I'd hoped that these two could be included.
>
> In other words, can't you change the side that launches the document
> viewer so that we do not have to rename anything in the first place?
>

The current help code will only show either 'git-<cmd>' man pages, or 
'git<guide>' pages so the current everyday and user-manual pages aren't 
served by the existing help code.
	$ git help everyday
	No manual entry for giteveryday
Hence the need for the rename and 'obsolete page' entries.

I'm guessing that serving any old .txt or .html page from the 
Documentation directories isn't sensible (rather than being prefix 
based), but it is a possibility.

Philip

Re: [PATCH 05/13] Help.c: add list_common_guides_help() function

[Philip Oakley]

On 25/02/13 05:24, Junio C Hamano wrote:
> "Philip Oakley" <philipoakley@iee.org> writes:
>
>> From: "Junio C Hamano" <gitster@pobox.com>
>> Sent: Sunday, February 24, 2013 9:01 AM
>>> Philip Oakley <philipoakley@iee.org> writes:
>>>
>>>> diff --git a/common-guides.h b/common-guides.h
>>>> new file mode 100644
>>>> index 0000000..a8ad8d1
>>>> --- /dev/null
>>>> +++ b/common-guides.h
>>>> @@ -0,0 +1,12 @@
>>>> +/* Automatically generated by ./generate-guidelist.sh */
>>>> +/* re-use struct cmdname_help in common-commands.h */
>>>
>>> Huh?
>> The first comment line fortells of patch 6 which can generate this .h
>> file.
>
> The Huh? was about that one, not about reuse.  I do not want to see
> a build artifact kept in the history without a good reason.
>
I'd copied it from generate-cmdlist.sh which is a common-cmd.h 
dependency and was introduced by

commit a87cd02ce02e97083eb76eb8b9bfeb2e46800fd7
Author: Fredrik Kuivinen <freku045@student.liu.se>
Date:   Thu Mar 9 17:24:19 2006 +0100

     Nicer output from 'git'

     [jc: with suggestions by Jan-Benedict Glaw]

     Signed-off-by: Fredrik Kuivinen <freku045@student.liu.se>
     Signed-off-by: Junio C Hamano <junkio@cox.net>

The reason in this (my) case, as then, is that it states how the file is 
generated so that it can be regenerated later. If the patches are 
successful then I'd want the generate-guidelist and generate-cmdlist to 
be joined together as an integral part of generating the help system data.

Mind you each review point turns over another stone that needs to be 
considered, such as the Makefile link of common-commands.h and similarly 
for the Documentation/Makefile - I'm thinking of the issues around 
'gitk' and its ilk which isn't a common command (because it has no 
hyphen) yet is in the command list, so can be confused with the support 
documentation, however I don't mark it as a common guide, so that's OK. 
('git help k' does offer the gitk man page ;-)

I'll tidy up the series over the next few days to include the points so far

Philip

Re: [PATCH 05/13] Help.c: add list_common_guides_help() function

[Junio C Hamano]

Philip Oakley <philipoakley@iee.org> writes:

>>> The first comment line fortells of patch 6 which can generate this .h
>>> file.
>>
>> The Huh? was about that one, not about reuse.  I do not want to see
>> a build artifact kept in the history without a good reason.
>>
> I'd copied it from generate-cmdlist.sh which is a common-cmd.h
> dependency and was introduced by
>
> commit a87cd02ce02e97083eb76eb8b9bfeb2e46800fd7
> Author: Fredrik Kuivinen <freku045@student.liu.se>
> Date:   Thu Mar 9 17:24:19 2006 +0100
>
>     Nicer output from 'git'
>
>     [jc: with suggestions by Jan-Benedict Glaw]
>
>     Signed-off-by: Fredrik Kuivinen <freku045@student.liu.se>
>     Signed-off-by: Junio C Hamano <junkio@cox.net>

Looking at the change again, I do not see us adding a build artifact
(in the case of that patch, common-cmd.h) to our history.  Only the
recipe to generate that file exists there, which is the right thing
to do.

Why do we want common-guides.h which is clearly marked as "A
generated file" at its top in our history?  That was what made me
say "Huh?".

Re: [PATCH 12/13] Documentation/Makefile: update git guide links

[Junio C Hamano]

Philip Oakley <philipoakley@iee.org> writes:

> On 25/02/13 05:29, Junio C Hamano wrote:
> ...
>> In other words, can't you change the side that launches the document
>> viewer so that we do not have to rename anything in the first place?
>
> The current help code will only show either 'git-<cmd>' man pages, or
> git<guide>' pages so the current everyday and user-manual pages aren't
> served by the existing help code.

That is exactly what I meant by "the side that launches the document
viewer".  We obviously would not want to type

	$ git help gituser-manual
        $ git help giteveryday

I was wondering if you can keep document names as-is, register these
names without "git" prefix (i.e. "user-manual.html") to the list of
guide documents you are generating and compiling into the binary,
and let the user ask:

	$ git help everyday

which you would turn into "browser %s/%s.html" % (GIT_HTML_PATH, 'everyday'),
after checking "everyday" is one of the guides that are available to us.

If some guides are already named with git prefix, you can keep them
in the compiled-in list with that name.  We do not have to worry
about redirects and people's bookmarks if we can avoid renaming
existing pages, so "because grabbing everything with git* glob was
easier to write the generate-guidelist script" is a false economy.
That is the single place we can afford to spend extra effort to make
the end result easier to use by the users, no?

Or am I misreading the series completely?

Re: [PATCH 12/13] Documentation/Makefile: update git guide links

[Philip Oakley]

On 26/02/13 00:04, Junio C Hamano wrote:
> Philip Oakley <philipoakley@iee.org> writes:
>
>> On 25/02/13 05:29, Junio C Hamano wrote:
>> ...
>>> In other words, can't you change the side that launches the document
>>> viewer so that we do not have to rename anything in the first place?
>>
>> The current help code will only show either 'git-<cmd>' man pages, or
>> git<guide>' pages so the current everyday and user-manual pages aren't
>> served by the existing help code.
>
> That is exactly what I meant by "the side that launches the document
> viewer".  We obviously would not want to type
>
> 	$ git help gituser-manual
>          $ git help giteveryday
Neither do I...

>
> I was wondering if you can keep document names as-is, register these
> names without "git" prefix (i.e. "user-manual.html")

I don't register them at all. I'm simply gathering a list of common 
guides in the array so that I can show that list as a 'usage' list, in 
exactly the same manner as the common commands list is used when 'git 
help' [ no options] is typed.

>   to the list of
> guide documents you are generating and compiling into the binary,
> and let the user ask:
>
> 	$ git help everyday

This is the existing way.
'git help tutorial' will display the gittutorial.txt man page - Note the 
git prefix is required by the code.

It is interesting to note that 'git help k' and 'git help gitk' produce 
the same response, while gitk can't be a common-command because it 
doesn't have a dashed form so isn't picked up by the script ;-)

>
> which you would turn into "browser %s/%s.html" % (GIT_HTML_PATH, 'everyday'),
> after checking "everyday" is one of the guides that are available to us.
>
> If some guides are already named with git prefix, you can keep them
> in the compiled-in list with that name.  We do not have to worry
> about redirects and people's bookmarks if we can avoid renaming
> existing pages, so "because grabbing everything with git* glob was
> easier to write the generate-guidelist script" is a false economy.

I was hoping to avoid more special casing of special files for special 
purposes..
> That is the single place we can afford to spend extra effort to make
> the end result easier to use by the users, no?
It could be done.

>
> Or am I misreading the series completely?
Yes, I think so (in terms of my starting point and approach).

I was using the existing common-commands approach _just_ to display a 
'usage' string of common guides. so that new users would be informed of 
their presence, and then they would use the existing command 'git help 
<guide>' to read about it (see also patch 2/13).

It was just unfortunate that the user-manual and everyday didn't fit the 
existing naming pattern causing the writing of patch 8 & 9 et seq to 
sort the renames to fit the pattern (just like git-remote-helpers)

Also, I think it's the user-manual, one of the files doesn't fit the 
'man page' style required by the MAN7 list in Documentation/Makefile, so 
that's another potential complication I need to bottom out - most likely 
keep it 'as is' in the Makefile and check that the Help command will 
display it properly if done that way.

Philip