[cairo] Use of git

[Carl Worth]

On Thu, 10 Jan 2008 19:04:24 -0500, Antoine Azar wrote:
> Thanks Baz and Carl for your informative messages. I'll definitely 
> check out those links.

No problem. And thanks for sharing your thoughts here. There's some
very good stuff here, (some or most of which should really be on the
git mailing list---I'm there too by the way---but I'll go ahead and
answer here for now[*]).

[*] The downside being that we miss out on a lot of git experts.

> Offline functionality indeed can be very useful, and I don't think 
> it's possible with Perforce or SVN.

It's definitely useful and was a big part of the switch away from CVS
as I explained in the post I linked to before.

> Perforce; I used to work in a gaming company, our engine was in 
> Perforce and each developer had his own private branch to work in. 
> Once the feature was tested and the branch compiled, a dev would 
> integrate his change into the root branch. I found that development 
> model very easy and safe. I do realize it might not be adapted for 
> more de-centralized development though.

That seems a fine model, and is also extremely well-supported by
git. The biggest difference from your experience there and with cairo
here is that you were all part of a company so things like trusting
users and creating accounts were already solved issues.

So, with git, I definitely like to see people working in private
branches. And a *huge* advantage of git over centralized systems is
that anyone can create a branch immediately in their own repository,
(we don't have to go through any steps to establish trust nor create
accounts).

Now, after you make a new branch, (which is what you've done as soon
as you've done your first "git commit"), you'll also want a convenient
way to share it. Some git experts love emailing of patches. I
definitely don't prefer it. I'd much rather see people post their code
where I can fetch it as a git branch. And that's a step that does
require the user to have at least _some_ place somewhere they can post
code. I do hand out freedesktop.org accounts like breath mints for
anyone that wants them. And then you can simply "git push" your
branches to a personal repository there and people can share them.

So the biggest difference there isn't really centralized
vs. distributed, but it's more about just whether we have a common
place to be able to publish our own branches, (and that's just plain
easier when within the walls of a single organization).

However, once you do have each developer publishing his own branch,
(or branches), the distributed setup starts to really shine compared
to a centralized setup. With your perforce setup what opportunity did
you have for collaborating with others? If two people wanted to work
together on a branch, but it still wasn't ready for the "mainline" was
it easy to share? That's where git totally rocks. I can share totally
crazy stuff that I wouldn't dream of letting near the centralized
repository, and I can merge it back and forth with other people as
much as needed until it gets into decent shape.

I've got great examples of this in the X server driver work I've been
doing for the past few months. I've been merging my code back and
forth with 3 other developers for months, but nobody tracking mainline
ever sees it, (nor would they want to yet). Nothing like that was even
remotely possible with cvs, (nor I think in svn---and again I have no
idea about perforce).

> Carl: Yes, the commands you listed are what I used as of now. But I 
> still have a few gripes (which might be answered by the info on the 
> links you provided):

Here's where you start getting into some good meaty stuff, (and
perhaps useful to pass on to the git mailing list).

> -I'm on Windows, and it's already been somewhat painful installing 
> and getting Git to run. Nevermind you get cryptic error messages 
> about index.lock when your repository is on FAT32.

This has definitely been a sore spot with git for a long time. But
it's also been a sore spot where lots of Windows users would complain
about missing support, but not a lot would help improve it. From what
I understand the recent msysgit efforts have made tremendous strides
recently, and should provide a better experience for users that don't
want/like the cygwin-based git stuff. I see that there is a .exe
installer for git here for example:

	http://code.google.com/p/msysgit/downloads/list

Have you tried that stuff?

> -I edited a makefile but it's a hack I want to keep without 
> submitting it. So I don't want to commit the change and submit it 
> later on by mistake. How can I exclude a file from getting committed 
> while still getting any updates from the original repo? The folks on 
> the IRC git channel recommended doing another branch for that one 
> change but I don't think it's the right solution.

The git IRC channel generally provides ready access to some serious
git experts, so I'd be more inclined to trust them if I were you. What
seems "not right" about the the proposed solution? It seems perfect to
me, and it would have avoided a lot of the pain you ran into below.

I can guess that one thing that would make it seem like a bad solution
is the pain of creating and merging branches in just about every other
system out there. But with git it really is ridiculously easy and you
should take advantage of it. I'll demonstrate how I would have done
this starting from a git clone:

	git clone git://anongit.freedesktop.org/git/cairo
	cd cairo
	# Hack, hack, hack. Cool, things work!

At this point I notice that some of my changes should be private, (the
Makefile hacks), so I'll put them on their own branch "build":

	git checkout -b build
	git commit makefile.win32

Now, let's go back to the original "master" branch and make a commit
for everything else:

	git checkout master
	git commit -a

And then let's imagine I noticed some indentation problems, or other
things, so I want to amend this last commit:

	# hack, hack, hack
	git commit -a --amend

