GitHub for Foreign Language Teachers

A Git / GitHub workflow for foreign language students and teachers was briefly discussed in a Skype conversation between Yuni, an online teacher of Indonesian, and Toomas, a Linux system engineer. They have agreed to go though it step by step, and so they did. Here, we are discussing things from the teacher’s perspective.

Grammar exercises as a Git repository published on GitHub

Yuni creates a new folder on her computer, and initializes a Git repository inside it.

mkdir sample_exercise
cd sample_exercise
git init

In this folder, Yuni creates a sample exercise on Indonesian personal pronouns, indonesian_pronouns.md It is written in Markdown format:

# Fill the gaps with appropriate pronouns in the following dialogue.

## Peter dan Dita pergi ke Jakarta. Tina tinggal di Jogja.

Dita: Tina, … pergi ke Jakarta. Saat ... kembali mari ... pergi ke Kesuma restoran.

Tina: Andy dan Ria pergi juga?

Dita: Tidak, ... harus bekerja.

Tina: Dan Anto?

Dita: ... bekerja juga.

Tina: Berapa lama libur kalian?

Dita: Empat hari.

Tina: ... iri padamu.

It’s just a plain text file that can be edited with many editors (Atom, Notepad++, TextWrangler, Vim, etc.). It is quite human-readable as it is, but when viewed on GitHub, parts of the text between empty lines will become paragraphs, and lines prepended with one or more # symbols will become headers. The file name must end with .md. That’s all you need to know for now, the full story is a three-minute read at GitHub .

For now, it is just a single file for simplicity of the example, but the intention is to maintain sets of exercises in Git repositories.

Yuni adds the newly created file to be tracked by Git:

git add *

and creates the first commit:

git ci -m 'Created an exercise on personal pronouns.'

She then creates a repository on GitHub, where she has a free account, sets it as a remote for her local repository, and pushes her local changes to the remote:

git remote add origin git@github.com:<USER NAME>/<REPOSITORY NAME>.git
git push -u origin master

The sample repository that we are discussing here can be viewed at https://github.com/tvendelin/language-exercise-example .

From now on, anyone can view the exercises Yuni has created, but only Yuni, the repository owner, can change them. More importantly, each of her students can fork this repository, that is, to create their own repositories with the same content, but under their own accounts.

Maria, a Yuni’s student, does exactly that: she creates an account on GitHub, forks Yuni’s repository with homework exercises, completes them, commits the changes, pushes them back to GitHub, and invites Yuni as a collaborator. The next chapter describes Maria’s little adventure in detail.

Yuni receives an e-mail with an invitation to collaborate on Maria’s repository. This is a fancy way to say it’s time for

Correcting a Student’s Homework

Yuni clones the repository with Maria’s homework. Cloning means creating a copy of a Git repository on your computer, locally. The cloned repository ‘remembers’ where it came from, and this is the important difference between cloning and downloading. The URL for cloning can be obtained at repository page by clicking ‘Clone or download’ button. The command is:

git clone <THE URL OF REPOSITORY> maria_<REPOSITORY NAME>

This creates a folder maria_<REPOSITORY NAME> with a Git repository’s working copy in it. It is a good idea to use a custom destination folder (maria_<REPOSITORY NAME> in our example) to distinct between different students. Yuni changes into this folder, and runs git log --pretty=reference to identify her last commit. In our example, it is c9ba48c.

To see which files changed since her last commit (that is, changed by her student), Yuni runs

git diff --compact-summary c9ba48c HEAD^ 

The output tells her that one file, indonesian_pronouns.md, has been modified:

 indonesian_pronouns.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

Now Yuni knows which files she must check and possibly correct. With a single student and a single exercise this may seem redundant, but later on with many exercises multiplied by many students this step will become quite handy.

Yuni corrects the exercise and commits the changes.

git commit -a

This opens the default editor on Yuni’s computer, which allows Yuni to create a detailed, multi-lined commit message, with a brief feedback on Maria’s mistakes:

Corrected exercise indonesian_pronouns.md

There are two pronouns for the first person plural: kita (inclusive),
and kami (exclusive). Tina isn't going to Jakarta with Peter and Dita
(Tina is not included = use kami), neither is she returning with them
(Tina is not included = use kami). But, once Peter and Dita are back,
they go all together to a restaurant. In this case, Tina is included, so
use kita.

The first line is the main commit message which is most often displayed in all kind of commit logs. The following lines are displayed more seldom, so in many cases (like creating a new exercise previously) a one-line commit message is all you need. Here, however, it’s a good place to provide a feedback.

Once the text is saved, the commit is created. Yuni then pushes her commit to the upstream remote repository on GitHub:

git push

If Maria didn’t botch notification settings in her repository, she will shortly receive an automatic e-mail from GitHub notifying her about a new commit by Yuni, meaning she can now view the corrections to her homework.