user-manual: revise birdseye-view chapter
Some revisions suggested by Junio along with some minor style fixes and one compile fix (asterisks need escaping). Cc: Johannes Schindelin <Johannes.Schindelin@gmx.de> Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
J. Bruce Fields committed
May 12, 2007 at 19:48 UTC
a5fc33b4937fb6f38918710be6f23ef925630a8a
1 file changed
+18
-28
Documentation/user-manual.txt
+18
-28
@@ -3161,43 +3161,33 @@ contrast, running "git prune" while somebody is actively changing the
3161
repository is a *BAD* idea).
3162
3163
[[birdview-on-the-source-code]]
3164
-A birdview on Git's source code
3165
------------------------------
3164
+A birds-eye view of Git's source code
3165
+-------------------------------------
3166
3167
-While Git's source code is quite elegant, it is not always easy for
3168
-new developers to find their way through it. A good idea is to look
3169
-at the contents of the initial commit:
3170
-_e83c5163316f89bfbde7d9ab23ca2e25604af290_ (also known as _v0.99~954_).
3167
+It is not always easy for new developers to find their way through Git's
3168
+source code. This section gives you a little guidance to show where to
3169
+start.
3170
3172
-Tip: you can see what files are in there with
3171
+A good place to start is with the contents of the initial commit, with:
3172
3173
----------------------------------------------------
3175
-$ git show e83c5163316f89bfbde7d9ab23ca2e25604af290:
3174
+$ git checkout e83c5163
3175
----------------------------------------------------
3176
3178
-and look at those files with something like
3179
-
3180
------------------------------------------------------------
3181
-$ git show e83c5163316f89bfbde7d9ab23ca2e25604af290:cache.h
3182
------------------------------------------------------------
3183
-
3184
-Be sure to read the README in that revision _after_ you are familiar with
3185
-the terminology (<<glossary>>), since the terminology has changed a little
3186
-since then. For example, we call the things "commits" now, which are
3187
-described in that README as "changesets".
3177
+The initial revision lays the foundation for almost everything git has
3178
+today, but is small enough to read in one sitting.
3179
3189
-Actually a lot of the structure as it is now can be explained by that
3190
-initial commit.
3180
+Note that terminology has changed since that revision. For example, the
3181
+README in that revision uses the word "changeset" to describe what we
3182
+now call a <<def_commit_object,commit>>.
3183
3192
-For example, we do not call it "cache" any more, but "index", however, the
3184
+Also, we do not call it "cache" any more, but "index", however, the
3185
file is still called `cache.h`. Remark: Not much reason to change it now,
3186
especially since there is no good single name for it anyway, because it is
3187
basically _the_ header file which is included by _all_ of Git's C sources.
3188
3197
-If you grasp the ideas in that initial commit (it is really small and you
3198
-can get into it really fast, and it will help you recognize things in the
3199
-much larger code base we have now), you should go on skimming `cache.h`,
3200
-`object.h` and `commit.h` in the current version.
3189
+If you grasp the ideas in that initial commit, you should check out a
3190
+more recent version and skim `cache.h`, `object.h` and `commit.h`.
3191
3192
In the early days, Git (in the tradition of UNIX) was a bunch of programs
3193
which were extremely simple, and which you used in scripts, piping the
@@ -3320,11 +3310,11 @@ Two things are interesting here:
3310
negative numbers in case of different errors -- and 0 on success.
3311
3312
- the variable `sha1` in the function signature of `get_sha1()` is `unsigned
3323
- char *`, but is actually expected to be a pointer to `unsigned
3313
+ char \*`, but is actually expected to be a pointer to `unsigned
3314
char[20]`. This variable will contain the 160-bit SHA-1 of the given
3325
- commit. Note that whenever a SHA-1 is passed as "unsigned char *", it
3315
+ commit. Note that whenever a SHA-1 is passed as `unsigned char \*`, it
3316
is the binary representation, as opposed to the ASCII representation in
3327
- hex characters, which is passed as "char *".
3317
+ hex characters, which is passed as `char *`.
3318
3319
You will see both of these things throughout the code.
3320