View Source

h2. GIT Remotes

Your remotes must be configured correctly in order to pull down changes from the ooici repository.  To check how your remotes are set up you can run:

'git remote \-v'

You should have an origin pointing to your fork on github, and an upstream which points to oceanobservatories on github, and should produce something like the following: 

origin &nbsp; &nbsp; &nbsp;https://<your github name>@github.com/<your github name>/mi-dataset.git (fetch)

origin&nbsp; &nbsp; &nbsp; https://<your github name>@github.com/<your github name>/mi-dataset.git&nbsp;(push)

upstream &nbsp; &nbsp; &nbsp; [https://github.com/oceanobservatories/mi-dataset.git (fetch|https://github.com/oceanobservatories/mi-dataset.git&nbsp;(fetch])

upstream &nbsp; &nbsp; &nbsp; [https://github.com/oceanobservatories/mi-dataset.git (push|https://github.com/oceanobservatories/mi-dataset.git&nbsp;(push])

To be able to push directly to gerrithub review, you should also add this review.gerrithub.io as a remote:

gerrit &nbsp; &nbsp; https://<your github name>@review.gerrithub.io/oceanobservatories/mi-dataset (fetch)

gerrit &nbsp; &nbsp; https://<your github name>@review.gerrithub.io/oceanobservatories/mi-dataset (push)

To configure these, you can edit them in the .git/config file in the top level directory of your git repository. &nbsp;

To add gerrit as a remote:

git remote add gerrit&nbsp;https://<your github name>@[review.gerrithub.io/oceanobservatories/mi-dataset|http://review.gerrithub.io:29418/oceanobservatories/mi-dataset]

To pull changes that have been made to the main repository into your working area,you should rebase them (not merge\!):

git pull \--rebase upstream master

If there are any conflicts merging, they will be given here. &nbsp;If there are, you will have to manually resolve them by going into the files with the conflicts and editing them (removing the added comments which mark the conflict areas)

h2. GIT Branching

Each task a developer is working on (i.e. each driver or bug fix) in git should be worked on in its own branch. &nbsp;By default, the master branch in git is selected, but additional branches can be created. &nbsp;It is best practice to not work on your master branch at all, and create different branches for each task you work on. &nbsp;

To create a branch, first set your branch to your master branch:

git checkout master

Before creating a new branch off master, it is good to ensure your local master branch matches that of upstream master:

git pull \--rebase upstream master

Then push any local master updates to your origin (your fork):

git push origin master


Now you can create your new branch based off the your local master which should be up to date.&nbsp; When you create a branch, it will use the currently selected branch as the baseline for that branch, so it is recommended that you make sure your master branch is up to date (with "git fetch upstream" then "git merge upstream/master"), then create the new branch while your master branch is selected.&nbsp;

You can create your new branch and switch to your new branch in one step or two.

Two step process:


'git branch <branch name>'

To switch to working on a branch:

'git checkout <branch name>'

One step process:

'git checkout \-b <branch name>'


To see which branch you have selected you can type:

'git branch'

which will provide a list of branches on your VM, with a star next to the currently selected branch. &nbsp;

'git status' will also display the currently selected branch on the first line. &nbsp;

To push a particular branch to github:

'git push origin <branch name>'

A pull request can be done directly from that branch, and after the code is pulled from there the code in that branch will be present in ooici. &nbsp;If the branch is no longer needed, it can be deleted. &nbsp;To delete just a local branch:

'git branch \-d <branch name>'

To delete the remote branch on github:

'git push origin \--delete <branch name>'

You can also merge branches with each other. &nbsp;To merge a branch into your master:

'git checkout master'

'git merge <branch name>'

If you have a change that was made in a commit on one branch that you would like to apply to another branch, without applying all the commits on that branch, you can use cherry-pick:

'git cherry-pick \-n <commit number>'

this will replay the change in the commit number onto the current branch, and stage that change

h2. Storing your changes

To see the status of your files:

'git status'

This can also be run in a less verbose manner with the '-s' flag. &nbsp;If you are handling conflicts it is recommended you view the full git status.

To stage your changed files:

'git add <filename>'

To commit all your changed files:

'git commit'

To add a commit message in one line, the \-m flag can be used. &nbsp;For example:

'git commit \-m "Changed feature X"'

*Never commit any changes to any extern submodules.*

To rename a file:

'git mv <old name> <new name>'

To remove a file from git (and from the filesystem):

'git rm <filename>'

To throw away changes to a file that have not been staged get:

'git checkout \-\- <filename>'

The git commit command only stores your changes in your local git repository. &nbsp;To get your changes onto git hub so others can view them you need to push them. &nbsp;

To push your committed changes from your virtual machine onto your fork of the github repository:

'git push origin'

This will push all branches. &nbsp;To just push a specific branch:

'git push origin branch_name'

To help in resolving merge conflicts, if an entire version should be selected, you can use the shortcut:

'git checkout \--theirs <filename>'

or

'git checkout \--ours <filename>'

to select either our version of the file or the other version of the file. &nbsp;

h2. GIT and Gerrithub Workflow


h3. Getting Started on a New Feature

First set your branch to your master branch:

git checkout master

Before creating a new branch off master, it is good to ensure your local master branch matches that of upstream master:

git pull \--rebase upstream master

Then push any local master updates to your origin (your fork):

git push origin master

You can create your new branch and switch to your new branch in one step or two.

Two step process:

'git branch <branch name>'

To switch to working on a branch:

'git checkout <branch name>'

One step process:

'git checkout \-b <branch name>'

h3. Getting Ready for Code Review

Before pushing your feature branch up to your git fork (i.e. origin), make your necessary feature branch changes via "git add/rm <file>".&nbsp;

*{+}Then execute a single commit.&nbsp; Do not commit more than once without using "git commit \--amend". &nbsp;(Unless using alternate workflow)+*

After doing your single commit or amending your prior first feature branch commit, execute the following commands to get your master branch in sync with upstream:

git checkout master


git pull \--rebase upstream master

git push origin master


Now switch back to your feature branch, and get your feature branch in sync with any changes upstream:

git checkout <feature-branch-name>

git rebase master

Perform any necessary steps to resolve merge conflicts if there are any.&nbsp; After resolving merge conflicts, you will need to execute the following command:

git rebase \--continue

Then run your unit tests and driver tests to ensure all of your feature branch changes are still working correctly.

Amend your last commit if changes were necessary to fix merge conflicts.


git commit \--amend

To push directly to gerrithub review (which requires gerrit to be set as a remote)

git push gerrit HEAD:refs/for/master

Doing this will generate a new review. &nbsp;When using https, the password is the one generated by gerrithub. &nbsp;You can view it in gerrithub Settings->HTTP Password, and must generate it by hitting the generate button if it is blank. &nbsp;

h4. Old Way (Thought to be Broken)


Now you are ready to push your feature branch changes to your fork (i.e. origin).

git push origin <feature-branch-name>


There should be no fast forward errors.&nbsp; If there are, we need to rework this GIT Gerrithub Workflow Wiki info.

Now go to github.com, select your fork and feature branch which was pushed, and issue a pull request.

Now go to gerrithub.io, and select the "Github" link, select the "Pull requests" link and de-select all pull requests that are not yours.&nbsp; Ensure your pull request is selected.&nbsp; Select the Next button.&nbsp; Your pull request will be imported into Gerrithub.&nbsp; Select Next again.&nbsp; Your code review should be displayed.&nbsp; Add participants to your code review, and wait to receive comments.



h3. Code Review Updates

Select the applicable feature branch which was used for the initial code review submission.

git checkout <feature-branch-name>


Make all necessary changes, run unit tests and driver tests to ensure good results.


After making all necessary updates based on code review comments, execute "git add/rm" commands to add or remove file elements required to resolve comments.


Now it is time for you to commit your changes.&nbsp; Obtain the change ID associated with your code review from Gerrithub.&nbsp;&nbsp;

Execute the command supplying the Change ID as the last line in your commit message:

git commit \--amend&nbsp;

Example git commit message for the amend:

Code review updates for <feature-name>.


Change-Id: I44ba9430890bd4c3110bb6576da095559782da4d &nbsp;

Execute the following commands to get your master branch in sync with upstream:

git checkout master

git pull \--rebase upstream master

git push origin master

Now switch back to your feature branch, and get your feature branch in sync with any changes upstream:

git checkout <feature-branch-name>


git rebase master

Perform any necessary steps to resolve merge conflicts.&nbsp; After resolving merge conflicts, you will need to execute the following command:

git rebase \--continue

Then run your unit tests and driver tests to ensure all of your feature branch changes are still working correctly.

Amend your last commit if changes were necessary to fix merge conflicts.

git commit \--amend

Push directly to gerrithub review (which requires gerrit to be set as a remote)

git push gerrit HEAD:refs/for/master

If the Change-Id format is correct, this will update the existing review. &nbsp;If it is not, a new review will be generated which is unrelated to the original.

h4. Old Way (Thought to be broken)

Now you are ready to push your feature branch changes to your fork (i.e. origin).

git push origin <feature-branch-name>

There should be no fast forward errors.&nbsp; If there are, we need to rework this GIT Gerrithub Workflow Wiki info.

Now go to github.com, select your fork and feature branch which was pushed, and issue a pull request.

Now go to gerrithub.io, and select the "Github" link, select the "Pull requests" link and de-select all pull requests that are not yours.&nbsp; Ensure your pull request is selected.&nbsp; Select the Next button.&nbsp; Your pull request will be imported into Gerrithub.&nbsp; Select Next again.&nbsp; Your code review should be displayed.&nbsp; You should see an additional patchset.&nbsp; Let folks know to re-review.

h4. Alternate Workflow for Code Review Updates

This workflow is being tested. &nbsp;

Select the applicable feature branch which was used for the initial code review submission.

git checkout <feature-branch-name>

Make all necessary changes, run unit tests and driver tests to ensure good results.

After making all necessary updates based on code review comments, execute "git add/rm" commands to add or remove file elements required to resolve comments.

Now it is time for you to commit your changes.&nbsp; Obtain the change ID associated with your code review from Gerrithub.&nbsp;&nbsp;

Execute the command supplying the Change ID as the last line in your commit message:

git commit&nbsp;

Example git commit message:

Code review updates for <feature-name>.

Change-Id: I44ba9430890bd4c3110bb6576da095559782da4d

If you need to make additional commits before pushing your changes to the origin to resolve the code review comments, use git commit \--amend to end up with one commit. &nbsp;After you have pushed your changes to the origin, make a new commit for additional changes. &nbsp;&nbsp;

Execute the following commands to get your master branch in sync with upstream:

git checkout master

git pull \--rebase upstream master

git push origin master

Now switch back to your feature branch, and get your feature branch in sync with any changes upstream:

git checkout <feature-branch-name>

git rebase master

Perform any necessary steps to resolve merge conflicts.&nbsp; After resolving merge conflicts, you will need to execute the following command:

git rebase \--continue

If you have resolved the merge conflicts, and only adding or removing files was changed, rebase may not understand that any changes have been resolved and&nbsp;

Then run your unit tests and driver tests to ensure all of your feature branch changes are still working correctly.

Now you are ready to push your feature branch changes to your fork (i.e. origin).

git push origin <feature-branch-name>

There should be no fast forward errors.&nbsp; If there are, we need to rework this GIT Gerrithub Workflow Wiki info.

Now go to github.com, select your fork and feature branch which was pushed, and issue a pull request.

Now go to gerrithub.io, and select the "Github" link, select the "Pull requests" link and de-select all pull requests that are not yours.&nbsp; Ensure your pull request is selected.&nbsp; Select the Next button.&nbsp; Your pull request will be imported into Gerrithub.&nbsp; Select Next again.&nbsp; Your code review should be displayed.&nbsp; You should see an additional patchset.&nbsp; Let folks know to re-review.


h2. GIT Aliases

You can create git aliases for commonly types commands. &nbsp;

'git config \--global alias.<alias name> "alias text"'

for example to alias "status \-s" to "s"

'git config \--global alias.s "status \-s"'

Then to run a "git status \-s" you can just type "git s"

This config only applies to your machine, if you ever change where you are working with the code aliases will need to be re-created.&nbsp;

h2. GIT view history / state

git diff can be used to compare two different versions of files or the repository in git

'git diff'

shows the difference between all committed files and changed files for this repository

'git diff <filename>'

shows the difference between the current file and the committed version of the file for a single file

'git diff \--staged'

shows the differences between the committed versions and staged versions of all the staged files&nbsp;

'git log \--oneline \--decorate'

shows the history of commits for this repository

'git show <commit number>'

shows the file changes that occured on a particular commit

'git reflog'

shows git local history of merge, commit, branch changes

h2. GIT undo

If you made a mistake in the previous commit (and only the previous commit, not 2 commits ago), you can fix it with:

git commit \--amend

This allows you to change the commit message, or if you have additional changes you would like to include in a commit, you can stage them, then type git commit \--amend and git will add them to the previous commit.&nbsp;

If you want to completely undo a commit, but still keep the history of that commit visible by creating a new commit, you can use revert:

'git revert HEAD~1'

will revert one commit, performing the opposite operations that the commit did (i.e. if you added a file, it deletes it). &nbsp;You can go back additional commits by increasing the number after the \~, for example HEAD~2 is the previous 2 commits.

If you want to undo a commit and get rid of the history of that commit, you can use git reset with 3 different levels, \--soft, \--mixed, or \--hard. &nbsp;

*Do not use these unless you really understand what you are doing\!*

'git reset \--soft HEAD~2'&nbsp;

will undo the last 2 commits by changing files and modifications that were committed so they are staged

'git reset \--mixed HEAD~1'

will undo the last commit by un-staging the committed files and modifications

'git reset \--hard HEAD~1'

will undo the last commit by remove all changes from that commit, including removing files and modifications. &nbsp;

h2. GIT History Fix

To fix a problem with your git history on a branch:

git checkout upstream/master

This will get you back to the state of the master branch on the remote. &nbsp;It will tell you this is a detached head state. &nbsp;You fix by making a new branch which you will add your changes to. &nbsp;

git checkout \-b new_branch_name

Now move your changes from the previous branch with the bad history over. &nbsp;For each file (or directory):

git checkout old_branch_name path_to_file_or_directory

If you have removed files on the old branch you will also have to git rm those same files on the new branch. &nbsp;