5 Tips🔗

5.1 Magit🔗

Mindstream sessions are stored as Git repos, so you can use standard Git tools as you might with any repo, including Magit.

Magit is useful to navigate the states in the session and see diffs representing the changes in each state. Of course, Magit can be used for a great many things, and you have that full power available to you to use with Mindstream sessions.

5.2 Git-Timemachine🔗

The git-timemachine Emacs package is a great way to temporally navigate your session. Unlike the usual undo and redo operations which track edits with high granularity, mindstream sessions are bounded by save-buffer invocations which tend to represent natural, distinct stages in your development. Mindstream doesn’t include a built-in way to navigate these states, but you can use the git-timemachine package to do this (in read-only mode).

5.3 Previewing🔗

Quick feedback loops are the engines of creative progress. With this in mind, for whatever you’re writing, it’s valuable to have a way to preview what you’ve produced in output form. For instance, if you’re writing documentation, you should have a keybinding to quickly build the file into HTML or a PDF, or render it within the buffer itself (as LaTeX modes sometimes allow), for you to review as you go. Likewise, if you’re writing code, you should have a way to quickly evaluate the contents of your buffer and see the result.

This tip is not about Mindstream specifically but more about a good workflow to develop with the major mode you’re using. For instance, with Racket Mode, it would be advisable to bind the command racket-run so that you can quickly see the output of your code. This command also saves the buffer so that the session history would represent natural points at which you felt the code was worth trying out. Similarly, if you’re writing Markdown or reStructuredText, you should explore the features provided by the relevant major modes that would allow you to preview the produced documentation in HTML form with the right keybinding incantation.

5.4 Marking Significant Versions🔗

Mindstream sessions can have a lot of commits, and they ensure that you never need to name your document at different stages of development out of fear that you’ll lose important work. But if you happen to be writing a book, say, you might like to mark specific points as being significant in some way, so that if you ever have to search through earlier versions of your work, you’ll know where to look. Traditionally, you might rename your file something like draft_first_revision_final.tex. From Mindstream’s perspective, this a confusion of space and time. We seek to capture a moment in time, but we use a distinct place in space (a new file) for this purpose. In Mindstream, it’d be better to use a standard feature of Git, tagging, to achieve the same result. That is, when you arrive at a version you think is significant, simply tag the current commit (using a Git client of your choice, such as Magit) with a name and a message. It’s a much more useful way to do it than draft_final_final_....tex! For example, it allows you to very quickly switch to different "good" versions (e.g. in Magit, bb and then select a tag in the completion menu) that you could show to editors for proofreading.

5.5 Choosing an Archive Path🔗

Mindstream stores anonymous sessions at mindstream-path (default: ~/mindstream/anon) in a randomly generated folder name filed under the session creation date under the name of the template used to create the session. Sessions that you don’t save are typically archived instead, which moves them to mindstream-archive-path (default: ~/mindstream/archive) following the same organization scheme.

The default value of mindstream-archive-path is a safe and good choice. But you may like to do things differently, and in that case, here are some options to consider.

It’s likely that you will work on dozens, hundreds, or thousands of anonymous sessions over time, of which you will only save a small minority. For the remaining, archived, sessions, though you may not wish to work on them further, they still serve as a detailed and organized log of your thoughts and work over time, and you may occasionally find a need to refer to them. For this reason, the archive is valuable and we recommend preserving this default behavior.

But if you prefer to consider anonymous sessions as ephemeral, to be forgotten if unsaved (perhaps you can only be truly creative if you can scrunch up that session and toss it in the bin so no one ever sees it again!), then you may prefer to delete the archive from time to time. Many operating systems provide standard ways to do this kind of thing – temp folders, usually named tmp – which are occasionally cleared automatically by the operating system, without requiring you to manage this. If your operating system provides a good option here, you may prefer to use it.

5.5.1 /var/tmp🔗

/var/tmp is a standard path on Unix systems for holding temporary files. Unfortunately, there is no accepted convention on its handling. Some systems clear its contents rarely or never, while others clear its contents on every reboot. As a primary use for Mindstream is for you to have a reliable place to capture your thoughts with very low overhead, it’s important that you should feel relatively secure that if your system were to crash, you would still be able to recover any (anonymous) Mindstream sessions you may have been in the middle of.

So if you’d like to use /var/tmp, first check the contents of this folder and refer to the documentation on your particular system to see how it handles this path. If that behavior is predictable enough for you (e.g. say the folder is cleared only on OS upgrades), then you can use it like this:

:custom

...

(mindstream-path "/var/tmp/mindstream")

5.5.2 Home/tmp🔗

Another option that’s similar to this one but more predictable is to define a new path in your home folder for this purpose (say ~/tmp), that you are at liberty to periodically clear yourself, and which you could share across all applications for this purpose. If you go with this option, you can use this path in Mindstream like so:

:custom

...

(mindstream-path

(concat (file-name-as-directory (getenv "HOME"))

"tmp/mindstream"))

Remember that the path we are configuring here is for anonymous sessions only. If you decide to keep a session around and save it via mindstream-save (default binding: C-c , C-s), it would be saved to mindstream-save-session-path which defaults to ~/mindstream/saved. You can customize this as well, of course:

:custom

...

(mindstream-save-session-path

(concat (file-name-as-directory (getenv "HOME"))

"my/mindstream/sessions/path"))

5.6 Organizing Sessions🔗

Anonymous sessions, and consequently archived sessions, are filed under their creation date under the template used to create them, in a folder structure reflecting this scheme.

For sessions saved by you to another location, over time, you may want to rename some of them, delete others, or reorganize them in some way so you can keep track of them more easily. What special features does Mindstream provide for this? None! Remember, Mindstream sessions are just ordinary folders containing ordinary Git repositories. You can use normal Emacs or shell tools to rename, delete, organize them as you see fit, and you would still be able to load them in Mindstream as usual (once you navigate to what may be their new locations).