Re: [PATCH] Add a birdview-on-the-source-code section to the user manual

From: Petr Baudis <pasky@suse.cz>
Date: May 9, 2007, 12:32 UTC
Message-ID: <20070509123205.GN4489@pasky.or.cz>
In-Reply-To: <Pine.LNX.4.64.0705091414280.4167@racer.site>

On Wed, May 09, 2007 at 02:19:03PM CEST, Johannes Schindelin wrote:

Show 21 quoted lines

> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index 2d58bb0..55934db 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -3197,7 +3197,15 @@ 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`.
> +`object.h` and `commit.h` in the current version.
> +
> +In the early days, Git (in the tradition of UNIX) was a bunch of programs 
> +which were extremely simple, and which you used in scripts, piping the 
> +output of one into another. This turned out to be good for initial 
> +development, since it was easier to test new things.  However, recently 
> +many of these parts have become builtins, and some of the core has been 
> +"libified", i.e. put into libgit.a for performance, portability reasons, 
> +and to avoid code duplication.
> 
>  By now, you know what the index is (and find the corresponding data 
>  structures in `cache.h`), and that there are just a couple of object types

I disagree, especially with the past tense of the first half of the paragraph. Git is _still_ a bunch of programs you use in scripts, piping the output of one into another. Another point is that implementation-wise many of the code is currently shared in an internal library, etc.

I'd be a bit careful to talk about libgit.a so leisurely since it might give the reader an impression that there really _is_ "the git library", with API and everything, that they can use externally. Of course you need to mention libgit.a, but I'd also mention that it is so far meant only for internal git's use and has no solidified API.

Show 12 quoted lines

> @@ -3300,8 +3321,10 @@ Two things are interesting here:
>  
>  - the variable `sha1` in the function signature of `get_sha1()` is `unsigned 
>    char *`, but is actually expected to be a pointer to `unsigned 
> -  char[20]`.  This variable will contain the big endian version of the 
> -  40-character hex string representation of the SHA-1.
> +  char[20]`.  This variable will contain the 160-bit SHA-1 of the given 
> +  commit.  Note that whenever a SHA-1 is passed as "unsigned char *", it 
> +  is the binary representation (big-endian), as opposed to the ASCII 
> +  representation in hex characters, which is passed as "char *".
>  
>  You will see both of these things throughout the code.

To be honest, I wouldn't even be *thinking* about the endianity of SHA-1 octet representation (you don't usually really deal with the hash as with a number, so expecting to have it in native endianity is not very natural; you just deal with it as with a data blob) and the "(big-endian)" would only confuse me and get me thinking about "huh, do they swap the bytes, or wait, they don't, ...?!".

But that's maybe just me.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
Ever try. Ever fail. No matter. // Try again. Fail again. Fail better.
		-- Samuel Beckett