@matheusbsbs / matheus-bagliano / commits / 9755afbd94
Fork 0

Documentation: not learning core git commands.

The initial section of tutorial was too heavy on internal workings for the first-time readers, so rewrite the introductory section of git(7) to start with "not learning core git commands" section and refer them to README to grasp the basic concepts, then Everyday to give overview with task/role oriented examples for minimum set of commands, and finally the tutorial. Also add to existing note in the tutorial that many too technical descriptions can be skipped by a casual reader. I initially started to review the tutorial, with the objective of ripping out the detailed technical information altogether, but I found that the level of details in the initial couple of sections that talk about refs and the object database in a hands-on fashion was about rigth, and left all of them there. I feel that reading about fsck-index and repack is too abstract without being aware of these directories and files. Signed-off-by: Junio C Hamano <junkio@cox.net>

Junio C Hamano committed Dec 13, 2005 at 02:38 UTC 9755afbd9467759bb77a6e5a535791243c5b907d
2 files changed +49 -22
Documentation/git.txt
+30 -21
@@ -33,34 +33,41 @@ OPTIONS
33 environment variable. If no path is given 'git' will print
34 the current setting and then exit.
35
36 -CORE GIT COMMANDS
37 ------------------
38 -Before reading this cover to cover, you may want to take a look
39 -at the link:tutorial.html[tutorial] document. If you are
40 -migrating from CVS, link:cvs-migration.html[cvs migration]
41 -document may be helpful after you finish the tutorial.
42 -
43 -The <<Discussion>> section below contains much useful definition
44 -and clarification info - read that first. After that, if you
45 -are interested in using git to manage (version control)
36 +
37 +NOT LEARNING CORE GIT COMMANDS
38 +------------------------------
39 +
40 +This manual is intended to give complete background information
41 +and internal workings of git, which may be too much for most
42 +people. The <<Discussion>> section below contains much useful
43 +definition and clarification - read that first.
44 +
45 +If you are interested in using git to manage (version control)
46 projects, use link:everyday.html[Everyday GIT] as a guide to the
47 minimum set of commands you need to know for day-to-day work.
48 +Most likely, that will get you started, and you can go a long
49 +way without knowing the low level details too much.
50 +
51 +The link:tutorial.html[tutorial] document covers how things
52 +internally work.
53 +
54 +If you are migrating from CVS, link:cvs-migration.html[cvs
55 +migration] document may be helpful after you finish the
56 +tutorial.
57
58 After you get the general feel from the tutorial and this
59 overview page, you may want to take a look at the
60 link:howto-index.html[howto] documents.
61
62 +
63 +CORE GIT COMMANDS
64 +-----------------
65 +
66 If you are writing your own Porcelain, you need to be familiar
67 with most of the low level commands --- I suggest starting from
68 gitlink:git-update-index[1] and gitlink:git-read-tree[1].
69
70
58 -David Greaves <david@dgreaves.com>
59 -08/05/05
60 -
61 -Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 and
62 -further on 2005-12-07 to reflect recent changes.
63 -
71 Commands Overview
72 -----------------
73 The git commands can helpfully be split into those that manipulate
@@ -582,14 +589,16 @@ include::../README[]
589
590 Authors
591 -------
585 - git's founding father is Linus Torvalds <torvalds@osdl.org>.
586 - The current git nurse is Junio C Hamano <junkio@cox.net>.
587 - The git potty was written by Andres Ericsson <ae@op5.se>.
588 - General upbringing is handled by the git-list <git@vger.kernel.org>.
592 +* git's founding father is Linus Torvalds <torvalds@osdl.org>.
593 +* The current git nurse is Junio C Hamano <junkio@cox.net>.
594 +* The git potty was written by Andres Ericsson <ae@op5.se>.
595 +* General upbringing is handled by the git-list <git@vger.kernel.org>.
596
597 Documentation
598 --------------
592 -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
599 +The documentation for git suite was started by David Greaves
600 +<david@dgreaves.com>, and later enhanced greatly by the
601 +contributors on the git-list <git@vger.kernel.org>.
602
603 GIT
604 ---
Documentation/tutorial.txt
+19 -1
@@ -18,7 +18,14 @@ doing.
18 The core git is often called "plumbing", with the prettier user
19 interfaces on top of it called "porcelain". You may not want to use the
20 plumbing directly very often, but it can be good to know what the
21 -plumbing does for when the porcelain isn't flushing...
21 +plumbing does for when the porcelain isn't flushing.
22 +
23 +The material presented here often goes deep describing how things
24 +work internally. If you are mostly interested in using git as a
25 +SCM, you can skip them during your first pass.
26 +
27 +[NOTE]
28 +And those "too deep" descriptions are often marked as Note.
29
30
31 Creating a git repository
@@ -252,6 +259,17 @@ tree. That's very useful.
259 A common shorthand for `git-diff-files -p` is to just write `git
260 diff`, which will do the same thing.
261
262 +------------
263 +$ git diff
264 +diff --git a/hello b/hello
265 +index 557db03..263414f 100644
266 +--- a/hello
267 ++++ b/hello
268 +@@ -1 +1,2 @@
269 + Hello World
270 ++It's a new day for git
271 +------------
272 +
273
274 Committing git state
275 --------------------