28

I an academic and I love to do as much of my writing as possible in Emacs. A key thing that is missing for me is the ability to easily review the changes I have made to a text file over time.

The tracking features on Wikipedia articles or Google Documents are both along the lines of what I am looking for. I have played with version control systems like git because they seem to be well supported by Emacs, but I found them difficult to use and far more complex then what I need. Registering repositories, checking in and out, all that was just troublesome.

I don't suppose there are any packages out there that provide the functionality I am looking for in a relatively user-friendly way?

  • 3
    I recommend using git and magit -- github.com/magit/magit -- since you've already played around a little bit with it. You'll probably want to familiarize yourself with the command-line options so you'll have a better understanding of what magit is doing. Emacs is not for non-coders, but you've been around the scene long enough to not be afraid of it -- :) You may also want to try playing with gist: github.com/defunkt/gist.el – lawlist Jan 31 '15 at 6:07
  • Technically, the goal of vc- group of commands is to simplify the process of using VCSs. Unfortunately, they aren't as intuitive as to allow users with no experience to make a good use of them. On the other hand, systems like those you mention are very limiting, so that one quickly develops demands which they can't satisfy. gnu.org/software/emacs/manual/html_node/emacs/… there's a simplistic mechanism of keeping backups, but due to above, I'd rather recommend learning to use some VCS instead. – wvxvw Jan 31 '15 at 8:54
  • 6
    I'm also an academic, and have started using git/magit for version control of my papers. It looks intimidating to start, but a) you don't have to learn it all at once, and b) it's enjoyable to use after getting over the initial learning curve. A good workflow also helps you discipline your writing tasks, as it encourages you to annotate what you're doing -- which is a great way to get a timeline of the evolution of the writing project. – Dan Jan 31 '15 at 12:19
  • What operating system are you on? I used RCS for years, and previously SCCS, but it started to be the case this was no longer bundled with the OS, and have recently switched to git, having had some papers under subversion. The check in process in git has one extra step compared to RCS, but in a number of situations, it is very useful to have sets of files checked in together. – Andrew Swann Jan 31 '15 at 14:29
  • This has been on my mind, and auto-commit may be part of the story: Automatically commit to git after each save projects.ryuslash.org/git-auto-commit-mode – grettke Feb 1 '15 at 0:38
43

The problem with existing version control systems is not so much their complexity; it's the fact that there is such a wealth of information out there that it can be very difficult for beginners to see the forest for the trees (i.e., to figure out what they do and don't need to learn when they are just getting started).

This post is going to focus on git, and describe how to control it from Emacs using an add-on package called magit. Yes, git is complex, but you don't need to learn a lot to use it productively for the purpose you describe.

I'm going to assume that you have git installed (if you don't, get it here), and that you don't want to leave Emacs at all.


Installing magit

magit is a git front-end for Emacs. It is available from MELPA and you can install it via:

M-x package-install RET magit RET

On the off chance that you haven't enabled MELPA in your configuration, you can find instructions on how to do that here.

Setting up a repository

Let's say you have a folder called ~/writing in your home directory that contains one or more documents that you'd like to put under version control.

  1. Open the folder in Dired: C-x d ~/writing RET
  2. Open a shell: M-x shell RET
  3. Type git init and hit RET.

That's it. You now have a git repository. There is no need to "register" it anywhere. git is a distributed version control system; it does not require a remote server to track changes.

Checking the status of your repository

  1. Switch back to the Dired buffer that lists the files in your repository.
  2. Do M-x magit-status RET.

You can think of the buffer that comes up as your "control panel" for working with your repository. For a new repository, it looks something like this:

Magit status buffer for newly created repository

  • You can navigate between different sections of this buffer using n (magit-goto-next-section) and p (magit-goto-previous-section).

  • You can refresh the buffer by pressing g (magit-refresh).

Note that you can bring up the status buffer from any file or directory that belongs to the repository you set up earlier.

Adding files

As you can see in the screenshot, there are three files in the repository that git is not currently tracking. To tell git to start tracking a file, you need to stage it: With point on the file you want to add, press s. The status buffer will then look like this:

Magit status buffer after adding file-1.txt

Committing

After staging one or more files, you can commit them by pressing c c. This will bring up a buffer that looks like this:

Magit buffer for entering commit message

Enter your commit message at the top and then press C-c C-c to finalize the commit. (To abort, press C-c C-k.)

The status buffer will then look like this:

Magit status buffer after first commit

Staging changes

If you make changes to a tracked file, they will be listed in a separate section ("Unstaged changes") in the status buffer:

Unstaged changes (collapsed)

To review the changes that you made to the file, navigate to the line that that says Modified file-1.txt and press TAB:

Unstaged changes (expanded)

To stage these changes, press s:

Magit status buffer after staging changes to tracked file

Viewing past commits

Finally, if you want to review past commits, you can press l l (that's two lower-case L's):

Magit log buffer

As usual, you can navigate the buffer that comes up with n and p. Magit will show the changes associated with individual commits listed in this buffer in a separate window.

Summary

From the shell:

  • git init: Initialize git repository in current directory

From any file or directory associated with a git repository:

  • M-x magit-status RET

