Contents

GitHub and Git Workflows

For an introduction to Git and version control, see the page Git Intro. This page outlines four levels of workflow complexity:

  1. Solo no branching workflow; the simplest use of GitHub as a repository for your own work only.

  2. Solo with branch and merge to manage your own development of features.

  3. Sharing but with no branching (not ideal).

  4. Fork & Pull Workflow.

Details follow.

1. Solo no branching workflow

The simplest use of GitHub as a repository for your own work only, with local editing.

  1. In your GitHub account, use the big green New button to make a new blank repository.

    1. It will ask you to name it, describe it briefly, declare it as public or private

    2. Also you should answer the “initialize this repository” by adding README and license files. (The “BSD 3-Clause License” is OK.) These two should be included as a matter of good practice.

    3. a .gitignore file is not needed yet, but may be added later.

  2. Update the README.md file

    1. Click the README.md file

    2. Click the edit pencil icon

    3. Add a line or two

    4. Below the edit box you will see “Commit changes” information. Describe the change in the top one-line box, add optional info if you like, check email, be sure you pick “Commit directly to the master branch” and click the Commit changes button.

  3. That’s all that is necessary.

    • Work can be carried out within the GitHub environment. Add new or upload files, edit text files (MarkDown or .md files or code, etc.)

The next step is to clone to your local computer so you can work on the project on your own computer or laptop.

  1. Install Git version control system on your own computer.

  2. There are GUIs for all platforms, but it is “safer” to start using the command line, and move to a graphical user interface once you are able to work from the command line.

2. Solo with branch and merge

No collaboration but use of branches to “contain” your own development of features.

  • Not yet written.

3. Sharing but with no branching (not ideal)

  • Could be derived from the tutorial at NSF’s National Ecological Observatory Network. This is part 7 from a succinct 7-part beginner’s Git tutorial. See also “Pointers & References” below.

NEED TO CHECK and integrate “A Pull Request Workflow Tutorial”.

4. Fork & Pull Workflow

Collaboration using a Fork from someone else’s repository, develop in a branch, maintain synchronicity with the originator’s master, and request addition of your work using pull request.

  1. Fork to your own repository

  2. Clone to your local

    1. In your local folder under which the new repo should reside: Git clone …URL…

    2. Track the original upstream version: Git remote add upstream

    3. (Verify the new remote with git remote -v .)

  3. At start of each editing session:

    1. Bring upstream’s branches (with edits) into the local repo.: git fetch upstream

    2. (View all branches, including those from upstream with git branch -va .)

    3. Checkout your master branch and merge with upstream’s master:

      git checkout master
git merge upstream/master

    4. If there were any new commits on upstream’s master, rebase your work branch:

      git checkout newfeature
git rebase master

      This means “rebase the newfeature branch onto the master branch.”

      • Golden rule of git rebase: never use it on public branches. For example never, never do git checkout master then git rebase newfeature. From this reference.

    5. OR, IF desired, at the same time as rebasing, clear up by squashing (some) smaller commits down into larger commits using interactive rebase:

      git checkout newfeature
git rebase -i master

  4. Do all editing on a branch, not master. Either git checkout newfeature or create a new branch by first checking out the master branch (the new branch should come from master) then create a new branch; git checkout master then git branch newfeature.

  5. When ready, push to your GitHub repo and ask to merge with original

    1. Send to your repo: git push

    2. Ask to contribute your work to owner of upstream.

      • NOTE: At your GitHub repo be sure to select your development branch (eg. newbranch)!

      • Click pull request.

    (NOTE: Subsequent changes to that branch will be tracked until pull request is accepted or rejected. )

Pointers & References

See the end of the page Git Intro.

Git Introduction Markdown