missing: git api, reference, user manual and mission statement

missing: git api, reference, user manual and mission statement

[Klaus Robert Suetterlin]

Dear all,

please don't bother me with ``read the source dude'' or similar answers to this post.  If it's tone or contents just piss You off, ignore it.

I read a little about git lately, and tried to get it running the
last two days.  I found the following things lacking:

1) There is no clear (e.g. by name) distinction between ``git as done
by Linus'', which is a kind of content addressable database with added
semantics, and ``git as done by the rest of You'', which is a kind of
SCM on top of Linuses stuff.

2) For Linuses stuff I dare to say that it is an evil hack from
hell.  A prototype come alive.  This is not meant as an insult;  I
guess Linus agrees.

What it misses the most is a written reasoning about the WHYs, HOWs and
WHATFORs of git.  There is the README which tells us a little about
the WHAT on a level just above source code.

Linus must have had an idea of the final product, and how to use
that.  The real day to day workflow.  From that, and from his
experience with BK and the glimpse he took at monotone, he deduced
what limits the backend of his new distributed SCM system should have.
That is what he implemented:  A storage backend for an SCM.
(Unfortunately he didn't tell us for which.  This is like having
the answer without the question.  That is gitLinus is just like
``42''.)

Unfortunately what this storage backend does not have is an API or
UI definition.  I.e. there is no definition of git interaction
except for the git source code and the application on BLOB, TREE,
CHANGESET as described in the README.

I do think there should be a well defined API or UI so that the
backend could be replaced / changed / improved as need dictates.

3) As of the gitSCM stuff, I really miss any kind of description
how it works.  That is it completely lacks any concept, except for
``we will use gitLinus as backend''.

Take a look at some other distributed SCM (e.g. monotone -- which
might be too slow for a project like the kernel) and see how much these
people think about usage.  Do not reinvent the wheel, there is prior
art for use cases, too!

Some examples are:
1) What does the typical usage look like?
2) What is a version?
3) What is fork? (Especially in the context of a distributed SCM.)
4) What is a branch?
5) Which questions do we want the SCM to answer?
6) What is our security modell?
7) How do we synchronise?  (Not what command do we use , i.e.
   ``rsync'', but what is the operation, e.g. ``full replication of
   state''.)

I really believe a lot of questions on the git mailing list could
be answered if there was a user manual and a reference for git.
Even before all of it will be implemented.

4) Concerning usability on systems other than Linux...  I guess
this one can be ignored by most.

The source still uses st->st_mtim.tv_nsec which should be ->st_mtimensec, I guess.

git is implemented as mostly sh shell scripts.
gitdiff-do and gitlog.sh rely on bash, more precisely on /bin/bash.
git pull uses rsync
...

The list of dependencies is long and growing.  So if the intent of
doing gitSCM with shell scripts was to make it portable: that goal was missed.

5) gitLinus as library.

First I have to say that between what I saw in git-0.04 and the
current stuff from git-pasky there has been quite a lot of work to
get further away from the evil prototype.

Still gitLinus lacks a clear definition of its interface, so I
guess no one will be able to tell if it works correct.  How could You
do a test case without knowing
a) what the software should do and
b) how You should tell it?

