Wrote the README_GIT file to be a proper tutorial on git, repo.or.cz and gtkD.

[gtkD.git] / gtkD / README_GIT

_A short tutorial on git, repo.or.cz and gtkD_

Disclaimer: I really don't know how to use git yet, but this will give
you a start, as all the other tutorials are not so good.


Install git (1.5 or newer).

First you should set your user name and info with:
        
                git config --global user.name "Your Name Comes Here"
                git config --global user.email you@yourdomain.example.com
        


_Changing the default commit message editor_

Open /home/youruser/.profile with a text editor.
Add the line
        
                GIT_EDITOR=/usr/bin/nano
        
When you commit stuff with git, you'll automatically have to write a 
commit message with a text editor. The default is some wierd editor
without any info on how to use it, so that was a big hurdle on my way
to know how to use git. Now I'm using nano which is a commandline based 
editor, but with a clear UI. You propably could use any text editor 
like gedit or whatever. But nano is good, as it starts fast 
and you only need to write your commit message, and do CTRL-O to save 
it and CTRL-X to quit nano.


_Pulling from repo.or.cz_

Go to your favorite programming directory on the command line and:
        
                mkdir gtkD
                cd gtkD
                git clone git://repo.or.cz/gtkD.git
        
There's an awful lot of subdirs named gtkD at the moment, so excuse me 
for those. Not my fault entirely.

Go to the first subdir gtkD. And write:
        
                git branch
        
It will give you output like:
        * master
Where the star will tell you which branch you're on, and there will 
only be one branch called master listed initially. If you'd have more, 
all their names would be listed.

With
                ls -a
you'll see, that there's a subdir called .git. That has your whole
local repository and settings. (If you want to dig more into that
you should check some other online manual on git. The interesting file
to me has been .git/config which has the settings of this git repo.)

To see what remote branches there are (in repo.or.cz), you can do
        
                git branch -r
        
That will show you something like:
        origin/HEAD
        origin/master
        origin/mob

We're now interested in the mob branch. It's a special branch that is 
specific to repo.or.cz. They've made it so that if a project has a 
branch named mob, any user with the name mob can push their changes to 
that special branch. It will basically allow anonymous access, and 
therefore you should always be careful when executing code from the 
mob branch, as there could be just anything there. But if all goes 
well, it will serve as a kind of wikilike method for anyone to 
participate on the public repository, without asking me to give them 
permission. (You're ofcourse welcome to ask me, and I'll add your user 
that you've created on repo.or.cz to the list of people allowed to do
changes on the whole repo, if you want.)

So. How do we get a copy of that mob branch? Do:

                git checkout origin/mob
                git checkout -b yourlocalmob_name_it_anything_you_like

The first command will change you to the origin/mob branch, which is
the remote branch called mob in repo.or.cz (Got it?). Since we're in
that branch, the second command will create a new local branch with
the given name. So now you've created a local copy of the remote mob
branch and you've moved to that new branch.


_Making your own local branch_

Now you could make a new branch for your own development. It will be 
based on the localmob branch as that's where you're now. (This will 
basically replace the files you're working on, if you've done some 
changes and haven't run git commit -a.)

                git checkout -b yourbranchname

OR

                git branch yourbranchname
                git checkout yourbranchname


Now you can see what branches you've got and where you're at with
                git branch

Create a file with some text editor. For example yourfile.d
Add it to your branch (so that git will track it).

                git add yourfile.d

You'll have to commit it to your new local branch. Otherwise it will 
get lost when you change branches. 

                git add yourfile.d

At anytime you can do

                git status

to see what you're currently doing, and haven't yet committed. 
(Committing means committing to your local repository, which is 
basically the directory "gtkD/.git/". If you put something into the 
internet (remote) repositories, that is called pushing.) So let's 
commit this. You'd better commit your changes before changing
branches as otherwise you'll just get confused with "staging".
And we won't go into that here, so just do:

                git commit -a

If you replaced your git editor as I told you in the beginning, you're 
represented with a nano screen (or the text editor of your choise). 
Write some description of what you did and why. It can be long and 
multiline if you want it to be, or if you've done a lot of changes. In 
nano you can then do CTRL-O to save it. Press ENTER to confirm the 
writing on the file that it suggests. And CTRL-X to quit nano. Then it 
will make the changes to your current branch.

                git status

will tell you that there's no more changes. It will also tell you in 
red if you have files that are not tracked by git. You can have such 
files, you don't need to add all stuff into git. Those untracked files 
will stay unchanged when changing branches.

Make changes to a file or many files. Run
                git status
to see some brief info on what you've done. And you can do
                git diff
or
                git diff --cached
                
to see some more info. (Press Q to quit that strange viewer.)

Commit it with

                git commit -a

and type in the commit message.

You can use
                gitk
        
if you've installed gitk. It's a small app to visually see what you've 
done, and what branches you've got and how they were merged.

You could now delete that silly file called yourfile.d with:

                git rm yourfile.d

and do a commit on that too:
                git commit -a

         
_Merging your changes to your local master branch_

After you've committed all your changes switch to e.g. the master 
branch with
        
                git checkout master
        
Then merge the yourbranchname branch with your master

                git merge yourbranchname

I'm not going to cover problems here, so let's just assume that the 
merge was easy and went fine. If you didn't make any changes to master 
after making changes to your yourbranchname branch then it should be 
fine. If you'd have done some little feature with your yourbranchname 
branch then you might not need it anymore, and could just get rid of it
with (this will lose your code if it's not merged to some other
branch):
        
                git branch -D mob
        
Or there's
        
                git branch -d mob
        
which will make sure you've merged it to current branch before deleting.

Branches in git are cheap. You should branch often, but don't make it 
too complex for yourself. You could always have a development branch.
When you've got that in good shape, and want to start on a new feature,
just create a new branch, and work on that. Once you're satisfied with 
it, commit, change to the development branch (or some other), merge, 
and delete the branch. You could have multiple branches where you 
develop many features at the same time. Then you could make a branch 
just for merging them, and if that works ok, you could merge
it to your development or even your master.

You should test all this stuff a few times to get a hang of it. You
can then always start over in another dir (or there might be some
git command to do it for you) with git clone git://repo.or.cz/gtkD.git.
And when you've got some good or bad changes you could go into the
next level and push your changes to the remote mob branch. Please
do that if you've got any changes that you'd think others could
benefit from. There will always be the history of all the pushes,
so your changes can easily be undone, if needed.


_Pushing your changes to the remote mob branch in repo.or.cz_

                git push ssh://mob@repo.or.cz/srv/git/gtkD.git yourbranchname:mob

Will do it. yourbranchname:mob means 
localsourcebranch:remotedestinationbranch. So if you'd have permissions
you could write to other remote branches as well. Currently there's
just master and mob. The mob@ is the username. If you've got a user in
repo.or.cz and I've given you permissions, you could just replace that
with your username. (And ultimately you could edit your .git/config 
file and add your user name there in the ssh:// line, but I won't go 
into that here.)


Further reading:
http://www.kernel.org/pub/software/scm/git/docs/user-manual.html
http://www.kernel.org/pub/software/scm/git/docs/tutorial.html