Moving xlibs modules to xorg

[Carl Worth]

On Mon, 6 Mar 2006 00:59:07 +0200, Daniel Stone wrote:
> 
> There's no concise git-in-two-minutes I can refer back to from that.
> 

I'm not much of a party to xorg tree-management discussions---I
haven't contributed much code to xorg recently, (though I do want to
get fb and pixman to start sharing common source files soon).

But I have made some effort toward understanding and explaining git to
others. And I've written a couple of git-in-two-minutes things, which
I included below in case they are useful.

This was adapted from my introduction of git to the cairo community,
which can be seen here:

	http://lists.freedesktop.org/archives/cairo/2006-February/006335.html

I've made a couple of tiny updates, and tried to generalize it away
from cairo-specific URLs a little bit.

-Carl

How to commit to a git-based repository in a central, cvs-like way
------------------------------------------------------------------
I think cogito is the best tool to use to make the migration from cvs
as easy as possible. It's little more than remembering to type 'cg-'
instead of 'cvs '. (Hey, you get to save one keypress per command and
you gain tab-completion!).

To get started, first you will need to clone the repository from a URL
that provides write-access (such as one using the git+ssh protocol).
The command is of the form:

	cg-clone <URL>

For example, committers to cairo's tree would use:

	cg-clone git+ssh://git.freedesktop.org/git/cairo

Then, development looks a lot like it does with cvs:

	# edit some stuff
	cg-add new-file
	cg-rm old-file
	cg-status
	cg-diff
	cg-commit

The only big change is that the cg-commit just makes a local commit,
(and this is a huge feature---you can now do all the offline commits
you want). So to actually push your new commits out the the central
repository, you need to remember to do:

	cg-push

Updating is, as expected, as simple as:

	cg-update

I personally haven't done a lot of merging yet with cogito, but the
cogito author promises that it will just tell you what to do and that
everything in cogito is designed to make the migration for cvs as easy
as possible:

	Cogito turbo-introduction
	http://marc.theaimsgroup.com/?l=git&m=113996590313352&w=2

WARNING: It appears that cg-commit is happy to commit files with
conflict markers left in them. This may be surprising to users of cvs.

How to use git to commit to a repository in a central, cvs-like way
-------------------------------------------------------------------
I said before that cogito is likely the best tool to use for someone
that just wants to commit to cairo in a central, cvs-like way.

But it's not really any harder to use the git client to do the same
thing. There's a bit more variation from cvs in the command naming,
and there are some additional conceptual underpinnings to some of the
commands (there's a learning opportunity here).

But you don't have to learn any more to get started. First clone the
repository with git, and using the git+ssh protocol. This command
requires a project-specific URL and is of the form:

	git clone <URL>

For example, committers to cairo's tree would use:

	git clone git+ssh//git.freedesktop.org/git/cairo

Then, development looks a bit like cvs, but with a couple extra
command-line arguments here and there:

	# edit some stuff
	git add new-file
	git status -a
	git diff HEAD
	git commit -a

Notice that there is no equivalent to "cvs rm" here. When you use
"git commit -a" file removals get picked up automatically.

As mentioned in the cogito example above, with git the commit happens
locally, so there's an extra command needed (compared to working with
cvs) in order to push things out to the central repository:

	git push origin

And to get other people's commits from the central repository, there's
a corresponding command:

	git pull

This does a similar job as "cvs update" or "cg-update" but it has a
name that matches git's push command quite nicely.

It can happen that git pull results in a conflict, and it will put
conflict markers in the local files. In this case git status will
indicate that files are in an "unmerged" state. Once the conflicts
have all been manually resolved, you can "git commit -a"
again.

WARNING: It appears that "git commit" is happy to commit files with
conflict markers left in them. This may be surprising to users of cvs.

For a bit more on working with git, you might see the following
tutorial:

	A tutorial introduction to git
	http://www.kernel.org/pub/software/scm/git/docs/tutorial.html

===

PS. The introductions above are geared toward using git with a single
branch of a central tree, (similar to how cvs is often used). I think
this is the right kind of information for people nervous about
switching from cvs. But you did also (implicitly) ask another
question:

>                   ... Even after that, I still can't tell you how to
>     make a branch in git, do some development in it, and merge to
>     mainline.  Ho hum.

Which is easy enough to answer after someone has the context of the
introductions above. Here's a quick version:

	# List available branches
	git branch

	# Create and switch to a branch based on the current state
	git checkout -b my-branch

	# Hack a bunch, commit a bunch

	# Switch back to master branch
	git checkout master

	# Merge/pull in the changes from my-branch
	git pull . my-branch

	# Push the new master up to the central repository
	git push

After which the documentation of git itself should be quite
satisfactory at completing the picture. Each command has a fairly
reasonable man page, (named git-branch, git-checkout, git-pull,
git-push, etc.)
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <http://lists.x.org/archives/xorg/attachments/20060306/e62969a2/attachment.pgp>