Engl507

Git and GitHub

Early in this seminar we will start using Git and GitHub. Git is version control software, and it will allow each of you to document and share changes to your work via a repository (or "repo") throughout the semester. Think of Git as a way of locally tracking the changes you make to a directory (or folder) of files and GitHub as a way of distributing those files and changes. GitHub is also a social network, but you won't be using that feature this semester unless you want to.

So let's get started. (Of note, a chunk of what's below is based on and inspired by Lauren Orsini's excellent introduction.)

• Sign up for GitHub and email me your handle.
• Once you are signed in to GitHub, visit your GitHub profile page (github.com/yourHandle) and click the plus button in the top right to create a new repository. Give the repository a simple name (e.g., english507 or 507) and a brief description. Decide whether you want it public or private (I'd default to private for now, even if that means you'll have to give folks such as me read or write access), but don't check that "Initialize this repository with a README" box. Once you're ready, click "Create respository" (green button at the bottom).
• Once you have a handle and a repo, download Git and install it.
• Once it is downloaded and installed, you should start the Git Bash app (Windows) or open your terminal (Mac). On a Mac, the terminal is a default app. Just use your spotlight to find it.
• For your reference, here are a few commands that you will likely use in the command line throughout the semester:
  • git help (lists popular Git commands; handy!)
  • git config (configure Git)
  • git clone (clone all files in a remote repo)
  • git add (add file contents to the index)
  • git commit (record changes to the repository)
  • git diff (show changes between commits and the repository's "working tree")
  • git fetch (download objects and refs from another repository)
  • git grep (print lines matching a pattern)
  • git init (initialize a Git repo)
  • git log (create an empty Git repo or reinitialize one)
  • git mv (move or rename a file or directory)
  • git remote (confirm or add a remote repo, such as a GitHub repo)
  • git pull (fetch from and merge with another repo)
  • git push (update remote refs along with associated objects)
  • git rm (remove files from the working tree and from the index)
  • git status (show the status of the working tree)
  • cd (change the directory; not specific to Git)
  • touch (create a file; not specific to Git)
  • ls (list the contents of the current directory)
• In the command line, move to your desktop's directory: cd ~/desktop. Just in case you're curious, cd stands for "change directory," and the use of ~/ means the repo is located at the top level of your computer's file structure.
• In the command line, please write the following command: git config --global user.name "Your Name". Replace "Your Name" with your name as you would like it to appear in your attribution metadata. When tracking changes, Git attributes each change to a particular name/identity, no matter how small the change.
• Now enter the following: git config --global user.email "emailaddress@email.ca". Replace "emailaddress@email.ca" with the email address you registered with GitHub. Note: this is very important. Make sure you don't enter the wrong address.
• Next, create a repository for your English 507 writing and research: git init directory. Replace "directory" with the name you gave to your GitHub repo (e.g., english507 or 507). Of note, if you use more than one word, then I recommend camel caps, where you use caps instead of spaces in your directory names (e.g., englishRepo or jenterySayers). I also recommend refraining from capitalizing the first word of your repo (e.g., jentery not Jentery). Among other things, spaces in repo or file names can cause a lot of problems down the line.
• At this point, you should have a folder sitting on your desktop. And you should now move into it: cd directory (where "directory" is the name of your new repo). To confirm your location, enter pwd, or "print working directory." The command line will respond with your location.
• Now we'll start adding content to the repo. In the command line, enter touch yourlastname.md, replacing "yourlastname" with your last name. Keep in mind that your last name will not start with a capital letter. Also, if your last name consists of two or more words, then they should be joined, without spaces, using capital letters (vanNielsen).
• You should now have an empty file, yourlastname.md, in your directory. This will be the file for your 507 research log. Open it using open yourlastname.md. The default application for editing Markdown files on your computer should open, and you should see the empty file.
• At the top of the file, create a header (using #) that includes your complete name and then (English 507) after it (e.g., Jentery Sayers (English 507)). Then create another header (below your name, using ##) that includes the following info: log entry number, date, and (if you wish) a title that describes the content (e.g., Log 1, 13 January, My Response to Galloway). As you add content to your research log throughout the semester, please make sure that the most recent content is at the top of the file (that is, in descending or reverse chronological order). All headers for log entries should use ##. If you use additional headers within those entries, then you might want to consider using ###.
• Once you've added some sample content, save yourlastname.md (either control+S or command+S). Git will track this change and add it to your change history.
• Now return the command line, enter touch readMe.md, and then open readMe.md. This file will describe your repository. Add whatever description you wish, save it, and then enter ls in the command line. You should receive a list of all files (just two?) in your current directory.
• Now let's sync your two files with your English 507 repo at GitHub. In the command line, enter git remote add 507 https://github.com/yourHandle/yourRepo.git. Replace "yourHandle" with your GitHub handle and "yourRepo" with the name of your GitHub repo. Don't forget .git at the end. Of note, 507 is just a name for the URL that follows it; it's shorthand. Feel free to replace it with whatever shorthand you'd prefer. It's arbitrary, really. Go with something you'll remember or make you smile.
• Now confirm that you are syncing to the appropriate repo: git remote -v. It should spit back the URL of your English 507 GitHub repo.
• Before syncing the content, let's bring Git's attention to the changes you've made to your local repo. In the command line, write git add --all. This adds or "stages" all of your changes to the repo.
• But staging the changes doesn't "commit" them to the repo. A commit is a bundle of changes, or just one change, which you deem significant enough to document or record in the repo's change history. In the command line, write git commit -m "First commit of yourlastname.md and readMe.md.", replacing "yourlastname" with your last name. The use of -m adds a message to the change history, describing what changes were made (giving these changes some metadata, if you will). These messages become informative over time, especially if you are collaborating with other people. They are also a way of integrating core textual studies practices into your own writing and research.
• Now "push" your changes to your GitHub repo using the following command: git push 507 master. If you didn't use 507 as the shorthand for your repo, then use whatever shorthand you did use. If the command is successful, then you should get a list of changes in the command line. You can also check your GitHub repo to verify your changes are there. If they are not, then wait at least ten to fifteen minutes before you get concerned. There's the occasional lag.
• As you change your local repo throughout the semester, just remember to use the git add --all, git commit -m "message", and git push 507 master commands to sync them with your GitHub repo. One perk of this approach is that you don't write in the cloud. Another is that you're backing up and sharing your work (if you wish) as you go. And another is that you start with a change history of your work (rather than thinking about it later or cooking it up after the fact).
• Also, as you proceed, you may want to create subdirectories in your local repo. To do so, enter mkdir subdirectoryName in the command line, replacing "subdirectoryName" with your preference (e.g., "images"). There you can dump or create files, such as image and data files, that are relevant to your research and writing.

That's it for now! You can of course do much, much more with Git and GitHub, but during the first few weeks of seminar we'll keep it simple. Get in touch with any questions or concerns.