A Basic Collaboration Workflow on Gist
The main purpose of this post is to introduce a basic workflow for collaborating on Gist.
First of all, gists are essentially git repositories hosted at gist.github.com. They are typically used to share snippets of code, but they can also be used to write live code examples, posts, and text-adventures.
You can learn more about how to create a gist and about gists on GitHub Help pages.
In this post, I will focus on managing forks and remotes to easily collaborate on a gist with your coworkers.
Prerequisites
You need a basic knowledge of Git and to have it installed on your PC.
Follow this guide to set up Git: https://help.github.com/articles/set-up-git/.
Follow this guide to learn Git basics: http://git-scm.com/book/en/v2/Getting-Started-Git-Basics.
Gists Are Git Repositories
A gist can be cloned like any other git repository using its clone URL.
Try cloning the example gist at gist.github.com/potomak/49832b4426a5f093037d by running:
1
giovanni$ git clone git@gist.github.com:/49832b4426a5f093037d.git hello-world
Now you can work on the gist as you would with any other git repository. For instance, you can update the hello-world.txt file, add it to the staging area, and commit your changes.
1
2
3
4
giovanni$ cd hello-world
giovanni$ echo "Foo" >> hello-world.txt
giovanni$ git add hello-world.txt
giovanni$ git commit -m "Update file"
If you run git log, you should see two commits:
- The initial commit I made to create the gist
- The second commit where I updated
hello-world.txt
1
2
3
giovanni$ git log --pretty=format:"%h - %an, %ar: %s"
b24c6d3 - Giovanni Cappellotto, 5 minutes ago: Update file
0927aec - Giovanni Cappellotto, 41 minutes ago:
To write your changes into the hosted repository, push your local master branch to the default origin remote.
1
giovanni$ git push origin master
Note: After the push, you can view the full list of commits online at https://gist.github.com/potomak/49832b4426a5f093037d/revisions.
Forks and Remotes
To collaborate on gist repositories, your teammates can fork them.
As a different GitHub user, you can fork the example gist, for instance, https://gist.github.com/gmarenda/57c23d008b770b4904ba, clone it, and update it by following these steps:
1
2
3
4
5
giorgia$ git clone git@gist.github.com:/57c23d008b770b4904ba.git hello-world
giorgia$ cd hello-world
giorgia$ echo " Bar" >> hello-world.txt
giorgia$ git add hello-world.txt
giorgia$ git commit -m "Update file from fork"
By doing so, Giorgia has updated hello-world.txt and committed her changes to her local repository, associated with the remote fork.
After her changes, the log on Giorgia’s local repository will look like this:
1
2
3
4
giorgia$ git log --pretty=format:"%h - %an, %ar: %s"
e5a386d - Giorgia, 47 seconds ago: Update file from fork
b24c6d3 - Giovanni Cappellotto, 48 minutes ago: Update file
0927aec - Giovanni Cappellotto, 84 minutes ago:
Now, if she pushes her changes to the origin remote:
1
giorgia$ git push origin master
I’ll be able to add her origin remote as a new gmarenda remote on my repository to merge her master branch with mine.
1
2
3
giovanni$ git remote add gmarenda git@gist.github.com:/57c23d008b770b4904ba.git
giovanni$ git fetch gmarenda
giovanni$ git merge gmarenda/master
In the local repo, there are now:
- My changes from some time ago
- Giorgia’s new commit
Giorgia’s commit has been merged from her master branch, which was fetched from the gmarenda remote based on her fork of the original gist.
Now I can push my updated master branch to origin to persist the changes in the hosted repo.
1
giovanni$ git push origin master
Conclusion
The process is a bit more manual than what people are used to with pull requests from GitHub’s web interface, but I find it interesting and useful to use such a simple collaboration flow on Gist.