Sending around LaTeX files via email is so 1990s. Let's not do this. Let's also not use Dropbox. Dropbox is great for syncing files between computers and serves as a great backup solution. But it's terrible for collaborating on text documents -- it can't handle conflicts (two people editing the same file at the same time creates a second copy of the file in the dropbox; Dropbox won't merge text for you).
Let's move on and use version control. It will make working together on the same document infinitely easier and will minimize the time we have to deal with merging different versions of the file we are working on together. There are multiple version control packages. For our project we will use git. You can learn more about git and version control in general on http://git-scm.com. If you are unconvinced, read this: Why use a Version Control System?
Here is how it works:
- Make sure you have git installed on your computer (I presume you have either a Mac or a PC that runs a flavor of Linux). Just open a terminal, type git, hit enter, and see if the command is found. If not, you need to install git.
- Make and send me a password-protected public ssh key as an email attachment (not cut & paste!). The standard path and file name for this are ~/.ssh/id_rsa.pub or ~/.ssh/id_dsa.pub. If you don't have such a key or you don't remember if it's password protected (or you dont remember your password...), type on the command line:
and follow the instructions. By all means, give your key a strong password. Then send me the file ~/.ssh/id_rsa.pub as an email attachment (do not cut & paste it into the email body)
ssh-keygen -t rsa
(2) Cloning the repository from the server
By now I have told you details about the repository and sent you the command needed to clone it from the server. Go into your preferred working directory (that's where you keep projects, papers, proposals etc.). Type:
This will clone the repo -- in other words, it will create a directory with the repository name in your working directory and will download the contents of the repo into it. If this does not happen and instead you are asked to enter a password, then your ssh key is not loaded. In this case, load your ssh key like this:
git clone [GITUSER]@[MACHINE HOSTNAME]:[REPOSITORY NAME]
Then try again. If this still does not do the trick or if you get an error message about no "ssh-agent" running, then try
This will spit out a few lines of text. Copy them and paste them back into the prompt, hit enter, then repeat
This should do the trick!
(3) Pulling in changes.
Before starting to work on a section of the document, you need to make sure to get the most recent changes. You must absolutely always do this before starting to work! Go into the repository directory.
(the "-r" is to make the pull a "rebase" -- don't worry about the meaning of this, just do it).
git pull -r
(4) Committing and pushing changes.
Whenever you have completed a significant addition or change to the document -- this may be a completed or edited paragraph, something that takes no longer than about 30 minutes of work, you need to commit and push your changes so that others can pull them onto their computers.
Please give sensible commit messages so that we others know what you changed!
git add [FILE YOU WERE EDITING] git commit -m "Your commit message goes here" git pull -r # this is to pull in any changes by others! git push
(5) Looking at the history of changes and checking the status of your repo.
That's very easy! First pull in all recent changes via
git pull -r. Then use
git logto browse through the repository history. Try
git statusto see what the status of your repo is. This will tell you which files have changed and should be committed. It will also tell you which files you have not yet added (i.e. "untracked" files).
(6) Golden Rules
Working with version controlled documents is easy and painless as long as you obey two simple rules:
git pull -rbefore starting to edit.
- Extremely frequently:
git add [FILE] git commit -m "[COMMIT MESSAGE]" git pull -r git push
(7) Adding additional files to the repo
(8) Resolving merge conflicts
git add [FILENAME] git commit -m "Added file [FILENAME] to repo" git pull -r git push
Oh boy. Somebody was editing the same portion of text you were editing (did you perhaps not sufficiently frequently commit and push?!?). You now need to resolve the conflict. Let's do this by example. Let's say you were editing a file called Readme.md. You added, committed, then pulled and ended up with the following git merge error:
Good luck! You now need to resolve the conflict. Let's look at the (hypothetical) file in question.
remote: Counting objects: 5, done. remote: Total 3 (delta 0), reused 3 (delta 0) Unpacking objects: 100% (3/3), done. From github.com:hypercott/ay190test 23ae277..b13d53f master -> origin/master Auto-merging README.md CONFLICT (content): Merge conflict in README.md Automatic merge failed; fix conflicts and then commit the result.
git has conveniently inserted information on what the conflict is. The stuff right beneath
$ cat README.md ay190test ========= <<<<<<< HEAD Test345 ======= Test3 >>>>>>> b13d53f9cf6a8fe5b58e3c9c103f1dab84026161
<<<<<< HEADis what is currently in the remote repository and the stuff just below the
=======is what we have locally. Let’s say you know your local change is correct. Then you edit the file and remove the remote stuff and all conflict stuff around it.
$ cat README.md ay190test ========= Test3
git committhe file, then you execute
git pushto update the remote with your local change. This resolves the conflict and all is good!