From the status buffer:

  • s to add new files or stage changes

  • c c to commit staged changes

    • C-c C-c to finalize commit
    • C-c C-k to abort commit
  • l l to view commit logs

That's it. :)

  • 7
    You don't need to git init from shell. If you call M-x magit-status somewhere outside any git repository it will offer to set up one. (But you will need to call it again to bring up the status buffer after you've finished with the setup). – wvxvw Jan 31 '15 at 10:52
  • You've convinced me it's worth giving version control another try, and this should be a helpful guide. Thanks! – Brian Z Feb 1 '15 at 19:25
  • 1
    So far so good but one frustration is that when I change a few words in a long paragraph, then the whole entire paragraph is highlighted as a staged change. I really want to see changes word by word rather than line by line. – Brian Z Feb 4 '15 at 5:59
  • 3
    @BrianZ You can customize the variable magit-diff-refine-hunk to get the behavior you want. Add (setq magit-diff-refine-hunk t) or (setq magit-diff-refine-hunk 'all) to your init-file. You can do C-h v magit-diff-refine-hunk RET to get more information about what the different settings mean. – itsjeyd Feb 4 '15 at 7:38
  • You will need to experiment with the magit-diff-refine-hunk settings to get closer to what you want. The default settings are great for tracking code changes, but not necessarily brilliant when your wanting to track changes in pros. It may take a bit before you get it quite right, but it should be possible and once you do, I suspect you will never go back! – Tim X Feb 21 '15 at 9:41
11

In addition to magit (as @itsjeyd's answer ably demonstrates), you can also try git-timemachine, which provides facilities for quick cycling through older versions of a file under git version control. According to its github page, the following default keybindings give you a sense of what you can do:

  • p Visit previous historic version
  • n Visit next historic version
  • w Copy the abbreviated hash of the current historic version
  • W Copy the full hash of the current historic version
  • q Exit the time machine.
8

I suspect you'll find Backups Mode and/or Backup Walker very interesting.

Both aim to leverage the existing backup mechanisms in Emacs, and provide better access to and visibility of your file history, without requiring an additional VCS.

6

As was mentioned, a simple way to have different versions of a file is Emacs backup system.

(setq backup-directory-alist '(("." . "~/emacs-backups"))
      version-control 'numbered
      make-backup-files t
      delete-old-versions 'never)

This will use a dedicated directory for numbered backups, which will never automatically deleted. Then you can use C-u C-x C-s to make another version at any time.

Though, I think, there is no easy, ready to use interface for e.g. diffing these versions. So you'd have to manually open one or two of those backups and use ediff-buffers on them and/or the original buffer.

  • 1
    You can diff the backups using, for example: gnu.org/software/emacs/manual/html_node/emacs/… (mark one file with m move point to the other file and press=). – wvxvw Jan 31 '15 at 15:15
  • 2
    This seemed like an attractive option in theory, but it just gives me an overwhelming folder full of random backups. The versions I am interested in are completely buried. Perhaps there is a way to manually trigger a numbered backup of a file, but only when I want it? If I could also attach a brief "commit message" to that backup somehow, then this would be a very nice solution. But for now, I guess I'm stuck learning magit :) – Brian Z Feb 4 '15 at 2:31
2

I've not yet had the opportunity to use this solution, but you may also want to consider Cory Doctorow and Thomas Gideon's flashbake. Here's what Doctorow has to say about it:

I was prompted to do this after discussions with several digital archivists who complained that, prior to the computerized era, writers produced a series complete drafts on the way to publications, complete with erasures, annotations, and so on. These are archival gold, since they illuminate the creative process in a way that often reveals the hidden stories behind the books we care about. By contrast, many writers produce only a single (or a few) digital files that are modified right up to publication time, without any real systematic records of the interim states between the first bit of composition and the final draft.

Enter Flashbake. Every 15 minutes, Flashbake looks at any files that you ask it to check (I have it looking at all my fiction-in-progress, my todo list, my file of useful bits of information, and the completed electronic versions of my recent books), and records any changes made since the last check, annotating them with the current timezone on the system-clock, the weather in that timezone as fetched from Google, and the last three headlines with your by-line under them in your blog’s RSS feed (I’ve been characterizing this as “Where am I, what’s it like there, and what am I thinking about?”). It also records your computer’s uptime. For a future version, I think it’d be fun to have the most recent three songs played by your music player.

That being said, I never had the opportunity to test it out, since I ended up writing a lot of stuff in org-mode, and was programming a lot, and... well... I kind of got better at using magit, and in the end, I kind of just... didn't need to use it.

In any case, this solution was aimed at writers working on non-technical projects. You may find that it may fit your requirements.

1

While it's absolutelly unrelated to emacs, you can still save your text files to Dropbox and if you're a pro user you can use the extended version history. (If you want encrytion, you might want to look at SparkleShare.)

Then there is flashbake which is a bit automated (here is a tutorial).

Also it was asked elsewhere too, for which the answers you might find useful.

  • Flashbake looks very promising. I'll definitely give that a try. – Brian Z Feb 1 '15 at 13:09
-1

You can use Dropbox. It makes revisable version of your file every time you press C-x C-s. For encryption of my text files i use GNU Privacy Guard, it supported by Emacs.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.