And of course there are still memory leaks.  The obvious
--- i.e. malloc and (missing) free in the same function --- I found
while reading the git-0.04 source yesterday are gone.  Still I found
one of the ``malloc in called function no free in caller'' leaks
in git-pasky as pulled NOW.  And all I did was `grep malloc *'.
Someone should sit down and read all the source top to bottom.  And
the software should either check its resource usage or someone
should use a good tool on it.



Thanks for Your time and patience,

--Robert Suetterlin (robert@mpe.mpg.de)
phone: (+49)89 / 30000-3546   fax: (+49)89 / 30000-3950

Re: missing: git api, reference, user manual and mission statement

[Kevin Smith]

Klaus Robert Suetterlin wrote:
> 1) There is no clear (e.g. by name) distinction between ``git as done
> by Linus'', which is a kind of content addressable database with added
> semantics, and ``git as done by the rest of You'', which is a kind of
> SCM on top of Linuses stuff.

I also see this as one of the biggest obstacles right now. It would be
very helpful if we could achieve the clear separation between git and
non-git that has been part of the design since the beginning.

Git is very immature, and currently should only be used by brave
pioneers. About the only way for a mortal to even try git is to stick to
git-pasky releases, and not try to track all the patches flying around.


> Linus must have had an idea of the final product, and how to use
> that.  The real day to day workflow.  

The best description I have seen so far is the README for git-pasky:
  http://pasky.or.cz/~pasky/dev/git/

It's not a bad mini-tutorial, really.

> I really believe a lot of questions on the git mailing list could
> be answered if there was a user manual and a reference for git.
> Even before all of it will be implemented.

As you know, documentation is a great way for non-coders to contribute
to a project. Until someone steps up to write it, it won't happen.

In a highly iterative development process like this one, it actually
doesn't make sense to write the docs first. You really don't know how it
should work until you code it, play with it, and then realize it should
be doing something different.


> The list of dependencies is long and growing.  So if the intent of
> doing gitSCM with shell scripts was to make it portable: that goal was missed.

I think the main goal was rapid implementation. I totally expect there
to be one or several wrappers, written in various languages, that will
eventually replace git-pasky.


> Still gitLinus lacks a clear definition of its interface, so I
> guess no one will be able to tell if it works correct.  How could You
> do a test case without knowing
> a) what the software should do and
> b) how You should tell it?

I agree that it would be nice to have automated unit tests.


> And of course there are still memory leaks.  

The code is still young, and these will be fixed. I'm not bothered that
there are leaks at this moment. I am a bit bothered by Linus's attitude
that some small leaks might not ever need to be fixed.

Kevin

Re: missing: git api, reference, user manual and mission statement

[Ingo Molnar]

* Kevin Smith <yarcs@qualitycode.com> wrote:

> Klaus Robert Suetterlin wrote:
> > 1) There is no clear (e.g. by name) distinction between ``git as done
> > by Linus'', which is a kind of content addressable database with added
> > semantics, and ``git as done by the rest of You'', which is a kind of
> > SCM on top of Linuses stuff.
> 
> I also see this as one of the biggest obstacles right now. It would be 
> very helpful if we could achieve the clear separation between git and 
> non-git that has been part of the design since the beginning.
> 
> Git is very immature, and currently should only be used by brave 
> pioneers. About the only way for a mortal to even try git is to stick 
> to git-pasky releases, and not try to track all the patches flying 
> around.

hey, it's a 2 weeks old project, but it's certainly one of the 
fastest-growing projects i've ever seen: it has so much steam that it's 
scary :) It seems that a true emergency focused a massive, spontaneous 
concentration of OSS development power.

	Ingo

Re: missing: git api, reference, user manual and mission statement

[Kevin Smith]

Ingo Molnar wrote:
> * Kevin Smith <yarcs@qualitycode.com> wrote:
> 
>>Git is very immature, and currently should only be used by brave 
>>pioneers. About the only way for a mortal to even try git is to stick 
>>to git-pasky releases, and not try to track all the patches flying 
>>around.
> 
> hey, it's a 2 weeks old project, but it's certainly one of the 
> fastest-growing projects i've ever seen: it has so much steam that it's 
> scary :) It seems that a true emergency focused a massive, spontaneous 
> concentration of OSS development power.

Absolutely! I'm totally impressed with the progress so far.

Kevin

Re: missing: git api, reference, user manual and mission statement

[Petr Baudis]

Dear diary, on Tue, Apr 19, 2005 at 02:36:32PM CEST, I got a letter
where Klaus Robert Suetterlin <robert@mpe.mpg.de> told me that...
> 1) There is no clear (e.g. by name) distinction between ``git as done
> by Linus'', which is a kind of content addressable database with added
> semantics, and ``git as done by the rest of You'', which is a kind of
> SCM on top of Linuses stuff.

There is git and git-pasky (git-pasky is superset; therefore various
patches floating around either get to git-pasky or to both). I'm not
sure what else do you mean.

> 2) For Linuses stuff I dare to say that it is an evil hack from
> hell.  A prototype come alive.  This is not meant as an insult;  I
> guess Linus agrees.

I don't think it's evil at all. Why should it?

> I do think there should be a well defined API or UI so that the
> backend could be replaced / changed / improved as need dictates.

It's stabilizing. Mind you, it's 2 weeks old.

> 3) As of the gitSCM stuff, I really miss any kind of description
> how it works.  That is it completely lacks any concept, except for
> ``we will use gitLinus as backend''.

Have you read the README? If you have any questions, go ahead and ask.
_Write_ the description if you miss it.

> 4) Concerning usability on systems other than Linux...  I guess
> this one can be ignored by most.
> 
> The source still uses st->st_mtim.tv_nsec which should be ->st_mtimensec, I guess.

Patches welcome.

> git is implemented as mostly sh shell scripts.
> gitdiff-do and gitlog.sh rely on bash, more precisely on /bin/bash.
> git pull uses rsync
> ...
> 
> The list of dependencies is long and growing.  So if the intent of
> doing gitSCM with shell scripts was to make it portable: that goal was missed.

I think the way to go now that it's working and we are to add some sweet
cream on it is to rewrite it in Perl. I have some parts in progress
already.

> 5) gitLinus as library.
> 
> First I have to say that between what I saw in git-0.04 and the
> current stuff from git-pasky there has been quite a lot of work to
> get further away from the evil prototype.
> 
> Still gitLinus lacks a clear definition of its interface, so I
> guess no one will be able to tell if it works correct.  How could You
> do a test case without knowing
> a) what the software should do and
> b) how You should tell it?

You couldn't. UTSL now and write the docs and the testcases, or wait a
while.

> And of course there are still memory leaks.  The obvious
> --- i.e. malloc and (missing) free in the same function --- I found
> while reading the git-0.04 source yesterday are gone.  Still I found
> one of the ``malloc in called function no free in caller'' leaks
> in git-pasky as pulled NOW.  And all I did was `grep malloc *'.
> Someone should sit down and read all the source top to bottom.  And
> the software should either check its resource usage or someone
> should use a good tool on it.

