You are probably reading this tutorial because you are a new collaborator on a CDRH project. Welcome! We are excited to work with you.
This tutorial will get you set up to use version control for our projects. What is "version control?" You may have used it before without knowing it, when you saved another copy of your paper called "Book Report Draft.docx" followed later by "Book Report Final.docx" and everybody's favorite, "Book Report Final FINAL.docx." Having something under version control means that you can keep track of what things used to look like and compare them with how they look now. We here at the CDRH use version control in order to:
- Keep a record of who has worked on different files, when, and what changes were made
- Share our work between computers and people
- Create a "backup" of all work, not just in place but also in time!
This image shows how we track changes for our projects.
You can see who was working on files each day.
Set Up Your Account
1. GitHub Account
First, go to github.com and sign up for an account. You may wish to use your UNL email, since you will be using GitHub for university work, but you are welcome to use your personal email (or you can use an existing GitHub account, if you already have one). It's easiest to sign up for GitHub on a device from which you can access whatever email you choose, since you will need to verify your account when you create it.
2. Join the CDRH Organization
After you've gotten your account verified, let a member of the CDRH know your GitHub username. This step is important, because they can add you to the CDRH organization, which will allow you to download project materials and upload changes back for all to see, referred to as a "push" in Git terminology.
When you are added, you should get an email inviting you to accept or you can head to https://github.com/cdrh/ to accept the invite there.
Download GitHub Desktop and Your Project
1. GitHub Desktop
In order to work with Git you will need some software! Download GitHub Desktop and open it. Log in with the credentials you just created for GitHub in the previous step. You'll then be prompted for what display name and email will accompany the changes you make. You may keep the default display name and email, or change it to your name and UNL email address.
2. Download a CDRH Project
After you log in, you'll get to a pretty empty looking screen in GitHub Desktop. That's because we need to add a new Git repository. A repository is just a directory with all the files you need to work on the project. You should see a couple repositories listed (different than in the below image). If you do not see any, check that you've successfully joined the CDRH organization and that you have logged into GitHub Desktop.
Select the project and click the "clone" button. You will now select a place on your computer to locate this repository (highlighted in pink in the image below). You may want to add a directory named "cdrh" on your Desktop or the C drive, for example, and select that as the destination. If you choose not to change the path, take note of where your project is being saved so you can find it later!
Set aside GitHub Desktop for a minute now, and find the repository you just cloned in your file system. If you open that directory, do you see a bunch of new files and directories inside of it? Congratulations, you just used Git to grab the files you need to start contributing to a digital humanities project!
Repository Structure
Most CDRH projects have a similar structure. You should see a "source" directory containing different format directories, such as "tei" and "xlsx." Depending on the project, you may see completely different ones than in the image below.
The "source/drafts" directory is where you can put basic transcriptions. For example, if you are typing out the text of a letter, you might first create a text file and save it into "source/drafts/specific_format." Later, you'll go back and add information to that file so that we can easily tell when the letter was written, who wrote it, where it was sent, and other information. At that point, you'll move the file out of the drafts and into a specific format directory in "source." Don't worry, we'll train you on how to do all of this work later, for now you just need to know that you're mostly working in the "source" directory!
Working on the Project
1. Pull!
No matter what, you should always update your repository each time you start working. This will ensure that you have the latest changes from everybody else who is working on the project. Sometimes that might even include your own changes, if you have been working on multiple computers!
You can click "fetch origin" to see if there have been any changes out there. The button will change to "pull" if there are changes available. Click it again to get the latest and greatest in work your collaborators have been doing.
Above you can see the "fetch origin" button. After clicking it, you may see "pull origin" like the lower screenshot.
The "pull origin" button is indicating that there is 1 change waiting to be pulled, so click that button!
2. Make some changes
Open up any file in the repository in a plain text editor, which means NOT in Microsoft Word. Many computers come with Notepad or TextEditor, which will work beautifully. Once you have opened the file, go ahead and type something! You could change a line, or add your name to the top, it doesn't matter. Save the file.
Now go look in your GitHub Desktop application. Do you see your changes?
3. Review, commit, and push!
Whenever you are done working for the day, you will want to open GitHub Desktop and review the things you have worked on. You can click on a file to view your changes.
If you're not happy with what you did, right click the file and select "discard changes." The file will be reset to the way it used to look before you made any changes. You'll probably want to do this right now to undo the changes you made in the previous step.
If you're happy with how everything looks, write a little message in the lower left area to help you remember what you worked on. "Added newspaper articles" or "fixed date errors in government documents," for example. Click the "commit" button.
Now, this is the trickiest part.....click "push origin" on the upper right! It's easy to forget this step, but it's one of the most important ones, because when you push your changes, you make them available for everybody else to see, including yourself on different computers.
Try to get in the habit each day --
What's Next?
When you work on a large digital project with lots of other people, keeping track of what everybody should be working on is very important. Each project handles this a little differently and a CDRH staff member will help you with this step. Still, sometimes when there are lots of people working at the same time, two people may edit the same file around the same time. When this happens Git doesn't know what it should do to combine the changes. Conflicts require a person to look at the two changes and figure out how to make them work together. If you ever push or pull and get messages about conflicts, please ask a CDRH staff member for help and we will show you how to review the file with the conflict. Conflicts are usually very simple to resolve, so do not worry!
At this point, you know the basics of version control that you will need to start working on a project! Please let a CDRH staff member know if you have any questions or problems. Thanks for working with us. We are excited to have you on the team :)