[ANNOUNCE] Git wiki

  Hi,

  I have just set up a (fairly crude, but hey, it seems to work) wiki at

	http://git.or.cz/gitwiki

  It's slow and ugly but if it becomes popular, I will move it to
something better than Apache CGI. ;-) I also haven't written more than
an introductory paragraph on the front page, the rest is up to you.

  I'm personally not exceptionally fond of wikis (other than Wikipedia)
but a wish to have one has been expressed several times and I hope it
will be helpful for the Git community; not only the newbies might dig
(and especially exchange!) some useful information, tips'n'trick and
such.  Ideally, it could become a melting pot for the Documentation/
directories or the rather austere (I take patches) Git homepage - or
something entirely different. Whatever _you_ make from it.

  Editally yours,

Petr Baudis <pasky@suse.cz> writes:

Thanks for doing this. I am not a Wiki person myself, and would rather want to see we have useful and authoritative bits in the Documentation set, but this would help the community.

I'd love to see somebody volunteer to act as an editor to feed cooked topics for inclusion of the Documentation/ set. Anybody?

On 5/3/06, Junio C Hamano <junkio@cox.net> wrote:

Junio, would be possible for you to write a Roadmap in a Wiki page, similar to what Mercurial did here: http://www.selenic.com/mercurial/wiki/index.cgi/RoadMap ?

BTW, do you know why GIT has not been selected as SCM for OpenSolaris? (they choose Mercurial).

Ciao,

-- Paolo http://paolociarrocchi.googlepages.com

Dear diary, on Wed, May 03, 2006 at 10:39:07AM CEST, I got a letter where Paolo Ciarrocchi <paolo.ciarrocchi@gmail.com> said that...

I think this has time and someone might emerge naturally.

You can already find a similar (albeit a bit more low-level) document at

	http://kernel.org/git/?p=git/git.git;a=blob;hb=todo;f=TODO

but you can certainly add a link to it to the wiki. ;-)

I think it's explained somewhere in their forums (or mailing lists or whatever they actually _are_).

On 5/3/06, Petr Baudis <pasky@suse.cz> wrote:

I was looking for something more "high level but I'll try to add that link to the wiki as soon as I back home from work.

I only found the announcement, not the rationales.

Ciao,

-- Paolo http://paolociarrocchi.googlepages.com

On Wed, 3 May 2006, Paolo Ciarrocchi wrote:

http://mail.opensolaris.org/pipermail/tools-discuss/2006-April/000366.html

Looks like they didn't buy the argument about the uselessness of recording file renames.

Nicolas

Nicolas Pitre <nico@cam.org> wrote:

The final evaluations are available from here (at the very bottom of the page):

  http://opensolaris.org/os/community/tools/scm/

It looks like Mercurial doesn't support renames either, but a lot of users are asking for it to be supported. So I don't think that's the reason. It looks more like they didn't enjoy porting GIT 1.2.2 (as 1.2.4 was found to not work in all cases) to Solaris and the tester ran into some problems with the conflict resolution support.

My own reading of the two final evaluations for GIT and Mercurial leaves me feeling like GIT is a more mature tool which is faster and more stable then Mercurial. GIT seemed to be more reliable during testing then Mercurial was, despite the cloning issue. Which makes me surprised that OpenSolaris selected Mercurial instead.

Shawn Pearce wrote:

Considering Sun's CEO's common comments on Solaris' superiority over Linux I think it's safe to assume that the same CEO wouldn't exactly jump of joy if his employees started depending on a tool fathered by Linus.

No offence intended to Mercurial or its developers. Although I don't know anything about how it works I'm fairly sure Sun's developers would never agree to be forced to use an inferior tool (congrats Mercurial devs). However, I *do* think that in a tie-break Mercurial would win for political reasons.

On 5/3/06, Andreas Ericsson <ae@op5.se> wrote:

Would be fantastic to see a fair comparison of the two tools but I can't find anything useful on the web.

-- Paolo http://paolociarrocchi.googlepages.com

Paolo Ciarrocchi wrote:

Three tools: Git/Cogito, Mercurial and Monotone.

On Wed, 3 May 2006, Andreas Ericsson wrote:

I doubt it went that high up, but with any kind of politics it's obviously possible that somebody consciously or unconsciously felt it might become a political problem, and it might have made a difference.

However, I think the _real_ issue is that Mercurial has a much nicer introductory phase. The standard mercurial web-page is so much more professional and nice to look at than any git page I have ever seen, and let's face it: first looks _do_ count.