"Someone"?

Again, patches welcome. The patches are likely usually no big deal now,
though. I'm by all means for fixing them, especially when git will start
to head towards libgit.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
C++: an octopus made by nailing extra legs onto a dog. -- Steve Taylor

RE: missing: git api, reference, user manual and mission statement

[Andrew Timberlake-Newell]

Petr Baudis graced us with:
> Dear diary, on Tue, Apr 19, 2005 at 02:36:32PM CEST, I got a letter
> where Klaus Robert Suetterlin <robert@mpe.mpg.de> told me that...
> > 1) There is no clear (e.g. by name) distinction between ``git as done
> > by Linus'', which is a kind of content addressable database with added
> > semantics, and ``git as done by the rest of You'', which is a kind of
> > SCM on top of Linuses stuff.
> 
> There is git and git-pasky (git-pasky is superset; therefore various
> patches floating around either get to git-pasky or to both). I'm not
> sure what else do you mean.

This goes back to the question of whether to rename git-pasky to cogito.  

Perhaps the crucial question is:  will the git plumbing be used for anything
other than SCM?

If so, then it could be useful to differentiate by program name, so that we
would know whether another project was utilizing git-plumbing or git-SCM.

If not, then there is effectively only one tool and the plumbing is a
[crucial] portion thereof:  a git (SCM and the file system around which it
was built).

So what's the answer to the question?  Anyone planning to use git (the file
system) outside of the SCM?