[PATCH] Stop telling users we are 'defaulting to local storage area'.

[PATCH] Stop telling users we are 'defaulting to local storage area'.

[Shawn O. Pearce]

Back in the old days of Git when people messed around with their
GIT_DIR environment variable more often it was nice to know whether
or not git-init-db created a .git directory or used GIT_DIR.

But now that we are making excuses in the documentation about why
this message gets printed by git-init-db we should just remove it
entirely.  It doesn't really help the user to understand what just
happened.  It also breaks from our normal behavior of not printing
anything if the command was successful.

Suggested by Andy Parkins in his Git 'niggles' list
(<200612132237.10051.andyparkins@gmail.com>).

Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
---
 Documentation/core-tutorial.txt |   14 +++-----------
 Documentation/tutorial-2.txt    |    1 -
 Documentation/tutorial.txt      |    6 ------
 builtin-init-db.c               |    4 +---
 4 files changed, 4 insertions(+), 21 deletions(-)

diff --git a/Documentation/core-tutorial.txt b/Documentation/core-tutorial.txt
index 47505aa..f90c66c 100644
--- a/Documentation/core-tutorial.txt
+++ b/Documentation/core-tutorial.txt
@@ -54,17 +54,9 @@ $ cd git-tutorial
 $ git-init-db
 ------------------------------------------------
 
-to which git will reply
-
-----------------
-defaulting to local storage area
-----------------
-
-which is just git's way of saying that you haven't been doing anything
-strange, and that it will have created a local `.git` directory setup for
-your new project. You will now have a `.git` directory, and you can
-inspect that with `ls`. For your new empty project, it should show you
-three entries, among other things:
+You will now have a `.git` directory, and you can inspect that with
+`ls`. For your new empty project, it should show you three entries,
+among other things:
 
  - a file called `HEAD`, that has `ref: refs/heads/master` in it.
    This is similar to a symbolic link and points at
diff --git a/Documentation/tutorial-2.txt b/Documentation/tutorial-2.txt
index 6389de5..f7f2e1c 100644
--- a/Documentation/tutorial-2.txt
+++ b/Documentation/tutorial-2.txt
@@ -18,7 +18,6 @@ Let's start a new project and create a small amount of history:
 $ mkdir test-project
 $ cd test-project
 $ git init-db
-defaulting to local storage area
 $ echo 'hello world' > file.txt
 $ git add .
 $ git commit -a -m "initial commit"
diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt
index 02dede3..88ace3b 100644
--- a/Documentation/tutorial.txt
+++ b/Documentation/tutorial.txt
@@ -35,12 +35,6 @@ $ cd project
 $ git init-db
 ------------------------------------------------
 
