Overleaf is our preferred platform for drafting notes and writing papers. To get started with Overleaf, go to Overleaf.com, click on Sign Up, and register, preferably with your Princeton e-mail account. It's fine to have only a free account.
- We are not using Overleaf v2 at this time; just plain Overleaf.
- Modest use of Overleaf to share files like Mathematica notebooks that are ancillary to a LaTeX project is fine. Since Overleaf is an editing platform, I assume they prefer that we don't share big files that aren't directly part of a LaTeX project. As a rule of thumb, how about switching to GitHub when such files exceed 100 MB in total for a given project?
- The first thing I should do is to add you to the OverleafTest project, which describes the basics of LaTeX and git; and it's a convenient spot for me to record everyone's Overleaf ID.
- An important rule with anything git-related is, make your own copy of Mathematica notebooks (.nb files) for just you to edit. For instance, if we've got ONmodel.nb on Overleaf, I would copy it to ONmodelSSG.nb, and then only I edit that file. I still commit it to git and Overleaf---that's no problem. Problems seem to arise only if multiple people try to edit the same .nb file within git/Overleaf.
We use a Princeton-specific form of GitHub for sharing code which is not (yet) related to a particular Overleaf project. This GitHub instance is maintained by Princeton's CSES group. As of 2018, the contact person is Benjamin Hicks.
Web login (once you are added to the repository) is a little confusing, because if you follow the above link you get a 404 message. Log in anyway (with your GitHub ID) and it should work.
Mostly we use GitHub from the command line. here's a brief synopsis of how to do it:
- To get started with command-line tools, say "git clone https://github.com/PrincetonUniversity/gubser-group.git" in a Unix shell, and you should see a subdirectory created, gubser-group, with all the files in the repository.
- Make changes on your local copy, and/or add new files.
- For any file you revised or added, "git add <filename>".
- Commit your changes locally with "git commit -m <commit message>".
- Pull in any changes that might have been made by other users, by saying "git pull --no-edit".
- At this stage you might have a conflict, and git will tell you if so. Briefly, if a file winds up conflicted, edit it to resolve the conflict (look for "=======" to see where conflicts arose), then add it, commit it, and pull again until no conflicts are reported.
- Push your changes to GitHub with "git push origin master".
- In most circumstances, after the first cloning, all you need to do is to git pull, edit locally, add, commit, pull, and push.
- Same warning as above about Mathematica notebooks: Make an obvious single-user filename to avoid git merging.
Here's how to add a user to the repository. (Admin privileges probably required):
- The user first has to get an account on GitHub.com. If at all possible they should use their Princeton ID (e.g. ssgubser) also as their GitHub ID.
- Log into GitHub so that you can see the current fileset.
- Click Settings Collaborators teams.
- Add a collaborator using their GitHub ID.
We use Google calendar (calendar name Gubser Group) to keep track of where we are.
It is occasionally conveniently to run asynchronous processes in Mathematica that let you keep computing in your primary notebook while some lengthy command executes on a secondary kernel. Here is some code to let you do this in a simple way. The main limitation is that you can only have one secondary process at a time.