Git Information

 

PDF of an email from John Liss with Git Instructions. This should give the general steps to get things setup. IT is a little dated, but most concepts still apply even if the screens have changed some.

Git instructions.. step by step

 

 

Tools

Git libraries.

Git SCM

TortoiseGit is the primary repository integration tool many of us use. This allows you to make commits, view history, etc. without having to use the command line tools in Git itself.

TortoiseGit

TortoiseGit Manuals

Visual studio also has support within it for Git and there are also many other plugins that provide integrations as well. You are welcome to use whatever you like and are comfortable with.

Branching practices

The general idea is that the master branch is, tracking the development for the next version. It’s stuff that’s going into the product, and will be included in the next version unless something is found to have an issue in testing.

(a) You should not commit stuff to your master branch. You should keep it up to date with the real master and make branches off of it for any new work your do. When you first decide to do work on Vixen, you would fork the master at all/master to your own copy of it. You should be able to build and get a running version of Vixen from that is current. Then you can easily make branches from that to work on. Tools like TortoiseGit make it easier to mange changing branches and committing work.

As a maintainer, even I do not commit any work directly to the master branch. All commits on the master branch are actually merges of work from other branches.

(b) Most work should be done based off of a ticket in the bug tracker. When you take on work for a particular item, you should create a branch off of the current master and name it the same as the ticket you are working on. I.E. VIX-1024. This provides a clear reference back to the description of the problem or feature. In addition to this, try to reference the ticket number in your commits as well. This will allow those commits to be linked to the ticket as well when they are eventually merged into the master.

(c) If the item you are working on will span some time and the current master gets updated with new features from other developers, you can keep your branch in sync by rebasing your changes onto the current version of the master. You would sync your copy of the master from the Vixen Git tree first. Then you can rebase your branch onto that. This will replay your commits onto the tail of the master giving you a up to date branch. Try to avoid merging the changes in the master into your own branch as this creates a messy commit history.

(d) If you are collaborating with another developer, then you may want to share work on a branch. Here you can both work on the same branch shared publicly or you can merge changes between yourself. This is not very common in our development structure so ask questions if it comes up and we can help guide you through it.

(e) If you want to have a play with someone else’s branch (to test, or add features to it), as long as they have pushed ac copy of it out to heir public repository, then you can always make your own branch at that point, and go from there. For example, Jeff might take a look at Gizmo’s “VersionControl” branch, and make a new one for himself, called “Jeffs_VC_additions” or something. He can do some more work to do with the version control, maybe updating stuff, adding a new feature, etc. Then, if Giz likes it, he can merge from Jeff’s VC branch back into his own VC branch! (since it’s all separate to ‘master’, he can do what he likes with it.) Once al the work is done between the two developers, the version with all the changes compiled together can be merged into the master.

(f) When work is complete on a branch, That branch should be pushed to your public repository. Then the ticket tracking it should be moved into the ready for merge status. This is my cue to go review it and either provide feedback or merge the changes. You should provide the information on the location of your GitHub repository so I can connect to it and pull the branch. If you made the branch name the same as the ticket it is easy for me to find it once I establish the path of your repository.

 

Bill’s email with Git Notes

I created a fork of vixen, another user makes a comit, and that is merged into the main repo…. Do I need to refork to have my fork match the main repo ?
The thing that took me a while to really understand with Git is that all the repos are ‘equal’ in terms of status.  None is more privileged than another. However, solely by consensus, here we all agree that (sall/master) ‘master’ branch on Github is the ‘official’ one.  It is the one that ‘official’ builds get done from.  It sounds like you’ve already got yourself set up with two repos:  The one on Github that you forked from sall/master and the one on your local machine that you ‘cloned’ from your Github repo.  Again, by convention, the only thing we use our Github repos for is sharing with others (easy because they are hosted on an easily accessed server… if you local machine was easily accessed by others for sharing you wouldn’t really need your Github repo.   Once you have forked from sall/master, you never need to ‘fork’ again (unless you blow away you Github repo and start over).  This might just be a personal style thing but I only ever modify my Github repo by ‘pushing’ to it from my local clone of it.
I made changes and pushed a comit… Then decided I should have done something alittle extra… The changes are shown as deletions or additions in my fork,
if I make a change and push it again, are those previous changes now going to be considered ‘the way it was’ and no longer be marked, and only have the most
recent changes marked ?
Each commit you do, is self-contained and is relative to the last state of that branch.  So if you do another commit, it will be relative to the state created by the previous commit.  Others can see both commits individually and could even choose to merge only one of them to their stuff (though that is less common).
One of the things you’ll want to do is set up some ‘remotes’ on your local repo. When you did your clone of your repo you got a ‘remote’ for it that pointed to you Github repo ‘for free’.  For sure, you’ll want to add a remote for sall/master on Github.  If you want to try out stuff from the rest of us before the maintainer merges our stuff into his master, you may want to set up remotes for some of us as well (I’d recommend just starting with sall/master for now… once you start doing your own merges from others, the branching and merging get more complex… there are more conventions to help simplify this).
Oh, and no Git post would be complete without the obligatory shout out to TortoiseGit – it makes doing some of these tasks much easier for me.