-
Notifications
You must be signed in to change notification settings - Fork 10
Git Introduction
This page describes common git operations in relation to the iSENSE repository.
A git repository is a source control solution. With the help of github, and git's "remote/pull" capabilities, git is well-suited for multi-developer projects. If the last two sentences were confusing, read more about git before continuing on.
From a developer's perspective, the world contains the following:
- The isenseDev/iSENSE repository
- Your forked repository, called username/iSENSE.
- A local repository on your development machine, which should have a close to identical AMMP setup.
- AMMP = Apache MySQL, MongoDB, Php5.
Before we go on, let's define push and pull. By push, it is meant that you are pushing changes from your repository to another repository. By pull, it is meant that you are pulling changes from another repository into your own repository.
You will only ever push to (2) Your forked repository. You might pull from your (2) forked repository if you plan on using multiple development machines. You will pull constantly from (1) the isenseDev/iSENSE repository.
To do much of anything you'll need your own fork. Gone are the times where changes are made directly to the live website.
To create your own fork, you must navigate to http://github.com/isenseDev/iSENSE and click the "fork" button in second to top bar in the top right of the screen. This will create your very own fork.
Next do the following:
Next you need to create a repository on your local machine.
To do this, you pick a place to store said repository, and then run the following
git clone git@github.com:yourusername/iSENSE.git
In order to keep your fork up to date, you will want to keep track of the main repository you forked from. To do this, we add what is called a "remote".
git remote add upstream git://github.com/isenseDev/iSENSE.git
Before you go on, you'll want to set up your local copy of the underlying website machinery (The servers and databases primarily). In order to do this you must also have an account on the iSENSE server so that you may download a copy of the database. Please contact James Dalphond or Michael McGuinness for help with this.
To clarify this, lets examine the work flow.
Before you go on, you should understand the idea of a branch. If you don't, take a minute and google git branches and read until the following makes sense.
isenseDev/iSENSE contains a stable, working branch called master. Your forked repository and local copy contain this as well. The point is to keep this branch functional and unmodified so you have a clean copy of the site easily accessible.
The first thing you would do before beginning work would be to make sure you have most up to date code, which is stored in isenseDev/iSENSE.
First, make sure you are on your master branch.
git checkout master
Then you pull any changes found on the master branch at isenseDev/iSENSE.
git pull upstream master
Notice the use the 'upstream' remote that you defined in the last section. This avoids having to type upstream git://github.com/isenseDev/iSENSE.git every time instead.
After this command executes, you should have an up to date version of the main repository. You also will want to keep the master branch on your github fork up to date, to do that you now want to push master.
git push origin master
Notice the use of the remote name 'origin'. This refers to the repository you _origin_ally cloned from. Now you're almost ready to start making changes.
To keep the master branch pristine, you would now create a branch. It's a very good idea for the sake of organization to include the bug number(s) the branch is addressing in the branch name. Lets call the branch myBranch-6.
git checkout -b myBranch-6
*The command "git checkout" allows you to, among other things switch between branches, git checkout switches to branch . The -b option creates the branch and then switches to it.
At this point you should know what to do. Modify the code. If you feel like taking a break, or reach a point where you'd like to save your progress, run git status.
git status will list all modified files, and instruct you on how to proceed. To indicate you intended to save a change in a particular file, you would run.
git add *file*
or for multiple files,
git add *expression selecting files*.
To commit these changes use,
git commit
This will open an editor to make a commit message. Please make these messages reasonable descriptive and meaningful - the build manager should have a reasonable idea of what you've done after reading your commit messages. Save the message and quit to finalize the commit.
You can commit as many times as you want, and should always do so before switching off the branch.
Throughout the process, and before you declare yourself done with a bug, you should fetch the latest changes from upstream again (git pull upstream master from the bug's branch) and make sure everything is still working.
You would now make sure you have pushed your latest changes to your local fork.
git push origin myBranch-6
Once you are done making a change you feel is worthy of existence on the live site. The idea is to issue a pull request to the build manager. This tells them through github that you wish to submit your changes to the site. They would then act appropriately and merge the changes from your branch on your fork into the master branch in the isenseDev repository.
To issue a pull request, you navigate to your repositories address on github (http://github.com/yourusername/iSENSE), select the branch containing your bug fix, and click pull request at the top. You then fill in the fields describing what the pull request is intended to do, this should reference the issue number of the bug you are fixing, ie. issue #6 in our example. If your pull request is approved, the next time you run a git pull upstream master you'll be pulling your own changes that have been merged with the main repository. If your pull request is found lacking in any way, you will be messaged in some capacity by the build manager about what is unacceptable about the pull. You should address these concerns (again in the same branch) and push them back up to your github fork. There is no need to issue a second pull request - your first one will automatically update - though it might be a good idea to inform the build manager that you've made the requested modifications.