User Tools

Site Tools


git_github_workflow

Overview

Typical workflow for contributing to a public GitHub project, demonstrating the use of branches and remotes.

Steps in the workflow

Sample project

Consider progit/progit2, available here to which you can try to contribute to the master branch.

Fork the project

Using your GitHub account, “fork” a copy of the project, which will now be available as rpjday/progit2 here.

Note well that your fork of the project will not be updated from the upstream project that you forked; rather, your fork will be used as the source for “pull requests” that you want to contribute upstream. In short, commits go in only one direction -- from your fork upstream, not vice versa.

Clone your fork to your local machine

At this point, you want to make yet another copy of the repository -- a local clone of your GitHub fork; it's in this local clone where you will make all of the changes you want to contribute:

$ git clone https://github.com/rpjday/progit2 pg2

Everything here is up to date with your GitHub fork:

$ git status
On branch master
Your branch is up-to-date with 'origin/master'.

nothing to commit, working tree clean
$

and, as you can see, your local clone has only one registered remote:

$ git remote -v
origin	https://github.com/rpjday/progit2 (fetch)
origin	https://github.com/rpjday/progit2 (push)
$

Note well that the remote origin is where you will push your contributions – to your GitHub fork, not to the project to which you want to contribute.

Adding a remote for the main project

You now have to add a remote for the main project itself, since that's where you'll be pulling any new commits from anyone contributing to the project (yourself or anyone else):

$ git remote add progit https://github.com/progit/progit2
$

Verify the new remote:

$ git remote -v
origin	https://github.com/rpjday/progit2 (fetch)
origin	https://github.com/rpjday/progit2 (push)
progit	https://github.com/progit/progit2 (fetch)
progit  https://github.com/progit/progit2 (push)
$

You can see this information in your .git/config file:

$ cat .git/config 
[core]
	repositoryformatversion = 0
	filemode = true
	bare = false
	logallrefupdates = true
[remote "origin"]
	url = https://github.com/rpjday/progit2
	fetch = +refs/heads/*:refs/remotes/origin/*
[branch "master"]
	remote = origin
	merge = refs/heads/master
[remote "progit"]
	url = https://github.com/progit/progit2
	fetch = +refs/heads/*:refs/remotes/progit2/*
$

Keeping up to date

Before you even start contributing to the main project, there are three steps involved in keeping up with everyone else's contributions.

First, fetch from the upstream progit remote into the remote tracking branch progit/master:

$ git fetch progit

Next, manually merge any new content into your local master branch:

$ git merge progit/master

Finally, push this new content to your GitHub fork of the project:

$ git push origin master

Do all of this on a regular basis to keep everything in sync.

Contributing changes

Contributing changes to the main project involves three steps:

  • Make and commit some local changes (preferably on a feature branch).
  • Push those changes (that branch) to your GitHub fork.
  • Make a “pull request” to have the main project accept your commit(s) on that branch.

First, create a new branch, make and commit a silly change:

$ git checkout -b topic/rpjday/issue42
Switched to a new branch 'topic/rpjday/issue42'
$

Make a simple change to README.asc and commit it:

$ git checkout -b topic/rpjday/issue42
Switched to a new branch 'topic/rpjday/issue42'
$
$ git commit -a -m "fix issue42"
[topic/rpjday/issue42 77fad5f] topic/rpjday/issue42
 1 file changed, 1 insertion(+), 1 deletion(-)
$
$ git show
commit 77fad5f0aadd229628baa7811b0b49c7580d96f0 (HEAD -> topic/rpjday/issue42)
Author: Robert P. J. Day <rpjday@crashcourse.ca>
Date:   Wed Feb 14 07:06:42 2018 -0500

    fix issue42

diff --git a/README.asc b/README.asc
index d7810fd..126bfd4 100644
--- a/README.asc
+++ b/README.asc
@@ -1,4 +1,4 @@
-= Pro Git, Second Edition
+= Pro Git, Second Edition (rday change)
 
 Welcome to the second edition of the Pro Git book.
 
$

At this point, you can push this new branch to your GitHub fork:

$ git push origin topic/rpjday/issue42

And over At GitHub

Provided you're logged into your account at GitHub, you'll suddenly see the appearance of a new branch sillyb. If you think it's ready to go, you can select “Compare & pull request” to examine and confirm that you want to hand that off to the main project.

If all goes well and your change is accepted and committed, you will have to perform the two earlier steps to fetch and merge your changes into your local clone into the master branch:

$ git fetch progit
$ git merge progit/master

In addition, you can now delete the sillyb branch if you have no further use for it.

git_github_workflow.txt · Last modified: 2019/04/04 12:32 by rpjday