27 Using Git

This document describes the steps required to download PEcAn, make changes to code, and submit your changes.

cd pecan git pull upstream master ./scripts/build.sh

27.1 Git

Git is a version control software; GitHub is a project-hosting website that is similar to Redmine but easier to use for open and collaborative development.

Git is a free & open source, distributed version control system designed to handle everything from small to very large projects with speed and efficiency. Every Git clone is a full-fledged repository with complete history and full revision tracking capabilities, not dependent on network access or a central server. Branching and merging are fast and easy to do.

A good place to start is the GitHub 5 minute illustrated tutorial. In addition, there are three fun tutorials for learning git:

For additional tutorials and background see References

URLs In the rest of the document will use specific URL’s to clone the code. There a few URL’s you can use to clone a project, using https, ssh and git. You can use either https or git to clone a repository and write to it. The git protocol is read-only.

27.1.1 PEcAnProject on GitHub: https://github.com/organizations/PecanProject

27.1.2 Milestones, Issues, Tasks

The Milestones, issues, and tasks can be used to organize specific features or research projects. In general, there is a heirarchy:

  • milestones (Big picture, “Epic”): contains many issues
  • issues (Specific features / bugs, “Story”): may contain a list of tasks; represent
  • task list (to do list, “Tasks”): list of steps required to close an issue, e.g.: ```
  • [ ] first do this
  • [ ] then this
  • [ ] completed when x and y ```

27.1.3 Quick and Easy

The easiest approach is to use GitHub’s browser based workflow. This is useful when your change is a few lines, if you are editing a wiki, or if the edit is trivial (and won’t break the code). The GitHub documentation is here but it is simple: finding the page or file you want to edit, click “edit” and then the GitHub web application will automatically forking and branch, then allow you to submit a pull request. However, it should be noted that unless you are a member of the PEcAn project that the “edit” button will not be active and you’ll want to follow the workflow described below for forking and then submitting a pull request.

27.3 During development:

  • commit often;
  • each commit can address 0 or 1 issue; many commits can reference an issue (see [[Link commits to issue|Using-Git#link-commits-to-issues]])
  • ensure that all tests are passing before anything is pushed into master.

27.3.1 Basic Workflow

PLEASE DO NOT USE THIS, SEE ADVANCED WORKFLOW!

  1. Get the latest code from the main repository

    git pull upstream master
  2. Do some coding

  3. Commit after each chunk of code (multiple times a day)

    git commit -m "<some descriptive information about what was done; references/fixes gh-X>"
  4. Push to YOUR Github (when a feature is working, a set of bugs are fixed, or you need to share progress with others)

    git push origin <branchname>
  5. Before submitting code back to the main repository, make sure that code compiles

    ./scripts/build.sh -c
  6. submit pull request with a reference to related issue (see [[Link commits to issue|Using-Git#link-commits-to-issues]]);

27.3.2 Advanced Workflow: A new branch for each change

  1. Make sure you start in master

    git checkout master
  2. Make sure master is up to date

    git pull upstream master
  3. Run any tests / make sure that code compiles

  1. Create a branch and switch to it

    git checkout -b <branchname>
  2. work/commit/etc

    git commit -m "<some descriptive information about what was done>"
  3. Run any tests / make sure that code compiles

For PEcAn: ./scripts/build.sh -c

  1. Push this branch to your github space

    git push origin <branchname>
  2. submit pull request with [[link commits to issues|Using-Git#link-commits-to-issuess]];

27.3.3 After pull request is merged

  1. Make sure you start in master

    git checkout master
  2. delete branch remotely

    git push origin --delete <branchname>
  3. delete branch locally

    git branch -D <branchname>

27.4 For PEcAn

./scripts/build.sh -c

27.4.1 Committing Changes Using Pull Requests

GitHub provides a useful overview of how to submit changes to a project, Using Pull Requests.

Once you have added a feature on your local fork of the project that you would like to contribute, these are the steps:

  • Submit a Pull Request
  • Pull request is reviewed by a member of the PEcAn core group
  • Any comments should be addressed
  • Additional commits are added to the pull request
  • When ready, changes are merged

27.4.2 Other Useful Git Commands:

  • GIT encourages branching “early and often”
  • First pull from master
  • Branch before working on feature
  • One branch per feature
  • You can switch easily between branches
  • Merge feature into main line when branch done

        git branch <name of branch>
        git checkout <name of branch>
        repeat 
          write some code
          commit
        until done
    
        git checkout master
        git merge <name of brach>
        git push

If during above process you want to work on something else, commit all your code, create a new branch, and work on new branch.

  • Delete a branch: git branch -d <name of branch>
  • To push a branch git: push -u origin`
  • To check out a branch: git fetch origin git checkout --track origin/<name of branch>

  • Get the remote repository locally:

    git clone URL
  • To update local repository to latest:

    git pull
  • To add new files to the local repository:

    git add <file>
  • To commit changes

    git commit <file|folder>
  • To update remote repository:

    git push
  • Show graph of commits:

    git log --graph --oneline --all

27.4.3 Tags

Git supports two types of tags: lightweight and annotated. For more information see the Tagging Chapter in the Git documentation.

Lightweight tags are useful, but here we discuss the annotated tags that are used for marking stable versions, major releases, and versions associated with published results.

The basic command is git tag. The -a flag means ‘annotated’ and -m is used before a message. Here is an example:

git tag -a v0.6 -m "stable version with foo and bar features, used in the foobar publication by Bob"

Adding a tag to the a remote repository must be done explicitly with a push, e.g.

git push v0.6

To use a tagged version, just checkout:

git checkout v0.6

To tag an earlier commit, just append the commit SHA to the command, e.g.

git tag -a v0.99 -m "last version before 1.0" 9fceb02

Using GitHub The easiest way to get working with GitHub is by installing the GitHub client. For instructions for your specific OS and download of the GitHub client, see https://help.github.com/articles/set-up-git. This will help you set up an SSH key to push code back to GitHub. To check out a project you do not need to have an ssh key and you can use the https or git url to check out the code.

27.5 Git + Rstudio

Rstudio is nicely integrated with many development tools, including git and GitHub. It is quite easy to check out source code from within the Rstudio program or browser. The Rstudio documentation includes useful overviews of version control and R package development.

Once you have git installed on your computer (see the Rstudio version control documentation for instructions), you can use the following steps to install the PEcAn source code in Rstudio.

27.5.1 Creating a Read-only version:

This is a fast way to clone the repository that does not support contributing new changes (this can be done with further modification).

  1. install Rstudio (www.rstudio.com)
  2. click (upper right) project

27.6 For development:

  1. create account on github
  2. create a fork of the PEcAn repository to your own account https://www.github.com/pecanproject/pecan
  3. install Rstudio (www.rstudio.com)
  4. generate an ssh key
  • in Rstudio:
  • Tools -> Options -> Git/SVN -> "create RSA key"
  • View public key -> ctrl+C to copy
  • in GitHub
  • go to ssh settings
  • -> 'add ssh key' -> ctrl+V to paste -> 'add key'
  1. Create project in Rstudio
  • project (upper right) -> create project -> version control -> Git - clone a project from a Git Repository
  • paste repository url git@github.com:<username>/pecan.git>
  • choose working dir. for repository

27.7 References:

27.7.0.1 Git Documentation

27.7.0.2 GitHub Documentation

When in doubt, the first step is to click the “Help” button at the top of the page.