Git is a revision control system for keeping all the members of a programming project in sync. Essentially, git makes it extremely easy for people to share changes and to work jointly on the same files. You'll want to use git,
- if you want to get the latest bleeding edge code that may not be fit for release—if it fixes a problem you have right now and you don't want to wait for the next release—or,
- if you want to contribute to niftools—by using git, you make it extremely easy for yourself to keep track of the official niftools code, and you make it also extremely easy for us to track your changes and to incorporate your patches into the official code.
- First, download and install msysgit.
- During install, enable Create a Desktop icon, Add Git "Bash Here", and Add "Git Gui Here" in the Select Aditional Tasks window.
- Leave the default Use Git Bash only.
- Leave the default Use Windows style line endings.
Once git is installed, start Git Bash, and type
cd My\ Documents
on XP, or
on Vista. Now you can start typing various git commands to clone existing codes, fetch changes from other developers, merge their changes with your code, publish your code online, and so on.
First, you'll want to inform git of your name and email address (you only need to do this once):
git config --global user.name "John Doe" git config --global user.email firstname.lastname@example.org
On any recent version of Fedora, simply type:
su -c 'yum install git git-gui'
and configure your name and email address as above.
Cloning the Source Code
Read-Only Git Clone
In case you simply want the latest source but not do any actual development, type for example in Git Bash (Windows) or in a terminal (Linux):
git clone --recursive git://niftools.git.sourceforge.net/gitroot/niftools/nifskope cd nifskope
This will give you a read-only clone (the --recursive option is required to get all submodules) of nifskope. For the other projects, simply replace the git://... url appropriately:
git://niftools.git.sourceforge.net/gitroot/niftools/blender_nif_scripts git://niftools.git.sourceforge.net/gitroot/niftools/maya_nif_plugin git://niftools.git.sourceforge.net/gitroot/niftools/max_nif_plugin git://niftools.git.sourceforge.net/gitroot/niftools/niflib git://niftools.git.sourceforge.net/gitroot/niftools/nifskope
The niftools git repositories can also be browsed.
Read-Only Svn Clone
If for some reason you prefer to track the code with Subversion, then it is actually possible to check out the clones on github with a subversion client (such as TortoiseSVN). The relevant subversion repository links for each project are:
http://svn.github.com/amorilia/blender_nif_scripts http://svn.github.com/amorilia/niflib http://svn.github.com/Alphax/nifskope
and for the subprojects:
http://svn.github.com/amorilia/kfmxml http://svn.github.com/amorilia/nifxml http://svn.github.com/amorilia/nifdocsys
Note that, with this method, you won't get the subprojects automatically, so you will have to set those up separately. For qhull (used in niflib and nifskope), there is no svn repository, so you will have to download it from gitorious and extract the code manually.
Writable Git Clone For Collaboration
However, if you plan to work on the source code of any of the niftools projects, you should first create a fork on github, since we use github for code collaboration. For example, to create a fork from the current lead nifskope dev, go to the developer's remote clone of nifskope (note that you'll need to have a github account for this):
Click fork and follow the instructions. You should then make a local clone from your github fork (i.e. of your remote clone):
git clone --recursive email@example.com:username/nifskope.git cd nifskope
If you want to track other people's branches, say the development branches of Alphax, PacificMorrowind, and amorilia, type
git remote add alphax git://github.com/Alphax/nifskope.git git remote add pacific git://github.com/PacificMorrowind/nifskope.git git remote add amorilia git://github.com/amorilia/nifskope.git
You can then check for instance Alphax's work with
git fetch alphax gitk --all
and merge it with your work via,
git merge alphax/master
If you are on the niftools core team, you will want to add a sourceforge branch to push your changes back:
git remote add sourceforge ssh://username,firstname.lastname@example.org/gitroot/niftools/nifskope
and you would usually push your changes also to sourceforge (unless maybe for a 'risky' change which requires further review before being pushed to the official sourceforge repository)
git push; git push sourceforge
Of course, if you want to collaborate on the submodules as well, you should fork those as well on github.
Here is a list of main project repositories on github from which you can create clones:
http://github.com/amorilia/blender_nif_scripts http://github.com/amorilia/niflib http://github.com/Alphax/nifskope
and for the subprojects:
http://github.com/amorilia/kfmxml http://github.com/amorilia/nifxml http://github.com/amorilia/nifdocsys
First, after starting Git Bash, remember to cd into the directory of the project that you want to work on. For example, for nifskope:
You can now type any of the git commands for this project.
Browsing the Project History
Listing all Branches
Checking Out a Branch
To get the master branch, type
git branch checkout master
Some projects have multiple branches. For example, the Blender nif scripts have a blender24x branch to work on the older scripts for Blender 2.49b, and a master branch for Blender 2.5x. To get the code of the scripts for the older Blender, you would type
git branch checkout blender24x
Updating to the Latest Code
If your current origin points to the sourceforge read-only repository:
otherwise, if you are working on your own clone on github, assuming that you've named the remote sourceforge repository sourceforge, and you are currently in the master branch,
git fetch sourceforge git merge sourceforge/master
If you are interested in other remotes and/or other branches, then of course just replace sourceforge with the name of the remote, and master with the name of the branch.
Committing a Change
Suppose you've made a change to some existing files in a project. To commit this change, simply type:
git commit -a -m "<short description of what you did>"
If you added a new file, first type:
git add <name of new file>
before committing. Note that committing only saves the changes into your local repository.
Publishing your Changes
To upload your changes to your remote (i.e. online) repository on github (or elsewhere), simply type:
and don't forget to drop us a line! ;-)
- Git - SVN Crash Course A git crash course for subversion users.
- Pro Git: an introductory book on Git.