Version 2 (modified by sc, 9 years ago) (diff)


Using Git for Puzzlebox Orbit software development

Git Workflow

Git is a popular revision control system, written by Linus Torvalds when he decided no existing solutions (such as Subversion, also popular with Open Source developers) were suitable for maintaining the Linux kernel.

The basic purpose of any versioning system is to allow specific points in ongoing development to be recorded and stored, with brief notes describing what was changed. If it was later discovered that some of the changes resulted in breaking another function of the program, each change which was "committed" could be rolled-back one by one until it was found and fixed. Several individual commits are expected in the course of developing any major new feature. This sequence also provides an "undo" capability to a developer if they find they have reached a dead-end and want to go back to an earlier "clean" version of their code.

Another key feature of Git and its brethren is the ability to create "branches" from a specific point or software version. A branch arranges all of their work to be isolated from the main repository, permitting them to work on their code and test their progress without affecting other developers who are working on their own features simultaneously. Individual changes can be committed to their branch and no one else will see it until the branch is finally "merged" back into the main tree. This "merging" process will require that any conflicts be resolved before it is accepted, meaning that if two people have been working on the same file or especially same section of code, the last one to commit (or merge) their changes would have to review and adjust for the latest version in the repository.

All of these features are present in other systems, however the unique benefit of using Git is that individual commits can happen on the developer's local computer. They are only uploaded and inserted back into the central repository when the "push" command is used. This permits more flexible independent development, including the ability to commit changes while offline.

Example Use

Let's consider a developer wishing to implement the "Hover Mode" feature from the Puzzlebox Orbit Roadmap:

Hover Mode

The first step would be to "clone" the Git repository for the Puzzlebox Orbit source code. (Other systems such as Subversion use the term "checkout")

Next, since this is a new major feature, the developer should create a new branch, perhaps calling it "Hover Mode" to match the roadmap name. Once created they will need to update their local working copy to use the new branch.

The developer would then begin about making changes to the code, specific to this feature. They might start by creating a new "Hover" button in the GUI and link it to a dummy routine which prints to log or reports to the screen when it has been successfully activated. Once this simple change is working, that would be a good point to commit changes to their branch. As soon as the "commit" command is issued, a text editor will appear asking the user to log what was changed. Good practice would be to describe what was changed in each file, with only one line per summarized change. These messages become crucial later when trying to trace where an error might have been made, especially for future developers trying to understand one another's code.

At any given point in the process, the developer may wish to "push" their changes back up to the server. This might be when they are preparing to change which computer or environment they are working from, or if they simply wish to have a backup copy made of their changes. Because they are working on their own branch, there is no drawback to "pushing" code back to the central server and this is recommended if connectivity is available.

Finally, when the feature is finished and working, and the developer has both "committed" and "pushed" all changes back into their branch on the central server, they should begin the "merge" process. If no one else has been working on the same components at the same time, there should be no complications to this process. However if someone else has made changes to any of the same files, and especially to the same sections of code, it will be necessary for the developer to review all of the new changes and adjust their code before the conflicts will be resolved and the merge can be completed. This is another point where having good commit logs is beneficial to all.

Git Commands

  • Checkout source from Puzzlebox repository
    git clone git://
  • Get information about git repostiory
    git remote show origin
    git remote -v.
  • Create new branch
    git branch "<new branch name>"
  • Change to new branch
    git checkout "<branch name>"
  • Commit changes
    git commit
  • Change back to master branch
    git checkout master
  • Merge branch
    git merge "<branch name>"
  • Remove branch
    git branch -d "<branch name>"
  • Push changes to server
    git push

Submitting New Code and Patches

If you have a patch to submit we would request that you first send it to us directly as we'd like to moderate what goes into the repository for a period of time per each new developer. If all goes well we'll set you up with a user account that has direct write access.