-Git will reply
-
-------------------------------------------------
-defaulting to local storage area
-------------------------------------------------
-
 You've now initialized the working directory--you may notice a new
 directory created, named ".git".  Tell git that you want it to track
 every file under the current directory with (notice the dot '.'
diff --git a/builtin-init-db.c b/builtin-init-db.c
index 235a0ee..405b9a1 100644
--- a/builtin-init-db.c
+++ b/builtin-init-db.c
@@ -274,10 +274,8 @@ int cmd_init_db(int argc, const char **argv, const char *prefix)
 	 * Set up the default .git directory contents
 	 */
 	git_dir = getenv(GIT_DIR_ENVIRONMENT);
-	if (!git_dir) {
+	if (!git_dir)
 		git_dir = DEFAULT_GIT_DIR_ENVIRONMENT;
-		fprintf(stderr, "defaulting to local storage area\n");
-	}
 	safe_create_dir(git_dir, 0);
 
 	/* Check to see if the repository version is right.
-- 

Re: [PATCH] Stop telling users we are 'defaulting to local storage area'.

[Nicolas Pitre]

On Thu, 14 Dec 2006, Shawn O. Pearce wrote:

[...]
> It also breaks from our normal behavior of not printing
> anything if the command was successful.

Before everybody starts believing  everybody agrees with this I'll have 
to throw a tile in the pond.

I really don't think this is a good rule.

NOte that I'm not against commands that are silent by default.  I really 
think that git-add should remain silent on success by default when 
successful.

But the rule of thumb should be about the importance of the action 
performed by the command.  git-add is a less important command than 
git-init-db or git-commit _conceptually_.  You can do multiple git-add 
in whatever order, even repeatedly, and it won't change the outcome.  
It is "conceptually lightweight".  But git-init-db is really important.  
Without it you just can't do anything. It should give the user the 
impression that something did actually happen, especially since this is 
the git comand any new git user is most likely to use first.  Saying 
back "git repository initialized" tells the user "OK you can start now".  
Saying nothing might just leave the user wondering if everything is 
actually fine.

Re: [PATCH] Stop telling users we are 'defaulting to local storage area'.

[Shawn Pearce]

Nicolas Pitre <nico@cam.org> wrote:
> On Thu, 14 Dec 2006, Shawn O. Pearce wrote:
> > It also breaks from our normal behavior of not printing
> > anything if the command was successful.

> I really don't think this is a good rule.
> 
> NOte that I'm not against commands that are silent by default.  I really 
> think that git-add should remain silent on success by default when 
> successful.
> 
> But the rule of thumb should be about the importance of the action 
> performed by the command.
> But git-init-db is really important.  

A very reasonable argument, butchered for my evil quoting needs.  :-)

If we want to keep letting git-init-db output something, then
the output should be a lot more meaningful to the average English
speaking new Git user than "defaulting to local storage area".

E.g.:

  $ git init-db
  Initialized empty Git repository in .git/

would probably make a lot more sense to new and expert users alike.
I'm fine with the above form, I just think that the message we have
now could benefit from being sent to the land from which there is
no return, or be rewritten...

BTW, I almost also submitted a patch to remove the "Committing
initial tree ..." message in git-commit-tree, but thought twice about
it as committing an initial tree is sort of an important difference
from normal activity that we should highlight it somehow...

-- 

Re: [PATCH] Stop telling users we are 'defaulting to local storage area'.

[Nicolas Pitre]

On Thu, 14 Dec 2006, Shawn Pearce wrote:

> Nicolas Pitre <nico@cam.org> wrote:
> > On Thu, 14 Dec 2006, Shawn O. Pearce wrote:
> > > It also breaks from our normal behavior of not printing
> > > anything if the command was successful.
> 
> > I really don't think this is a good rule.
> > 
> > NOte that I'm not against commands that are silent by default.  I really 
> > think that git-add should remain silent on success by default when 
> > successful.
> > 
> > But the rule of thumb should be about the importance of the action 
> > performed by the command.
> > But git-init-db is really important.  
> 
> A very reasonable argument, butchered for my evil quoting needs.  :-)
> 
> If we want to keep letting git-init-db output something, then
> the output should be a lot more meaningful to the average English
> speaking new Git user than "defaulting to local storage area".

Absolutely!

> BTW, I almost also submitted a patch to remove the "Committing
> initial tree ..." message in git-commit-tree, but thought twice about
> it as committing an initial tree is sort of an important difference
> from normal activity that we should highlight it somehow...

Please ignore that one.  I'm working on a patch to handle the commit 
case (need to update the tutorial accordingly).

[PATCH] Provide more meaningful output from 'git init-db'.

[Shawn O. Pearce]

Back in the old days of Git when people messed around with their
GIT_DIR environment variable more often it was nice to know whether
or not git-init-db created a .git directory or used GIT_DIR.
As most users at that time were rather technical UNIXy folk the
message "defaulting to local storage area" made sense to some and
seemed reasonable.

But it doesn't really convey any meaning to the new Git user,
as they don't know what a 'local storage area is' nor do they
know enough about Git to care.  It also really doesn't tell the
experienced Git user a whole lot about the command they just ran,
especially if they might be reinitializing an existing repository
(e.g. to update hooks).

So now we print out what we did ("Initialized empty" or
"Reinitialized existing"), what type of repository ("" or "shared"),
and what location the repository will be in ("$GIT_DIR").

Suggested in part by Andy Parkins in his Git 'niggles' list
(<200612132237.10051.andyparkins@gmail.com>).

Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
---
 Documentation/core-tutorial.txt |    2 +-
 Documentation/tutorial-2.txt    |    2 +-
 Documentation/tutorial.txt      |    2 +-
 builtin-init-db.c               |   21 ++++++++++++++-------
 4 files changed, 17 insertions(+), 10 deletions(-)

diff --git a/Documentation/core-tutorial.txt b/Documentation/core-tutorial.txt
index 47505aa..abe74a7 100644
--- a/Documentation/core-tutorial.txt
+++ b/Documentation/core-tutorial.txt
@@ -57,7 +57,7 @@ $ git-init-db
 to which git will reply
 
 ----------------
-defaulting to local storage area
+Initialized empty Git repository in .git/
 ----------------
 
 which is just git's way of saying that you haven't been doing anything
diff --git a/Documentation/tutorial-2.txt b/Documentation/tutorial-2.txt
index 6389de5..7a692d7 100644
--- a/Documentation/tutorial-2.txt
+++ b/Documentation/tutorial-2.txt
@@ -18,7 +18,7 @@ Let's start a new project and create a small amount of history:
 $ mkdir test-project
 $ cd test-project
 $ git init-db
-defaulting to local storage area
+Initialized empty Git repository in .git/
 $ echo 'hello world' > file.txt
 $ git add .
 $ git commit -a -m "initial commit"
diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt
index 02dede3..cb808d9 100644
--- a/Documentation/tutorial.txt
+++ b/Documentation/tutorial.txt
@@ -38,7 +38,7 @@ $ git init-db
 Git will reply
 
 ------------------------------------------------
-defaulting to local storage area
+Initialized empty Git repository in .git/
 ------------------------------------------------
 
 You've now initialized the working directory--you may notice a new
diff --git a/builtin-init-db.c b/builtin-init-db.c
index 235a0ee..8f2b750 100644
--- a/builtin-init-db.c
+++ b/builtin-init-db.c
@@ -164,13 +164,14 @@ static void copy_templates(const char *git_dir, int len, const char *template_di
 	closedir(dir);
 }
 
-static void create_default_files(const char *git_dir, const char *template_path)
+static int create_default_files(const char *git_dir, const char *template_path)
 {
 	unsigned len = strlen(git_dir);
 	static char path[PATH_MAX];
 	unsigned char sha1[20];
 	struct stat st1;
 	char repo_version_string[10];
+	int reinit;
 
 	if (len > sizeof(path)-50)
 		die("insane git directory %s", git_dir);
@@ -218,7 +219,8 @@ static void create_default_files(const char *git_dir, const char *template_path)
 	 * branch, if it does not exist yet.
 	 */
 	strcpy(path + len, "HEAD");
-	if (read_ref("HEAD", sha1) < 0) {
+	reinit = !read_ref("HEAD", sha1);
+	if (!reinit) {
 		if (create_symref("HEAD", "refs/heads/master") < 0)
 			exit(1);
 	}
@@ -239,6 +241,8 @@ static void create_default_files(const char *git_dir, const char *template_path)
 		git_config_set("core.filemode",
 			       filemode ? "true" : "false");
 	}
+
+	return reinit;
 }
 
 static const char init_db_usage[] =