Also, the fact that Solaris had the unfortunate bug with signals probably didn't much help to endear git to them, since it made it look like git had problems. Never mind that we solved it - I think it took us a while to even realize that Solaris had a problem, because we weren't intimately involved.

Which brings me to the final point, which is that I think the hg team was very active and supporting, perhaps Matt himself. That's _important_ - the OpenSolaris people probably felt very comfortable with strong support from the developers. It can often be _the_ best (and biggest) reason to choose any product - regardless of anything else.

Even if I think the git mailing list itself is very responsive, I think the hg people were just more directly and actively involved. For git, they had to come to us.

I also suspect that some people find python scripts somewhat less intimidating than C. I'll also happily admit that my coding standards tend to lean towards the "sparse" when it comes to comments, and I much prefer the "small and well-named functions" approach, and git seems to have stuck to that with Junio. Which just turns some people off.

So I don't think you need politics to explain it. I think hg is doing quite well. It took some different design decisions, and while I personally think the git ones are better, I'm somewhat biased ;)

			Linus

On 5/3/06, Linus Torvalds <torvalds@osdl.org> wrote:

I can only agree.

I'm not a git developer, I'm even not a _real_ developer, I only hack for fun during my very poor spare time but web pages, wiki and introduction offered by Mercurial are really a lot nicer to what git is offering at the moment.

Perhaps is just a silly idea, but would be possible for OSDL to host a web site (www.git.org) where we can host pages/wiki an so on?

Ciao, -- Paolo http://paolociarrocchi.googlepages.com

On Wed, 3 May 2006, Paolo Ciarrocchi wrote:

I don't think hosting it would be a problem (it probably would be the same kernel.org thing - OSDL is partly involved in maintaining it). The problem is the content, and the artistic talent.

_I_ personally have what I'd call "negative artistic talent". I think I'm occasionally good at designing beautiful data structures (and I think git is that, including the pack-files), but that clearly doesn't translate to any visual ability what-so-ever. None. Nada. Zilch.

Maybe the new Wiki can evolve into that. It sure looks better today than it looked yesterday (now, when I first saw it, it was so ugly that I had to dig my eyeballs out with a spoon, so that's not necessarily saying all that much ;)

		Linus

Linus Torvalds wrote:

As to content, we could I think use material found at Wikipedia Git page, and on External Links in Wikipedia Git_(software) article, not repeating of course what is in official Git Documentation/

On 5/3/06, Jakub Narebski <jnareb@gmail.com> wrote:

I just added the TODO list link but I'm not a wiki expert, if you know how to link to the article from Wikipedia please do it ;-)

Ciao, -- Paolo http://paolociarrocchi.googlepages.com

Paolo Ciarrocchi wrote:

I thought about copying contents, not making a link to WikiPedia article. I tried to make InterWiki link, WikiPedia:Git_(software) but MoinMoin engine doesn't deal well with parentheses.

On Wed, 3 May 2006, Jakub Narebski wrote:

please go ahead and put a lot of the info that is in the GIT Documentation/ on the wiki. it's far easier to go to one site and browse around to find things then to run into issues where you have to go somewhere else (with different tools) to find the info.

even if you just put all the documentation files there, as-is (as text files even, no hyperlinks in them) they should still be there.

David Lang

Dear diary, on Wed, May 03, 2006 at 09:21:54PM CEST, I got a letter where David Lang <dlang@digitalinsight.com> said that...

Then who will keep it in sync (BOTH ways)? That would be quite a lot of work, I think.

That said, having the documentation in a wiki is not a bad idea per se, but you need to keep things consistent and converging. And I believe (and hope) that killing Documentation/ directory is no option - I hate it when documentation of software I installed just tells me "look at this URI" (which documents a different version anyway, and it's all very useful when I'm sitting in a train with my notebook).

On Wed, 3 May 2006, Petr Baudis wrote:

I agree with this completely.

as for keeping it in sync, the ideal situation would be for a documentation manager to take that job ;-) but lacking that just put the documentation in a non-editable page somewhere and link to it from the wiki (this could even be pages at kernel.org or wherever you have the raw source available outside of git itself)

David Lang

Dear diary, on Wed, May 03, 2006 at 09:46:33PM CEST, I got a letter where David Lang <dlang@digitalinsight.com> said that...

Well, that one is pretty easy.

	http://www.kernel.org/pub/software/scm/git/docs/
	http://www.kernel.org/pub/software/scm/cogito/docs/

On Wed, 3 May 2006, Petr Baudis wrote:

Clearly the solution is a wiki with a git backend and asciidoc for the formatting language. Then the wiki just has to pull from kernel.org occasionally, and Junio can pull from the wiki's repository when there are good changes there.

I'm actually only somewhat joking; I wrote a Python CGI for this at one point, and got as far as having it basically work, but then I couldn't come up with a way to safely use asciidoc to format an attacker's file.

	-Daniel
*This .sig left intentionally blank*

Mercurial also has an easier learning curve; and while the "Everyday Git with 20 commands or so" is a very good document, and I've found it invaluable for getting started, if you compare it to the "Quick Start for the Impatient" page on the front page of the Mercurial Wiki, for many people Mercurial will *appear* to be an order of magitude simpler and is yet powerful enough for their project.

Of course, a lot of it is that git *is* much more powerful, much like the difference between a stickshift with a racing clutch (git) and a car with an automatic transmission (hg). So maybe one thing that would help git would be a stronger emphasis of cogito for those projects that don't need the full power of using git "straight up".

Just a thought....

						- Ted

On Wed, 3 May 2006, Theodore Tso wrote:

I don't think that's necessarily a good comparison.

The "easy things" are easy even with git. Our explanation pages and tutorials just tend to want to show off, and do more than they need to.

Even the "everyday git in 20 commands" actually starts out scaring people with listing commands that they don't need to know about immediately. The whole fsck/count-object/pruning thing shouldn't even be mentioned until after you've shown how easy it is to just do

	git init-db
	git add .
	git commit -a

to import an old project, and then do an example commit or something (one of the early examples).

So yeah. We should have a main page that starts off with the "everyday git" link (preferably further simplified) very prominently, and just looks less scary.

People are probably already expecting the worst - partly because git is newer than some of the other projects (not hg, but svn/svk/monotone etc), and partly because I was actively trying to not over-promise or over-sell early on when it wasn't clear how good git was going to get..

So looking pretty and easy to use is clearly important, and I think git has the _capability_ for that, we've not just documented it that way.

			Linus

On Wed, May 03, 2006 at 10:06:25AM -0700, Linus Torvalds wrote:

Yeah, but the fact that you have to use repack and prune in order to keep the disk space usage from exploding (especially with the Linux 2.6 tree) , means that we have to expose that mess to the beginning user. Could git be made to do the repacking automatically when it makes sense using some hueristic algorithm?

						- Ted

On Wed, 3 May 2006, Theodore Tso wrote:

No you don't. You get it packed when it's cloned, and the disk usage doesn't go up _that_ fast. By the time you need to worry about disk usage you have certainly had time to learn the basics.

No need to start talking about fsck or repacking until the second day.

This was discussed, and yeah, it _could_, but I suspect you really don't want to repack in the middle of some op. Even if your repo was _mostly_ packed, it's an irritating hickup at a time when you don't need to.

I think it's much better to teach people to repack once a week (if that). But to teach them only after they've already _used_ it for a week and aren't intimidated by the basic ops any longer.

		Linus

On Wed, May 03, 2006 at 10:06:25AM -0700, Linus Torvalds wrote:

20 commands is much more than I use in my daily use of git.

Lets see: git clone git diff git reset --hard git ls-files git grep git add git rm cg-commit cg-restore git push git am

I may have missed one or two - but this is it. Lees then 20. And I never use pack or fsck.

It is not that difficult. A few cogito commands creeped in also. I just find them easier to use.

In other words - the tutorials are covering too much as stated by others.

	Sam

Dear diary, on Thu, May 04, 2006 at 12:39:32AM CEST, I got a letter where Sam Ravnborg <sam@ravnborg.org> said that...

I think git ls-files isn't used directly very frequently. OTOH, you don't use cg-log or git log and cg-status/git status? :) Also, most people will pull.

On Thu, May 04, 2006 at 12:46:45AM +0200, Petr Baudis wrote:

	I use git ls-files, becuase it's the only way I know how to
blow away dirty state that added files.  I ran into this just yesterday,
actually.  git checkout -f won't remove files that are unknown.

    $ git ls-files -o | xargs rm -rf

Joel

Dear diary, on Thu, May 04, 2006 at 12:50:56AM CEST, I got a letter where Joel Becker <Joel.Becker@oracle.com> said that...

You can use cg-clean, and I think Git has got git-clean added recently.

On Wed, 3 May 2006, Theodore Tso wrote:

Actually, we could almost steal their QuickStart, replace "hg" with "git", and have it actually be correct.