Cool. That's probably ready for submission, but I need to be able
build it to test, and doing that requires my custom changes on the
build branch:

	git checkout build
	git merge master
	# build and test

Everything checks out, so we can generate our patch now. We want a
patch series for everything from what was upstream ("origin") to what
is on our "master" branch, (but nothing that's specific to the build
branch). So that's as simple as:

	git format-patch origin..master

Going forward, it's nice to work with the "build" branch checked out,
since things actually build here. But each time I'm ready to commit,
I'll first do "git checkout master" in order to prepare a nice clean
series of commits without my private build changes.

And while on master, I can do "git pull" to get new upstream
changes. Every time I change master, (with either "git commit" or "git
pull), the next time I go back to my build branch I'll do "git merge
master" to keep things in synch.

Does that make sense?

If I were teaching you in person I'd also bring up gitk to demonstrate
how nicely the visualization in provides explains everything that's
going on. (And it's my understanding that gitk works fine on Windows.)

> -So now I'm careful about which files get committed because I want to 
> exclude that makefile.

Here you're causing yourself a bunch of pain just to avoid using
branches. I wouldn't recommend this approach.

> -I then find out I can do this with git reset. It seems like git 
> reset can either undo a commit or mark a file for not being included 
> at the next commit? those are two very different functionalities in
> my mind.

I agree. There are definitely two distinct things that can be changed
by git-reset, (change which commit the current branch points to or
change what's currently "staged" in the index). So that can be
confusing.

> -Seemingly no good way of doing a 3-way diff when I do a merge or 
> review a patch, at least on Windows?

I'm not sure in exactly what situation you're having trouble getting a
good diff. Could you explain this question in more detail.

> -Definitions in the doc: checkout, staged, unstaged, and other terms 
> seem used all over the doc without definitions.

I think documentation could always be improved. And as a new user to
git you're in a rare position to be able to provide excellent
feedback. I'd suggest you send things you notice to the git mailing
list, and I think you might be surprised at how quickly helpful
suggestions will get incorporated into the documentation.

It's often just plain hard for experienced users to know which
documents someone might read first or even to realize which concepts
need to be defined more clearly upfront.

>           I'm still unclear about staged and unstaged. It seems to 
> mean whether a file will be committed at the next commit operation, 
> but I couldn't find a definition in the doc.

Yes, one (optionally) stages files into the index with "git add" in
order to commit them with the next "git commit" operation. Or instead,
don't bother with that and just use "git commit -a" to commit all
changed files.

> -Some commands don't seem symmetrical: for example, git add will 
> either add a file to the index or mark a modified file for the next 
> commit.

I agree this can be confusing. Historically, updating the content of
an existing file in the index used the command "git update-index"
which was definitely a fairly awkward name, (and had even more awkward
usage associated with it). The decision was made to document the
existing "git add" command as the way to stage changes into the
index.

From a technical level, this actually makes sense---whether the file
is new or not, "git add" always shoves the content of the file into
the index. But I'm with you on this one. I think "add" should have
been documented for adding new files and that something else, ("git
stage" perhaps), should have been the command to stage content of
known files into the index.

But then, I also argued that the behavior of "git commit -a" should be
the default behavior of "git commit", and that if a user explicitly
wanted to commit staged content that differed from the current then
the command to use would have been something like "git commit
--staged". But I lost that debate.

So I'll agree with you that some of git's user-interface is less than
ideal, but I don't think any of it is bad enough to outweigh all the
benefits.

> -In switching branches, it seems that you can't have any uncommitted 
> changes?

No, it will carry your uncommitted changes along just fine, unless the
same files were also modified in the branch you're changing to. And in
that case, you can _still_ carry changes while changing branches with
"git checkout -m", ('m' for 'merging' changes).

> -I just miss a good GUI like Perforce's one to see in a glance 
> everything about your project.

Me, I've never really wanted a GUI for actually interacting with the
system, (that is for making new commits, etc.). I have found that
visualizing the graph of commit history with a tool like gitk can be
extremely valuable.

There are some people that really like GUI-integration for their
source-control systems, (there's some "tortoise" named thing that
seems to be popular, and there's stuff in eclipse as well). I can't
imagine it would be at all hard for anyone motivated to do that kind
of thing for git. And I imagine people already have. I just don't know
anything about it.

> Anyways, these might all be "Git newbie" issues, but the fact that I 
> didn't encounter these issues with other SC software suggests that 
> Git is indeed harder to use. I do appreciate though it might have 
> unique features that make it the only tool for the job. My experience 
> might be also worse because I'm using it on Windows through Cygwin 
> and can't use any of the GUIs available.

Ah, you said Windows/Cygwin here. You should try the msysgit port and
see if it isn't any smoother, (I have no idea what GUI stuff it might
include).

Thanks for your detailed questions,

And do have fun hacking on cairo (in spite of git for the time being!)

-Carl
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.cairographics.org/archives/cairo/attachments/20080110/483be121/attachment.pgp