Git repo layout variants

This page summarizes two alternate ways of organizing your git development workflow with respect to the main project QMCPACK/qmcpack repository, your own fork on github at github_user_id/qmcpack, and your local working respository.

First, it will be helpful to define some terminology:

• origin refers to the remote repository that the local repository was cloned from. If you run git clone https://github.com/QMCPACK/qmcpack.git, then the QMCPACK/qmcpack GitHub repository will be 'origin'. Likewise, if you run git clone https://github.com/some_user_id/qmcpack.git, then some_user_id/qmcpack will be 'origin' for that particular local repository.
• remote refers to any repository that is not the local working repository. A remote is normally used to pull/push branches in order to share code changes. 'origin' is a special remote that gets configured automatically when the local repository is cloned. Other remotes can be configured using the git remote set of commands.
• A fork in this document refers to the repository that lives on GitHub that was created using the "Fork" button in the GitHub interface. Most commonly, a some_user_id/qmcpack fork will be created from the QMCPACK/qmcpack repository.
• upstream in this document refers to the GitHub repository that a fork was created from. Most commonly, QMCPACK/qmcpack would be considered 'upstream' for a some_user_id/qmcpack repository that was created using the "Fork" button on the QMCPACK/qmcpack page.
• A local branch is tracking a remote branch when it has been configured to do so, with the consequence of that particular remote branch being used by default when git pull and git push are typed in the local branch without other arguments.

You can always use git branch -vv to see how the local branches have been configured to track various remotes.

Variant 1 - QMCPACK/qmcpack as upstream; github_user_id/qmcpack as origin

Note that this variant is the same workflow that is described on the main Development Workflow page

Workflow summary

This variant will require a few one time steps for initial configuration of the local repository.

1. (One time only) Create your fork some_user_id/qmcpack from QMCPACK/qmcpack using the instructions at Forking QMCPACK on GitHub

2. (One time only) Create the local repository by cloning your fork.

    $ git clone https://github_user_id@github.com/github_user_id/qmcpack.git
   

3. (One time only) Configure your local repository to use QMCPACK/qmcpack as 'upstream'

    $ git remote -v
    origin  https://grahamlopez@github.com/grahamlopez/qmcpack.git (fetch)
    origin  https://grahamlopez@github.com/grahamlopez/qmcpack.git (push)
   
    $ git remote add upstream https://grahamlopez@github.com/QMCPACK/qmcpack.git
   
    $ git remote -v
    origin  https://grahamlopez@github.com/grahamlopez/qmcpack.git (fetch)
    origin  https://grahamlopez@github.com/grahamlopez/qmcpack.git (push)
    upstream    https://grahamlopez@github.com/QMCPACK/qmcpack (fetch)
    upstream    https://grahamlopez@github.com/QMCPACK/qmcpack (push)
   

After the initial configuration is completed, the normal development cycle in this variant will be:

1. Pull new changes from upstream into your local repository

    $ git checkout develop
    $ git pull upstream develop
   

2. Create a new branch

    $ git checkout develop
    $ git checkout -b <feature_branch>
   

3. Make some code modifications, commits, etc.

4. Push your local branch to 'origin' (your fork) to share with others or create a pull request

    $ git push -u origin <feature_branch>
   

Variant 2 - No upstream; QMCPACK/qmcpack as origin