[Kst] git recipe

[Peter Kümmel]

> I am in favor of us switching to github since it is by far the easiest thing
> for us to do.
>
> In preparation for this, Peter: could you write some quick instructions for
> what we should do, (like the lines we type to 'checkout', 'update' and
> 'commit' (using svn words and concepts)  including a description of the
> workflow you currently use.
>
> My impression is that there are a number of different approaches one can
> take...

Yes, there are many possible workflows, but for Kst I would propose the same
as for svn: everyone just commits to trunk (master in the git slang).

As already mentioned one could proceed using subversion, would be the simplest.

When you wanna use git there are many manuals, e.g.
"Git - SVN Crash Course" http://git.or.cz/course/svn.html
or the official documentation
http://git-scm.com/doc
and there are a lot of hits when searching the web.


When you wanna start using git it is worth to invest some time at the
beginning to understand the basic of "distributed version control system":

There are for levels:

I.
Remote repositories on an arbitrary server or filesystem
e.g.
git at github.com:Kst-plot/kst.git
git at github.com:syntheticpp/kst.git


II.
Complete copy of the remote repository on your local file system
or a repository which exists only locally
Managed by git in the .git folder
"git remote" lists the repositories


III.
ONE local repository, initially a 1:1 copy of the remote repository with complete
history.

IV.
Checked out files on the local filesystem are a branch or a specific commit
of a local or remote repository.


The git commands:

git clone git at github.com:Kst-plot/kst.git
Makes a complete copy of the listed repository, the repository has the name "origin" by 
default. Also a checkout of master is done automatically.

"clone" is short for

git init // create empty git repository:
git remote add origin git at github.com:Kst-plot/kst.git  // add remote
git fetch // download remote repository
git checkout -b master origin/master  // create branch "master" on local filesystem and 
checkout the branch "master" of the copied repository


You commit against the local repository:
git add >files<    // mark all files which changes should be committed
git commit -m"Message" // or use -a to commit all changes, new files still need the add 
command


After a commit the local copy of the branch is different to the one on the server.
To update branch of the repository on the server:
git push origin master

mostly "git push" is enough.


When the branch on the server has changes push fails, because there could be conflicts.
Resolving conflicts:
git fetch    // update copy of remote rep.
git rebase origin/master  // - temporary undo all local commits
                              - update the local branch
                              - commit local changes again on the updated repository
Short form: "git pull --rebase"

When there are conflicts you could edit the commits.

Also
git fetch
git merge origin/master
updates the local repository, but then you get ugly commit messages in the history.
Short form: "git pull"



Contrary to most of the git tutorials I suggest to use git only with the low level
commands at the beginning (e.g. git fetch, git rebase, instead of git pull) because
the you learn what's going on in the background, and git doesn't look like a black box,
which does crazy things.

Peter