From fd3eb826cb259a09e6eda03d0a94bd7023aa93a4 Mon Sep 17 00:00:00 2001 From: Jonas Kivi Date: Thu, 29 Nov 2007 14:14:45 +0200 Subject: [PATCH] Wrote the README_GIT file to be a proper tutorial on git, repo.or.cz and gtkD. --- gtkD/README_GIT | 351 +++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 244 insertions(+), 107 deletions(-) rewrite gtkD/README_GIT (72%) diff --git a/gtkD/README_GIT b/gtkD/README_GIT dissimilarity index 72% index 50b0039..72847b4 100644 --- a/gtkD/README_GIT +++ b/gtkD/README_GIT @@ -1,107 +1,244 @@ -This is the public mob branch that you can push to. I created this file to test it myself. - - - -And here's a brief intro on git, which I really don't know how to use yet: - -Install git (1.5 or newer). - -First you should set your user name and info with: -[code]git config --global user.name "Your Name Comes Here" -git config --global user.email you@yourdomain.example.com[/code] - -[b]Changing the default commit message editor[/b] - -Open /home/youruser/.profile with a text editor. -Add the line -[code]GIT_EDITOR=/usr/bin/nano[/code] -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 geany 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. - -[b]Pulling from repo.or.cz[/b] -Go to your favorite programming directory on the command line and: -[code] -mkdir gtkD -cd gtkD -git clone git://repo.or.cz/gtkD.git -[/code] -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: -[code]git branch[/code] -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. - -[b]Making your own local branch[/b] - -First make a new branch called mob. It will be based on the master 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.) -[code]git checkout -b mob[/code] -OR -[code]git branch mob -git checkout mob[/code] - -Now you can see what branches you've got and where you're at with -[code]git branch[/code] - -Create a file with some text editor. For example yourfile.d -Add it to your branch (so that git will track it). -[code]git add yourfile.d[/code] -You'll have to commit it to your new local branch. Otherwise it will get lost when you change branches. -[code]git add yourfile.d[/code] -At anytime you can do -[code]git status[/code] -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 repositories, that is called pushing.) -So let's commit this. You'll have to commit your changes before switching branches, or otherwise they'll get lost. -[code]git commit -a[/code] -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. -[code]git status[/code] -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 -[code]git status[/code] -to see some brief info on what you've done. And -[code]git diff[/code] -or -[code]git diff --cached[/code] -to see some more info. (Press Q to quit that strange viewer.) - -Commit it with -[code]git commit -a[/code] -and type in the commit message. - -You can use -[code]gitk[/code] -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. - -[b]Merging your changes to your local master branch[/b] -After you've committed all your changes switch to the master branch with -[code]git checkout master[/code] -Then merge the mob branch with your master -[code]git merge mob[/code] -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 mob branch then it should be fine. -If you'd have done some little feature with your mob 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): -[code]git branch -D mob[/code] -Or there's -[code]git branch -d mob[/code] -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. -When you've got master 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 master (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 master. - +_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 + -- 2.11.4.GIT