@@ -256,7 +260,7 @@ int cmd_init_db(int argc, const char **argv, const char *prefix)
 	const char *sha1_dir;
 	const char *template_dir = NULL;
 	char *path;
-	int len, i;
+	int len, i, reinit;
 
 	for (i = 1; i < argc; i++, argv++) {
 		const char *arg = argv[1];
@@ -274,10 +278,8 @@ int cmd_init_db(int argc, const char **argv, const char *prefix)
 	 * Set up the default .git directory contents
 	 */
 	git_dir = getenv(GIT_DIR_ENVIRONMENT);
-	if (!git_dir) {
+	if (!git_dir)
 		git_dir = DEFAULT_GIT_DIR_ENVIRONMENT;
-		fprintf(stderr, "defaulting to local storage area\n");
-	}
 	safe_create_dir(git_dir, 0);
 
 	/* Check to see if the repository version is right.
@@ -287,7 +289,7 @@ int cmd_init_db(int argc, const char **argv, const char *prefix)
 	 */
 	check_repository_format();
 
-	create_default_files(git_dir, template_dir);
+	reinit = create_default_files(git_dir, template_dir);
 
 	/*
 	 * And set up the object store.
@@ -314,5 +316,10 @@ int cmd_init_db(int argc, const char **argv, const char *prefix)
 		git_config_set("receive.denyNonFastforwards", "true");
 	}
 
+	printf("%s%s Git repository in %s/\n",
+		reinit ? "Reinitialized existing" : "Initialized empty",
+		shared_repository ? " shared" : "",
+		git_dir);
+
 	return 0;
 }
-- 

Re: [PATCH] Stop telling users we are 'defaulting to local storage area'.

[Jakub Narebski]

Shawn O. Pearce wrote:

> Back in the old days of Git when people messed around with their
> GIT_DIR environment variable more often it was nice to know whether
> or not git-init-db created a .git directory or used GIT_DIR.
> 
> But now that we are making excuses in the documentation about why
> this message gets printed by git-init-db we should just remove it
> entirely.  It doesn't really help the user to understand what just
> happened.  It also breaks from our normal behavior of not printing
> anything if the command was successful.
> 
> Suggested by Andy Parkins in his Git 'niggles' list
> (<200612132237.10051.andyparkins@gmail.com>).

Perhaps we should print something _if_ GIT_DIR is set, then?

>        * Set up the default .git directory contents
>        */
>       git_dir = getenv(GIT_DIR_ENVIRONMENT);
> -     if (!git_dir) {
> +     if (!git_dir)
>               git_dir = DEFAULT_GIT_DIR_ENVIRONMENT;
> -             fprintf(stderr, "defaulting to local storage area\n");
> -     }
>       safe_create_dir(git_dir, 0);
>  

I'd rather leave block, even if it consist now of single statement.

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [PATCH] Provide more meaningful output from 'git init-db'.

[Jakub Narebski]

Shawn O. Pearce wrote:

> So now we print out what we did ("Initialized empty" or
> "Reinitialized existing"), what type of repository ("" or "shared"),
> and what location the repository will be in ("$GIT_DIR").

>  ----------------
> -defaulting to local storage area
> +Initialized empty Git repository in .git/
>  ----------------

> +     printf("%s%s Git repository in %s/\n",
> +             reinit ? "Reinitialized existing" : "Initialized empty",
> +             shared_repository ? " shared" : "",
> +             git_dir);

It seems like this lack this " in " part you have mentioned in
commit message and in tutorial.

+1. Very nice. Making git more newbie-friendly.
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [PATCH] Provide more meaningful output from 'git init-db'.

[Shawn Pearce]

Jakub Narebski <jnareb@gmail.com> wrote:
> Shawn O. Pearce wrote:
> 
> > So now we print out what we did ("Initialized empty" or
> > "Reinitialized existing"), what type of repository ("" or "shared"),
> > and what location the repository will be in ("$GIT_DIR").
> 
> >  ----------------
> > -defaulting to local storage area
> > +Initialized empty Git repository in .git/
> >  ----------------
> 
> > +     printf("%s%s Git repository in %s/\n",

-------------------------------------^^^^

> It seems like this lack this " in " part you have mentioned in
> commit message and in tutorial.

Uh, no it doesn't.  See above.

-- 

Re: [PATCH] Stop telling users we are 'defaulting to local storagearea'.

[David Lang]

On Thu, 14 Dec 2006, Nicolas Pitre wrote:

> On Thu, 14 Dec 2006, Shawn O. Pearce wrote:
>
> [...]
>> It also breaks from our normal behavior of not printing
>> anything if the command was successful.
>
> Before everybody starts believing  everybody agrees with this I'll have
> to throw a tile in the pond.
>
> I really don't think this is a good rule.
>
> NOte that I'm not against commands that are silent by default.  I really
> think that git-add should remain silent on success by default when
> successful.
>
> But the rule of thumb should be about the importance of the action
> performed by the command.  git-add is a less important command than
> git-init-db or git-commit _conceptually_.  You can do multiple git-add
> in whatever order, even repeatedly, and it won't change the outcome.
> It is "conceptually lightweight".  But git-init-db is really important.
> Without it you just can't do anything. It should give the user the
> impression that something did actually happen, especially since this is
> the git comand any new git user is most likely to use first.  Saying
> back "git repository initialized" tells the user "OK you can start now".
> Saying nothing might just leave the user wondering if everything is
> actually fine.

how about makeing it silent on sucess unless the output is a tty? that way you 
don't mess up scripts with the 'it worked' message and you still reassure the 
user that something actually happened.

David Lang