Git is a widely used version control system, much used e.g. by software developers. But others, even writers of one-author paper or book projects, swear by it too. Thus Richard Baron writes:
The last time the Open Logic Text was discussed on the Logic Matters blog ( https://logicmatters.net/2015/05/10/the-open-logic-text/ ), there was some discussion of the merits of Git, and Richard Zach put up some material on the OLT blog about the use of Git. Since then I have experimented on GitLab, starting from zero knowledge, and can confirm that it is a wonderful system, even for a one-author project. So I encourage everyone to have a go.
This is from the comment thread here, where a discussion continues. This post is simply to point out the exchange to anyone interested in this sort of thing (but who might not be delving into comments on OLT). And to invite anyone else who has views/experiences about Git or some other version control system (as a paper/book author) to share them — either in that thread, or [better?] in new comments here.
I have always preferred Mercurial (abbreviated Hg) over Git, for its conceptual simplicity and the ease of use of its tooling. It has the excellent BitBucket website/platform for project hosting, which is at least as good as GitHub, for me.
Some good web pages / article on Mercurial vs Git (either neutral or pro-Hg):
http://stackoverflow.com/questions/35837/what-is-the-difference-between-mercurial-and-git
https://www.wikivs.com/wiki/Git_vs_Mercurial
http://blogs.atlassian.com/2012/02/mercurial-vs-git-why-mercurial/
http://stevelosh.com/blog/2010/01/the-real-difference-between-mercurial-and-git/
https://jhw.dreamwidth.org/1868.html
http://programmers.stackexchange.com/questions/87217/why-is-mercurial-considered-to-be-easier-than-git
Former student of yours here, now a heavy git user in my day job.
Git is an incredibly powerful and useful tool, particularly when collaborating with others, and particularly when working on source code. But for a single author writing prose I can’t see how the benefits would be worth the required investment of time. Git’s interface has improved significantly over the years, but it’s still a long way from user friendly. And the system you just described sounds perfectly adequate.
People who don’t use a VCS generally end up creating their own (commenting out sections, copying files, etc), which is just as much hassle and less reliable.
Remember Dropbox is not safe (they do lose data occassionally).
With git, I like specifying what should be committed and when, and leaving a short explanatory commit message. I don’t like auto-sync like Dropbox.
Ivan
What’s supposed to be the big problem with copying files? It’s a lot simpler than what a VCS does, and copy is reliably supported by the file system. (Doesn’t the VCS rely on that?) As I mentioned earlier, using a VCS is a lot like using a more complicated file system that works in odd ways.
Re commenting out sections, people do that when they’re using a VCS too. It’s a lot easier than having to find when the thing was last in and restore it, and it can also serve as a useful reminder. When I commend out, it’s because I want it right there to refer to when I’m reading or think I might well want to bring it back.
There’s nothing wrong with making up your own VCS. I prefer git.
Certainly git is a sprawl. I use a handful of commands. It has helped me develop a workflow I am comfortable with. I prefer git’s VCS to Subversion and to the various ad hoc VCSs I made up before I used that.
Ivan
My two-pennyworth (and that’s no doubt an over-valuation!)
1. I’m working always in LaTeX. I have Current Work folder is a Dropbox folder (so lives locally on each computer, and in the cloud).
2. I do a lot of commenting-out of paragraphs, sections etc. if I’m doing major revision so I can recover easily if I change my mind. And on the rare occasions when I’m doing something really radical like deciding to completely change the order I discuss topics (as with the category theory notes at the moment) I make a copy of the pre-change folder, and on we go. (Just once in the last two years, as far as I can recall, has a section of a chapter actually “gone missing” in the short term. But since DropBox keeps previous versions of files for 30 days, I instantly got it back.)
3. I do have to remember to quit LaTeX on my fancy home laptop before picking up my old café/library laptop (and quit LaTeX on that when I get home), in order to avoid conflicts. But that is hardly a difficult habit to acquire, and in any case Dropbox is tolerant and allows you to recover from any accidental conflicts easily.
So I’m still not sure what I’d gain from using Git or an equivalent (I also have Time Machine running and do occasional snap-shot clones of the hard disk on my main machine using SuperDuper, so I’m not short of plain old-fashioned backups.)
Using Git (or any other similar tool) gives you the same kind of advantages as stepping from carefully named files to using a folder structure; only this time it is not about keeping an order in files but in their content.
The complexity of using Git for tracking files content in on par with navigating in a folder structure.
Extra bonuses:
* You get a history for free
* You can collaborate with others if needed
Warning:
Please don’t conflate Git with Github.com. Git is a tool, Github.com is a commercial service specializing in hosting git repositories.
There’s a lot to be said for not using a computer, let alone a VCS, at least until the final stages of writing something. The most important technology for writing is a waste paper bin. Write first of all with a pencil, with liberal use of an, er, eraser. Place what you have written on the floor behind your chair. (Use just one side of the paper — the other side will come in handy later.) When you are feeling good about yourself, turn your chair around and look at what you have written. Make brief notes (in pencil) about anything worth preserving.
At a later stage, use a fountain pen, in the best handwriting you can manage — this concentrates the mind.
When it gets to the point that your career is in jeopardy, give up, and do what everyone else does.
By the way, I learnt these lessons when decades ago I was writing computer code.
To add to Sara’s comments, here is what I have worked out you need to do to start using GitLab (which allows you to keep repositories private). As with Sara’s comments, this is all for the Linux command line. Some of the methods I suggest may be more cumbersome than necessary, and you can always google around for help on particular points. And this is for the really simple approach, with only the master and no branches – just enough to get you started.
1. Getting yourself set up.
On your own computer, set yourself up like this:
git config –global user.name “John Doe”
git config –global user.email johndoe@example.com
On your own computer, set up an SSH key like this:
to generate key: ssh-keygen -t rsa -C “johndoe@example.com”
to show the key in the terminal: cat ~/.ssh/id_rsa.pub
(This is what GitLab told me to do; I found different instructions in other places, but this worked for me.)
On GitLab, register yourself as a user.
Give GitLab your SSH public key.
2. Creating a new project
On Gitlab, create the project, name it (you only need the last part, it completes the path for you; we’ll call it philogit, to distinguish the name on Gitlab from the name of the folder on your computer, but you could use the same name for both), click to add a readme file, and then put a few words in readme and click to commit them.
Create the folder on your own hard disk (we’ll call it philosophy and assume it is in the documents folder).
Change directory to that folder: cd /home/johndoe/documents/philosophy/
Make it into a git repository by: git init
Pull what is already on the Gitlab server by: git pull git@gitlab.com:johndoe/philogit.git
3. The pull and push commands
First change directory to your philosophy folder on your computer.
To pull from GitLab: git pull git@gitlab.com:johndoe/philogit.git
To push to GitLab: git push -u git@gitlab.com:johndoe/philogit.git
You should be able to do these without going to the GitLab website and logging in.
4. Adding files in master
Method (a)
Create on GitLab (there is a space for a filename at top left and choose text at top right)
Put in a line of text
Then fill in a commit message and commit on GitLab
Then get into the right directory on your computer and pull to it.
Then write or paste in what you need on local, then push back to GitLab.
Method (b)
Create the files on your computer, then add and stage and commit, then push to GitLab.
Note that Git will ignore new folders in your repository until there are files within them.
5. Things to do on your own computer.
First change directory to the philosophy directory.
To start tracking a file you have added (you need to do this even if you created the file on GitLab then pulled it):
git add filename
To stage all changes (this should also start tracking new files, saving you the trouble of doing git add filename):
git add -A
To commit all changes:
git commit -m “comment needed here”
6. Gitignore
Whenever you compile a PDF in LaTeX, you get loads of extra files that you probably do not want to track. You can list the file types you want Git to ignore (.aux and so on) in a Gitignore file.
To create a local Gitignore file, change directory to your Git repository, then type: touch .gitignore
(You can also create a global Gitignore file to go in your Git configuration.)
Then edit the file in a text editor, just putting in the list of file types you want to ignore, one type on each line.
7. Your remote backup service (copy.com, dropbox, or whatever)
Git generates hidden files, so if you are as nervous about losing material because of inadequate backup as you should be, check that it backs up hidden files as well as non-hidden files.
Whoops, WordPress has tidied up double hyphens into long dashes (just like LaTeX). In my section 1, the long dash before the word “global” (on the user.name and user.email lines) should be typed as two short hyphens with one space before the first one, no space between them, and no space after the second one, not as a long dash.
When I read instructions like that, it confirms my decision not to use Git.
It is all much too complicated.
Hello Prof. Smith,
I’d recommend using git even for a single-author paper. Other VCSes would work too, but git is more used so you’ll more often find help with it. It is also very fast.
There are a lot of advantages of using a VCS over not using it.
– You get a nice way to revert back changes and compare, for instance, different rewrites of the same paragraphs, to chose which one will appear in the final paper, without keeping track of them manually by copying folders. LaTeX also has a nice package that works with git to show differences between two branches directly in the output PDF.
– Even a single author can have the need of working on different computers (a desktop and a laptop for example), and git takes care of always having the most up-to-date source at hand. When I work on the laptop offline during a journey, even without having pulled the last revision, I can reliably continue the work because the merge with the other branch at home will be painless.
– Also, remember that you don’t need an online service to have all these features, because git is decentralized. Any working copy is a full-fledged repository. I don’t have to buy private repos from github or the like, I can put a so-called “bare” repository (a git repository without a checked-out working copy) on a Dropbox folder and use that folder, synchronized between my two computers, as the “remote repository”.
– If you do use systems like github or gitlab, you can get the most out of them even if you work alone. For example, you can use the issue tracking system as an advanced TODO list, tracking things you have still to write or to correct, and automatically closing them by simply mentioning it in a commit message (e.g. if the commit message reads like “Finished the introduction section, closes #2”, issue number #2 will be automatically closed on the github/gitlab interface)
Regarding the “git for philosopher” guide, there exist an introduction to git which is exactly that: Git for Philosophers, that you can read at the following link
https://github.com/rzach/git4phi/blob/master/git4phi.md
Hope I helped a bit.
Nicola
P.S. I loved your notes, especially those about Category Theory and Gödel theorems!
When people who advocate using a VCS compare what happens when you’re not using one to what happens when you are, it often sounds like you have to do something such as “manually copy folders” when you’re not using one, but don’t have to do anything when you are. But if I want to create a ‘branch’ when I’m not using a VCS, I type a command; and if I want to create one when I am using a VCS, I type a command. Much the same goes for comparing different versions, and so on. Without Git, I can still use latexdiff to show differences between two versions in the output PDF.
There are costs to using a VCS; it’s not all benefits. Using something like Git is a lot like using a more complicated file system that works in odd ways (such as whisking files in and out of a directory when you change branches, so that you might need to “stash” things out of the way). There’s extra complication most of the time. There’s also a lot to learn, even if you start simply — and it’s all tedious to learn too, rather than interesting. I’d have to learn enough to be able to understand and recover from any mistakes I made in how I used it, and learn the complicated, poorly designed command-line interface or a GUI that tries to hide the complications. There are things like the “–no-ff” option for merge that I discovered only by chance but which would make a significant difference to me if I used Git. There’s the “.gitignore” file and how to use that. The list goes on an on.
If I’m going to spend the time and effort to learn something, there are many much more interesting things to learn than Git.
Some of the things presented as advantages would even make things worse for me. For instance, in order to use the issue-tracking system as a to-do list, and use commit messages to automatically close issues, it looks like I have to have numbered issues and use numbers to refer to them. That’s not quite as bad as the meaningless unique ids Git generates for commits, but it’s still something I don’t want to do.
I do a lot of writing, both text and software. I use more than one computer. Although I can think of situations where I would find a VCS invaluable, I have never actually been in one. For the things I’ve actually done, I’ve always felt a VCS would be more trouble than it was worth, and those things include moderately large (100s of Java files), small group (2-4 people) software projects.
I have ALL of my work, single- and multi-authored, in git. One too many times going “AUGH WHERE DID THAT PARAGRAPH I KNOW I WROTE LAST WEEK GO???” during the Ph.D. process.
Any recommendation, Sara, for teach-yourself-Git for philosophers/logicians?
Not for Windows or Mac, but if you work on the command line in linux, and use github, there’s basically three things you need to know:
1. How to clone a repo locally:
# git clone git@github.com:DIRECTORY/GITREPONAME.git
2. Git add to add files to be tracked.
3. Always do git pull before git push.
If you aren’t working with multiple authors or multiple branches, most of the other functionality you won’t use.
This tutorial by Richard Zach is very nice:
https://github.com/rzach/git4phi
I have never had the “where did that paragraph go” problem when not using a VCS.
To keep repos private, Bitbucket is a great alternative. For communication, I suggest Slack, which integrate brilliantly and has a mobile app that is a great relief to your email inbox.
No doubt, it’s a good idea to use a version control system, even when not working in a group. But in a certain sense git is a bit over-engineered. I recommend to read
Santiago Perez de Rosso and Daniel Jackson: What’s wrong with git?: a conceptual design analysis, http://dl.acm.org/citation.cfm?doid=2509578.2509584