At the end of last year we split out lessons to have one Git repository per topic that we teach. To ensure that all lessons have the same look we use one template for our lessons. If you want to create a new lesson from scratch we already have a nice step-by-step guide but what about if you want to contribute to the template itself? In this post I will explain how I wrote my pull request for our template.
I start by cloning our example:
$ git clone -b gh-pages https://github.com/swcarpentry/lesson-example.git
and add some remote repositories:
$ cd lesson-example $ git remote add template https://github.com/r-gaia-cs/swc-lesson-template.git $ git remote add template-upstream https://github.com/swcarpentry/lesson-template.git $ git remote -v origin https://github.com/swcarpentry/lesson-example.git (fetch) origin hhttps://github.com/swcarpentry/lesson-example.git (push) template https://github.com/r-gaia-cs/swc-lesson-template.git (fetch) template https://github.com/r-gaia-cs/swc-lesson-template.git (push) template-upstream https://github.com/swcarpentry/lesson-template.git (fetch) template-upstream https://github.com/swcarpentry/lesson-template.git (push)
I use our example because it is easy to debug but if you want to use
origin as your fork of the lessons you are working is totally OK.
Every time before I start to hack the template I update my local copy using:
$ git fetch origin $ git fetch template $ git fetch template-upstream
Once my local copy is updated I create a feature branch, starting from the last commit on
lesson-example, where I will work:
$ git checkout -b example-centering-image origin/gh-pages
For this how-to, suppose that I want to add the class
img-responsive to every
img elements of our lessons. One quickly and dirty way to do that is change
$ git diff diff --git a/Makefile b/Makefile index 4d38850..ff49ca9 100644 --- a/Makefile +++ b/Makefile @@ -55,6 +55,7 @@ motivation.html : motivation.md _layouts/slides.revealjs Makefile --filter=tools/filters/id4glossary.py \ $(INCLUDES) \ -o $@ $< + sed -i "s/^<img /<img class="img-responsive" /g" $@ # Pattern to convert R Markdown to Markdown. %.md: %.Rmd $(R_CHUNK_OPTS)
To avoid losing my work, I save it in the staging area:
$ git add -u
Now I compile the HTML files:
$ make -B preview
and verify the changes.
$ git diff diff --git a/01-one.html b/01-one.html index 7622e55..1fc0d45 100644 --- a/01-one.html +++ b/01-one.html @@ -56,7 +56,8 @@ program</code></pre> </div> <p>or an image from the <code>figs</code> directory:</p> <div class="figure"> -<img src="fig/example.svg" title="this is the image's alt text" alt="this is the image's title" /><p class="caption">this is the image"s title</p> +<img class="img-responsive" src="fig/example.svg" title="this is the image's alt text" alt="this is the image's title" /> +<p class="caption">this is the image"s title</p> </div> <div id="challenge-title" class="challenge panel panel-success"> <div class="panel-heading">
This is exactly what I want, so I can now commit my changes:
$ git commit -m "Add img-responsive class to img" [example-centering-image a9cc86d] Add img-responsive class to img 1 file changed, 1 insertion(+)
I will also save the change to the HTML file.
$ git add -u $ git commit -m "Update HTML" [example-centering-image 1ebf8c3] Update HTML 1 file changed, 2 insertions(+), 1 deletion(-)
Copying the change to template
If you have taken the Git lesson at a Software Carpentry workshop, you should be comfortable with what you see until now. What I need to do is copy my change at
Makefile to template using
git cherry-pick. If you are trying to remember it from our workshop, don't panic because we don't teach it but you will discover that it is very simple to use.
Before anything else I need to know the ID of the commit I want to copy, the one where I changed
$ git log --oneline -3 1ebf8c3 Update HTML a9cc86d Add img-responsive class to img 5426365 Merge pull request #1 from gvwilson/updating-docs
The commit that I want is
a9cc86d. I will save the ID for a moment until I create a new branch starting from the template (instead of the example):
$ git checkout -b template-centering-image template-upstream/gh-pages
Now I can copy my changes from
a9cc86d into the current branch and create a new commit, and for that I use
$ git cherry-pick a9cc86d [template-centering-image 2004c4f] Add img-responsive class to img Date: Sat Apr 4 18:19:26 2015 -0300 1 file changed, 1 insertion(+)
I can check that the commit was copied
$ git log --oneline -2 2004c4f Add img-responsive class to img cf25427 Merge pull request #218 from wking/trailing-newlines
The commit ID change but this is OK and is desired. Now I can upload my changes
$ git push template template-centering-image
Once the pull request was created our contributors will review it and eventually merge it. From time to time we will propagate the change at our template to our lessons.
If your changes are in the CSS that we use you must copy your changes to this repository instead of
As always, in case of troubles with Git you can contact us and one of our Git gurus will get back to you for help.
Dialogue & Discussion
You can review our commenting policy here.