This tutorial and sequence of assignments is adapted from newtFire.
This course requires all students to learn Git, the field standard for collaborative version control for coding. Git is a powerful tool and knowing how to use it will pay dividends for a wide variety of computing methods even outside this course. However, Git was designed with programmers in mind, which means that it takes some getting used to. If you find the learning curve frustrating at times, do not worry!: you are not alone. By the end of this course, the basic Git workflow will be second nature, and this initial sequence of activities will help you get there.
Because many of the challenges and pitfalls that crop up when getting to know Git are specific to indvidual user experiences, we will not devote much class time to Git. But you can use the Slack channel, comments in your homework submissions, and project group meetings to troubleshoot.
This assignment helps orient you to version control systems and how they work. It's the system we use with git and Github for sharing files and the system you'll be using to publish and share your website for this class.
Read the following articles:
After reading these brief articles carefully, write a short response paper (by the date indicated on the syllabus, and submitted via Canvas) addressing at least some of the following questions:
This assignment is straightforward: set up your Github account and cloud service. (We will leave the command line application from which you will normally interact with your account for the next step in this sequence.) To do so, follow these steps.
After you have created your account, submit a comment simply listing your full name to this issue in the course Git repo. Github forums use a format called "Markdown" (which you may have used when texting without even realizing it, for instance *italics* surrounded by asterisks automatically reformatted to italics ). Read the GitHub three-minute guide to Mastering markdown. Then, to complete this assignment, submit a link to your comment via the Canvas assignment, experimenting with Markdown formatting (e.g., formatting your first name in bold and your last name in italics ).
The next step is to install Git tools on your personal computer so that you can interact with the remote repository (the one hosted on the website) from your local repository. This is where you might start to run into some challenges.
To install Git locally, follow the set of instructions that corresponds to your operating system. Note that this will be an "invisible" app / program that you interact with from command line: there is no icon to click on, and it will not appear in your Applications folder.
Common pitfalls at this stage:
Now that you have the application installed on your machine, we need to authorize your machine (home to your local repository) to interact with the remote repository hosted on the Github website. You might assume that you could simply provide the same username and password that you created when you registered for a free Github account (and in the past you indeed you could), but these days Git favors a Token system of authorization because it is more secure. (After all, software developers are using this same infrastructure to develop code worth millions of dollars!) Fortunately, this added step of security is fairly straightforward, and in practice works a bit like a temporary password. (Note that there is another way to authenticate using an SSH key, which you are welcome to use, but we will favor the Token for instructional purposes.)
To set up your Token and link your local repo with your remote repo, follow these steps:
To submit this assignment: Upload a screen capture of your new repository with its README file featured to the relevant Canvas assignment.
This is where it all comes together. You are ready for this assignment if you have set up your GitHub account, set up your GitHub personal access token/credential storage, and created a public GitHub repo for yourself with a Readme.md file to start.
First, examine the following videos and slides (created by Elisa Beshero-Bondar) carefully for a general orientation:
Next, follow these steps carefully:
Find the best place on your computer to work on GitHub: Make sure you have just ONE folder ("directory" in computing terminology) where you will store Github repos. Make a directory called github or GitHub in a place on your computer that you can reliably use to find and open files. It needs to be a place that is easy to access when you go to open a file in the oXygen XML Editor.
You can make this directory if you have navigated there in the command line (Git Bash or Terminal) with mkdir github, or you can create it in your Windows File Manager or Mac Finder on your computer. You can then right-click on the directory and open (on Windows) a new Git Bash shell or (on Mac, under Services) a new Terminal here. Use your Git Bash Shell (Windows) or the Terminal (Mac) and practice navigating to this space and getting information with command line codes: cd yourDirectoryName, cd .., ls, pwd.
Note : If the "home" location on your computer is not one you can easily find from your GUI File Manager/ file viewer, it may be easier to right-click and open a Bash shell at a point you can reliably open on your computer to make your GitHub directory.
It's time to clone the GitHub repo you created! (You only need to do this once.) Go on a web browser to your profile on GitHub, look at the code view, and click the green "Code" button to copy your repo's clone address with HTTPS: the address should end with .git.
Next, enter git clone and paste in the address you copied. The command should look something like this: git clone https://github.com/....git (with your full GitHub repo address showing). Press Return on your keyboard. You should then see the repo being cloned to your directory space on your computer.
Okay, let's do that again! This time, clone our class's shared GitHub repo at https://github.com/pickettj/teaching. Be careful! You must clone it inside the GitHub folder, not inside your personal repo! If you clone one repo inside another, the .git files start colliding--it's not healthy. If this happens, delete the repo on the inside. (If this happens and you don't notice for a while, it's probably a good idea to trash the double-nested Repo blunder (and empty the trash)! And clone them again properly. Navigate to the outer GitHub folder you created before you clone.)
Your GitHub folder should now have two directories inside it: GitHub/yourNewRepo and GitHub/teaching. If you do your cloning successfully, when you visit your github or GitHub directory, and enter the ls command you should see your repo, and the introDH-Hub listed.
To complete this assignment: Upload a screen capture of your command shell with you navigated to your github directory to the relevant Canvas assignment showing the results of the ls command.
Once you have your repositories (both personal and project) cloned to your personal computer, your basic Git workflow will look something like this:
To complete this assignment, submit a screen capture of your command line as you move through this sequence of steps with a file of your choosing from a repo of your choosing (which can be your project repo.)