----------------------------------------------------------------------------
WARNING:  This use-case is *NOT* ready for general use yet.  More work-flow
testing and documentation is required before this use-case is really ready
for the general PLplot developer public.  If you're interested, and have the
emotional fortitude for some turbulence, feel free to contact me (Geoff)
privately and let me know your experiences with this use-case.  I'll remove
this warning message when I'm a little more satisfied that it's "safe" and
behaves in a comprehensible manner, and have documentation here to explain it
in a reasonably self-contained manner to non-git folk.  At that point, I'll
advertise its availability on pldev.
----------------------------------------------------------------------------

One very basic thing one might like to do during svn-to-git transition
planning, is to have a git repository which "tracks" the official PLplot svn
master repository.  This is accomplished using the git svn gateway system.
In case 1, we examine a specific, stylized way to do this.

1) Make sure you have the necessary commands on your system.

[Somebody fill in comments on the svn client itself]

Obtain git.
    On Fedora 11:  yum install git-all
    [Need guidance for other systems, especially non-Linux systems]

Note that in older versions of git (1.5.x and prior), there were many
commands with names of the form git-xyz installed.  In git 1.6 this practice
is dropped.  Instead, there is just the git wrapper command, and all git
subcommands are activated by passing the sub command as the second token on
the command line.

With specific reference to the git-svn gateway, in git 1.5.x and prior this
was called "git-svn", but in git 1.6.x+, it is invoked as "git svn".

Note that in older versions of git, the git program was able to find the
scripts (or executables) for its subcommands.  So "git svn" worked in both
old and new git (if you had the git svn gateway installed).  But in git 1.6
and beyond, you have to say "git svn", as "git-svn" is no longer recognized.

2) Obtain the files in this directory (plplot/git/case-1) and place them in
   your directory structure at the point where you want to create a git
PLplot repo which is a gateway to the svn PLplot master repo.  For example:

% ls -l ~/plplot/t3
total 16
-rwxr-xr-x.  1 furnish xxxxx  136 2009-03-27 07:25 pl-make-svn-gateway
-rw-r--r--.  1 furnish xxxxx 1133 2009-03-28 19:51 svn-authors

3) Run the pl-make-svn-gateway script:

    % ./pl-make-svn-gateway

This takes quite a while.  Exact times depend on your internet connection
bandwidth.  But for a good DSL-grade connection in North America, figure on a
few hours for this to run.  If it errors out for any reason, just run it
again and it will pick up where it left off.  This happens sometimes,
apparently due to network spasms.

ALERT: Please be assured that the time to perform the initial setup of this
svn gateway git repo is not indicative of the timescales for your normal
day-to-day operations with git.  Generally speaking, git is /very/ fast
compared to other source control systems, for essentially all common
operations.  The explanation for the long run time of the git-svn import step
is that svn does not store all the version relationships that git is looking
for in a useable manner, so the git svn clone step has to do a bunch of
analysis to discern things that can't be querried directly using the protocol
spoken between svn clients and servers.

Research topic:  It might be interesting to see if there's a way to speed up
this step by rsync-ing over the PLplot master repo, and then doing the git
svn clone on a local disk, without further use of the network.  But note that
we would want the resulting git repo to know that it's upstream URL is the
master svn repo, not the rsync'd local copy.  Seems like it should be
feasible, but there's probably a bit of work needed to figure out exactly how
to do this correctly.

4) Examine what you got:

cd plplot
git branch -a

[Add more comments about the output from the above, what it means, and why we
did it that way.]

5) Make yourself a git working (aka "topic") branch which tracks the svn
   trunk. 

git checkout -b w_trunk svn/trunk

6) Edit/commit in the usual git way.

7) Pull in changes from upstream:

% git svn fetch
% git svn rebase

8) "Push" up the local changes to the svn master repo.

% git svn dcommit

Then watch for the commit notice to propagate to plplot-cvs.

----------------------------
Working with a repo that has been setup by git svn

[Fill this in.]


----------------------------
Issues

1) git svn --authors-file gone stale

We know that if you are running the svn import ("git svn clone ..."), with
the --authors-file=<filename> option, and git svn encounters a commit by
someone not listed in the authors-file, then git svn import (clone) balks.

    Aside:  If that happens to you, what you need to do is update the
    authors-file with the new biographical entry or entries, and then rerun
    the git svn clone step.  It will continue where it left off.  There is no
    need to rm the under-construction repo and start over from the
    beginning.

Question:  What if your authors-file is up to date at the time you run the
repo import, but then new team members make new commits to the svn master?
What happens when you next do a git svn fetch?

Answer:  Not yet completely clear.  Some careful tests are in order.  But one
thing is clear, git svn fetch is not looking in the authors file, and does
not stop the way git svn clone does when there's a mising entry in the
authors file.  So it would seem then that the git svn fetch is clearly
producing a repo that is in some ways different than if you did a fresh
clone.

To me, this seems quite contrary to the "git way", and is yet another reason
to be irked with the whole git svn approach to mirroring an svn repo.
