diff --git a/.zenodo.json b/.zenodo.json index cc507654..913d7a6e 100644 --- a/.zenodo.json +++ b/.zenodo.json @@ -2,388 +2,182 @@ "contributors": [ { "type": "Editor", - "name": "Silvia Di Giorgio" - }, - { - "type": "Editor", - "name": "Christopher Erdmann", - "orcid": "0000-0003-2554-180X" - }, - { - "type": "Editor", - "name": "Thea Atwood", - "orcid": "0000-0001-8348-1097" + "name": "Drew Heles" }, { "type": "Editor", - "name": "Eric Lopatin" + "name": "Chuck McAndrew" }, { "type": "Editor", - "name": "Drew Heles" + "name": "Silvia Di Giorgio" }, { "type": "Editor", - "name": "Eva Seidlmayer" + "name": "Eric Lopatin", + "orcid": "0000-0002-5296-1116" } ], "creators": [ { - "name": "Christopher Erdmann", - "orcid": "0000-0003-2554-180X" + "name": "Greg Wilson", + "orcid": "0000-0001-8659-8979" }, { - "name": "Katrin Leinweber", - "orcid": "0000-0001-5135-5758" - }, - { - "name": "Belinda Weaver" + "name": "Belinda Weaver", + "orcid": "0000-0002-6156-7997" }, { "name": "James Baker", "orcid": "0000-0002-2682-6922" }, { - "name": "Nora McGregor" - }, - { - "name": "Dan Michael O. Heggø" - }, - { - "name": "Jonah Duckles", - "orcid": "0000-0002-8985-3119" - }, - { - "name": "Alex Mendes" - }, - { - "name": "Jamene Brooks-Kieffer" - }, - { - "name": "Tim Dennis", - "orcid": "0000-0001-6632-3812" - }, - { - "name": "Jeffrey Oliver", - "orcid": "0000-0003-2160-1086" - }, - { - "name": "Bill McMillin" + "name": "Christopher Erdmann", + "orcid": "0000-0003-2554-180X" }, { - "name": "DSTraining" + "name": "Katrin Leinweber", + "orcid": "0000-0001-5135-5758" }, { - "name": "Evan Williamson", - "orcid": "0000-0002-7990-9924" + "name": "Daniel van Strien" }, { - "name": "Ryan Wick", - "orcid": "0000-0003-2143-7407" + "name": "Jez Cope", + "orcid": "0000-0003-3629-1383" }, { - "name": "Thea Atwood" + "name": "Francois Michonneau", + "orcid": "0000-0002-9092-966X" }, { - "name": "222064h" + "name": "Chuck McAndrew" }, { - "name": "Alexander Mendes" + "name": "Nora McGregor" }, { - "name": "ajtag" + "name": "Dan Michael Heggø", + "orcid": "0000-0002-6189-5958" }, { - "name": "Kunal Marwaha", - "orcid": "0000-0001-9084-6971" + "name": "davanstrien" }, { - "name": "Shari Laster" + "name": "Jonah Duckles", + "orcid": "0000-0002-8985-3119" }, { - "name": "Yuri" + "name": "W. Trevor King" }, { - "name": "Madicken Munk" + "name": "Alex Mendes" }, { - "name": "Katherine Koziar", - "orcid": "0000-0003-0505-7973" + "name": "Tim Dennis", + "orcid": "0000-0001-6632-3812" }, { - "name": "Raniere Silva" + "name": "Jamene Brooks-Kieffer" }, { - "name": "Rich McCue" + "name": "Mateusz Kuzak", + "orcid": "0000-0003-0087-6021" }, { - "name": "Nima Hejazi" + "name": "Jeffrey Oliver", + "orcid": "0000-0003-2160-1086" }, { - "name": "Simon Waldman" + "name": "Naupaka Zimmerman", + "orcid": "0000-0003-2168-6390" }, { "name": "Rémi Emonet", "orcid": "0000-0002-1870-1329" }, { - "name": "Rayna Harris", - "orcid": "0000-0002-7943-5650" - }, - { - "name": "Amy Olex", - "orcid": "0000-0001-8064-521X" - }, - { - "name": "Erin Alison Becker", - "orcid": "0000-0002-6832-0233" - }, - { - "name": "Jake Lever" - }, - { - "name": "Marie-Helene Burle", - "orcid": "0000-0003-4853-4901" - }, - { - "name": "Brian Moore", - "orcid": "0000-0003-1575-9696" - }, - { - "name": "Umihiko Hoshijima" - }, - { - "name": "Amiya Maji", - "orcid": "0000-0002-6242-6184" - }, - { - "name": "Begüm D. Topçuoğlu" - }, - { - "name": "Christoph Junghans", - "orcid": "0000-0003-0925-1458" - }, - { - "name": "Lex Nederbragt", - "orcid": "0000-0001-5539-0999" - }, - { - "name": "Alexander Gary Zimmerman", - "orcid": "0000-0003-2577-3942" - }, - { - "name": "Annika Rockenberger" - }, - { - "name": "Casey Youngflesh", - "orcid": "0000-0001-6343-3311" - }, - { - "name": "Garrett Bachant" - }, - { - "name": "hdinkel", - "orcid": "0000-0002-9316-5204" - }, - { - "name": "James E McClure" - }, - { - "name": "James Tocknell" - }, - { - "name": "Janoš Vidali" - }, - { - "name": "James O'Donnell", - "orcid": "0000-0002-5650-4318" - }, - { - "name": "Joe Atzberger" - }, - { - "name": "jonestoddcm" - }, - { - "name": "Kurt Glaesemann", - "orcid": "0000-0002-9512-1395" - }, - { - "name": "Andrew Lonsdale", - "orcid": "0000-0002-0292-2880" - }, - { - "name": "Maneesha Sane", - "orcid": "0000-0003-0726-5696" - }, - { - "name": "Michael Zingale", - "orcid": "0000-0001-8401-030X" - }, - { - "name": "Nicola Soranzo", - "orcid": "0000-0003-3627-5340" - }, - { - "name": "pllim", - "orcid": "0000-0003-0079-4114" - }, - { - "name": "Saskia Hiltemann" - }, - { - "name": "abracarambar" - }, - { - "name": "Benjamin Bolker", - "orcid": "0000-0002-2127-0443" - }, - { - "name": "William Sacks", - "orcid": "0000-0003-2902-5263" - }, - { - "name": "butterflyskip" - }, - { - "name": "cmjt", - "orcid": "0000-0003-1201-2781" - }, - { - "name": "David Jennings" - }, - { - "name": "Grant Sayer" - }, - { - "name": "Ian Lee", - "orcid": "0000-0001-6952-2585" - }, - { - "name": "James Tocknell" - }, - { - "name": "Jeremy Teitelbaum" - }, - { - "name": "Jeyashree Krishnan" - }, - { - "name": "João Rodrigues" - }, - { - "name": "Jonathan Cooper", - "orcid": "0000-0001-6009-3542" - }, - { - "name": "L.C. Karssen" - }, - { - "name": "Lauren Ko" - }, - { - "name": "Mark Woodbridge" - }, - { - "name": "Martino Sorbaro" - }, - { - "name": "Matt Critchlow" - }, - { - "name": "Matteo Ceschia" - }, - { - "name": "Matthew Bourque" - }, - { - "name": "Matthew Hartley" - }, - { - "name": "Maxim Belkin" + "name": "Ryan Wick", + "orcid": "0000-0003-2143-7407" }, { - "name": "Megan Potterbusch" + "name": "Katrin Leinweber" }, { - "name": "Michael Torpey" + "name": "Bill McMillin" }, { - "name": "Mingsheng Zhang" + "name": "Cornelia Cronje", + "orcid": "0000-0003-2736-6267" }, { - "name": "Oscar Arbeláez" + "name": "DSTraining" }, { - "name": "Peace Ossom Williamson", - "orcid": "0000-0001-6229-7514" + "name": "Evan Williamson", + "orcid": "0000-0002-7990-9924" }, { - "name": "Rene Gassmoeller" + "name": "Thea Atwood" }, { - "name": "Richard Barnes" + "name": "Tracy Teal" }, { - "name": "Ruud Steltenpool" + "name": "222064h" }, { - "name": "Samuel Lelièvre" + "name": "Adrian Pohl" }, { - "name": "Sarah Stevens", - "orcid": "0000-0002-7040-548X" + "name": "Alexander Mendes" }, { - "name": "Schlauch, Tobias" + "name": "ajtag" }, { - "name": "Scott Bailey" + "name": "Anna Oates" }, { - "name": "Samniqueka Halsey", - "orcid": "0000-0002-6312-2297" + "name": "Christina Koch", + "orcid": "0000-0001-8600-8158" }, { - "name": "Stefan Siegert" + "name": "Daniel Brett" }, { - "name": "Thomas Morrell", - "orcid": "0000-0001-9266-5146" + "name": "Eric Lopatin" }, { - "name": "Tommy Keswick" + "name": "Jonah Duckles" }, { - "name": "Tracy Teal", - "orcid": "0000-0002-9180-9598" + "name": "Kunal Marwaha", + "orcid": "0000-0001-9084-6971" }, { - "name": "Trevor Keller", - "orcid": "0000-0002-2920-8302" + "name": "Madhulika B" }, { - "name": "TrevorLeeCline" + "name": "marswrae" }, { - "name": "Tyler Crawford Kelly", - "orcid": "0000-0002-2288-4906" + "name": "mfgaede" }, { - "name": "Tyler Reddy", - "orcid": "0000-0003-2364-6157" + "name": "Nitesh Turaga" }, { - "name": "Veronica Ikeshoji-Orlati" + "name": "Shari Laster" }, { - "name": "Wes Harrell" + "name": "skramer-Y2K" }, { - "name": "Will Usher" + "name": "VictorE87" }, { - "name": "Wolmar Nyberg Åkerström" + "name": "Yuri" } ], "license": { diff --git a/_episodes/02-getting-started.md b/_episodes/02-getting-started.md index 2287b6eb..2d5e069e 100644 --- a/_episodes/02-getting-started.md +++ b/_episodes/02-getting-started.md @@ -18,18 +18,18 @@ keypoints: ### Using Git -One of the main barriers to getting started with git is the language. Although some of the language used in git is -fairly self-explanatory, other terms are not so clear. The best way to get to learn the language - which consists of a -number of verbs such as `add`, `commit` and `push` (preceded by the word 'git') - is by using it, which is what we will be doing during this -lesson. These commands will be explained as we proceed from setting up a new version-controlled project to publishing +One of the main barriers to getting started with git is the language. Although some of the language used in git is +fairly self-explanatory, other terms are not so clear. The best way to get to learn the language - which consists of a +number of verbs such as `add`, `commit` and `push` (preceded by the word 'git') - is by using it, which is what we will be doing during this +lesson. These commands will be explained as we proceed from setting up a new version-controlled project to publishing our own website. ### Creating a repository -A Git **repository** is a data structure used to track changes to a set of project files over time. Repositories are -stored within the same directory as these project files, in a hidden directory called `.git`. We can create a new git -repository either by using [GitHub's web interface](https://github.com/new), or via the command line. Let's use the command line to create a git +A Git **repository** is a data structure used to track changes to a set of project files over time. Repositories are +stored within the same directory as these project files, in a hidden directory called `.git`. We can create a new git +repository either by using [GitHub's web interface](https://github.com/new), or via the command line. Let's use the command line to create a git repository for the experiments that we're going to do today. First, we will create a new directory for our project and enter that directory. @@ -39,29 +39,29 @@ First, we will create a new directory for our project and enter that directory. $ mkdir hello-world $ cd hello-world ~~~ -{: .bash} +{: .language-bash } -We will now create an empty git repository to track changes to our project. To do this we will use the git **init** command, +We will now create an empty git repository to track changes to our project. To do this we will use the git **init** command, which is simply short for *initialise*. ~~~ $ git init ~~~ -{: .bash} +{: .language-bash } ~~~ Initialized empty Git repository in /hello-world/.git/ ~~~ {: .output} -The `hello-world` directory is now a git repository. +The `hello-world` directory is now a git repository. -If we run the `ls` command now (`ls` lists the content of the `hello-world` -directory), the repository might seem empty; however, adding the `-a` flag -for all files via `ls -a` will show all hidden files, which in this case +If we run the `ls` command now (`ls` lists the content of the `hello-world` +directory), the repository might seem empty; however, adding the `-a` flag +for all files via `ls -a` will show all hidden files, which in this case includes the new hidden directory `.git`. Flags can simply be thought of as command line options that can be added to shell commands. -Note that whenever we use git via the command line, we need to preface each command (or verb) with `git`, so that the computer knows +Note that whenever we use git via the command line, we need to preface each command (or verb) with `git`, so that the computer knows we are trying to get git to do something, rather than some other program. ### Displaying the current project's status @@ -71,7 +71,7 @@ We can run the `git status` command to display the current state of a project. L ~~~ $ git status ~~~ -{: .bash} +{: .language-bash } ~~~ On branch master No commits yet @@ -79,14 +79,14 @@ nothing to commit (create/copy files and use "git add" to track) ~~~ {: .output} -The output tells us that we are on the master branch (more on this later) and that we have nothing to commit (no +The output tells us that we are on the master branch (more on this later) and that we have nothing to commit (no unsaved changes). ### Adding and committing -We will now create and save our first project file. This is a two-stage process. First, we **add** any files for which -we want to save the changes to a staging area, then we **commit** those changes to the repository. This two-stage +We will now create and save our first project file. This is a two-stage process. First, we **add** any files for which +we want to save the changes to a staging area, then we **commit** those changes to the repository. This two-stage process gives us fine-grained control over what should and should not be included in a particular commit. Let's create a new file using the `touch` command, which is a quick way to create an empty file. @@ -94,7 +94,7 @@ Let's create a new file using the `touch` command, which is a quick way to creat ~~~ $ touch index.md ~~~ -{: .bash} +{: .language-bash } The `.md` extension above signifies that we have chosen to use the Markdown format, a lightweight markup language with plain text formatting syntax. We will explore Markdown a bit later. @@ -103,7 +103,7 @@ Let's check the status of our project again. ~~~ $ git status ~~~ -{: .bash} +{: .language-bash } ~~~ On branch master No commits yet @@ -116,21 +116,21 @@ nothing added to commit but untracked files present (use "git add" to track) ~~~ {: .output} -This status is telling us that git has noticed a new file in our directory that we are not yet tracking. With colourised -output, the filename will appear in red. To change this, and to tell Git we want to track any changes we make to +This status is telling us that git has noticed a new file in our directory that we are not yet tracking. With colourised +output, the filename will appear in red. To change this, and to tell Git we want to track any changes we make to index.md, we use `git add`. ~~~ $ git add index.md ~~~ -{: .bash} +{: .language-bash } This adds our Markdown file to the **staging area** (the area where git checks for file changes). To confirm this we want to use `git status` again. ~~~ $ git status ~~~ -{: .bash} +{: .language-bash } ~~~ On branch master @@ -153,7 +153,7 @@ has spotted the changes. ~~~ $ git status ~~~ -{: .bash} +{: .language-bash } ~~~ On branch master @@ -172,16 +172,16 @@ Changes not staged for commit: ~~~ {: .output} -This lets us know that git has indeed spotted the changes to our file, but that it hasn't yet staged them, so let's add +This lets us know that git has indeed spotted the changes to our file, but that it hasn't yet staged them, so let's add the new version of the file to the staging area. ~~~ $ git add index.md ~~~ -{: .bash} +{: .language-bash } -Now we are ready to **commit** our first changes. -Commit is similar to 'saving' a file to Git. +Now we are ready to **commit** our first changes. +Commit is similar to 'saving' a file to Git. However, compared to saving, a commit provides a lot more information about the changes we have made, and this information will remain visible to us later. @@ -189,7 +189,7 @@ and this information will remain visible to us later. ~~~ $ git commit -m 'Add index.md' ~~~ -{: .bash} +{: .language-bash } ~~~ [master (root-commit) e9e8fd3] Add index.md 1 file changed, 1 insertion(+) @@ -197,7 +197,7 @@ $ git commit -m 'Add index.md' ~~~ {: .output} -We can see that one file has changed and that we made one insertion, which was a line with the text '#Hello, world!'. +We can see that one file has changed and that we made one insertion, which was a line with the text '#Hello, world!'. We can also see the commit message 'Add index.md', which we added by using the `-m` flag after `git commit`. The commit message is used to record a short, descriptive, and specific summary of what we did to help us remember later on without having to look at the actual changes. @@ -229,6 +229,6 @@ along with metadata about who made the commit and at what time. ![The Git Staging Area](../fig/git-staging-area.svg) -At the moment, our changes are only recorded locally, on our computer. If we wanted to +At the moment, our changes are only recorded locally, on our computer. If we wanted to work collaboratively with someone else they would have no way of seeing what we've done. We will fix that in the next episode by using GitHub to share our work. diff --git a/_episodes/03-sharing.md b/_episodes/03-sharing.md index b297e2b4..03356527 100644 --- a/_episodes/03-sharing.md +++ b/_episodes/03-sharing.md @@ -73,7 +73,7 @@ to the GitHub repository: ~~~ $ git remote add origin https://github.com/some-librarian/hello-world.git ~~~ -{: .bash} +{: .language-bash } where `some-librarian` should be replaced with your own username. @@ -88,7 +88,7 @@ We can check that it is set up correctly with the command: ~~~ $ git remote -v ~~~ -{: .bash} +{: .language-bash } ~~~ origin https://github.com//hello-world (fetch) origin https://github.com//hello-world (push) @@ -105,7 +105,7 @@ will have to "push" our local changes to the GitHub repository. We do this using ~~~ $ git push -u origin master ~~~ -{: .bash} +{: .language-bash } ~~~ Counting objects: 3, done. Writing objects: 100% (3/3), 226 bytes | 0 bytes/s, done. @@ -118,22 +118,22 @@ Branch master set up to track remote branch master from origin. The nickname of our remote repository is "origin" and the default local branch name is "master". The `-u` flag tells git to remember the parameters, so that next time we can simply run `git push` -and Git will know what to do. +and Git will know what to do. -Pushing our local changes to the Github repository is sometimes referred to as "pushing changes `upstream` to Github". -The word `upstream` here comes from the git flag we used earlier in the command `git push -u origin master`. -The flag `-u` refers to `-set-upstream`, so when we say pushing changes upstream, it refers to the remote repository. +Pushing our local changes to the Github repository is sometimes referred to as "pushing changes `upstream` to Github". +The word `upstream` here comes from the git flag we used earlier in the command `git push -u origin master`. +The flag `-u` refers to `-set-upstream`, so when we say pushing changes upstream, it refers to the remote repository. You may be prompted to enter your GitHub username and password to complete the command. -When we do a `git push`, we will see Git 'pushing' changes upstream to GitHub. Because our file is very small, this -won't take long but if we had made a lot of changes or were adding a very large repository, we might have to wait a -little longer. We can check where we're at with `git status`. +When we do a `git push`, we will see Git 'pushing' changes upstream to GitHub. Because our file is very small, this +won't take long but if we had made a lot of changes or were adding a very large repository, we might have to wait a +little longer. We can check where we're at with `git status`. ~~~ $ git status ~~~ -{: .bash} +{: .language-bash } ~~~ On branch master Your branch is up-to-date with 'origin/master'. @@ -141,17 +141,17 @@ nothing to commit, working tree clean ~~~ {: .output} -This output lets us know where we are working (the master branch). We can also see that we have no changes to commit +This output lets us know where we are working (the master branch). We can also see that we have no changes to commit and everything is in order. -We can use the `git diff` command to see changes we have made before making a commit. Open index.md with any text +We can use the `git diff` command to see changes we have made before making a commit. Open index.md with any text editor and enter some text on a new line, for instance "A new line" or something else. We will then use `git diff` to see the changes we made: ~~~ $ git diff ~~~ -{: .bash} +{: .language-bash } ~~~ diff --git a/index.md b/index.md index aed0629..989787e 100644 @@ -168,12 +168,12 @@ index aed0629..989787e 100644 The command produces lots of information and it can be a bit overwhelming at first, but let's go through some key information here: -1. The first line tells us that Git is producing output similar to the Unix `diff` command, comparing the old and new +1. The first line tells us that Git is producing output similar to the Unix `diff` command, comparing the old and new versions of the file. -2. The second line tells exactly which versions of the file Git is comparing; `aed0629` and `989787e` are unique +2. The second line tells exactly which versions of the file Git is comparing; `aed0629` and `989787e` are unique computer-generated identifiers for those versions. 3. The third and fourth lines once again show the name of the file being changed. -4. The remaining lines are the most interesting; they show us the actual differences and the lines on which they occur. +4. The remaining lines are the most interesting; they show us the actual differences and the lines on which they occur. In particular, the + markers in the first column show where we have added lines. We can now commit these changes: @@ -182,16 +182,16 @@ We can now commit these changes: $ git add index.md $ git commit -m 'Add another line' ~~~ -{: .bash} +{: .language-bash } -If we are very forgetful and have already forgotten what we changes we have made, `git log` allows us to look at what +If we are very forgetful and have already forgotten what we changes we have made, `git log` allows us to look at what we have been doing with our git repository (in reverse chronological order, with the very latest changes first). ~~~ $ git log ~~~ -{: .bash} +{: .language-bash } ~~~ commit 8e2eb9920eaa0bf18a4adfa12474ad58b765fd06 Author: Your Name @@ -207,9 +207,9 @@ Date: Fri Jun 2 18:15:43 2017 +0100 ~~~ {: .output} -This shows us the two commits we have made and shows the messages we wrote. It is important to try to use meaningful -commit messages when we make changes. This is especially important when we are working with other people who might not -be able to guess as easily what our short cryptic messages might mean. Note that it is best practice to always write +This shows us the two commits we have made and shows the messages we wrote. It is important to try to use meaningful +commit messages when we make changes. This is especially important when we are working with other people who might not +be able to guess as easily what our short cryptic messages might mean. Note that it is best practice to always write commit messages in the imperative (e.g. 'Add index.md', rather than 'Adding index.md'). ## Pushing changes (again) @@ -224,8 +224,8 @@ And if you click on `index.md` you will see that it contains the "Hello, world!" but not the new line we just added. This is because we haven't yet pushed our local changes to the remote repository. -This might seem like a mistake in design but it is -often useful to make a lot of commits for small changes so you are able to make careful revisions later and you don't +This might seem like a mistake in design but it is +often useful to make a lot of commits for small changes so you are able to make careful revisions later and you don't necessarily want to push all these changes one by one. Another benefit of this design is that you can make commits without being connected to internet. @@ -235,7 +235,7 @@ But let's push our changes now, using the `git push` command: ~~~ $ git push ~~~ -{: .bash} +{: .language-bash } ~~~ Counting objects: 3, done. Writing objects: 100% (3/3), 272 bytes | 0 bytes/s, done. @@ -250,16 +250,16 @@ And let's check on GitHub that we now have 2 commits there. ## Pulling changes When working with others, or when we're making our own changes from different machines, we need a way of pulling those -remote changes back into our local copy. For now, we can see how this works by making a change on the GitHub website and +remote changes back into our local copy. For now, we can see how this works by making a change on the GitHub website and then 'pulling' that change back to our computer. -Let's go to our repository in GitHub and make a change. Underneath where our index.md file is listed you will see a -button to 'Add a README'. Do this now, entering whatever you like, scrolling to the bottom and clicking 'Commit new +Let's go to our repository in GitHub and make a change. Underneath where our index.md file is listed you will see a +button to 'Add a README'. Do this now, entering whatever you like, scrolling to the bottom and clicking 'Commit new file' (The default commit message will be 'Create README.md', which is fine for our purposes). > ## The README file -> It is good practice to add a README file to each project to give a brief overview of what the project is about. If you -> put your README file in your repository's root directory, GitHub will recognize and automatically surface your README +> It is good practice to add a README file to each project to give a brief overview of what the project is about. If you +> put your README file in your repository's root directory, GitHub will recognize and automatically surface your README > to repository visitors {: .callout} @@ -269,7 +269,7 @@ our local repository using the `git pull` command. ~~~ $ git pull ~~~ -{: .bash} +{: .language-bash } ~~~ remote: Counting objects: 3, done. remote: Compressing objects: 100% (2/2), done. @@ -288,6 +288,6 @@ Fast-forward The above output shows that we have fast-forwarded our local repository to include the file README.md. We could confirm this by entering the `ls` command. -When we begin collaborating on more complex projects, we may have to consider more aspects of git functionality, but +When we begin collaborating on more complex projects, we may have to consider more aspects of git functionality, but this should be a good start. In the next section, we can look more closely at collaborating and using GitHub pages to create a website for our project. diff --git a/_episodes/05-github-pages.md b/_episodes/05-github-pages.md index ca1805b3..c7d290f1 100644 --- a/_episodes/05-github-pages.md +++ b/_episodes/05-github-pages.md @@ -22,22 +22,22 @@ which renders Markdown into HTML and makes it really easy to setup a blog or a t ### Why GitHub Pages is awesome! -GitHub Pages allows you to version control your website. This is useful for a lot of different reasons. It allows you to -keep a record of what changes you have made. It allows people to reference your website at a particular point in time -and (if you make your source open) to see what it was like at that particular point in time. This is very useful for -academic citations. Most people have had the experience of following up a reference to a website and either getting a -404 error or seeing something completely different. Although using versions on your site doesn't guarantee this won't +GitHub Pages allows you to version control your website. This is useful for a lot of different reasons. It allows you to +keep a record of what changes you have made. It allows people to reference your website at a particular point in time +and (if you make your source open) to see what it was like at that particular point in time. This is very useful for +academic citations. Most people have had the experience of following up a reference to a website and either getting a +404 error or seeing something completely different. Although using versions on your site doesn't guarantee this won't happen, it does make it easier to manage old versions of your site. -GitHub Pages also mean that you can collaborate on a website with a lot of people without everyone having to -communicate endlessly back and forwards about what changes need to be made, or have been made already. You can create -'issues' (things that need discussing or fixing), list things to do in the future, and allow other people visiting your +GitHub Pages also mean that you can collaborate on a website with a lot of people without everyone having to +communicate endlessly back and forwards about what changes need to be made, or have been made already. You can create +'issues' (things that need discussing or fixing), list things to do in the future, and allow other people visiting your website to quickly suggest, and help implement changes through pull requests. ### Setting up a site -Now we're all persuaded of how awesome GitHub Pages is (or you've identified some fatal flaws in my reasoning), it -would be useful to try playing around with some things we can do with it. This will help us cement what we +Now we're all persuaded of how awesome GitHub Pages is (or you've identified some fatal flaws in my reasoning), it +would be useful to try playing around with some things we can do with it. This will help us cement what we have learned in the previous hour and may help spark discussion for the last section of this session. There are various options for setting up a GitHub Pages site. Let's run through a few of them now. @@ -56,7 +56,7 @@ So we will move back to the command line and type $ git checkout -b gh-pages $ git push ~~~ -{: .bash} +{: .language-bash } ~~~ fatal: The current branch gh-pages has no upstream branch. To push the current branch and set the remote as upstream, use @@ -77,7 +77,7 @@ So let's do that: ~~~ $ git push --set-upstream origin gh-pages ~~~ -{: .bash} +{: .language-bash } ~~~ Total 0 (delta 0), reused 0 (delta 0) To https://github.com/danmichaelo/hello-world.git @@ -103,29 +103,29 @@ Usually it's available instantly, but it can take a few seconds and in the worst > > To practice using Git, GitHub pages and Markdown we can contribute to a GitHub pages site. > Pair up in groups of two (or more if needed) and do the exercises below together. -> +> > 1. Go to https://github.com/some-librarian/hello-world, where "some-librarian" is the username of your exercise partner. > 2. Click on "Fork" in the upper right part of the screen to create a copy of the repository on your account. Once you have a fork > of your partner's repository, you can edit the files in your own fork directly. > 3. Click the "index.md" file, then click the edit pencil icon: -> +> > ![GitHub edit pencil](../fig/github-edit-pencil.png) -> +> > 4. Now is good chance to try some Markdown syntax. > Try some of the examples at [Mastering Markdown](https://guides.github.com/features/mastering-markdown/). > You can preview how it will look before you commit changes. > 5. Once you are ready to commit, enter a short commit message, > select "Create a new branch for this commit and start a pull request" > and press "Propose file change" to avoid commiting directly to the master branch. -> +> > ![Commit and create pull request](../fig/github-commit-pr.png) -> -> 8. You can now go to the repository on your account and click "New Pull Request" button, +> +> 8. You can now go to the repository on your account and click "New Pull Request" button, > where you can select base branches repositories, review the changes and add an additional > explanation before sending the pull request (this is especially useful > if you make a single pull request for multiple commits). > 9. Your partner should now see a pull request under the "Pull requests" tab > and can accept ("Merge pull request") the changes there. Try this. -> +> > This whole process of making a fork and a pull request might seem a bit cumbersome. > Try to think of why it was needed? And why it's called "pull request"? > @@ -168,7 +168,7 @@ Usually it's available instantly, but it can take a few seconds and in the worst > > ![Branch selector on GitHub](../fig/github-gh-pages.png) > -> 2. To add a new file directly on GitHub, press the "Create new file" button. +> 2. To add a new file directly on GitHub, press the "Create new file" button. > > ![Create new file on GitHub](../fig/github-create-new-file.png) > diff --git a/setup.md b/setup.md index f6c8de2c..a0a5397c 100644 --- a/setup.md +++ b/setup.md @@ -13,25 +13,25 @@ If you haven't done so already, to follow this lesson you will need to: $ git config --global user.name "Your Name" $ git config --global user.email "your@email" ~~~ -{: .bash} +{: .language-bash } -This user name and email will be recorded with each commit in the history of your repositories. +This user name and email will be recorded with each commit in the history of your repositories. The email address should be the same one you used when setting up your GitHub account. By default, Git will open the Vi / Vim text editor to request commit messages (for example when merging conflicts). -To avoid confusion, most people will want to change the default editor to something more familiar using the `core.editor` config. -Any text editor can be made default by adding the correct file path and command line options (see [GitHub help](https://help.github.com/articles/associating-text-editors-with-git/)). -However, the simplest `core.editor` values are `"notepad"` on Windows, `"nano -w"` on Mac, and `"nano -w"` on Linux. +To avoid confusion, most people will want to change the default editor to something more familiar using the `core.editor` config. +Any text editor can be made default by adding the correct file path and command line options (see [GitHub help](https://help.github.com/articles/associating-text-editors-with-git/)). +However, the simplest `core.editor` values are `"notepad"` on Windows, `"nano -w"` on Mac, and `"nano -w"` on Linux. For example: ~~~ $ git config --global core.editor "notepad" ~~~ -{: .bash} +{: .language-bash } You will NOT get an immediate error message if you specify an incorrect or non-existent text editor command here. Therefore, you may first wish to test that the text editor you specify can be invoked, with (for the above example of `"notepad"` on Windows): ~~~ $ touch deleteme.txt -$ notepad deleteme.txt +$ notepad deleteme.txt ~~~ -{: .bash} +{: .language-bash }