|-project
    |-'final.doc'

Fixed conclusion

Julie pointed out that I had missed 
the critical bit in the assignment 
regarding stratigraphy. This was 
added in the concluding section.

1.3.2 Key Terms

• repository: a single folder that holds all of the files and subfolders of your project
• commit: this means, ‘take a snapshot of the current state of my repostiory’
• publish: take my folder on my computer, and copy it and its contents to the web as a repository at github.com/myusername/repositoryname
• sync: update the web repository with the latest commit from my local folder
• branch: make a copy of my repository with a ‘working name’
• merge: fold the changes I have made on a branch into another branch
• fork: to make a copy of someone else’s repo
• clone: to copy an online repo onto your own computer
• pull request: to ask the original maker of a repo to ‘pull’ your changes into their master, original, repository
• push: to move your changes from your computer to the online repo
• conflict: when two commits describe different changes to the same part of a file

1.3.3 Take-aways

• Git keeps track of all of the differences in your files, when you take a ‘snapshot’ of the state of your folder (repository) with the commit command
• Git allows you to roll back changes
• Git allows you to experiment by making changes that can be deleted or incorporated as desired
• Git allows you to manage collaboration safely
• Git allows you to distribute your materials

1.3.4 Further Reading

We alluded above to the presence of ‘helper’ programs that are designed to make it easier to use Git to its full potential. An excellent introduction to Github’s desktop GUI is at this Programming Historian lesson on Github. A follow-up lesson explains the way Github itself can be used to host entire websites! You may explore it here. In the section of this chapter on open notebooks, we will also use Git and Github to create a simple open notebook for your research projects.

You might also wish to dip into the archived live stream; link here from the first day of the NEH funded Institute on Digital Archaeology Method and Practice (2015) where Prof. Ethan Watrall discusses project management fundamentals and, towards the last part of the stream, introduces Git.

1.3.5 Exercises

(sg: wordpress has buggered up my numbering, and life is too short to try to fix it nicely. So let bolded words represent a new exercise)

1. How do you turn a folder into a repository? With the git init command. At the command line (remember, the $ just shows you the prompt; you don’t have to type it!):

1. make a new director: $ mkdir first-repo
2. type $ ls (list) to see that the director exists. Then change directory into it: cd first-repo. (remember: if you’re ever not sure what directory you’re in, type $ pwd, or print working directory).
3. make a new file called readme.md. You do this by calling the text editor: nano readme.md. Type an explanation of what this exercise is about. The .md signals that you’re writing a text file that uses the markdown format of signalling things like headings, lists, tables, etc. (A guide to markdown syntax is here). Hit ctrl+x to exit, then y to save, leave the file name as it is.
4. type $ ls again to check that the file is there.
5. type $ git init to tell the Git program that this folder is to be tracked as a repository. If all goes correctly, you should see a variation on this message: Initialized empty Git repository in /home/demonstration/first-repo/.git/. But type $ ls again. What do you (not) see?

The changes in your repo will now be stored in that hidden directory, .git. Most of the time, you will never have reason to search that folder out. But know that the config file that describes your repo is in that folder. There might come a time in the future where you want to alter some of the default behaviour of the git program. You do that by opening the config file (which you can read with a text editor). Google ‘show hidden files and folders’ for your operating system when that time comes.

2. Open your readme.md file again with the nano text editor, from the command line. Add some more information to it, then save and exit the text editor.

1. type $ git status
2. Git will respond with a couple of pieces of information. It will tell you which branch you are on. It will list any untracked files present or new changes that are unstaged. We now will stage those changes to be added to our commit history by typing $ git add -A. (the bit that says -A adds any new, modified, or deleted files to your commit when you make it. There are other options or flags where you add only the new and modified files, or only the modified and deleted files.)
3. Let’s check our git status again: type $ git status
4. You should see something like this:

