Johannes Schindelin <Johannes.Schindelin@xxxxxx> writes:
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index 13db969..3c3f1b4 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -3160,6 +3160,225 @@ confusing and scary messages, but it won't actually do anything bad. In
> contrast, running "git prune" while somebody is actively changing the
> repository is a *BAD* idea).
>
> +[[birdview-on-the-source-code]]
> +A birdview on Git's source code
> +-----------------------------
Perhaps two dashes too short here...
> +
> +While Git's source code is quite elegant, it is not always easy for
> +new developers to find their way through it. A good idea is to look
> +at the contents of the initial commit:
> +_e83c5163316f89bfbde7d9ab23ca2e25604af290_ (also known as _v0.99~954_).
I am not sure we would need to say "is quite elegant". Why
don't we be blunt and say "It is not always easy for ...". That
holds true for any project of nontrivial size. I would rewrite
the first part like this.
It is not always easy for new developers to find their
way through Git's source code. This section gives you a
gentle guidance to show where to start.
A good place to start is to look at the contents of the
initial commit, with this command:
----------------------------------------------------------------
$ git checkout e83c516
----------------------------------------------------------------
and would not bore users with v0.99~954 or "git show" details.
"git show" to inspect one file at a time is not a good way to
get the feel of unknown set of source files, even though it is
very handy once you know where things were. And then continue
on to this part...
> +Be sure to read the README in that revision _after_ you are familiar with
> +the terminology (<<glossary>>), since the terminology has changed a little
> +since then. For example, we call the things "commits" now, which are
> +described in that README as "changesets".
> +
> +Actually a lot of the structure as it is now can be explained by that
> +initial commit.
It is also worth to point out that the initial revision, while
laying the foundation of almost every important factor of git we
have today, is small enough for reading everything in one
sitting, probably upfront, instead of making it a parenthesized
comment in a later paragraph. If somebody wants to dive into
git development to take a source-code tour, it is not really "it
will help you", but is a small enough required investment of
time.
> +For example, we do not call it "cache" any more, but "index", however, the
> +file is still called `cache.h`. Remark: Not much reason to change it now,
> +especially since there is no good single name for it anyway, because it is
> +basically _the_ header file which is included by _all_ of Git's C sources.
> +
> +If you grasp the ideas in that initial commit (it is really small and you
> +can get into it really fast, and it will help you recognize things in the
> +much larger code base we have now), you should go on skimming `cache.h`,
> +`object.h` and `commit.h` in the current version.
Other than that, I think this is well written, and if everybody
thinks it should be in the user's manual, I am fine with it.
By the way, when I sent the outline of hacker's manual as a
follow-up to the discussion, I think I forgot to properly say
this, so here it is: Thanks for starting the bird's eye view.
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
