Merging

Within these castle walls be forged Mavens of Computer Science ...

— Merlin, The Coder

Research

Introduction to Version Control (Emacs)

Experiment

Note: You will need to work with a partner for this lab. (We'll call the partners, Partner A and Partner B.)

First Steps

Only Partner A should perform the following steps:

Log on to GitHub
Click on New next to "Repositories"
On the next page: Enter "TheStory" as the Repository name Select Private Select Initialize this repository with a README Click on Create repository
At the top of the next page, click on Settings
On the left-hand list, select Collaborators
On the right-hand side: Enter the GitHub user name of Partner B's GitHub account Click the Add collaborator button Enter the GitHub user name of your invigilator Click the Add collaborator button

Only Partner B should perform the following steps:

Partner B will receive an invitation email from GitHub. Partner B should open the email. If it doesn't appear to arrive within a minute or two check the SPAM/Junk folder. Partner B should click on the Accept Invitation link.
If Partner B sees the image on the right he/she should log in to GitHub and then click on the link in the email again.

Both Partners

Both partners should now log on to the server.

Create a project directory:

cd ~/projects
mkdir project-1601
cd project-1601

Important: Do not skip this step! In order to successfully complete the remainder of the lab, it's important that your username and password (credentials) for GitHub are saved for future access. You can accomplish this by following the steps here and then continuing with this project.

Next, both partners should clone the newly created repository. Note that the actual name of the repository will depend on the user name of Partner A. Adjust the URL appropriately by replacing PARTNER_A_USER_NAME with the actual Partner A user name.

 git clone https://github.com/PARTNER_A_USER_NAME/TheStory

Depending on your configuration, you may need to enter your username and password for GitHub. However, after this point, your credentials should be cached and you shouldn't need to enter them again and again.

Now, enter the directory and then pull the contents from the repository.

cd TheStory
git pull

Partner B on the Command Line

Partner B should now perform the following:

1. Create a new file, "story.txt", with emacs:

emacs story.txt

Next, copy and paste the following text into the file. Then, save the file and exit.

Whilst we were talking, we heard a sort of sound between a
yelp and a bark. It was far away; but the horses got very restless,
and it took Johann all his time to quiet them. He was pale and said,
"It sounds like a wolf - but yet there are no wolves here now."
"No?" I said, questioning him. "Isn't it long since the wolves were
so near the city?"

Check the status of your local git repository by typing:

git status

Question: After carefully reading the output text of the command, why do you think "story.txt" is listed as "untracked"?

In order to track the file, type:

git add story.txt

Helpful hint: If you need to add multiple files there's no need to issue the command multiple times. Just list the files one after another, separated by a space.

Check the status again:

git status

Question: After carefully reading the output text of the command, why do you think "story.txt" is listed as "new file"?

In order to commit your changes to your local repository, type:

git commit

Emacs will open enabling you to type a description of what you've changed (added, modified, deleted). This should be a useful message. For ideas about how to ensure that your message is useful, read The Art of the Commit (by David Demaree). After entering your message, save and exit emacs as usual.

Check the status again:

git status

Question: After carefully reading the output text of the command, what do you think is meant by "Your branch is ahead of 'origin/master' by 1 commit"?

Let's push the changes to the remote repository:

git push

Verify that your changes are visible on GitHub by going to the same URL that you used for the git clone operation.

Partner A on the Command Line

Partner A can now receive the changes made by Partner B. To do so, Partner A should execute:

git pull

To check the directory contents, execute:

ls

Open the file in emacs:

emacs story.txt

Next, copy and paste the following text to the end of the file. Then, save the file and exit.

"Long, long," he answered, "in the spring and summer; but with
the snow the wolves have been here not so long."

What changed from the previous commit? Have a look with:

git diff

Now, check the status:

git status

Question: After carefully reading the output text of the command, why do you think "story.txt" is shown in red as "modified"?

Now, use git to add, commit, and push your changes to your remote repository on GitHub.

Partner B in Emacs

Partner B can now receive the changes made by Partner A, but let's be smarter and use the features available from within emacs.

Start emacs, opening "story.txt".

Question: Pay close attention to the mode line in emacs. In addition to your file's name, is there any indication that this file is under source control?

Pull the latest changes from the remote GitHub repository. There's no need to exit emacs; emacs contains a built-in client for interacting with many source control systems. Enter the sequence: C-x v +

Emacs has now executed git pull and displayed the results in a separate window. You'll note that the text in the window indicates that "story.txt" was changed. You may also note that the buffer (for story.txt) hasn't yet changed. In order to refresh the buffer, type M-x revert-buffer and answer "yes". (Don't worry! If you forget to do this emacs will warn you.)

Add the following text to the end of the file:

Whilst he was petting the horses and trying to quiet them, dark
clouds drifted rapidly across the sky. The sunshine passed away,
and a breath of cold wind seemed to drift over us. It was only a
breath, however, and more of a warning than a fact, for the sun
came out brightly again.

Save the file with C-x s

Within emacs, we can check for differences between the version in the local repository and our uncommitted changes by typing C-x v =

Remember, that to close a window in emacs, with the cursor in that window, type C-x 0 (the last character is a zero). Close the diff window now.

Add and commit this change of adding the third paragraph by typing C-x v v. A new window will open asking you to type in a check-in comment. Do so and then type C-c C-c to exit that window.

To view a log of changes, type C-x v l (the last character is a lowercase L). You can scroll through the log in the same way that you scroll through any other buffer in emacs.

At this point, we've modified the file, added it to our local repository and committed it, but we haven't yet pushed it to the remote repository. We can do that by typing C-x v P

Helpful hint: If you have several windows open but only care about one you can go to that window (using one or more C-x o) and then typing C-x 1 (that's the digit one)

Helpful hint: There are many version-control commands. If you forget the key-sequence you can look it up with C-x v ?