[gst-devel] GStreamer switching to git

[Rov Juvano]

On Thu, Jul 10, 2008 at 01:59:11PM +0100, Jan Schmidt wrote:
> [...] we need to make sure that
> there is sufficient support (wiki pages, IRC people) to help people like
> me who've hardly used git before learn (at least) the equivalents for
> the CVS commands I regularly use.

That last thought has lead to a lot of git haters.  You may
want to forget everything you know about revision control--it
could save you a lot of frustration.  Git is more like 'cp -r'
+ diff + patch than CVS.

The index (sometimes --cached) has been a stumbling block for
many git newbies.  The index can seem like a major design flaw
until you grok it.

I find it helpful to think of the index as a second working
tree, as if I:
  # cvs $repo co $module index
  # cvs $repo co $module working-tree
then edit files in working-tree, copy them to index, and
commit from index.

It may take you a while to see the advantages of this approach.
And while there are options that allow you to ignore the index
(e.g. 'git commit -a'), just about every git command interacts
with it, so ignoring it can cause you unnecessary strife.

One advantage of this approach but a trouble spot for noobs
is the third class for files: untracked.  By default all files
are untracked.  Once added to the index via 'git add', the
file becomes tracked until it is removed from the index via
'git rm'.  And like CVS, files can also be explicitly ignored.
With the above 'two working tree' analogy, 'git add' acts
like 'cp -r' from the working-tree into the index and 'git rm'
like 'rm' from the index and working tree.

Since most commands ignore untracked files, this can trip up
those who try to ignore the index.  This can be particular
troublesome with 'git diff'.

With nothing staged, the index is identical to HEAD giving
the false impression that 'git diff' defaults to diffing
against HEAD--wrong.  To diff against against HEAD, use
'git diff HEAD' but...

It also does not diff against the index, because it ignores
untracked files.  'git diff' defaults to showing changes the
working tree makes to files in the index.  Use 'git status'
to see which files have changed, whether staged, tracked, or
untracked.  Similarly, 'git diff <tree>' shows the changes
the working tree makes to files in the referenced tree, again
ignoring untracked files.

To diff the index against a tree, use 'git --cached <tree-ish>'.
When diffing two trees (e.g. the index and HEAD), untracked
files in the working directory are, of course, irrelevant.

Because most git commands interact with the index, understanding
it can save you a lot of heartache.

If the index trips you up, read the section "The Workflow"
of chapter 9 "Low-level git operations" in the git manual.
It goes into painstaking detail on how git uses the index.
Understanding the diagram at the end of this section can go
a long way towards grokking the git.

Other documentation I recommend:
  the documentation that comes with git,
  'git help <command>'
  GitWiki: (http://git.or.cz/gitwiki)
  Git Magic: http://www-cs-students.stanford.edu/~blynn/gitmagic/
  GitCasts http://www.gitcasts.com/ (particularly "RailsConf Git Talk")

Soon you'll know 50 ways to reference a commit and you'll
understand why git is called stupid.  Then you'll discover
'git rebase --interactive'.

--
rovjuvano