Skip to content

Git repo layout variants

Jump to bottom
Graham Lopez edited this page Jan 18, 2017 · 15 revisions

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.

You might notice that the major difference in these variants is the one time configuration; the daily development workflow remains the same with either choice. Variant #1 is preferred because it is typically safer (see bold text in the variant #2 section).

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 normally refers to the main project code base. This also commonly 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)

  4. (One time only) Configure your local 'develop' branch to track upstream.

     $ git branch -vv
 * develop 81f7038 [origin/develop] Some current commit message from the logs

 $ git branch develop -u upstream/develop
 Branch develop set up to track remote branch develop from upstream.
 
 $ git branch -vv
 * develop 81f7038 [upstream/develop] Some current commit message from the logs

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

  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 to create a pull request

     $ git push -u origin <feature_branch>

    After this, 'feature_branch' is configured to track 'origin/feature_branch', so that git push and git pull can be used without other arguments during further development.

Variant 2 - No upstream; QMCPACK/qmcpack as origin

This variant requires some care, as a lot of the git command defaults and help messages will use 'origin' for various operations. However, QMCPACK/qmcpack should only be modified via pull requests submitted on GitHub, so one must pay attention if QMCPACK/qmcpack is configured as 'origin' to the local repository.

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 the main project repository.

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

  3. (One time only) Configure your local repository to use some_user_id/qmcpack as a remote

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

 $ git remote add graham https://grahamlopez@github.com/grahamlopez/qmcpack.git

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

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

  1. Pull new changes from the main project repository (configured as 'origin') into your local repository.

     $ git checkout develop
 $ git pull

  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 your fork to share with others or to create a pull request

     $ git push -u graham <feature_branch>

    After this, 'feature_branch' is configured to track 'grahamlopez/feature_branch', so that git push and git pull can be used without other arguments during further development.

Clone this wiki locally