On branch master
Initial commit
Changes to be committed:
  (use "git rm --cached <file>..." to unstage)
        new file:   readme.md```

5. Let’s take a snapshot: type $ git commit -m "My first commit". What happened? Remember, Git keeps track not only of the changes, but who is making them. If this is your first time working with Git in the Archaebox, Git will ask you for your name and email. Helpfully, the Git error message tells you exactly what to do: type $ git config --global user.email "you\@example.com" and then type $ git config --global user.name "Your Name". Now try making your first commit.
6. The command above represents a bit of a shortcut for making commit messages by using the -mflag to associate the text in the quotation marks with the commit. Open up your readme.md file again, and add some more text to it. Save and exit the text editor. Add the new changes to the snapshot that we will take. Then, type $ git commit. Git automatically opens up the text editor so you can type a longer, more substantive commit message. In this message (unlike in markdown) the # indicates a line to be ignored. You’ll see that there is already some default text in there telling you what to do. Type a message indicating the nature of the changes you have made. Then save and exit the text editor. DO NOT change the filename!

Congratulations, you are now able to track your changes, and keep your materials under version control!

3. Go ahead and make some more changes to your repository. Add some new files. Commit your changes after each new file is created. Now we’re going to view the history of your commits. Type $git log. What do you notice about this list of changes? Look at the time stamps. You’ll see that the entries are listed in reverse chronological order. Each entry has its own ‘hash’ or unique ID, the person who made the commit and time are listed, as well as the commit message eg:

commit 253506bc23070753c123accbe7c495af0e8b5a43
Author: Shawn Graham <shawn.graham@carleton.ca>
Date:   Tue Feb 14 18:42:31 2017 +0000

Fixed the headings that were broken in the about section of readme.md

1. We’re going to go back in time and create a new branch. You can escape the git log by typing q. Here’s how the command will look: $ git checkout -b branchname <commit> where branch is the name you want the branch to be called, and <commit> is that unique ID. Make a new branch from your second last commit (don’t use < or >).
2. We typed git checkout -b experiment 253506bc23070753c123accbe7c495af0e8b5a43. The response: Switched to a new branch 'experiment' Check git status and then list the contents of your repository. What do you see? You should notice that some of the files you had created before seem to have disappeared – congratulations, you’ve time travelled! Those files are not missing; but they are on a different branch (the master branch) and you can’t harm them now. Add a number of new files, making commits after each one. Check your git status, and check your git log as you go to make sure you’re getting everything. Make sure there are no unstaged changes – everything’s been committed.

4. Now let’s assume that your experiment branch was successful – everything you did there you were happy with and you want to integrate all of those changes back into your master branch. We’re going to merge things. To merge, we have to go back to the master branch: $ git checkout master. (Good practice is to keep separate branches for all major experiments or directions you go. In case you lose track of the names of the branches you’ve created, this command: git branch -va will list them for you.)

1. Now, we merge with $ git merge experiment. Remember, a merge is a special kind of commit that rolls all previous commits from both branches into one – Git will open your text editor and prompt you to add a message (it will have a default message already there if you want it). Save and exit and ta da! Your changes have been merged together.

5. One of the most powerful aspects of using Git is the possibility of using it to manage collaborations. To do this, we have to make a copy of your repository available to others as a remote. There are a variety of places on the web where this can be done; one of the most popular at the moment is Github. Github allows a user to have an unlimited number of public repositories. Public repositories can be viewed and copied by anyone. Private repositories require a paid account, and access is controlled. If you are working on sensitive materials that can only be shared amongst the collaborators on a project, you should invest in an upgraded account (note that you can also control which files get included in commit; see this help file. In essence, you simply list the file names you do not want committed; here’s an example). Let’s assume that your materials are not sensitive.

1. Go to Github, register for an account.
2. On the upper right part of the screen there is a large + sign. Click on that, and select new public repository
3. On the following screen, give your repo a name.
4. DO NOT ‘initialize this repo with a readme.md’. Leave add .gitignore and add license set to NONE.
5. Clic the green ‘Create Repository’ button.
6. You now have a space into which you will publish the repository on your machine. At the command line, we now need to tell Git the location of this space. We do that with the following command, where you will change your-username and your-new-repo appropriately:

   $ git remote add origin https://github.com/YOUR-USERNAME/YOUR-NEW-REPO.git

7. Now we push your local copy of the repository onto the web, to the Github version of your repo:

   git push -u origin master

NB If you wanted to push a branch to your repository on the web instead, do you see how you would do that? If your branch was called experiment, the command would look like this:

$ git push origin experiment

8. The changes can sometimes take a few minutes to show up on the website. Now, the next time you make changes to this repository, you can push them to your Github account – which is the ‘origin’ in the command above. Add a new text file. Commit the changes. Push the changes to your account.

6. Imagine you are collaborating with one of your classmates. Your classmate is in charge of the project, and is keeping track of the ‘official’ folder of materials (eg, the repo). You wish to make some changes to the files in that repository. You can manage that collaboration via Github by making a copy, what Github calls a fork.

1. Make sure you’re logged into your Github account on the Github website. We’re going to fork an example repository right now by going to https://github.com/octocat/Spoon-Knife. Click the ‘fork’ button at top-right. Github now makes a copy of the repository in your own Github account!
2. To make a copy of that repository on your own machine, you will now clone it with the git clonecommand. (Remember: a ‘fork’ copies someone’s Github repo into a repo in your OWN Github account; a ‘clone’ makes a copy on your own MACHINE). Type:

   $ cd.. 
   $ pwd

   We do that to make sure you’re not inside any other repo you’ve made! Make sure you’re not inside the repository we used in exercises 1 to 5, then proceed:

$ git clone https://github.com/YOUR-USERNAME/Spoon-Knife
$ ls

You now have a folder called ‘Spoon-Knife’ on your machine! Any changes you make inside that folder can be tracked with commits. You can also git push -u origin master when you’re inside it, and the changes will show up on your OWN copy (your fork) on Github.com. c. Make a fork of, and then clone, one of your classmates’ repositories. Create a new branch. Add a new file to the repository on your machine, and then push it to your fork on Github. Remember, your new file will appear on the new branch you created, NOT the master branch.

7. Now, you let your collaborator know that you’ve made a change that you want her to merge into the original repository. You do this by issuing a pull request. But first, we have to tell Git to keep an eye on that original repository, which we will call upstream. You do this by adding that repository’s location like so:

1. type (but change the address appropriately):

$ git remote add upstream THE-FULL-URL-TO-THEIR-REPO-ENDING-WITH-.git

2. You can keep your version of the remote up-to-date by fetching any new changes your classmate has done:

   $ git fetch upstream

3. Now let’s make a pull request (you might want to bookmark this help document). Go to your copy of your classmate’s repository at your Github account. Make sure you’ve selected the correct branch you pushed your changes to, by selecting it from the Branches menu drop down list.
4. Click the ‘new pull request’ button.
5. The new page that appears can be confusing, but it is trying to double check with you which changes you want to make, and where. ‘Base Branch’ is the branch where you want your changes to go, ie, your classmate’s repository. ‘head branch’ is the branch where you made your changes. Make sure these are set properly. Remember: the first one is the TO, the second one is the FROM: the place where you want your changes to go TO, FROM the place where you made the changes.
6. A pull request has to have a message attached to it, so that your classmate knows what kind of change you’re proposing. Fill in the message fields appropriately, then hit the ‘create pull request’ button.