Setting up public access follows a slightly different pattern, but otherwise, all of the operations on that page are identical or simpler in git than as given in that document, AFAICT.

	-Daniel
*This .sig left intentionally blank*

On Wed, 3 May 2006 12:47:32 -0400 Theodore Tso <tytso@mit.edu> wrote:

The docs and higher-level user commands can still use some work, but telling people they have to install and learn an entire extra layer isn't going to win many converts. Personally I think Git needs a bit more polish and to stop thinking of itself as mostly plumbing. Even so Git really has become pretty good at making simple things simple:

init-db, add/rm, commit -a, status, show, log, gitk, diff, branch, checkout, clone, fetch/pull

The fact that it's faster, requires less disk space, and has all the lower level tools you need to do "complex stuff", should make it a tempting choice once the remaining rough edges are removed. But there is nothing inherently complex about Git.

Sean

Linus Torvalds <torvalds@osdl.org> writes:

I agree with this 100%. I happened to be talking with Eric about the clone breakage he was having on #git channel, and I asked him to help me diagnose the problem, which resulted in the solution we saw on the list. It turned out to be the same "1.2.2 works but 1.2.4 not" problem OpenSolaris evaluator was having. I was never contacted from somebody in the OpenSolaris circle during the whole exercise.

But reading their Mercurial report apparently suggests that their hg evaluator was with direct contact with the right community from early on. I still do not even know (I've seen it once in _their_ report) who the git evaluator on their end was. I am not surprised that the difference in depth of involvements and contact between the development community and the respective evaluator contributed to the result in a major way.

That is _very_ unfair to me. It is not like git and hg both submitted proposals to be chosen by them and then we dropped the ball by not supporting them properly. They have to come to us.

The time I personally became aware about their DSCM selection contest was when its initial phase was almost over; even if I were willing to help them, it was too late. And no, I do not have enough time to go fishing for such opportunities everywhere to help many random projects, either.

Junio C Hamano <junkio@cox.net> writes:

Sorry, my memory is failing.  It was Oejet I was talking with.
 

On Wed, 3 May 2006, Junio C Hamano wrote:

Oh, sorry, I didn't mean it in that way. Of _course_ they should have come to us with their issues.

So I don't think git was doing anything wrong there, I was just stating it as a neutral fact, rather than any criticism - the hg people were involved (and I think they were pushing it), and the git people weren't, because they never came to us.

Not a big deal. I actually think we'll be better off with some competition to keep us on our toes.

			Linus

Dear diary, on Wed, May 03, 2006 at 05:30:26PM CEST, I got a letter where Linus Torvalds <torvalds@osdl.org> said that...

Yes, I've already learned earlier that this made quite a bad impression on many people and had the homepage revamp on top of my TODO list for the last few weeks.

Well, here we go, I've just uploaded a new version of the Git homepage; I wonder how you feel about it now.

Obviously, it still feels rather empty and I'm certainly not much of a webmaster myself, but I take patches and pull requests; see http://git.or.cz/community.html for the Git homepage git repository information.

I've borrowed Jonas Fonseca's ELinks homepage design first, but the contents ended up almost entirely rewritten as well (except the Related Tools section, which stayed mostly as it was). Git now poses as a real version control system and the plumbing stuff is mentioned only in the bottom paragraphs. ;-)

BTW, if anyone is into CSS and stuff, after half an hour of beating it I couldn't manage to make the top bar look right - everything is shifted slightly to the top. :/

Petr Baudis wrote:

Very nice, although earlier version had the advantage of having everything on one page. I hope that no information was lost.

What it lacks is the link in menu bar to Home (or News), i.e. http://git.or.cz/ or http://git.or.cz/index.html page.

About Download page (http://git.or.cz/download.html) - it would be nice to have in comments about firewalls told which port git uses for git:// protocol.

Dear diary, on Thu, May 04, 2006 at 03:01:33AM CEST, I got a letter where Jakub Narebski <jnareb@gmail.com> said that...

Perhaps few bits but I think they were insignificant or just confusing. :) (Like Cogito/StGit commands for cloning Git repository).

You could get there clicking on the Git logo, but I agree that this wasn't very intuitive. I've added a link.

Good idea, added.

By the way, it has been suggested on #git that it might be worth sharing the same color scheme between gitweb and the homepage. I have tried it out but the gitweb's color scheme might be a bit too dull for the homepage, dunno (I might also just already get too used to the bluish theme). Opinions welcome. It's the "Gitweb gray" stylesheet (in Firefox, View -> Page style).

Thanks,