Git - using
git is used to track changes to the source code of fluxbox during development. This is a small overview over the most important commands and work flows important to the developers.
The fluxbox developers encourage you to use git and help developing / improving fluxbox, no matter if you code or help out with the documentation or with the translation or whatever.
Fetch and build
To get your very own copy of the whole fluxbox repository (including the complete history) you have to clone the repository:
$ git clone git://git.fluxbox.org/fluxbox.git fluxbox.git
After this step you can cut off the network, you can develop completely without any connection to the world. To keep in sync with the latest "official" code just do
$ cd fluxbox.git $ git pull
If you plan to change the code then:
$ git config --global user.email Your.Email@domain.com $ git config --global user.name "Your Real Name"
so when you sent us patches your name will show up in the repository correctly (and we can point fingers if something crashed :))
Use your beloved editor and change the code, '
git-mv' to rename files, '
git-add' to add new files, '
git-rm' to remove files from the repository. Check the current status of the working copy with
$ git status
Every change you did is transfered to the repository the very moment you execute
$ git commit
and this is transfered only to the current 'branch' you are in right now.
Branching and Merging
Branching and merging is very powerful in git. You can create thousands of local branches, one for each bug you work on or feature you implement. It is good practice to do this because it safes your from accidentally pushing changes to another repository.
Creating and removing a branch
You create a branch 'bugfix123' from the 'master' branch:
$ git checkout -b bugfix123 master
If your are done with the branch:
$ git branch -d bugfix123
After that the complete branch is gone.
Another option for creating branches is to create a new clone; you can clone from your local repository as well:
$ git clone fluxbox.git big_rewrite.git
For big changes this could be a good method to keep the working directory pretty clear from the leftovers of other branches.
Show all local branches:
$ git branch
Show remote branches:
$ git branch -r
Switch between branches
To easily switch between branches:
$ git checkout 'branchname'
When you are done with the changes for the bugfix or the new feature, it's time to merge some branches. Even when you are working in a branch on a bugfix and the 'master' branch evolves, it's time to merge to reflect the latest changes into the current branch:
$ git checkout to_check master $ git merge --squash --no-commit bugfix123 $ git commit
Git would squash now all the 100 commits to your local branch 'bugfix123' to appear as ONE big commit. This way you can even work with your 'own' revision control on the bugfix without ending up with commit messages as fine as « what the f... is wrong here? » in the official repository.
Exchange patches / code
Especially for 'rogue' developers, it is important to give back the changes they made to the core developers somehow. To create a nice patch, use:
$ git format-patch -C -k --stdout master..to_push > bugfix123.diff
Which would put all the changes made to fix the 'bug123' into the one file you can mail or attach to the issue tracker. In case you once receive such a patch, you can apply it with:
$ git applymbox -k bugfix123.diff
Another way would to exchange chunks of code would be to create a bundle (compressed patch):
$ git checkout to_check master $ git-bundle create bugfix123.bdl master..bugfix123
Which could be applied with:
$ git-fetch bugfix123.bdl bugfix123:check_bugfix123
This would create a new branch 'check_bugfix123' where one can check if the bugfix really works.
- tig is a nice ncurses based git-viewer.
Links and further information
Learn more about git: