threads / discuss / 43506

Re: Hyphens and hiding core commands

Subject: Re: Hyphens and hiding core commands

## tl;dr

3 messages between Nov 28, 2006 and Nov 29, 2006.

replies: 2people: 3as markdown or json

Theodore Tso· Nov 28, 2006, 05:40 UTC · lore
On Mon, Nov 27, 2006 at 06:18:54PM -0800, Junio C Hamano wrote:
> Read what I wrote again.  You can explain it without talking
> about index at all.  I really do not think you need to break
> "git commit" nor rename "update-index" to "resolve" to explain
> things to new people.

I think you're both right, and talking past each other to a certain extent. Yes, pedagogically it would be better to talk about "git commit Makefile hello.c ..."; and "git commit -a" as a short-cut to not have to list all of the files explicitly.

Show 6 quoted lines
> The tutorial might be better reworked not to start talking about
> -a but start building small project from a newly created
> hello.c, git add it, and "git commit" (the first commit), then
> edit hello.c and "git commit hello.c" (the second commit).
> 
> Perhaps.

Carl was saying that the totorial should be changed to do this. I would change "perhaps" to "DEFINITELY".

I would go further and argue that the man page for git-commit should be changed to list the:

	git commit file ...
and
	git -a

alternatives first, and then talk about the index in a subsequent paragraph (perhaps with a note that the first two usages are best for novice users) might also be a good idea. Yes, the man page is supposed to be a reference, but some novice users do bother to try to learn by reading the man page (shock! horror!), and it might be good if they don't run screaming into the night.

But hey, there's room for many distributed SCM's, and we can always let those users use Mercurial and be happy.... (Just know that project leaders who are worried about keeping their developer base broad might choose Mercurial because it has a gentler learning curve --- and that perhaps a few simple documentation changes plus some syntatic sugar might make git much more attractive to them and to novice git users.)

Junio C Hamano· Nov 28, 2006, 09:15 UTC · re: Theodore Tso · lore
Theodore Tso <tytso@mit.edu> writes:
> Carl was saying that the totorial should be changed to do this.  I
> would change "perhaps" to "DEFINITELY".  
You are right.

How about doing something like this? I tried to make it neutral to be usable whichever default we end up taking.

---
diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt
index 35af81a..5ddd2e9 100644
--- a/Documentation/tutorial.txt
+++ b/Documentation/tutorial.txt
@@ -11,6 +11,18 @@ diff" with:
 $ man git-diff
 ------------------------------------------------
 
+It is a good idea to introduce yourself to git before doing any
+operation.  The easiest way to do so is:
+
+------------------------------------------------
+$ cat >~/.gitconfig
+[user]
+	name = Your Name Comes Here
+	email = you@yourdomain.example.com
+^D
+------------------------------------------------
+
+
 Importing a new project
 -----------------------
 
@@ -31,7 +43,8 @@ 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
+every file under the current directory with (notice the dot '.'
+that means the current directory):
 
 ------------------------------------------------
 $ git add .
@@ -40,7 +53,7 @@ $ git add .
 Finally,
 
 ------------------------------------------------
-$ git commit -a
+$ git commit
 ------------------------------------------------
 
 will prompt you for a commit message, then record the current state
@@ -55,11 +68,17 @@ $ git diff
 to review your changes.  When you're done,
 
 ------------------------------------------------
-$ git commit -a
+$ git commit file1 file2...
 ------------------------------------------------
 
 will again prompt your for a message describing the change, and then
-record the new versions of the modified files.
+record the new versions of the files you listed.  It is cumbersome
+to list all files and you can say `-a` (which stands for 'all')
+instead.
+
+------------------------------------------------
+$ git commit -a
+------------------------------------------------
 
 A note on commit messages: Though not required, it's a good idea to
 begin the commit message with a single short (less than 50 character)
@@ -75,7 +94,7 @@ $ git add path/to/new/file
 ------------------------------------------------
 
 then commit as usual.  No special command is required when removing a
-file; just remove it, then commit.
+file; just remove it, then tell `commit` about the file as usual.
 
 At any point you can view the history of your changes using
Michael S. Tsirkin· Nov 29, 2006, 07:14 UTC · re: Junio C Hamano · lore
Show 7 quoted lines
> +------------------------------------------------
> +$ cat >~/.gitconfig
> +[user]
> +	name = Your Name Comes Here
> +	email = you@yourdomain.example.com
> +^D
> +------------------------------------------------

I used to use the ^D convention when explaining git to beginners and I noticed some people try to cut-and-paste it.

So the following might be a better way to put it:

+$ cat <<EOF >~/.gitconfig +[user] + name = Your Name Comes Here + email = you@yourdomain.example.com +EOF

← back to recent threads