My dear collaborators, I am convinced that within a very near future, all our research will have to be consigned, written, and published using GitHub as a plateform to host, review, and communicate our research material, and that markdown, R markdown in particular, bookdown, etc. are going to be among the tools we will all need to master to let others know about our research. I am convinced that if we use these tools well, they will largely simplify our work and make it a lot better.
There is a bit of a learning curve and I went through it myself this summer 2017 and I would like to share some of the things I have found with you, hoping to make the learning curve slope a bit less steep for you. So I have started assembling material that, hopefully, will help. However, there is no way around it: you are the ones who will need to read, watch, install, and learn. I cannot do it for you. And I know that you will, just like me, be glad you did.
I just cannot explain GitHub better than the guys who have made it, so here is a list of websites that I have chosen that explain things rather well:
Now, after I spent quite a bit of time trying to understand the master, branches, commit, etc. I was a bit confused I must admit. The more I read blogs, posts, etc., the more I realized that the easiest way to “add”,“commit”, “push”, and “pull”, from my local directory to my repository on GitHub was not through the browser, but through the good old terminal (for mac) or cmd (for windows).
I realize that this way to navigate through the directories of your computer is not something you have been taught. Well, in the 1990s in BAE, we had to learn Unix, so I happen to be somewhat familiar with the process. There is really nothing to be afraid of. Once you start a little bit, you will be glad you started this.
All this to say that I think that you should install Git on your computer. This website has the directions on how to do it. This is what I did and it worked for me.
I think there are two complementary ways to learn how all this works:
I have made quite a few mistakes when I tried to do this so if I can help such that you do not make the same mistakes, then I will have done something good! Eventually you will create a directory on your own computer where you will host all the files that you want to be tracked with GitHub. But before you do that, go to your GitHub page (you will have signed in and created your own page above), and click on repositories at the top of your page like below (just right of the ‘overview’ tab).
When you do this, you should get to a page that looks just like this:
Click on the green “New” icon and you should get to a page that looks just like this. Type the name of your repository. You will see that GitHub automatically adds dashes for spaces in the name. In fact, in GitHub and markdown, it seems to be better to use “-” instead of "_".
The initial page will give you something that will look like this:
Do not close this webpage! There are very useful code in there that you will need later. But first, go to the next step.
Now, and only now, is the time for you to create a directory where all your files will be locally stored. Make sure that there are no files in this directory, yet. I made that mistake several times and I spent lots of time to find the instructions to correct for this. If you do things in this order, it should really make things smooth. Actually, after I rewatched some of the videos, it might be possible to have files in a directory in the end, but really I am not sure as my experience is that things will stop working if you do…
OK, so by now, you should have started a repository from your browser. Navigate to the directory where your files are going to be stored and “pushed” to GitHub. Remember, this directory should be empty. It is now time to copy and paste the text under “… or create a new repository on the command line” that came . Normally now, you are set up and you are good to go!! It did take me a while to get there because I did not follow all the good instructions and burnt steps, etc. Hopefully this worked for you a bit more smoothly…!
On the GitHub workflow page, they insist (rightfully so), on the importance of “branches” compare to “master”. This is the prerequisite for working on a collaborative basis. Now, at the time I am writing this post, I have not needed to use branches, yet. I suggest that as a first step, you need not to either, just yet.
At this introductory stage, you really need less than 10 commands. I think this page really has all you need here! I am going to paraphrase this with I have used.
OK, so you want to have your file published in Github. The first thing you need to do is add the files in the ‘adding batch’ or ‘stage area’ using: * git add
$ git add <filename>
In reality, in most cases you may want to add all the new files you have created so you can use to synthaxes for this:
$ git add .
$ git add -a
(-a for all)
Then you will want to commit these files that you want to upload. The idea here is that the commit command will check whether or not there has been changes in what you have done and want to upload. So the code is:
$ git commit -m "this is the reason for this commit"
You can just do “git commit” with no extension but it will send you to some very weird screen (you will have to press insert, type your message and then press esc, and then type ‘:wq’, as you might have seen in the videos). so the synthax ‘-m “your message”’ (-m for ‘message’) is thus the way to go. The content of the message is particularly needed when the project is a collaborative work. If you are the only one committing, then you just want to have a history of what you have done. But for thesis editing, I think we will want to be precise in there.
Then you want to push what you have committed by just typing
$ git push
At this point you should be able to see your additions in your GitHub browser. All other useful commands are in the address above.