diff --git a/01-what-is-git.md b/01-what-is-git.md new file mode 100644 index 00000000..b50b7d47 --- /dev/null +++ b/01-what-is-git.md @@ -0,0 +1,82 @@ +--- +title: What is Git/GitHub? +teaching: 10 +exercises: 0 +--- + +::::::::::::::::::::::::::::::::::::::: objectives + +- recognize why version control is useful +- distinguish between Git and GitHub + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- What is Git? +- What is GitHub? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +## What is Version Control + +Version control is a name used for software which can help you record changes you make to the files in a directory on your computer. Version control software and tools (such as Git and Subversion/SVN) are often associated with software development, and increasingly, they are being used to collaborate in research and academic environments. Version control systems work best with plain text files such as documents or computer code, but modern version control systems can be used to track changes in most types of file. + +At its most basic level, version control software helps us register and track sets of changes made to files on our computer. We can then reason about and share those changes with others. As we build up sets of changes over time, we begin to see some benefits. + +### Benefits of using version control? + +- **Collaboration** - Version control allows us to define formalized ways we can work together and share writing and code. For example merging together sets of changes from different parties enables co-creation of documents and software across distributed teams. +- **Versioning** - Having a robust and rigorous log of changes to a file, without renaming files (v1, v2, *final\_copy*) +- **Rolling Back** - Version control allows us to quickly undo a set of changes. This can be useful when new writing or new additions to code introduce problems. +- **Understanding** - Version control can help you understand how the code or writing came to be, who wrote or contributed particular parts, and who you might ask to help understand it better. +- **Backup** - While not meant to be a backup solution, using version control systems mean that your code and writing can be stored on multiple other computers. + +There are many more reasons to use version control, and we'll explore some of these in the library context, but first let's learn a bit about a popular version control tool called Git. + +## What are Git and GitHub? + +We often hear the terms ***Git*** and ***GitHub*** used interchangeably but they are slightly different things. + +***Git*** is one of the most widely used version control systems in the world. It is a free, open source tool that can be downloaded to your local machine and used for logging all changes made to a group of designated computer files (referred to as a "git repository" or "repo" for short) over time. It can be used to control file versions locally by you alone on your computer, but is perhaps most powerful when employed to coordinate simultaneous work on a group of files shared among distributed groups of people. + +Rather than emailing documents with tracked changes and some comments and renaming different versions of files (example.txt, exampleV2.txt, exampleV3.txt) to differentiate them, we can use Git to save (or in Git parlance, "commit") all that information with the document itself. This makes it easy to get an overview of all changes made to a file over time by looking at a log of all the changes that have been made. And all earlier versions of each file still remain in their original form: they are not overwritten, should we ever wish to "roll back" to them. + +Git was originally developed to help software developers work collaboratively on software projects, but it can be and is used for managing revisions to any file type on a computer system, including text documents and spreadsheets. Once installed, interaction with Git is done through the Command Prompt in Windows, or the Terminal on Mac/Linux. Since Word documents contain special formatting, Git unfortunately cannot version control those, nor can it version control PDFs, though both file types can be stored in Git repositories. + +*How can understanding Git help with work in libraries?* + +- Enables you to contribute to, collaborate on, and support digital research projects +- Enables you to control changes to your files over time without keeping multiple copies of those files + +***GitHub*** on the other hand is a popular website for hosting and sharing Git repositories remotely. It offers a web interface and provides functionality and a mixture of both free and paid services for working with such repositories. The majority of the content that GitHub hosts is open source software, though increasingly it is being used for other projects such as open access journals (e.g. [Journal of Open Source Software](https://joss.theoj.org/)), blogs, and regularly updated text books. In addition to GitHub, there are other Git hosting services that offer many similar features such as [GitLab](https://about.gitlab.com/), [Bitbucket](https://bitbucket.org/) and [Gitee](https://gitee.com/). + +*How can GitHub help with work in libraries?* + +- A place to discover and reuse ("fork") a huge amount of openly licensed digital projects and open source software +- A new and alternative means for publishing content online. Any GitHub repository can have its own project website, blog and wiki using GitHub Pages. + +## Uses in a Library Context + +Consider these common library world scenarios: + +### Scenario 1: Local library looking to start a crowdsourcing project + +A local librarian is looking to put thousands of historical photographs of the area online so that the community can help identify the people and places they depict. She combs the web for examples of existing crowdsourcing projects, and even though they all appear unique to each institution, she notices quite a few seem to have almost the exact same functionality and structure. Rather than build a whole new version from scratch herself, she wishes there was a way to just copy the code of an existing one, and modify it to reflect her project. She notices the [GitHub icon](https://github.com/logos) at the bottom of one of the projects she likes, but clicking on the link just brings her to a confusing directory of files and oddly labeled buttons such as "Fork". + +GitHub hosts many open-licensed projects and allows any user to fork any public project. By clicking the "fork" button, any GitHub user can almost instantaneously create their own version of an existing project. That "forked" project can be used as the basis for a new project, or can be used to work out new features that can be merged back into the original. (From: [GitHub for Academics](https://hybridpedagogy.org/push-pull-fork-github-for-academics/) ) + +### Scenario 2: Multiple people editing metadata for a collection + +A metadata specialist has exported a spreadsheet from a repository for cleaning and editing. She's working with a group of library workers and students, so they need to make sure edits don't conflict. They also need to be able to undo any edits and preserve the original metadata. Once edits are complete, the whole group wants to review the changes before re-ingesting the spreadsheet of metadata into the repository. + +The team can choose to use Git by itself to track changes and resolve conflicts or they can choose to use GitHub to host the project so that users can collaborate and review changes on the Web. Git will preserve the original metadata as well as all edits. GitHub will facilitate discussion about what changes should be made, who should make them, and why. + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- Version control helps track changes to files and projects +- Git and GitHub are not the same + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + diff --git a/02-getting-started.md b/02-getting-started.md new file mode 100644 index 00000000..ac5ebbd1 --- /dev/null +++ b/02-getting-started.md @@ -0,0 +1,331 @@ +--- +title: Getting started with Git +teaching: 25 +exercises: 0 +--- + +::::::::::::::::::::::::::::::::::::::: objectives + +- create a Git repository +- track changes to files using the Git repository +- query the current status of the Git repository + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- What are repositories and how are they created? +- What do `add` and `commit` mean? +- How do I check the status of my repository? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +### Setting up Git + +When we use Git on a new computer for the first time, +we need to configure a few things. The basic elements of a configuration for Git are: + +- your name and email address, +- what your preferred text editor is, +- the name of your default branch (branches are an important component of Git that we will cover later). + +To start we will check in on our current Git configuration. Open your shell terminal window and type: + +```bash +$ git config --list +``` + +On MacOS, without any configuration your output might look like this: + +```output +credential.helper=osxkeychain +``` + +On Windows, without any configuration your output might look like this: + +```output +diff.astextplain.textconv=astextplain +filter.lfs.clean=git-lfs clean -- %f +filter.lfs.smudge=git-lfs smudge -- %f +filter.lfs.process=git-lfs filter-process +filter.lfs.required=true +http.sslbackend=openssl +http.sslcainfo=C:/Program Files/Git/mingw64/ssl/certs/ca-bundle.crt +core.autocrlf=true +core.fscache=true +core.symlinks=false +pull.rebase=false +credential.helper=manager-core +credential.https://dev.azure.com.usehttppath=true +init.defaultbranch=main +``` + +If you have different output, then you may have your Git configured already. If you have not configured Git, we will do that together now. +First, we will tell Git our user name and email. + +Please note: You need to use the same email address in your Git configuration in the shell as you entered into GitHub when you created your GitHub account. Later in the lesson we will be using GitHub and the email addresses need to match. If you are concerned about privacy, please review [GitHub's instructions for keeping your email address private](https://help.github.com/articles/keeping-your-email-address-private/). + +Type these two commands into your shell, replacing `Your Name` and the email address with your own: + +```bash +$ git config --global user.name "Your Name" +$ git config --global user.email "yourname@domain.name" +``` + +If you enter the commands correctly, the shell will merely return a command prompt and no messages. To check your work, ask Git what your configuration is using the same command as above: + +```bash +git config --list +``` + +```output +user.name=Your Name +user.email=yourname@domain.name +``` + +Let's also set our default text editor. A text editor is necessary with some of your Git work, and the default from Git is Vim, which is a text editor that is hard to learn at first. Therefore, we recommend setting a simpler text editor in your Git configuration for this lesson. + +::::::::::::::::::::::::::::::::::::::::: callout + +## Text editors + +There are a lot of text editors to choose from, and a lot of people are enthusiastic about their preferences. +Vi and Vim are popular editors for users of the BASH shell. If you will be using Git or the Shell with a group of people for a project or for work, asking for recommendations or preferences can help you pick an editor to get started with. If you already have your favorite, then you can set it as your default editor with Git. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +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: + +```bash +$ git config --global core.editor "notepad" +``` + +```bash +$ git config --global core.editor "nano -w" +``` + +Lastly, we need to set the name of our default branch to `main.` + +```bash +$ git config --global init.defaultBranch main +``` + +The `init.defaultBranch` value configures git to set the default branch to `main` instead of `master`. + +### 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 +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. We will explain commands as we go along. + +```bash +$ mkdir hello-world +$ cd hello-world +``` + +### Using Git + +One of the main barriers to getting started with Git is understanding the terminology necessary to executing commands. Although some of the language used in Git aligns with common-use words in English, other terms are not so clear. The best way to learn Git terminology - which consists of a number of verbs such as add, commit and push (preceded by the word 'git') - is to use it, which is what we will be doing during this lesson. We will explain these commands as we proceed from setting up a new version-controlled project to publishing our own website. + +On a command line interface, Git commands are written as `git verb options`, +where `verb` is what we actually want to do and `options` is additional optional information which may be needed for the `verb`. So let's get started with our setup. + +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*. + +```bash +$ git init +``` + +```output +Initialized empty Git repository in /hello-world/.git/ +``` + +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 +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 +we are trying to get git to do something, rather than some other program. + +### Displaying the current project's status + +We can run the `git status` command to display the current state of a project. Let's do that now. + +```bash +$ git status +``` + +```output +On branch main +No commits yet +nothing to commit (create/copy files and use "git add" to track) +``` + +The output tells us that we are on the main branch (more on this later) and that we have nothing to commit (no +unsaved changes). + +### Two steps: Adding and committing + +We will now create and save our first project file. This is a two-step 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. + +```bash +$ touch index.md +``` + +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. + +Let's check the status of our project again. + +```bash +$ git status +``` + +```output +On branch main +No commits yet +Untracked files: + (use "git add ..." to include in what will be committed) + + index.md + +nothing added to commit but untracked files present (use "git add" to track) +``` + +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`. + +```bash +$ git add index.md +``` + +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. + +```bash +$ git status +``` + +```output +On branch main + +No commits yet + +Changes to be committed: + (use "git rm --cached ..." to unstage) + + new file: index.md +``` + +If we are using colourised output, we will see that the filename has changed colour (from red to green). Git also tells us that there +is a new file to be committed but, before we do that, let's add some text to the file. + +We will open the file `index.md` with any text editor we have at hand (e.g. Notepad on Windows or TextEdit on Mac OSX) and enter `# Hello, world!`. The +hash character is one way of writing a header with Markdown. Now, let's save the file within the text editor and check if Git +has spotted the changes. + +```bash +$ git status +``` + +```output +On branch main + +No commits yet + +Changes to be committed: + (use "git rm --cached ..." to unstage) + + new file: index.md + +Changes not staged for commit: + (use "git add ..." to update what will be committed) + (use "git checkout -- ..." to discard changes in working directory) + + modified: index.md +``` + +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. + +```bash +$ git add index.md +``` + +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. + +```bash +$ git commit -m 'Add index.md' +``` + +```output +[main (root-commit) e9e8fd3] Add index.md + 1 file changed, 1 insertion(+) + create mode 100644 index.md +``` + +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. +If we just run `git commit` without the `-m` option, Git will launch nano (or whatever other editor we configured as `core.editor`) +so that we can write a longer message. + +Having made a commit, we now have a permanent record of what was changed, +and git has also recorded some additional metadata: who made the commit (you!) and when the commit was made (timestamp). You are building a mini-history of your process of working with the files in this directory. + +::::::::::::::::::::::::::::::::::::::::: callout + +## More on the Staging Area + +If you think of Git as taking snapshots of changes over the life of a project, +`git add` specifies *what* will go in a snapshot +(putting things in the staging area), +and `git commit` then *actually takes* the snapshot, and +makes a permanent record of it (as a commit). +If you don't have anything staged when you type `git commit`, +Git will prompt you to use `git commit -a` or `git commit --all`, +which is kind of like gathering *everyone* for the picture! +However, it's almost always better to +explicitly add things to the staging area, because you might +commit changes you forgot you made. (Going back to snapshots, +you might get the extra with incomplete makeup walking on +the stage for the snapshot because you used `-a`!) +Try to stage things manually, +or you might find yourself searching for "git undo commit" more +than you would like! + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +![](fig/git-staging-area.svg){alt='The Git Staging Area'} + +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. + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- When you initialize a Git repository in a directory, Git starts tracking the changes you make inside that directory. +- This tracking creates a history of the way the files have changed over time. +- Git uses a two-step process to record changes to your files. Changes to files must first be added to the staging area, then committed to the Git repository. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + diff --git a/03-sharing.md b/03-sharing.md new file mode 100644 index 00000000..e52b7508 --- /dev/null +++ b/03-sharing.md @@ -0,0 +1,455 @@ +--- +title: Sharing your work +teaching: 75 +exercises: 0 +--- + +::::::::::::::::::::::::::::::::::::::: objectives + +- create a remote repository on GitHub +- link a local Git repository to a remote GitHub repository +- move changes between the local and remote repositories using `push` and `pull` +- examine the difference between an edited file and the file's most recently committed version + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- How can I use Git and GitHub to share my work? +- How do I link a local Git repository to GitHub? +- How do I move changes between a local Git repository and a GitHub repository? +- How can I see the differences between my current file and my most recent commit? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +## The power of sharing + +The real power of Git lies in being able to share your work with others and in being able to work collaboratively. The best way to do this is to use a remote hosting platform. For this lesson, we are using GitHub. Let's log in there now. + +## Create a repository on GitHub + +Once we have logged in to GitHub, we can create a new repository by clicking the **\+** icon in the upper-right corner of +any page then selecting **New repository**. Let's do this now. + +![](fig/github-repo-new.png){alt="The GitHub website top navigation with the 'add new ...' button."} + +- Click "New Repository" + +Clicking `New Repository` will take you to a creation page with different options. For this workshop, we are not using any of the options available. + +- Name your repository "hello-world." + +![](fig/github-repo-new-setup_copy.png){alt="The 'create a new repository' form on GitHub" .image-with-shadow } + +GitHub will ask if you want to add a README.md, license or a `.gitignore` file. Do not do any of that for now -- We want you to start with a completely empty repository on GitHub. + +- Click `Create Repository` button. + +::::::::::::::::::::::::::::::::::::::::: callout + +## Choosing a license + +When you are ready to use GitHub to host your own work, you should review the different license options. Choosing a license is an important part of openly sharing your creative and research work online. For help in wading through the +many types of open source licenses, please visit [https://choosealicense.com/](https://choosealicense.com/). + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +## Connecting your local repository to the GitHub repository + +The next page that GitHub displays contains some information to help you connect your repository on GitHub with your local repository (on your own computer). To make this connection, we want to tell our local repository that GitHub is the `remote` repository. In order to do that we need the information that GitHub displays in the "Quick setup" box on this page. + +We will use the Secure Shell (SSH) protocol for this lesson, so please make sure that button shows that it is selected (gray highlight) and that the address in the text box starts with git@github. It will look something like this: + +![](fig/github-repo-connect.png){alt="The repository set up page in GitHub showing the SSH address to use."} + +::::::::::::::::::::::::::::::::::::::::: callout + +## HTTPS vs. SSH + +We use SSH here because, while it requires some additional configuration, it is a +security protocol widely used by many applications. The steps below describe SSH at a +minimum level for GitHub. + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + + +In the previous episode we created a local repository on our own computer. +Now we have also created a remote repository on GitHub. +But at this point, the two are completely isolated from each other. +We want to link them together to synchronize them and share our project with the world. + +To connect the repository on our own computer (local) to the repository we just created on GitHub, we will use the commands provided by GitHub in the box with the heading "...or push an existing repository from the command line." + +![](fig/github-instructions.png){alt="GitHub instructions"} + +Let's use these instructions now. Move back to your shell application and enter the first command: + +```bash +$ git remote add origin git@github.com:yourname/hello-world.git +``` + +Make sure to use the URL for your actual repository user name rather than `yourname`: the only +difference should be your username instead of `yourname`. + +Let's breakdown the elements of the command. All commands related to Git in the shell start by invoking the Git language by typing `git` at the start. +`remote add` is the command in the Git language we use to configure a remote repository, e.g., another Git repository that contains the same content as our local repository, but that is not on our computer. +`origin` is the nickname we're telling our local machine to use to for the following long web address. After we enter this command, we can use `origin` to refer to this specific repository in GitHub instead of the URL. + +We can check that it is set up correctly with the command: + +```bash +$ git remote -v +``` + +```output +origin git@github.com:/hello-world.git (fetch) +origin git@github.com:/hello-world.git (push) +``` + +## SSH Background and Setup + +We still need to do a little more setup before we can actually connect to this remote repository. +We need to set up a way for our local computer to authenticate with GitHub so that GitHub recognizes our computer as belonging to the same person who owns the GitHub repository. + +We will use SSH as our authentication method. SSH stands for Secure SHell protocol. SSH is a cryptographic network protocol that allows secure communication between computers using an otherwise insecure network. + +SSH uses what is called a key pair -- two keys that work together to validate access. One key is used publicly (the public key) and the other key is kept private (the private key). + +You can think of the public key as a padlock, and only you have the key (the private key) to open it. You use the public key where you want a secure method of communication, such as your GitHub account. You give this padlock, or public key, to GitHub and say "lock the communications to my account with this so that only computers that have my private key can unlock communications and send Git commands as my GitHub account." + +What we will do now is the minimum required to set up the SSH keys and add the public key to a GitHub account. +I'm not going to lie, this is a bit tedious and confusing. But you have to do it to get to the fun part, so hang in there. + + + + + + + +The first thing we are going to do is check if this has already been done on the computer you're on. + +::::::::::::::::::::::::::::::::::::::::: callout + +## Keeping your keys secure + +You shouldn't really forget about your SSH keys, since they keep your account secure. It's good +practice to audit your secure shell keys every so often. Especially if you are using multiple +computers to access your account. + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +We will run the list command (`ls`) to check what key pairs already exist on your computer. +In our command we use the `~` as the shorthand for "my home directory." + +```bash +ls -al ~/.ssh +``` + +Your output is going to look a little different depending on whether or not SSH has ever been set up on the computer you are using. + +If you have not set up SSH, your output might look like this: + +```output +ls: cannot access '/c/Users/YourName/.ssh': No such file or directory +``` + +If SSH has been set up on the computer you're using, the public and private key pairs will be listed. The file names are either `id_ed25519`/`id_ed25519.pub` or `id_rsa`/`id_rsa.pub` depending on how the key pairs were set up. + +If you do not have SSH set up, let's set it up now. Use this command to create key pairs: + +```bash +$ ssh-keygen -t ed25519 -C "yourname@domain.name" +``` + +```output +Generating public/private ed25519 key pair. +Enter file in which to save the key (/c/Users/YourName/.ssh/id_ed25519): +``` + +We want to use the default file, so just press Enter. + +```output +Created directory '/c/Users/YourName/.ssh'. +Enter passphrase (empty for no passphrase): +``` + +Your computer is now asking you for a passphrase to protect this SSH key pair. We recommend that you use a passphrase and that you make a note of it. There is no "reset my password" option for this setup. If you forget your passphrase, you have to delete your existing key pair and do this setup again. It's not a big deal, but easier if you don't have to repeat it. + +```output +Enter same passphrase again: +``` + +After entering the same passphrase a second time, you will receive the confirmation + +```output +Your identification has been saved in /c/Users/YourName/.ssh/id_ed25519 +Your public key has been saved in /c/Users/YourName/.ssh/id_ed25519.pub +The key fingerprint is: +SHA256:SMSPIStNyA00KPxuYu94KpZgRAYjgt9g4BA4kFy3g1o yourname@domain.name +The key's randomart image is: ++--[ED25519 256]--+ +|^B== o. | +|%*=.*.+ | +|+=.E =.+ | +| .=.+.o.. | +|.... . S | +|.+ o | +|+ = | +|.o.o | +|oo+. | ++----[SHA256]-----+ +``` + +The "identification" is actually the private key. You should never share it. The public key is appropriately named. The "key fingerprint" +is a shorter version of a public key. + +Now that we have generated the SSH keys, we will find the SSH files when we check. + +```bash +ls -al ~/.ssh +``` + +```output +drwxr-xr-x 1 YourName 197121 0 Jul 16 14:48 ./ +drwxr-xr-x 1 YourName 197121 0 Jul 16 14:48 ../ +-rw-r--r-- 1 YourName 197121 419 Jul 16 14:48 id_ed25519 +-rw-r--r-- 1 YourName 197121 106 Jul 16 14:48 id_ed25519.pub +``` + +Now we need to give our public key (the padlock) over to GitHub. + +First, we need to copy the public key. Be sure to include the `.pub` at the end, otherwise you're looking at the private key. + +```bash +cat ~/.ssh/id_ed25519.pub +``` + +```output +ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDmRA3d51X0uu9wXek559gfn6UFNF69yZjChyBIU2qKI yourname@domain.name +``` + +Copy that entire line of output, and we will paste the copied text into GitHub in the next step. + +Now, going to GitHub.com, click on your profile icon in the top right corner to get the drop-down menu. Click "Settings," then on the +settings page, click "SSH and GPG keys," on the left side "Account settings" menu. Click the "New SSH key" button on the right side. Now, +you can add the title (A person might use the title "My 2021 work laptop," just a little description to remind themselves which computer this public key connect to). +Paste your SSH key into the field, and click the "Add SSH key" to complete the setup. + +Now that we've set that up, let's check our authentication from the command line. + +```bash +$ ssh -T git@github.com +``` + +```output +Hi YourName! You've successfully authenticated, but GitHub does not provide shell access. +``` + +## Pushing changes + +Now we have established a connection between the two repositories, but we still haven't +synchronized their content, so the remote repository is still empty. To fix that, we +will have to "push" our local changes to the GitHub repository. We do this using the +`git push` command: + +```bash +$ git push -u origin main +``` + +```output +Counting objects: 3, done. +Writing objects: 100% (3/3), 226 bytes | 0 bytes/s, done. +Total 3 (delta 0), reused 0 (delta 0) +To https://github.com/ main +Branch main set up to track remote branch main from origin. +``` + +The nickname of our remote repository is "origin" and the default local branch name is "main". +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. + +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 main`. +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`. + +```bash +$ git status +``` + +```output +On branch main +Your branch is up-to-date with 'origin/main'. +nothing to commit, working tree clean +``` + +This output lets us know where we are working (the main 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 +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: + +```bash +$ git diff +``` + +```output +diff --git a/index.md b/index.md +index aed0629..989787e 100644 +--- a/index.md ++++ b/index.md +@@ -1 +1,2 @@ +-# Hello, world! +\ No newline at end of file ++# Hello, world! ++A new line +``` + +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 + versions of the file. +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. + In particular, the + markers in the first column show where we have added lines. + +We can now commit these changes: + +```bash +$ git add index.md +$ git commit -m 'Add another line' +``` + +If we are very forgetful and have already forgotten what we changed, `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). + +```bash +$ git log +``` + +```output +commit 8e2eb9920eaa0bf18a4adfa12474ad58b765fd06 +Author: Your Name +Date: Mon Jun 5 12:41:45 2017 +0100 + + Add another line + +commit e9e8fd3f12b64fc3cbe8533e321ef2cdb1f4ed39 +Author: Your Name +Date: Fri Jun 2 18:15:43 2017 +0100 + + Add index.md +``` + +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) + +Now, let's have a look at the repository at GitHub again +(that is, `https://github.com/some-librarian/hello-world` with `some-librarian` replaced with your username). +We see that the `index.md` file is there, but there is only one commit: + +![](fig/github-one-commit.png){alt="Only one commit on GitHub"} + +And if you click on `index.md` you will see that it contains the "Hello, world!" header, +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 +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. + +But let's push our changes now, using the `git push` command: + +```bash +$ git push +``` + +```output +Counting objects: 3, done. +Writing objects: 100% (3/3), 272 bytes | 0 bytes/s, done. +Total 3 (delta 0), reused 0 (delta 0) +To https://github.com//hello-world + e9e8fd3..8e2eb99 main -> main +``` + +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 +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 +file' (The default commit message will be 'Create README.md', which is fine for our purposes). + +::::::::::::::::::::::::::::::::::::::::: callout + +## 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 +to repository visitors + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +Our local repository is now out of sync with our remote repository, so let's fix that by pulling the remote changes into +our local repository using the `git pull` command. + +```bash +$ git pull +``` + +```output +remote: Counting objects: 3, done. +remote: Compressing objects: 100% (2/2), done. +remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0 +Unpacking objects: 100% (3/3), done. +From https://github.com//hello-world + 8e2eb99..0f5a7b0 main -> origin/main +Updating 8e2eb99..0f5a7b0 +Fast-forward + README.md | 1 + + 1 file changed, 1 insertion(+) + create mode 100644 README.md +``` + +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 +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. + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- remote repositories on GitHub help you collaborate and share your work +- `push` is a Git verb for sending changes from the local repository to a remote repository +- `pull` is a Git verb for bringing changes from a remote repository to the local repository +- `diff` is a Git verb for viewing the difference between an edited file and the file's most recent commit + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + diff --git a/04-review.md b/04-review.md new file mode 100644 index 00000000..33e80426 --- /dev/null +++ b/04-review.md @@ -0,0 +1,46 @@ +--- +title: Review +teaching: 5 +exercises: 20 +--- + +::::::::::::::::::::::::::::::::::::::: objectives + +- rephrase Git commands using everyday language +- demonstrate Git's functions by drawing or sketching + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- How can I cement my understanding of Git's functions? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +## Let's review + +It is likely that some things won't have stuck from the last hour. To try to reinforce how things work we can work in groups to develop diagrams to illustrate Git functions and language. This should make carrying out more complicated aspects of Git clearer in our heads. + +In groups: + +- illustrate the concepts discussed in the first hour +- try to 'draw' what different commands mean +- try to come up with synonyms for what the commands are doing. + +### Exercise - visualising git + +In group work, spend some time trying to illustrate some of the commands we've used with Git: + +- try to express git commands in a non 'git' way +- try to visualise what commits are doing to your repository + +If you want to practise more feel free to keep practicising making changes to your file and committing the changes. If you want to explore more git commands, search for some more online or follow one of the suggested links below. + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- the language of Git can be confusing and intimidating +- rephrasing commands and drawing concepts can clarify Git's workflow + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + diff --git a/05-github-pages.md b/05-github-pages.md new file mode 100644 index 00000000..145b3041 --- /dev/null +++ b/05-github-pages.md @@ -0,0 +1,175 @@ +--- +title: GitHub Pages +teaching: 15 +exercises: 20 +--- + +::::::::::::::::::::::::::::::::::::::: objectives + +- create a GitHub Pages branch and push a file to it +- with a partner, experiment with collaborating on a GitHub Pages website +- apply the workflow between local and remote repositories to collaborate on a website + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- What is GitHub Pages? +- How can I use GitHub Pages to collaborate and share my work? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +## GitHub Pages + +GitHub Pages is a simple service to publish a website directly on GitHub from a Git repository. +You add some files and folders to a repository and GitHub Pages turns it into a website. +You can use HTML directly if you like, but they also provide Jekyll, +which renders Markdown into HTML and makes it really easy to setup a blog or a template-based website. + +### 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 +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 +website to quickly suggest, and help implement changes through pull requests. + +### Enable GitHub Pages + +GitHub Pages is turned off by default for all new repositories, and can be turned on in the settings menu for any repository. + +Let's set up a new site by enabling GitHub Pages for our project. + +Go to the Pages section of your repository's Settings: + +![](fig/github-repo-settings-pages.png){alt="GitHub repository's Pages settings"} + +#### Source branch (required) + +Pages needs to know the branch in your repository from which you want to serve your site. This can be any branch, including `main`. + +Select then save the source branch: + +![](fig/github-repo-settings-pages-branch.png){alt="GitHub Pages source branch menu"} + +![](fig/github-repo-settings-pages-save.png){alt="GitHub Pages source branch save"} + +#### Theme (optional) + +GitHub Pages provides different themes to visually style and organize your site's content. Choosing a theme is optional, and themes can be interchanged quickly. + +![](fig/github-repo-settings-pages-theme.png){alt="GitHub Pages choose theme"} + +See the [GitHub Pages documentation](https://docs.github.com/en/pages/getting-started-with-github-pages/adding-a-theme-to-your-github-pages-site-with-the-theme-chooser) for further information on using themes. + +### View your site + +If we now visit `https://some-librarian.github.io/hello-world/`, +we should see the contents of the index.md file that created earlier. +Usually it's available instantly, but it can take a few seconds and in the worst case a few minutes if GitHub are very busy. + +::::::::::::::::::::::::::::::::::::::: challenge + +## Challenge: Contributing to a page owned by someone else (slightly easier way) + +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](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: + + ![](fig/github-edit-pencil.png){alt="GitHub edit pencil"} + +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 main branch. + + ![](fig/github-commit-pr.png){alt="Commit and create pull request"} + +6. 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). + +7. 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"? + +::::::::::::::: solution + +## Solution + +We made a fork and a pull request because we did not have permission to edit +(or commit) the repository directly. A fork is a copy of the repository that +we *can* edit. By making a pull request we ask the owner of the repository if +they would like to accept (pull in) the changes from our fork (our copy) into +their version. The owner can then review the changes and choose to accept or +reject them. + +You can open pull requests on any repository you find on GitHub. If you are a +group of people who plan to collaborate closely, on the other hand, +it's more practical to grant everyone access to commit directly instead. + +::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +> ## Optional challenge: Contributing to a page owned by someone else (slightly more complicated way) +> +> Instead of making edits on the GitHub website you can 'clone' the fork to your local machine +> and work there. + +::::::::::::::::::::::::::::::::::::::: challenge + +Try following the rest of the steps in this guide under ["Time to Submit Your First PR"](https://www.thinkful.com/learn/github-pull-request-tutorial/Writing-a-Good-Commit-Message#Time-to-Submit-Your-First-PR). + +(If you followed step 1 and 2 in the previous challenge, +you already have a fork and you can skip the creation of a new fork. +Start instead at the section titled "Cloning a fork." +You can submit multiple pull requests using the same fork.) + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## Optional challenge: Adding an HTML page + +GitHub Pages is not limited to Markdown. If you know some HTML, try adding an HTML page +to your repository. You could do this on the command line or directly on GitHub. The +steps below are for working directly on GitHub: + +1. To add a new file directly on GitHub, press the "Create new file" button. + + ![](fig/github-create-new-file.png){alt="Create new file on GitHub"} + +2. Name it 'test.html', add some HTML and click "Commit new file". + +3. Try opening `https://some-librarian.github.io/hello-world/test` + (replace "some-librarian" with your username). + Notice that the HTML extension is not included. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- GitHub Pages offer an automated way to create a website that is version controlled and accessible for collaboration +- Collaborating on a GitHub Pages website uses the same Git/GitHub workflow you learned for collaborating via a GitHub repository + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..f19b8049 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,13 @@ +--- +title: "Contributor Code of Conduct" +--- + +As contributors and maintainers of this project, +we pledge to follow the [The Carpentries Code of Conduct][coc]. + +Instances of abusive, harassing, or otherwise unacceptable behavior +may be reported by following our [reporting guidelines][coc-reporting]. + + +[coc-reporting]: https://docs.carpentries.org/topic_folders/policies/incident-reporting.html +[coc]: https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 00000000..7632871f --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,79 @@ +--- +title: "Licenses" +--- + +## Instructional Material + +All Carpentries (Software Carpentry, Data Carpentry, and Library Carpentry) +instructional material is made available under the [Creative Commons +Attribution license][cc-by-human]. The following is a human-readable summary of +(and not a substitute for) the [full legal text of the CC BY 4.0 +license][cc-by-legal]. + +You are free: + +- to **Share**---copy and redistribute the material in any medium or format +- to **Adapt**---remix, transform, and build upon the material + +for any purpose, even commercially. + +The licensor cannot revoke these freedoms as long as you follow the license +terms. + +Under the following terms: + +- **Attribution**---You must give appropriate credit (mentioning that your work + is derived from work that is Copyright (c) The Carpentries and, where + practical, linking to ), provide a [link to the + license][cc-by-human], and indicate if changes were made. You may do so in + any reasonable manner, but not in any way that suggests the licensor endorses + you or your use. + +- **No additional restrictions**---You may not apply legal terms or + technological measures that legally restrict others from doing anything the + license permits. With the understanding that: + +Notices: + +* You do not have to comply with the license for elements of the material in + the public domain or where your use is permitted by an applicable exception + or limitation. +* No warranties are given. The license may not give you all of the permissions + necessary for your intended use. For example, other rights such as publicity, + privacy, or moral rights may limit how you use the material. + +## Software + +Except where otherwise noted, the example programs and other software provided +by The Carpentries are made available under the [OSI][osi]-approved [MIT +license][mit-license]. + +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the "Software"), to deal in +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies +of the Software, and to permit persons to whom the Software is furnished to do +so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +## Trademark + +"The Carpentries", "Software Carpentry", "Data Carpentry", and "Library +Carpentry" and their respective logos are registered trademarks of [Community +Initiatives][ci]. + +[cc-by-human]: https://creativecommons.org/licenses/by/4.0/ +[cc-by-legal]: https://creativecommons.org/licenses/by/4.0/legalcode +[mit-license]: https://opensource.org/licenses/mit-license.html +[ci]: https://communityin.org/ +[osi]: https://opensource.org diff --git a/config.yaml b/config.yaml new file mode 100644 index 00000000..2b357158 --- /dev/null +++ b/config.yaml @@ -0,0 +1,85 @@ +#------------------------------------------------------------ +# Values for this lesson. +#------------------------------------------------------------ + +# Which carpentry is this (swc, dc, lc, or cp)? +# swc: Software Carpentry +# dc: Data Carpentry +# lc: Library Carpentry +# cp: Carpentries (to use for instructor training for instance) +# incubator: The Carpentries Incubator +carpentry: 'lc' + +# Overall title for pages. +title: 'Library Carpentry: Introduction to Git' + +# Date the lesson was created (YYYY-MM-DD, this is empty by default) +created: '2018-04-12' + +# Comma-separated list of keywords for the lesson +keywords: 'software, data, lesson, The Carpentries' + +# Life cycle stage of the lesson +# possible values: pre-alpha, alpha, beta, stable +life_cycle: 'stable' + +# License of the lesson materials (recommended CC-BY 4.0) +license: 'CC-BY 4.0' + +# Link to the source repository for this lesson +source: 'https://github.com/librarycarpentry/lc-git' + +# Default branch of your lesson +branch: 'main' + +# Who to contact if there are any issues +contact: 'team@carpentries.org' + +# Navigation ------------------------------------------------ +# +# Use the following menu items to specify the order of +# individual pages in each dropdown section. Leave blank to +# include all pages in the folder. +# +# Example ------------- +# +# episodes: +# - introduction.md +# - first-steps.md +# +# learners: +# - setup.md +# +# instructors: +# - instructor-notes.md +# +# profiles: +# - one-learner.md +# - another-learner.md + +# Order of episodes in your lesson +episodes: +- 01-what-is-git.md +- 02-getting-started.md +- 03-sharing.md +- 04-review.md +- 05-github-pages.md + +# Information for Learners +learners: + +# Information for Instructors +instructors: + +# Learner Profiles +profiles: + +# Customisation --------------------------------------------- +# +# This space below is where custom yaml items (e.g. pinning +# sandpaper and varnish versions) should live + + +url: 'https://librarycarpentry.github.io/lc-git' +analytics: carpentries +lang: en diff --git a/contribute.md b/contribute.md new file mode 100644 index 00000000..1c6bb0ae --- /dev/null +++ b/contribute.md @@ -0,0 +1,9 @@ +--- +layout: page +title: Contribute +--- +There are three main ways to contribute to Library Carpentry: + +- Join our [discussion forum]({{ site.contact }}). Here you can suggest new content, volunteer to become a lesson maintainer, or help shape future developments. +- Suggest an improvement or correct an error by [raising an Issue](https://github.com/librarycarpentry/lc-data-intro/issues). +- Run a workshop at your own institution! If you do, [let us know]({{ site.contact }}): we're happy to help promote the workshop and offer guidance on running it. Remember, there is no better way to deepen your own knowledge of software skills than to teach others. diff --git a/discuss.md b/discuss.md new file mode 100644 index 00000000..3f5463c6 --- /dev/null +++ b/discuss.md @@ -0,0 +1,10 @@ +--- +title: Discussion +--- + +There are many ways to discuss Library Carpentry lessons: + +- Join our [Slack organisation](https://slack-invite.carpentries.org/) and #libraries channel. +- Stay in touch with our [Topicbox Group](https://carpentries.topicbox.com/groups/discuss-library-carpentry). +- Follow updates on [Twitter](https://twitter.com/LibCarpentry). +- Make a suggestion or correct an error by [raising an Issue](https://github.com/LibraryCarpentry/lc-git/issues) or [submit a pull request](https://github.com/LibraryCarpentry/lc-git/pulls). diff --git a/fig/git-staging-area.svg b/fig/git-staging-area.svg new file mode 100644 index 00000000..c74c2987 --- /dev/null +++ b/fig/git-staging-area.svg @@ -0,0 +1,93 @@ + + + + + + + + .git + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + git add + + + + + + git commit + + staging area + + repository + + diff --git a/fig/github-commit-pr.png b/fig/github-commit-pr.png new file mode 100644 index 00000000..ff493551 Binary files /dev/null and b/fig/github-commit-pr.png differ diff --git a/fig/github-create-new-file.png b/fig/github-create-new-file.png new file mode 100644 index 00000000..eeaffa6c Binary files /dev/null and b/fig/github-create-new-file.png differ diff --git a/fig/github-edit-pencil.png b/fig/github-edit-pencil.png new file mode 100644 index 00000000..9588a726 Binary files /dev/null and b/fig/github-edit-pencil.png differ diff --git a/fig/github-gh-pages.png b/fig/github-gh-pages.png new file mode 100644 index 00000000..ade7539a Binary files /dev/null and b/fig/github-gh-pages.png differ diff --git a/fig/github-instructions.png b/fig/github-instructions.png new file mode 100644 index 00000000..3ede5290 Binary files /dev/null and b/fig/github-instructions.png differ diff --git a/fig/github-one-commit.png b/fig/github-one-commit.png new file mode 100644 index 00000000..27fd9faa Binary files /dev/null and b/fig/github-one-commit.png differ diff --git a/fig/github-repo-connect.png b/fig/github-repo-connect.png new file mode 100644 index 00000000..da5a4b45 Binary files /dev/null and b/fig/github-repo-connect.png differ diff --git a/fig/github-repo-new-setup.png b/fig/github-repo-new-setup.png new file mode 100644 index 00000000..008425de Binary files /dev/null and b/fig/github-repo-new-setup.png differ diff --git a/fig/github-repo-new-setup_copy.png b/fig/github-repo-new-setup_copy.png new file mode 100644 index 00000000..97cbd595 Binary files /dev/null and b/fig/github-repo-new-setup_copy.png differ diff --git a/fig/github-repo-new.png b/fig/github-repo-new.png new file mode 100644 index 00000000..17164bcd Binary files /dev/null and b/fig/github-repo-new.png differ diff --git a/fig/github-repo-settings-pages-branch.png b/fig/github-repo-settings-pages-branch.png new file mode 100644 index 00000000..71832835 Binary files /dev/null and b/fig/github-repo-settings-pages-branch.png differ diff --git a/fig/github-repo-settings-pages-save.png b/fig/github-repo-settings-pages-save.png new file mode 100644 index 00000000..8ba3e176 Binary files /dev/null and b/fig/github-repo-settings-pages-save.png differ diff --git a/fig/github-repo-settings-pages-theme.png b/fig/github-repo-settings-pages-theme.png new file mode 100644 index 00000000..c166d8e9 Binary files /dev/null and b/fig/github-repo-settings-pages-theme.png differ diff --git a/fig/github-repo-settings-pages.png b/fig/github-repo-settings-pages.png new file mode 100644 index 00000000..041af291 Binary files /dev/null and b/fig/github-repo-settings-pages.png differ diff --git a/fig/repository-url.png b/fig/repository-url.png new file mode 100644 index 00000000..c4613995 Binary files /dev/null and b/fig/repository-url.png differ diff --git a/index.md b/index.md new file mode 100644 index 00000000..1b654f9d --- /dev/null +++ b/index.md @@ -0,0 +1,29 @@ +--- +site: sandpaper::sandpaper_site +--- + +#### What We Will Try to Do + +**Begin** to understand and use Git/GitHub. You will not be an expert by the end of the class. You will probably not even feel very comfortable using Git. This is okay. We want to make a start but, as with any skill, using Git takes practice. In this lesson we use Git from the Unix Shell. Some previous experience with the shell is expected, but is not mandatory. + +#### Be Excellent to Each Other + +- If you spot someone in the class who is struggling with something and you think you know how to help, please give them a hand. Try not to do the task for them: instead explain the steps they need to take and *what* these steps will achieve. + +#### Be Patient With The Instructor and Yourself + +- This is a big group, with different levels of knowledge, different computer systems. +- This isn't your instructor's full-time job (though if someone wants to pay them to play with computers all day they'd probably accept). They will do their best to make this session useful. +- This is your session. If you feel we are going too fast, then please put up a pink sticky. We can decide as a group what to cover. + +:::::::::::::::::::::::::::::::::::::::::: prereq + +## Prerequisites + +1. Setup a [GitHub account](https://github.com/) +2. [Install git on your own computer](https://help.github.com/articles/set-up-git/) + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + diff --git a/instructor-notes.md b/instructor-notes.md new file mode 100644 index 00000000..93fdb0e9 --- /dev/null +++ b/instructor-notes.md @@ -0,0 +1,101 @@ +--- +title: Instructors' Guide +--- + +*** + +# Tips and Tricks + +Known problems that learners encounter: + +*Windows*: When using an outdated version of Windows OpenSSH, learners cannot set up the SSH connection to GitHub. SOLUTION: Update OpenSSH version. + +*** + +## Making a handout + +To make a handout for this lesson, adapt/print from [https://librarycarpentry.org/lc-git/reference.html](https://librarycarpentry.org/lc-git/reference.html). + +*** + +# General notes on Git + +Using a software tool to handle the versions of your project files +lets you focus on the more interesting/innovative aspects of your project. + +- Version control's advantages + - It's easy to set up + - Every copy of a Git repository is a full backup of a project and its history + - A few easy-to-remember commands are all you need for most day-to-day version control tasks + - The [GitHub](https://github.com/) hosting service provides a web-based collaboration service +- Two main concepts + - *commit*: a recorded set of changes in your project's files + - *repository*: the history of all your project's commits +- Why use GitHub? + - No need for a server: easy to set up + - GitHub's strong community: your colleagues are probably already there + +## Overall + +Version control might be the most important topic we teach, but Git is +definitely the most complicated tool. However, GitHub presently dominates the +open software repository landscape, so the time and effort required to teach +fundamental Git is justified and worthwhile. + +Because of this complexity, we don't teach novice learners about many +interesting topics, such as branching, hashes, and commit objects. + +Instead we try to convince them that version control is useful for researchers +working in teams or not, because it is + +- a better way to "undo" changes, +- a better way to collaborate than mailing files back and forth, and +- a better way to share your code and other scientific work with the world. + +## Teaching Notes + +- Resources for "splitting" your shell so that recent commands remain in view: [https://github.com/rgaiacs/swc-shell-split-window](https://github.com/rgaiacs/swc-shell-split-window). + +- Make sure the network is working *before* starting this lesson. + +- Drawings are particularly useful in this lesson: if you have a whiteboard, + use it to visualise and describe the [GitHub flow](https://guides.github.com/introduction/flow/). + +- Version control is usually not the first subject in a workshop, + so get learners to create a GitHub account after the session before. + Remind learners that the username and email they use for GitHub (and setup + during Git configuration) will be viewable to the public by default. + However, there are many reasons why a learner may not want their personal + information viewable, and GitHub has [resources for keeping an email address + private](https://help.github.com/en/github/setting-up-and-managing-your-github-user-account/setting-your-commit-email-address). + +- If some learners are using Windows, there will inevitably be issues + merging files with different line endings. (Even if everyone's on + some flavor of Unix, different editors may or may not add a + newline to the last line of a file.) Take a moment to explain + these issues, since learners will almost certainly trip over them + again. If learners are running into line ending problems, GitHub + has a [page](https://help.github.com/en/articles/dealing-with-line-endings) that helps with troubleshooting. + +- We don't use a Git GUI in these notes because we haven't found one that + installs easily and runs reliably on the three major operating systems, and + because we want learners to understand what commands are being run. That + said, instructors should demo a GUI on their desktop at some point during + this lesson and point learners at [this page](https://git-scm.com/downloads/guis). + +- Instructors should show learners graphical diff/merge tools like + [DiffMerge](https://sourcegear.com/diffmerge/). + +- When appropriate, explain that we teach Git rather than CVS, Subversion, or + Mercurial primarily because of GitHub's growing popularity: CVS and + Subversion are now seen as legacy systems, and Mercurial isn't nearly as + widely used in the sciences right now. + +- Further resources: + + - [git-it](https://github.com/jlord/git-it-electron#git-it-desktop-app) is a self-paced command-line Git demo, + with [git-it-electron](https://github.com/jlord/git-it-electron) its GitHub Desktop successor. + - Try GitHub's [resources to learn Git](https://try.github.io/) or Codeacademy's [Learn Git](https://www.codecademy.com/learn/learn-git). + - For instructors, [the Git parable](https://tom.preston-werner.com/2009/05/19/the-git-parable.html) is useful background reading. + + diff --git a/learner-profiles.md b/learner-profiles.md new file mode 100644 index 00000000..434e335a --- /dev/null +++ b/learner-profiles.md @@ -0,0 +1,5 @@ +--- +title: FIXME +--- + +This is a placeholder file. Please add content here. diff --git a/md5sum.txt b/md5sum.txt new file mode 100644 index 00000000..ad281e05 --- /dev/null +++ b/md5sum.txt @@ -0,0 +1,16 @@ +"file" "checksum" "built" "date" +"CODE_OF_CONDUCT.md" "c93c83c630db2fe2462240bf72552548" "site/built/CODE_OF_CONDUCT.md" "2023-04-21" +"LICENSE.md" "b24ebbb41b14ca25cf6b8216dda83e5f" "site/built/LICENSE.md" "2023-04-21" +"config.yaml" "15804557c932ba3637a1f4b5402da4d7" "site/built/config.yaml" "2023-04-21" +"contribute.md" "6f688a330994cf2ec8aab8076927dc05" "site/built/contribute.md" "2023-04-21" +"index.md" "773cf78e1289f5ca1461848f3c59dfdb" "site/built/index.md" "2023-04-21" +"episodes/01-what-is-git.md" "9b8eb4224703f7c67eb0bc969f2b6331" "site/built/01-what-is-git.md" "2023-10-17" +"episodes/02-getting-started.md" "c07bff9a400d05f46c3608b2c86ca517" "site/built/02-getting-started.md" "2023-04-21" +"episodes/03-sharing.md" "fa93ae93bdde6c549f0a27449c537177" "site/built/03-sharing.md" "2023-04-21" +"episodes/04-review.md" "9e589dcefa2ff8f2d9ce79e2f5eda5df" "site/built/04-review.md" "2023-04-21" +"episodes/05-github-pages.md" "3557acd2d88322190d2a31282733cc05" "site/built/05-github-pages.md" "2023-04-21" +"instructors/instructor-notes.md" "a45553efc112e3823f231cc16c2da968" "site/built/instructor-notes.md" "2023-04-21" +"learners/discuss.md" "95bb205074ca2133f2001f99bb405179" "site/built/discuss.md" "2023-10-17" +"learners/reference.md" "523a1e2ffd0aa0ef631151bcec384665" "site/built/reference.md" "2023-04-21" +"learners/setup.md" "b6128d6d1214aeaf72d4deda093cb8bf" "site/built/setup.md" "2023-10-17" +"profiles/learner-profiles.md" "60b93493cf1da06dfd63255d73854461" "site/built/learner-profiles.md" "2023-04-21" diff --git a/reference.md b/reference.md new file mode 100644 index 00000000..f05e7f19 --- /dev/null +++ b/reference.md @@ -0,0 +1,106 @@ +--- +title: 'FIXME' +--- + +## Glossary + +## Quick reference + +### Navigating the shell + +`pwd` +: print working directory + +`ls` +: list directory +: +: - `-l`: list file information +: - `-lh`: list human readable file information + +`cd` +: change directory + +### Interacting with files in the shell + +`mkdir` +: make directory + +`cat` +: send file or files to output (in most cases, print to shell) + +`head` +: output first parts of a file or files + +`tail` +: output last parts of a file or files + +`mv` +: rename or move a file or files. Syntax for renaming a file: `mv FILENAME NEWFILENAME` + +`cp` +: copy a file or files. Syntax: `cp FILENAME NEWFILENAME` + +`>` +: redirect output. Syntax with `cat`: `cat FILENAME1 FILENAME2 > NEWFILENAME` + +`rm` +: remove a file or files. NB: *USE WITH CAUTION!!!* + +### Git commands + +Git cheat sheet handouts: + +- [GitHub git cheat sheet](https://github.github.com/training-kit/downloads/github-git-cheat-sheet.pdf) +- [Tower client git cheat sheet](https://www.git-tower.com/blog/git-cheat-sheet/) + +`git init` +: create a new local git repository + +`git status` +: view the status of your files in the working directory and staging area + +`git add` +: tell git to start tracking a file, or a series of files + +`git commit` +: save file changes from the staging area permanently to the project history + +`git push` +: upload all commits to a remote repository, such as GitHub + +`git log` +: show history of commits in reverse chronological order + +`git diff` +: show changes made to tracked files + +`git pull` +: download upstream changes and merge them into your local repository + +`git remote add origin` +: add a remote repository named 'origin', to upload changes to or download changes from + +## Useful library GitHub repositories + +- [DavidChouinard/mrc\_to\_csv](https://github.com/DavidChouinard/mrc_to_csv): 'Python script for converting MARC21 files to a saner format (CSV), originally designed for the Harvard Libraries MARC21 records' +- [Process MARC records from Python](https://gitlab.com/pymarc/pymarcc) + - [https://pypi.org/project/pymarc/](https://pypi.org/project/pymarc/) +- [umd-mith/git-intro](https://umd-mith.github.io/git-intro/): high level intro to git +- [edsu/mirador](https://github.com/edsu/mirador) +- [edsu/microdata](https://github.com/edsu/microdata) +- [dhtaxonomy/TaDiRAH](https://github.com/dhtaxonomy/TaDiRAH) +- [OpenAPC/openapc-de](https://github.com/OpenAPC/openapc-de) +- [JiscMonitor/allapc](https://github.com/JiscMonitor/allapc) +- [Python Programming for Humanities](https://www.karsdorp.io/python-course/) +- [Code4Lib 2008 lightning talk – Git and distributed cataloging](https://galencharlton.com/blog/2008/03/code4lib-2008-lightning-talk-git-and-distributed-cataloging/) +- [Open Science Guide](https://book.openingscience.org.s3-website-eu-west-1.amazonaws.com/) + +## Further reading + +- The [help pages](https://help.github.com/) of GitHub are a good place to start +- GitHub has '[activities](https://guides.github.com/activities/hello-world/)' which aim to explain how git works +- GitHub also has interactive tutorials for their [online version (Learning Labs)](https://lab.github.com/) and for [using Git offline (Git-It)](https://github.com/jlord/git-it-electron#git-it-desktop-app) +- Atlassian has in depth but clear [tutorials](https://www.atlassian.com/git/tutorials) on using git +- The [Programming Historian](https://programminghistorian.org) uses GitHub to manage lessons useful to historians and also people working in libraries. It is a useful resource for lessons but also to see GitHub in action. + + diff --git a/setup.md b/setup.md new file mode 100644 index 00000000..708f7fa4 --- /dev/null +++ b/setup.md @@ -0,0 +1,50 @@ +--- +title: Setup +--- + +## Installing Git + +Since several Carpentries lessons rely on Git, please see +[this section of the workshop template][workshop-setup] for +instructions on installing Git for various operating systems. + +- [Git installation on Windows][workshop-setup] +- [Git installation on MacOS][workshop-setup] +- [Git installation on Linux][workshop-setup] + +## Creating a GitHub Account + +You will need an account for [GitHub](https://github.com) to follow this lesson. + +1. Go to and follow the "Sign up" link at the top-right of the window. +2. Follow the instructions to create an account. +3. Verify your email address with GitHub. +4. Configure multifactor authentication (see below). + +### Multi-factor Authentication + +In 2023, GitHub introduced a requirement for +all accounts to have +[multi-factor authentication (2FA)](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/about-two-factor-authentication) +configured for extra security. +Several options exist for setting up 2FA, which are summarised here: + +1. If you already use an authenticator app, + like [Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=en&co=GENIE.Platform%3DiOS&oco=0) + or [Duo Mobile](https://duo.com/product/multi-factor-authentication-mfa/duo-mobile-app) on your smartphone for example, + [add GitHub to that app](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-a-totp-mobile-app). +2. If you have access to a smartphone but do not already use an authenticator app, install one and + [add GitHub to the app](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-a-totp-mobile-app). +3. If you do not have access to a smartphone or do not want to install an authenticator app, you have two options: + 1. [set up 2FA via text message](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-text-messages) + ([list of countries where authentication by SMS is supported](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/countries-where-sms-authentication-is-supported)), or + 2. [use a hardware security key](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-a-security-key) + like [Youbikey](https://www.yubico.com/products/yubikey-5-overview/) + or the [Google Titan key](https://store.google.com/us/product/titan_security_key?hl=en-US&pli=1). + +The GitHub documentation provides [more details about configuring 2FA](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication). + +[workshop-setup]: https://carpentries.github.io/workshop-template/install_instructions/#git + + +