NifTools/Using Git

From NifTools
Jump to: navigation, search

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.

Contents

Getting Git

Windows

  • 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

cd Documents

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 johndoe@example.com

Linux

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):

http://github.com/Alphax/nifskope

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 git@github.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,niftools@niftools.git.sourceforge.net/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

Git Commands

First, after starting Git Bash, remember to cd into the directory of the project that you want to work on. For example, for nifskope:

cd Documents\nifskope

You can now type any of the git commands for this project.

Browsing the Project History

gitk

Listing all Branches

git branch

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:

git pull

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:

git push

and don't forget to drop us a line! ;-)

Further Reading

Personal tools