Working with Git ¶
Proword ¶
Echo utilises a modern Source Control Management (further only SCM) tool called git. It's quite powerful and has a lot of futures and thus may seem a little hard to work with from the start. That's why we provide this simple guide how-to work with echo-icon-theme's git repository.
Some basics ¶
Unlike some other SCM like cvs or svn, git is sort of decentralised since you work locally with full-featured repository in which you can even have local development branches, etc. That means you can do many changes to the repository when working offline and than just push the changes to the master repository, but it also means that
git commit
will make changes only to the local repository, unlike cvs.
Installing git ¶
This is the easiest step, since all you need to do (as root) is
yum install git-all
which will install the basic git commands as well as some useful extras (like simple gui that helps managing your git repository).
Copying the master repository ¶
Now that you've set up git, you need to copy the master repository so that you can make changes locally. In order to do so, navigate into a folder you'd like to keep your echo-icon-theme git repository in and issue
git clone ssh://git.fedorahosted.org/git/echo-icon-theme
which will make a exact copy of the master repository in your disk. After the repository is cloned, you can start browsing - it has normal directory structure and the only directory that has something to do with git, is the hidden .git directory.
Note: The command above expects that you have a working fedora account and you are member of gitecho-icon-theme group. We use this one, because it simplifies life a little more after you want to push your changes back to master repository - the ssh access is read & write. If you don't need to push your changes back or you don't have ssh access, you can use
git clone git://git.fedoraproject.org/echo-icon-theme
Setting up local branches ¶
Apart from master branch we also keep stable branches (for updates to stable echo-icon-theme releases) that can have different conent than the master branch. One of such branches is 0.3.x. On it we will show you an example how to set up a local branch that's keeped in sync with the remote one.
First go to the echo-icon-theme directory you just git-cloned and issue
git gui
A not so nice, but pretty usable app shows up ;-) You can even do your commits from there. But not yet. Now go to Repository -> Visualise All Branch History. Another window shows up. Try to play with it a little, if you screw up your repository, you can always start from scratch by deleting it and cloning it again (or restoring it from a backup copy, if you had done any). After you feel comfortable with it, find a branch you want to track localy (master branch is already tracked by default) - as an example we use 0.3.x. Right-click on the commit message and select Create new branch, as shown in the example image.
A pup-up windows appear. Fill in the branch name. It does not necessary need to be same like the remote branch name, but it is more convenient. See the example image.
Now you need to tell git to synchronise your branch with the remote one. Go to .git folder and open the config file in there. It should look similar to that:
[core]
repositoryformatversion = 0
filemode = true
bare = false
logallrefupdates = true
[remote "origin"]
url = ssh://git.fedorahosted.org/git/echo-icon-theme
fetch = +refs/heads/*:refs/remotes/origin/*
[branch "master"]
remote = origin
merge = refs/heads/master
Now add there a new branch section following the example of master branch. In our example the final config file will look like this:
[core]
repositoryformatversion = 0
filemode = true
bare = false
logallrefupdates = true
[remote "origin"]
url = ssh://git.fedorahosted.org/git/echo-icon-theme
fetch = +refs/heads/*:refs/remotes/origin/*
[branch "master"]
remote = origin
merge = refs/heads/master
[branch "0.3.x"]
remote = origin
merge = refs/heads/0.3.x
Switching between branches ¶
There are more ways how to switch between branches, we'll explain two of them which we think are most convenient. The first one is pretty straightforward, as it's done by simple git command:
git checkout
If you do not remember how you named the branch you'd like to switch to, another git command might be handy:
$ git branch
0.3.x
* master
As you can see in the example output, we have two branches - 0.3.x and master branch. The star notes which is the branch you are in now, in our case master. If you'd like now to switch to the 0.3.x branch use the git command mentioned above with the correct branch name:
git checkout 0.3.x
The second way is for command line haters ;-) Open again git-gui and let it visualise All branch history. Now find the branch you'd like to switch to, right-click on its label and select Checkout branch as shown in the example image.
Keeping your local repo in sync ¶
Before you make changes to your repository, it's good thing to sync it with master repository so that your local copy is up-to-date. Navigate to the main folder of your repository and issue
git pull origin
This should put your local repository to be up-to-date with the one on fedorahosted.org.
Commiting your changes ¶
Now you've got to the step when you want to commit your changes to your local git repository. First switch to the branch you want your changes to make to, then make your changes to the content of the repository (modifying/removing/adding files/directiories) and issue
git commit -a
Examine if everything is OK. If there are any untracked files which you want to commit, abort the commit (press :q! and hit enter to quit the vim editor) and issue
git add *
which would add the new files into git index. Try to commit once again, now everything should be OK. The default editor used for commit messages is vim. The basics you need to know in order to be able to easily make those messages are these:
- press i to enter into edditing mode
- press escape to quit edditing mode
- if not in edditing mode, press : to start command mode
- in command mode press q! and hit enter to exit without changes (in this case it means that you'll abort the commit)
- in command mode press wq and hit enter to save the changes (in this case it means you'll finish the commit)
You can later review the chages in the gui again, this time you don't need all branches history though, so issuing only
gitk
is just enough to visualise the current branch history.
Pushing your changes to fedorahosted.org ¶
Now this step should be again one of the easier ones. If you cloned the repository originaly using the ssh access, or had set up the origin (in .git/config) to the ssh address, simple
git push origin
is enough. If not, but have the ssh access, substitute the origin with the ssh address:
git push ssh://git.fedorahosted.org/git/echo-icon-theme
Learning more ¶
If you feel like learing more about git you can:
- play around a little with the gui's
- git help
- man git
- Official Git Tutorial
Posts
No comments:
Post a Comment