# Re: Hyphens and hiding core commands 3 messages from 2006-11-28 to 2006-11-29. Participants: Michael S. Tsirkin, Junio C Hamano, Theodore Tso. Thread: https://gitlist.dev/t/43506 ## Theodore Tso, 2006-11-28 05:40 Subject: Re: Hyphens and hiding core commands Message-ID: <20061128054032.GC11122@thunk.org> URL: https://gitlist.dev/e/20061128054032.GC11122%40thunk.org In-Reply-To: <7vk61gcnzl.fsf@assigned-by-dhcp.cox.net> ``` 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. > 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, 2006-11-28 09:15 Subject: Re: Hyphens and hiding core commands Message-ID: <7vu00k3pao.fsf@assigned-by-dhcp.cox.net> URL: https://gitlist.dev/e/7vu00k3pao.fsf%40assigned-by-dhcp.cox.net In-Reply-To: <20061128054032.GC11122@thunk.org> ``` Theodore Tso 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, 2006-11-29 07:14 Subject: Re: Hyphens and hiding core commands Message-ID: <20061129071449.GH5061@mellanox.co.il> URL: https://gitlist.dev/e/20061129071449.GH5061%40mellanox.co.il In-Reply-To: <7vu00k3pao.fsf@assigned-by-dhcp.cox.net> ``` > +------------------------------------------------ > +$ 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 <~/.gitconfig +[user] + name = Your Name Comes Here + email = you@yourdomain.example.com +EOF -- ```