-
Notifications
You must be signed in to change notification settings - Fork 392
Cookbook for Working with Git and VIC
Git is a version control tool that we use to...
- track changes over time in the VIC source code,
- facilitate parallel development between multiple model developers and research projects,
- encourage peer code review and bug tracking, and
- to distribute official and bleeding edge releases of the model source code.
In general, if you are only going to be using the model and not working directly on the source code, you may just download the model either from VIC github page ( recommended ) or from our UW website. Additional archived tags and releases (including all previous VIC versions) are available here.
If you plan on contributing to model development or would like a systematic way to incorporate updates to the VIC source code, we encourage you to use Git. The following sections are designed to get you started using git and working with the VIC source code repository.
If you are not familiar with Git yet, we encourage you to spend a few minutes getting antiquated with the system before you starting working with the VIC source code and Git. It's not difficult to use and a few minutes of learning about Git will go along way in helping you manage your code development.
There are a number of good Git learning resources that will provide a basic introduction to the version control system.
The basics steps to get the VIC source code repository are as follows. This is basically a VIC specific rendition of https://help.github.com/articles/fork-a-repo
If you do not have a github account, create one. It's free for public repos (like the VIC one). On the UW-Hydro/VIC page, click "Fork" in the upper right hand corner.
You've successfully forked the VIC repository, but so far it only exists on GitHub. To be able to work on the project, you will need to clone it to your local machine.
Run the following code on your local machine:
git clone https://github.com/username/VIC.git
This clones your fork of the repository into the current directory in terminal
When a repository is cloned, it has a default remote called origin that points to your fork on GitHub, not the original repository it was forked from. To keep track of the original repository, you need to add another remote. You can name this anything you want, but the name upstream is descriptive and an informal convention.
Changes the active directory in the prompt to the newly cloned "VIC" directory:
cd VIC
Assign the original repository to a remote tracking branch called "upstream":
git remote add --tracking upstream https://github.com/UW-Hydro/VIC.git
You can then pull changes not present in your local repository, without modifying your files:
git fetch upstream
You've successfully forked a repository, but get a load of these other cool things you can do:
Once you've made some commits to a forked repository and want to push it to your forked project, you do it the same way you would with a regular repository:
Push commits to your remote repository (which has the alias origin) stored on GitHub:
git push origin master
If the original repository you forked your project from is updated, you can add those updates to your fork by running the following code:
Fetch any new changes from the original repository:
git fetch upstream
Merge any changes fetched into your working files:
git merge upstream/master
Branching allows you to build new features or test out ideas without putting your main project at risk. In git, branch is a sort of bookmark that references the last commit made in the branch. This makes branches very small and easy to work with. More on this on the VIC-Git workflow page.
If you are hoping to contribute back to the original fork, you can send the original author a pull request. Unwatch the main repository
When you fork a particularly popular repository, you may find yourself with a lot of unwanted updates about it. To unsubscribe from updates to the main repository, click the "Unwatch" button on the main repository.
At some point you may decide that you want to delete your fork. To delete a fork, just follow the same steps as you would to delete a regular repository.
You have now forked a repository. Alright, now git to work.
In order for us to leverage Git to its full potential, we have implemented a Git-oriented workflow. This requires developers to adhere to a few rules regarding branch names and merge requests. A full description of the workflow we use can be found here.