-
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 out website (insert html here), from our code page (link here). Additionally archived tags and releases may be found (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
Step 1: Fork the "UW-Hydro/VIC" repository
Step 2: Clone your fork
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:
git clone https://github.com/username/VIC.git# Clones your fork of the repository into the current directory in terminal
Step 3: Configure remotes
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 named upstream:
cd VIC# Changes the active directory in the prompt to the newly cloned "VIC" directory git remote add upstream https://github.com/UW-Hydro/VIC.git# Assigns the original repository to a remote called "upstream"
git fetch upstream# Pulls in changes not present in your local repository, without modifying your files
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:
git push origin master# Pushes commits to your remote repository stored on GitHub
If the original repository you forked your project from gets updated, you can add those updates to your fork by running the following code:
git fetch upstream# Fetches any new changes from the original repository
git merge upstream/master# Merges any changes fetched into your working files
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.
Click "Unwatch"
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: