Using animated gifs are a lightweight way to show Emacs in action, as can be seen at Emacs Gifs.

I am creating a workshop on developing Clojure with Spacemacs, so here is a little guide as to how I create animated gifs and videos for this workshop directly from Emacs itself using camcorder.el.

There are several different ways to create animated gifs and so far I have found camcorder.el to be the easiest. This approach has been tested on Ubuntu Linux 16.10.

Why an animated gif rather than video?

Being an image format, animated gifs can be used like any other image. So they are easy to include in websites. They will also play continually without any additional code.

Animated gifs are typically smaller in size, so are quicker to download than video and use less resources too.

Some small amount of quality is lost when converting to an animated gif. However, using the optimised and hence slower conversion gives a reasonable quality. I am still experimenting with the setting though to see if I can make the conversion better.

camcorder.el

camcorder.el enables you to create a screen capture specifically of Emacs. When run, a new Emacs frame is created with the contents of the current buffer and your actions in that frame are recorded as a video.

Then camcorder.el can convert the video to an animated gif.

Requirements for camcorder.el

The camcorder.el package itself does not actually do the recording or even the converting, its simply a convienient way to manage other tools without having to leave Emacs.

• recordmydesktop - a linux based video & audio recorder
• mplayer - movie player and converter
• imagemagick - create, edit, compose, or convert bitmap images
• ffmpeg - video conversion tools

For a quick and simple conversion from video to animated gif you can select ffmpeg. If you want to optimise the size of the resulting animated gif then select the combination of mplayer and imagemagick.

1

sudo apt-get install recordmydesktop mplayer imagemagick

Add camcorder to Spacemacs

As far as I am aware there is not yet a Spacemacs layer that includes camcorder.el. So instead we add camcorder.el as an additional package.

Edit your ~/.spacemacs configuration file and find dotspacemacs-additional-packages. Then add camcorder to that list of packages:

1

dotspacemacs-additional-packages '(camcorder)

You will need to either reload your Spacemacs configuration with SPC f e R or restart Emacs.

Capturing with camcorder

Run either camcorder-record or camcorder-mode to record Emacs. You are first prompted to give the file name of the video output (ogv video format).

Once you have specified the video name, a 3 second countdown will run before starting the recording.

Screencasts are generated in ogv format, although if you hack camcorder.el you could change the video format used and even the video capture tool (recordmydesktop).

As capturing creates a video file, you can edit that file with tools such as OpenShot or Blender video editors. So if you make a small error or want to shorten (or lengthen) a part of the video, then edit it before you convert it to gif.

Converting with camcorder

You can convert the videos you generated during capturing, or any other supported video type. So you can also used camcorder.el if you recorded Emacs (or other tools) separately.

Run the M-x camcorder-convert-to-gif and you are prompted for the video file to convert to an animated gif.

Tweaking camcorder.el

I initially made one tweak to camcorder.el, to change the size of the frame created for the capture. I fount the frame too small to work with on a high resolution monitor. The only challenge with this is it creates a larger file for the animated gif.

I changed the height from 20 to 32 and the width from 65 to 120. These sizes provided more space to see the Spacemacs menu as I demonstrate features. When creating screen captures I run my desktop at a resolution of 1360x768 and a Spacemacs font size of 16 (Ubuntu Mono).

1
2
3
4
5
6
7
8

(defcustom frame-parameters
  '((name . "camcorder.el Recording - F12 to Stop - F11 to Pause/Resume")
    (height . 32)
    (width . 120)
    (top .  80))
  "Parameters used on the recording frame.
See `make-frame'."
  :type '(alist :key-type symbol :value-type sexp))

After some testing I have now reverted back to the original height of 20 and width of 32. I have also reduced the font settings in Spacemacs to us Ubuntu Mono with a font size of 12.

In Summary

The package camcorder.el provides a simple 2-step process to create animated gif images of Emacs demos. You can tweak the script easily and can also use different tools to do the screen capture.

Animated gifs are very easy to distribute, especially on web pages and github pages sites. With this process you also have a video version of the demo too.

Keeping your demos short, between 10 and 20 seconds, typically makes the animated gifs easy to follow. So think about what the most important point you are trying to convey when you are creating a new animated gif.

A Kanban board is a way to visualise your work and help you get more work done. You organise your work into tasks that need completeing and use the board to show the state of each card. Kanban encourages you to get work finished before starting new work.

The amazing Emacs Org-mode can be used to create a very fast and easy to use Kanban board that is with you where ever you are.

Update: Using Org-mode doesnt give me everything I want from a Kanban board, but it was an interesting exersice. For now, I am just sticking to my list view of a Kanban board.

Org-mode is built into Emacs / Spacemacs so there is no need to install any packages or layers for any of the following.

Designing a kanban board

The columns on your kanban board represent the state of work and represent your typical workflow. You can represent the states as the most generic todo, doing, done workflow, or anything more specific that adds value to how you manage work.

I have been using kanban for a while, so I am using a five stage workflow: planning, in progress, blocked, review, done

• planning - work I’d like to do that needs organising so I can do it.
• in progress - what I am currently working on. I try and keep this to a minimum so I get things done
• blocked - things I’ve started working on but currently arent able to complete
• review - work I have completed. Check if there are any follow on tasks or lessons learnt
• done - things I have completed. Gives feeling of satisfaction

Creating Org-mode stages

Its easy to create your own Org-mode stages, to represent the state of work in your Kanban board. Please see my earlier article on Configuring Emacs Org-Mode to Managing Your Tasks

Create an Org-mode file

Create a new file by opening a new buffer M-x find-files and type in the new file name, ending in .org. Any files with a .org filename extension will automatically set the Emacs major mode to Org-mode.

I use a file called kanban.org for my kanban board.

Create a kanban board

Lets assume you created a file called kanban.org. Edit this file and create a table for the kanban board. You can start creating ths manually by typing | for the table layout or use M-x org-table-create and enter the number of columns and rows for the table. For example, to create for a table with 5 columns and 3 rows, you would speciify 5x3

Add the names of the kanban board in the first row of the table. If you did not use M-x org-table-create then add a header row with M-x org-table-insert-hline.

In my kanban board, this gives

Adding tasks to the kanban board

Each item on the board represents a task and we use the Org-mode interal link to jump from the board to the details of the task. To create a link of the same name as the task, simply type the name inside double square brakets [[]].

Moving the tasks across the board

Its easy enough to move the columns around with Alt - <arrow-keys> in org-mode, but there is not a single keybinding to move a cell.

To move the individual tasks between the columns use selective cut and paste:

• Move the cursor to the cell you want to move and use C-c C-x C-w
• Use TAB to move to the new cell
• Paste/Yank the value into the new cell using C-c C-x C-y

However, simply moving the task does not update the Org-mode stage. As each task is a link, I can click on that link and I am taken to the task and can easily update the task stage to match the board.

It would be great if moving the tasks on the board updated the associated task stage and vice versa.

El Kanban - updating the board from task stage changes

I found the El Kanban package that will updated the kanban board based on the task org-mode stages. This uses the Org-mode table format directive that you run each time you want to update the board.

I installed this package and it did pull in my custom org-mode stages for the headers. Unfortunately it did not pull in the tasks to the board, so I will either need to fix the package or find another solution.

Any suggestions are more than welcome.

References

• Configuring Emacs Org-mode to manage your tasks
• Emacs Org-mode Kanban pomodoro… oh my… - Posted on August 8, 2011 by Bryan Morris
• El Kanban - an org-mode table that updates based on task stages

Thank you.
@jr0cket

Using yasnippet saves time by avoiding the need to write boilerplate code and minimising other commonly typed content. YASnippet contains mode-specific snippets that expand to anything from a simple text replacement to a code block structure that allows you to skip through parameters and other sections of the code block. See YASnippet in action in this Emacs Yasnippet video.

To use a specific snippet simply type the alias and press M-/. For example, in html-mode typing div and pressing M-/ expands to <div id="▮" class="▯">▯</div> and places the cursor so you can type in the id name, then TAB to the class name, finally TAB to the contents of the div.

You can also combine yasnippets with autocompletion select snippets from the autocompletion menu.

Spacemacs has lots of snippets for most of the languages and modes it supports. However, YASnippets also uses a simple template system in plain text, so its pretty easy to learn. Lets look at how to add your own snippets with Spacemacs.

In regular Emacs, yasnippets expand funciton is usually bound to TAB, but that key is used already in Spacemacs so M-/ is used instead.
If you just want text replacement you can also use Emacs Abbrev mode.

Adding your private snippets to Spacemacs

The easiest place to add your own snippet definitions is in the ~/.emacs.d/private/snippets directory. Under this directory structure you should create a folder named after the relevant mode for your snippets, eg markdown-mode. Inside this mode folder, create files whos names are based on the snippet alias you wish.

So for a work in progress snipped called wip in markdown mode I created ~/.emacs.d/private/snippets/markdown-mode/wip file.

You need to load this new snippet into Spacemacs by either restarting or using the command M-x yas-load-snippet-buffer command in the buffer of the new snippet you have just written. Ths snippet with then work within any markdown mode buffer.

Managing your snippets

Although the private snippets directory is easy to use, it is not under version control. So although its not over-riddend by Spacemacs it also means your private snippets are not backed up anywhere.

If you use the ~/.spacemacs.d/snippets/modename-mode/ directory structure for your snippets then you can version them with Git or similar versioning tools.

How to write a snippet

Typically each snippet template is contained in its own file, named after the alias of the snippet. So a snippet called wip will be in a filename wip, in a directory named after the relevant Emacs mode.

The basic structure of a snippet template is:

1
2
3
4
5

#key : the name of the snippet you type
#name : A description of the snippet (this shows in autocompletion menu too)
#contributor: John Stevenson <john@jr0cket.co.uk>
# --
Add the content you want to replace the snippet name with when it expands

The content can be anything, simple text or more usefully a code strucuture with placeholders for tab stops. You can even include Emacs lisp (elisp) code in there too.

Example: Simple text replacement

I use markdown mode for writing a lot of content, especially for technical workshops. As I am developing these workshops its useful to highlight which sections are still work in progress. Rather than type the common message I use, I’ve created a simple snippet called wip.

1
2
3
4
5

#key : wip
#name : WorkInProgress
#contributor: John Stevenson <john@jr0cket.co.uk>
# --
> **Fixme** work in progress

When you expand this snippet with M-/ then the snippet name is replaced by the content.

Example: Using tab stops

Lets look at an existing snippet called form in the html-mode. This expands into a html form, but also helps you jump from method, id, action and content.

1
2
3
4
5
6

#contributor : Jimmy Wu <frozenthrone88@gmail.com>
#name :<form method="..." id="..." action="..."></form>
# --
<form method="$1" id="$2" action="$3">
  $0
</form>

This snippet is the same as the simpler example, except we have added tab stops using the $ sign and a number. When you expand this snippet, the snippet name is replaced by the content as usual but the cursor is placed at the first tab stop $1. Each time you press TAB you move to the next tab stop.

$0 is our exit point from the snippet, so pressing TAB reverts to the usual behaviour outside of YASnippet.

Creating a snippet from existing text

A really fast way of creating a new snippet is to use a finished version of what you would like the snippet to expand to. For a simple text replacement you just hightlight all the text and call helm-yas-create-snippet-on-region, save the snippet and you are done.

For a code structure with tab stops, simply hightlhght a completed code stucture, call helm-yas-create-snippet-on-region and edit the body of your snippet to replace the specific names and values with tab stop placeholders, $1 $2, $3, etc.

Example: Create a simple text replacement

When I write blogs I include a image thumbnail that gives a visual clue as to the topic of the article. Rather than type this in I created a snippet.

First I mark the text I want my new snippet to expand too, in this example: {% img img-thumbnail /images/spacemacs.png %} .

Then I call the function helm-yas-create-snippet-on-region. This prompts me for the mode for the snippet, in this case markdown-mode, then prompts for the location for the snippet file, ~/.emacs/private/snippets/markdown-mode/imgtmb-spacemacs. A new buffer is created with my snippet already filled in.

1
2
3
4
5
6

# -*- mode: snippet -*-
#name : imgtmb-spacemacs
#key : imgtmb-spacemacs
#contributor : jr0cket
# --
{% img img-thumbnail /images/spacemacs.png %}

The new snippet buffer already has the name and key values populated from the filename I gave for the snippet, imgtmb-spacemacs. The snippet body is also populated automatically from the text I had highlighted. So all I need to do is save the new snippet and try it out.

Testing your snippets

Once you have written your snippet, you can quickly test it using M-x yas-tryout-snippet. This opens a new empty buffer in the appropriate major mode and inserts the snippet so you can then test it with M-/.

If you just want to try the snippet in an existing buffer, then use M-x yas-load-snippet-buffer to load this new snippet into the correct mode. M-x yas-load-snippet-buffer does exactly the same except it kills the snippet buffer (prompting to save first if neccessary).

There are no default keybindings for these commands in Spacemacs, so you could create a binding under C-o, for example C-o C-s t to try a snippet and C-o C-s l to load a snippet.

Adding yas-snippets to autocompletion in Spacemacs

By adding the autocompletion layer in Spacemacs the YASnippets can be shown in the autocompletion menu as you type.

By default, snippets are not shown in the auto-completion popup, so set the variable auto-completion-enable-snippets-in-popup to t.

1
2
3

(setq-default dotspacemacs-configuration-layers
              '((auto-completion :variables
                                 auto-completion-enable-snippets-in-popup t)))

Summary

Find out more about YASnippets and autocompletion from the Github repository for Spacemacs autocompletion layer.

For more details and examples on writing your own snipplets, take a look at:

• Emacs YASnippet video tutorial
• Snippet development.
• Adding YASnippets snippets
• Snippet expansion with YASnippet

Thank you.
@jr0cket

Github Gists are really useful when you want to share a piece of code or configuration without setting up a version control project. Rather than copy & paste into a Github Gists website, you can create a Gist from any Spacemacs buffer with a single command.

All you need is to add the github layer to your ~/.spacemacs configuration file and reload your configuration M-m f e R or restart Spacemacs. Lets see just how easy it is to use Gists with Spacemacs.

You can also use gist.el with your own Emacs configuration

Connecting to your Github account

When you first run any of the Gist or Github commands you will be prompted for your username, password and 2Factor code. The Gist.el code will create a personal access token on your Github account, avoiding the need to prompt for your Github login details each time.

If you are prompted to enter your personal access token in Emacs, then visit your Github profile page and view the personal acccess tokens section. Edit the token named git.el and regenerated the token. This will take you back to the personal access tokens page and display the new token for git.el. Copy this token into the [github] section of your ~/.gitconfig as follows

1
2
3

[github]
	user = jr0cket
	oauth-token = thisishweretherealtokenshouldbepasted

If git.el adds a password line to the [github] section of your ~/.gitconfig you should remove that password line. These Github actions only require your username and token.

Creating a Gist from Spacemacs

The current buffer can be copied into a Github Gist using the command M-x gist-buffer.

You can also create a gist just from a selected region of the buffer. First select the region using C-SPC and run the command M-x gist-region.

If this is the first time using Github from Spacemacs, you will be prompted for your Github username & password. If you have already used Github from Spacemacs, then your account details will have been saved so you do not need to enter them each time.

Keyboard shortcuts

• M-m g g b : create a public gist from the current Spacemacs buffer
• M-m g g B : create a private gist from the current Spacemacs buffer
• M-m g g r : create a public gist from the highlighted region
• M-m g g R : create a private gist from the highlighted region
• M-m g g l : list all gists on your github account

Replace M-m with SPC if you are using Spacemacs evil mode

Updating a Gist

When you create a Gist from a buffer there is no direct link between your buffer and the Gist. So if you make changes to your buffer you want to share, you can generate a new gist using M-x gist-buffer & delete the original one (see listing & managing gists below).

Alternatively, once you have created a Gist, you can open that Gist in a buffer and make changes. When you save your changes in the Gist buffer, C-x C-s, the gist on gist.github.com is updated.

Listing & managing Gists

Use the command M-x gist-list or keybinding M-m g g l to show a list of your current Gists.

In the buffer containing the list of your gists, you can use the following commands

• RETURN : opens the gist in a new buffer
• g : reload the gist list from server
• e : edit the gist description, so you know what this gist is about
• k : delete current gist
• b : opens the gist in the current web browser
• y : show current gist url & copies it into the clipboard
• * : star gist (stars do not show in gist list, only when browsing them on github)
• ^ : unstar gist
• f : fork gist - create a copy of your gist on gist.github.com
• + : add a file to the current gist, creating an additional snippet on the gist
• - : remove a file from the current gist

Creating Gists from files

If you open a dired buffer you can make gists from marked files, m, by pressing @. This will make a public gist out of marked files (or if you use with a prefix, it will make private gists)

Summary

Its really easy to share code and configuration with Github Gists. Its even easier when you use Spacemacs) to create and manages gists for you. Have fun sharing your code & configurations with others via gists.

Thank you.
@jr0cket

Adding the Clojure layer to Spacemacs provides great support for the language via CIDER, Clojure-mode, clj-refactor and lots of useful tools.

The Clojure layer also adds to the auto-completion layer, providing matches for anything currently defined in the current namespace. The yasnippets package also allows you to expand shortcuts for common Clojure code structures, eg. def, defn, let, require.

Adding Clojure support

Clojure support in Spacemacs is configured by adding the clojure layer. Edit ./spacemacs and add clojure to the list of layers defined in dotspacemacs-configuration-layers` function

1

(dotspacemacs-configuration-layers '(clojure)

For an example, see my spacemacs configuration on github. Please note that there are more configuration options added to this file than required for Clojure, only add the ones you understand.

Restarting Emacs will download by the related packages for Clojure.

You can also use SPC f e R (evil mode) or M-m f e R (holy mode) to reload the Spacemacs configuration and download packages, however for a big layer I have found a restart of Emacs is needed to load in all the new configuration.

Configure Pretty symbols

You can configure the Clojure layer to use pretty symbols to represent a few things in Clojure, such as:

1
2
3
4

(λ [a](+ a 5)) ;; anonymous function (fn ...)
ƒ(+ % 5)       ;; anonymous function shorthand #(...)
∈{2 4 6}       ;; set #{...}
Ƥ              ;; partial function (partial ...)

To enable this feature, edit the ./spacemacs file and add the following snippet to the dotspacemacs/user-config function:

1

(setq clojure-enable-fancify-symbols t)

Configure Leiningen

Install Leiningen using the instructions on Leiningen.org, or if you already have Leiningen installed then check you have the latest version via lein upgrade

Leiningen should be version 2.6.x or greater as of 22nd February 2015

If you are using CIDER 0.11 or greater then you are done, as from this version the Leiningen dependencies are automatically injected when you start cider-jack-in.

Only for CIDER 0.10 or earlier

Edit the Leiningen profile configuration for your useer, eg. ~/.lein/profiles.clj and add the following plugins and dependencies:

1
2
3
4

{:user {:plugins      [[cider/cider-nrepl "0.11.0-SNAPSHOT"]
                       [refactor-nrepl "2.0.0-SNAPSHOT"]]
        :dependencies [[alembic "0.3.2"]
                       [org.clojure/tools.nrepl "0.2.12"]]}}

Plugin versions are the latest as of 28th December 2015.
You can also check for the latest versions of cider-nrepl, refactor-nrepl, alembic & tools.nrepl

The cider-nrepl plugin should match the version of CIDER used in Spacemacs, found by using M-x cider-version. You will see a warning message in the REPL buffer if the versions do not match, for example:

Summary

Now you have the Clojure layer and Leiningen configured so you can create your Clojure apps with ease. Next time we will show how to use the REPL to evaluate code, giving you almost instant feedback on what you have created.

Thank you
jr0cket

Spacemacs is a community developed configuration for Emacs that makes it easier for anyone to use this amazing developer tool. Spacemacs is a well thought out way to apply the vast and diverse power of Emacs, making it more accessible especially to those who are used to using Vi.

Unless you’ve spent the last few years hand-crafting your own Emacs configuration, then I think you will enjoy Spacemacs. Here are some reasons why I love Spacemacs as an Emacs user.

Spacemacs is fast

The startup for Spacemacs is really quick, less than 2 seconds, even after adding a whole host of features (layers). Some of this speed may be due to the lazy loading approach that Spacemacs takes. In the best tradition of Lisp, some things are only loaded in Spacemacs when they are first used. For example, when you open a Clojure source code file for the first time, the Clojure layer is loaded and clojure mode is applied.

Goodbye init.el, hello dotspacemacs

The init.el file has long been the entry point for your Emacs configuration with many different ways to setup an Emacs configuration. With Spacemacs you have the .spacemacs file and layers, giving a very structured approach that is easy to follow.

The .spacemacs file has three sections

• dotspacemacs/init - configuration applied when Spacemacs first starts, eg evil or holy mode(emacs), themes, fonts, full screen, recent files, etc
• dotspacemacs/layers - add features to spacemacs using layers, a layer can contain elisp and packages from Melpa/Elpa
• dotspacemacs/config - additional layer configuration or your own customisations

The (emacs) keybindings for dotspacemacs are

M-m f e d - open the ~/.spacemacs file
M-m f e R - reload the configuration from ~/.spacemacs

Some changes in the ~/.spacemacs file still require a restart of Emacs , especially when pulling in a large number of packages in a layer.

Navigating with Helm

Developers drive Emacs with keybindings or use commands via M-x. The more features you add to Emacs, the more keybindings and commands you have at your fingertips. So to manage all this power, Spacemacs uses Helm to organise these keybindings & commands into groups. Helm also helps you navigate the file system too, minimising the need to type directory and file names in full.

Commands are grouped by their nemonic character, for example

• S - spelling
• T - themes
• a - applications
• b - buffers
• f - files
• g - git/version control

Helm is an incremental completion and selection
narrowing framework. Its the central control tower of Spacemacs, it is used to manage buffers, projects, search results, configuration layers, toggles and more.

Once you have learnt the Spacemacs groupings for Helm its really fast to do anything, so take a look at the Helm documentation wiki.

You can still type in command names using M-x command-name too, if you know the name of the command you are looking for.

ido mode is still available in Spacemacs but by default it is over-ridden by Helm. You can enable ido using dotspacemacs-use-ido t in the dotspacemacs/init section of .spacemacs, however this only replaces a few commands.

Other features of Spacemacs

• numbered buffers - each buffer gets a number in the status bar, allowing you to jump to any buffer using the M-m or SPC and the buffer number, eg. M-n 3 jumps to buffer number 3.

• smartparens and symbol balancing/highlighting - speeding up typing and reducing errors due to unmatched symbols. For most symbols in most modes a matching symbol is created. So if you type ( then a matching ) is created too. If you want to surround some existing text with a symbol pair, then simply highlight the text and press the opening symbol. A closing symbol is also highlighted when the cursor is at the opening symbol. Spacemacs also highlights the surrounding symbols, including any parents. So if you are in a nested list, (parent code (nested code)), then if the cursor is on the nested code, both nested & parent symbols are highlighted.

• smooth scrolling - unlike the traditional jump-scrolling of Emacs, Spacemacs uses smooth scrolling as you fing in most other text editors.

Getting started with Spacemacs

Here are a few basic steps I took when starting Spacemacs

Installing & develop branch

With Emacs 24 installed I simply clone the Spacemacs configuration (first moving any existing Emacs configuration out of the way)

1

git clone --recursive https://github.com/syl20bnr/spacemacs ~/.emacs.d

Before running Emacs I switched to the develop branch so I would have all the latest additions to Spacemacs (it seems pretty stable so far)

1

git checkout develop

Then I just ran Emacs as normal and saw Spacemacs taking shape. There were a number of Emacs packages to download, so this bit took about a minute.

Holy mode

I’ve been using Emacs for several years as my main browser so am very familiar with the Emacs bindings. So when first starting Spacemacs I naturally chose the holy mode (aka Emacs mode)

Adding layers

Spacemacs has only a few layers by default so I added auto-completion, clojure, git, html, javascript, markdown, org-mode, syntax-checking and version control to the dotspacemacs/layers function in ~/.spacemacs

After saving the changes to ~/.spacemacs the configuration was reloaded with M-m f e R. As I installed a lot of packages, I also restarted Emacs once everything had finished.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

dotspacemacs-configuration-layers
'(
  ;; ----------------------------------------------------------------
  ;; Example of useful layers you may want to use right away.
  ;; Uncomment some layer names and press <SPC f e R> (Vim style) or
  ;; <M-m f e R> (Emacs style) to install them.
  ;; ----------------------------------------------------------------
  auto-completion
  better-defaults
  clojure
  emacs-lisp
  git
  html
  javascript
  markdown
  org
  syntax-checking
  version-control
  )

Using Helm is an easy way to see what layers are already available in Spacemacs, using the keyboard combo M-m f e h. This gives you a list of all layers and if you hit return on any of the layer names you are taken to the docs for that layer.

You can also create your own layers with M-m configuration-layer/create-layer. See http://thume.ca/howto/2015/03/07/configuring-spacemacs-a-tutorial/ for more info as well as the Spacemacs docs.

Changing font size

I set the default font to Ubuntu 16, the smallest usable font for my laptop for my own use.

1
2
3
4
5

dotspacemacs-default-font '("Ubuntu Mono"
                            :size 16
                            :weight normal
                            :width normal
                            :powerline-scale 1.1)

I often share my laptop with others or give a presentation using Emacs. So I’ve added two keyboard bindings I commonly used to increase & decrease the font size in the current buffer. This was added to the dotspacemacs/config function in ~/.spacemacs

1
2

(define-key global-map (kbd "C-+") 'text-scale-increase)
(define-key global-map (kbd "C--") 'text-scale-decrease)

Fullscreen at startup

I like to see Emacs in full screen mode for minimum distraction, so I changed the following option in the dotspacemacs/init function of ~/.spacemacs

1

dotspacemacs-fullscreen-at-startup t

In Summary

I really like the way Spacemacs is organised and have not felt the need to change anything, other than adding a few keybindings. Its obvious right from the start that Spacemacs has been well thought out. There is also a great community behind Spacemacs and there is always plenty of help.

There is still a lot to learn to get the most out of Spacemacs, but after a day I am pretty comfortable and productive. The biggest thing to try is probably the modal editing approach you get with Vi and other eVIl features of Spacemacs. This could make development with Emacs even faster.

It is well worth reading the Spacemacs guide, which I found easy to follow.

Thank you.

jr0cket

An effective way to have a clean and valuable commit history is to create the smallest valuable commit each time, with a descriptive commit message. This sounds obvious, but when you are in the midst of work things can get messy. Using Emacs Magit you can be highly selective as to what changes you include in each commit, down to individual characters.

This follows on from staging patches for cleaner commits with the command line, git add -p. Also see how to drive Git with Emacs and Magit for more background.

Emacs Magit

Magit is an amazing tool for managing Git repositories, providing all the standard features of a graphical tool. It is part of the Emacs Live and available via the useual Emacs package managers.

To run magit, I typically open a file under version control and hit C-x g or M-x magit-status.

Magit keeps track of the changes in your project and the status can be updated using g in the magit buffer.

To stage all the changes in a file you can move the cursor to the unstaged file you want to add and press s, or stage all changes using S.

To unstage a file, again move the cursor against its name and press u or unstage all files added using U.

Selective commits using hunks

Its easy to be more selective than just staging everything in a file. Move the cursor against the filename and press tab to show the hunks within a file.

A hunk is the name Git gives to continuous lines that contain changes in a file. So if all your changes are made line after line, there will be one hunk. If you have unchanged lines between the lines you have changed, you will have more than one hunk.

Move the cusor to the hunk you want to add and pres s to stage that hunk. Using n & p to move to the next or previous hunks if they exist.

Sometimes Git organised the changed lines into hunks that have too many changes in, or to few changes. You can change hunk sizes using + or - to expand or shrink the hunk (shrinking is essentially splitting a hunk where possible).

It may not always be possible to split a hunk enough for your commit.

Selective commits using regions

If you really need to refine what you are committing, you can select a region to stage by selecting characters and lines.

Open a file that has unstaged changes using tab

Select a region of the text using C-SPC or C-@

Hit s to stage the selected region

Make sure you have not shrunk any hunks, or the region selection may not work.

You can check the correct text has been added by viewing the newly added entry in Staged changes section.

Summary

So Emacs Magit give a really easy way to stage changes in the size of commit that is most valuable. So take a few seconds longer to think about what you are committing and how useful it will be to others and yourself during the life of the project.

You dont want to be spending too much time unpicking commits to find a bug and applying a patch.

Thank you.
@jr0cket

Continuing my modeline customisation with powerline, I wanted to add colour to match the Cyberpunk theme of Emacs Live. To do this I copied the default them and custmised it, adding colours and chaning the style of seperatr. Here is how I customised the powerline code to make my own theme.

See how I previously tweaked Emacs modeline with powerline, as this article carries on from that. My modeline also includes an earlier tweak for the minor modes.

Modeline seperators as waves

Although the arrows are nice way to seperate the different parts of the modeline, I tried out the different styles. My favorite was the wave style.

To change the style, I edited the lib/powerline.el file and change the powerline-default-separator to the value to wave. The choice list shows you all the styles of seperator available.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

(defcustom powerline-default-separator 'wave
  "The separator to use for the default theme.
  :group 'powerline
  :type '(choice (const alternate)
                 (const arrow)
                 (const arrow-fade)
                 (const bar)
                 (const box)
                 (const brace)
                 (const butt)
                 (const chamfer)
                 (const contour)
                 (const curve)
                 (const rounded)
                 (const roundstub)
                 (const slant)
                 (const wave)
                 (const zigzag)
                 (const nil)))

I restarted Emacs each time I changed the seperator style for it to take effect. I am not sure how to update the style without a restart.

Creating my own theme for Emacs Powerline

I wanted to change the colours of the modeline to make it more personal to me and also help it stand out between all the text of the buffers.

Rather than mess up the default theme I simply edited the lib/powerline/powerline-theme.el file and copied the default theme completely, called the new theme powerline-default-theme. This allowed me to experiment whilst still having a working reference theme to fall back on.

To use my new theme, I edited the configuration file ~/.live-packs/jr0cket-pack/config/powerline.el and changed the line defining the theme

1
2

(require 'powerline)
(powerline-jr0cket-theme)

Removing modeline information I’m not interested in

There are some of the elements I was not interested in, such as the size of buffer and mule-info. So I edited my jr0cket theme and removed the lines

1
2

(powerline-buffer-size nil 'l) 
(powerline-raw mode-line-mule-info nil 'l)

Removing extra spacing

The default theme adds padding between some elements by adding a space character.

1

(powerline-raw " ")

There was aso padding around some elements on the modeline, specifically the line l & column c numbers and the percentage of buffer above the currently visible text p. The default theme adds numbers in front of these caracters adds padding, which I didnt feel was needed so I deleted those numbers.

1
2
3

(powerline-raw "%l" face1 'l)
(powerline-raw "%c" face1 'r)
(powerline-raw "%p" nil 'r)

Changing Colours in the modeline**

The powerline default theme is very grey, so I wanted to add some colours that would work with the Emacs Live Cyberpunk theme. Changing colours is done in the lib/powerline/powerline.el file.

I changed the text colour using :foreground, the background colour with :backgroundand made the text bold using :weight bold.

1
2
3
4
5
6
7

(defface powerline-active1 '((t (:foreground "#d0d0f0" :background "purple" :inherit mode-line)))
  "Powerline face 1."
  :group 'powerline)

(defface powerline-active2 '((t (:foreground "#63b132" :weight bold :background "black" :inherit mode-line)))
  "Powerline face 2."
  :group 'powerline)

Adding an extra face for the buffer name

The defalt powerline theme has two faces (styles) for inactive and active windows - powerline-active1, powerline-active2, powerline-inactive1 & powerline-inactive2 Different parts of the modeline are assigned to one of the faces and therefore display in different styles. There are a few parts of the modeline, like the buffer name, that are not assinged to a face and display in the colour of the Emacs theme (Emacs Live)

I wanted to change the style of the buffer name, so rather than change the Emacs theme I added a third face to the lib/powerline/powerline-theme.el.

1
2
3
4
5
6
7
8

(defface powerline-active0 '((t (:foreground "deep pink" :weight bold :background "black" :inherit mode-line)))
  "Powerline face 0."
  :group 'powerline)

(defface powerline-inactive0
  '((t (:background "black" :weight bold :inherit mode-line-inactive)))
  "Powerline face 0."
  :group 'powerline)

I then tried out different colours for the buffer name and settled on the reverse of face0, so updated the lib/powerline/powerline.el file by adding an active0 and inactive0 configuration as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

(defface powerline-active0 '((t (:foreground "purple" :weight bold :background "#d0d0f0" :inherit mode-line)))
  "Powerline face 0."
  :group 'powerline)

(defface powerline-inactive0
  '((t (:background "black" :weight bold :inherit mode-line-inactive)))
  "Powerline face 0."
  :group 'powerline)

``` 
  The final active modeline with my theme and colours applied looks very nice and very useful to me

![Emacs - Powerline jr0cket theme fullscreen](/images/emacs-emacs-live-powerline-theme-jr0cket-modeline.png)

  Here is the overal view of Emacs with the jr0cket theme and colours applied.

![Emacs - Powerline jr0cket theme fullscreen](/images/emacs-emacs-live-powerline-theme-jr0cket-fullscreen.png)


## Final version of the jr0cket powerline theme

  Here is the complete code for the `powerline-jr0cket-theme`

``` elisp 
    (defun powerline-jr0cket-theme ()
      "Customisation of the default powerline theme"
      (interactive)
      (setq-default mode-line-format
        '("%e"
          (:eval
           (let* (
             (active (powerline-selected-window-active))
             (mode-line (if active 'mode-line 'mode-line-inactive))
             (face0 (if active 'powerline-active0 'powerline-inactive0))
             (face1 (if active 'powerline-active1 'powerline-inactive1))
             (face2 (if active 'powerline-active2 'powerline-inactive2))
             (separator-left
              (intern
               (format "powerline-%s-%s"
                       powerline-default-separator
                       (car powerline-default-separator-dir))))
             (separator-right
              (intern (format "powerline-%s-%s"
                              powerline-default-separator
                              (cdr powerline-default-separator-dir))))
             (lhs (list (powerline-raw "%*" face0 'l)
                        (powerline-buffer-id face0 'l)
                        (when (and (boundp 'which-func-mode) which-func-mode)
                          (powerline-raw which-func-format face0 'l))
                        (powerline-narrow face0 'l)
                        (funcall separator-left face0 face1)
                        (when (boundp 'erc-modified-channels-object)
                          (powerline-raw erc-modified-channels-object face1 'l))
                            (powerline-major-mode face1 'l)
                            (powerline-process face1)
                            (powerline-raw " " face1 'r)
                            (powerline-minor-modes face1 'l)
                            (powerline-narrow face1)
                            (funcall separator-left face1 face2)
                            (powerline-vc face2 'r)))
             (rhs (list (powerline-raw global-mode-string face2 'r)
                        (funcall separator-right face2 face1)
                        (powerline-raw "%l" face1)
                        (powerline-raw ":" face1)
                        (powerline-raw "%c" face1)
                        (funcall separator-right face1 face0)
                        (powerline-raw "%p" face0)
                        (powerline-hud face2 face1))))
             (concat (powerline-render lhs)
                     (powerline-fill face2 (powerline-width rhs))
                     (powerline-render rhs)))))))

Summary

Powerline is a really nice way to add that extra touch to the Emacs experience. Its also pretty easy to configure to give you your own personalised look to the Emacs modeline. Let me know if you have any interesting customisations to your Emacs setup.

Thank you.
@jr0cket

It important to enjoy the development tools you use day after day, so after seeing some of the great looking Emacs modeline customisations, I couldnt resist pimping my modeline (again).

Previously I tweaked the modeline for Clojure development, this time I’ve added styling to the modeline using powerline. I aim to create a modeline worthy of the rest of the Emacs Live experience.

There are several other versions of powerline listed on the EmacsWiki powerline page.

Installing powerline

I use Emacs Live as my base configuration for Emacs, so I added the powerline project to my personal configuration ~/.live-packs/jr0cket-pack/

First I cloned the powerline Gitub repository into the lib folder of my live pack

1
2

cd ~/.live-packs/jr0cket-pack/lib
git clone https://github.com/milkypostman/powerline

Then I created a configuration file for the powerline project

1

emacslcient ~/.live-packs/jr0cket-pack/config/powerline.el &

Adding the following code to the powerline config file loads the files in lib/powerline. I also state which theme I want to use.

1
2

(require 'powerline)
(powerline-default-theme)

There are several other themes avaiable in powerline, including (powerline-center-theme) and (powerline-nano-theme)

Finally, I added a function to load the powerline library at startup in my Emacs Live live-pack init.el file, ~/.live-packs/jr0cket-pack/init.el

1

(live-load-config-file "powerline.el")

I restarted Emacs and was presented with my new modeline

In full screen with several windows open you can see the difference between active and inactive windows.

Summary

The powerline project is an easy way to tweak your modeline into something more stylised. Next I want to create my own powerline theme to have my own design touches and tailor it more to my needs.

Thank you.
@jr0cket

CIDER is the Clojure IDE and REPL for Emacs. It is built on top of nREPL, the Clojure networked REPL server and replaces the direct use of nREPL in Emacs.

In this article we are using CIDER that is packaged in Emacs Live, a very complete, well organised and extensible configuration for Clojure and many other things in Emacs.

CIDER includes the standard interactive code evaluation developers are used to. There are also many other features that I want to explore further, including error and warning highlighting, human-friendly stacktraces, smart code completion, definition & documentation lookup, value inspector & function tracing, interactive macroexpansion, Grimoire integration, clojure.test integration, classpath browser, namespace browser, nREPL session management, scratchpad, minibuffer code evaluation, integration with company-mode and auto-complete-mode

Emacs Live

CIDER is now the default in the latest version of Emacs Live, so there no set up to do if you already have the latest version. If you need to update, or are not sure you are on the latest version of Emacs live, simply run a git pull from within ~/.emacs.d directory:

git pull origin master

If you dont have Emacs Live, you can install it from the Emacs Live Github repository and either clone the repository into ~/.emacs.d (moving or deleting any existing directory) or preferably use the install script that also sets up a ~/.live-packs extension directory.

1
2
3
4
5
6
7
8
9
10
11
12

    bash <(curl -fksSL https://raw.github.com/overtone/emacs-live/master/installer/install-emacs-live.sh)
```  

## Leiningen configuration

  CIDER requires the use of [nREPL middleware](https://github.com/clojure-emacs/cider-nrepl) between Emacs and Leiningen.  For example, when you run CIDER `M-x cider-jack-in` in Emacs it calls Leiningen to start the REPL.  So you need to add a plugin to your Leiningen configuration.
  
  Edit the `~/.lein/plugings.clj` file (or create this file if it does not exist yet) and add the `[cider/cider-nrepl "0.8.1"]` plugin.  The `~/.lein/plugings.clj` should look similar to this:
  
```clojure
    {:user {:plugins [[lein-pprint "1.1.1"]
                      [cider/cider-nrepl "0.8.1"]]}}

You can find the available versions of the cider-nrepl plugin on Clojars.org. The plugin version should be the same version of CIDER you are using in your Emacs configuration, which at the time of writing was 0.8.1.

Running CIDER in Emacs

Either create a new Clojure project using lein new my-project-name or open an existing project in Emacs (either the project.clj file or a .clj file from src/my-project-name/).

With your cursor in the Clojure file buffer, run CIDER using the keybinding C-c M-j or the emacs command

M-x cider-jack-in

Alternatively, you could run a REPL using lein repl on the command line and connect to that REPL using C-c M-c or M-x cider. You will be prompted for the connection details of the running repl, ie. host, port.

Using CIDER in Emacs

There are a number of Cider keyboard shortcuts (keybindings) already defined, here are some of the most common ones I use:

• C-c C-e - evaluates the form immediately before the cursor and shows the result in the minibuffer. So place your cursor right after the closing parentheses ) of your expression, hit the keybinding and see the minibuffer for the result.

• C-c M-e - the same as above except the result is sent to the REPL

• C-c C-k - evaluate the whole buffer. So with the cursor in a Clojure source file, all the forms / expressions are evaluate as if the code was loaded in from scratch.

• C-c C-d d - show the documentaion as you would with (doc function-name). Place the cursor over a function name, hit the keybinding and see the documenation for that funtion. This also works inside the REPL buffer, so no need to use (doc), which is not loaded by default.

• C-c M-n - switch to namespace of current Clojure buffer. So with the cursor in a Clojure source file, hit the keybinding and your REPL buffer will now be in the namespace for that Clojure code.

Changing into a namespace does not automatically evaluate the code in that namespace, so evaluate the whole buffer C-c C-k or evaluate specific expressions (forms) C-c M-e. Once evaluated, you can evaluate that code in the REPL.

• M-> or M-x cider-jump-to-var prompts you for a var, a function (defn) or symbol name (def) and moves the cursor to its definition. If the cusor is already on a matching name the the cursor jumps straight to that definition.

• C-c C-q or M-x cider-quit - close the REPL and its associated buffer.

  There are many more things you can do within Clojure files and the REPL, so take a look at the Cider keyboard shortcuts (keybindings) once you have the basics mastered.

Further reading

Some further reading around CIDER:

• Cider keyboard shortcuts (keybindings)

• Clojure on Emacs - A CIDER workflow hack - Kris Jenkins

  Have fun and be productive with CIDER, Emacs and Clojure. If you have any other suggestions on getting them most out of these tools, please let me know.

Thank you.
@jr0cket

Once you have more buffers (files) open than windows in Emacs, then having a quick way to cycle through buffers is invaluable. Even with 4 windows open, I still find myself using IBuffer, C-c C-x, many times.

Sometimes I just want to switch between the current and previous buffer in the same window. So this is how I tweaked my Emacs configuration (based on Emacs Live) to cycle through buffers.

Cycling through buffers

Emacs has two functions to move through buffers in the current window, next-buffer and previous-buffer. These can be called in the usual way using Meta-x:

M-x next-buffer
M-x previous-buffer

Using these functions is quick than firing up an IBuffer, however if we create some good keybindings then we can cycle buffers even faster.

Creating keybindings

I already have several keybindings defined in my Emacs Live personal pack, so I simply add two more keybindings. The file I put my keybindings in is called ~/.live-packs/jr0cket-pack/config/keybindings.el and these bindings are loaded by adding the following line to ~/.live-packs/jr0cket-pack/init.el

(live-load-config-file "keybindings.el")

The key combination I decided to use was Ctrl - PageUp for previous button and Ctrl - PageDown for the next buffer.

;; Set keybindings for cycling buffers
(global-set-key [C-prior] 'previous-buffer)
(global-set-key [C-next] 'next-buffer)

The PageUp key is referenced by the name prior and the PageDown key is referenced by the name next.

Thank you.
@jr0cket

Emacs is a tool that just keeps on giving and Org-mode is a fantantastic way to create text based content and manage it effectively. As Org-mode is just a text format then it can be easily converted by Emacs into other formats (markdown, pdf, html, etc). I’ll show you how to create other formats from Org-mode, so you can confidently write everything in Org-mode and generate any format you need.

In previous articles I have covered generating presentations from Org-mode using Reveal.js.

Why write in Org-mode

If you are writing anything more than a few paragraphs of text then it gets quite easy to become lost in your own writing. Having to scroll around to see what you covered earlier can slow down your creative process.

With Org-mode you can structure you content easily, as your “topics or table of contents” are your structure. Every heading and sub-heading can fold away the content underneath it, unfolding the only the parts of your writing you want to see.

Another useful aspect of Org-mode is that it hides the link part of the URL, so you only see the text part of the link. This helps keep your text easy to read.

As with many other languages supported by Emacs you also get colour highlighting for different styles along with spell checking and suggested words as you type.

[TODO: Insert picture of Org-mode - or maybe even a video]

Reasons I need to use Markdown

I use markdown for my Jekyll based blog and website and as these are relativley small I often just write them directly in Markdown. However, if its a series of posts on the same topic then I can easily structure that series using Org-mode and generate the markdown content when I am ready to add it to my blog.

I also need to use markdown for the self-publishing book website, https://leanpub.com/. I write the whole book in Org-mode, again so I can structure it sensibly and jump to specific parts of the content easily. I can also see topics (headings) I have written about in each chapter of the book very easily by open and closing sections of the Org-mode file.

Generating Markdown from Org-mode

In Emacs, open your Org-mode file (or switch to the buffer containing it). Then export a copy of then content into markdown with one of the following commands

M-x org-md-export-to-markdown
C-c C-e m m

Exports the current Org-mode file as a new text file of the same name but with the .md extension rather than .org.

When you export again, the .md file will be overwritten without warning, so if you want to make changes you edit the Org-mode file and re-generate the markdown file.

If you want to see the markdown file as soon as it is created, use the following command to open it in Emacs:

C-c C-e m o

If you do not wish to create a file from the export, the following command generated markdown and places it inside a tempory Emacs buffer:

M-x org-md-export-as-markdown
C-c C-e m M 

[TODO: what does this command do?]
M-x org-md-convert-region-to-markdown

The Markdown export is build on top of the http://orgmode.org/manual/HTML-export.html#HTML-export and anything not supported by the markdown syntax will be converted by that HTML export process. See the Org-mode website for more details on http://orgmode.org/manual/Markdown-export.html#Markdown-export and other formats.

For the header and sectioning structure the Markdown export can generate both atx and setext types for headlines, according to org-md-headline-style. ATX introduces a hard limit of two levels of headings, whereas Setext pushes it to six. Headings below that limit are exported as lists. You can also set a soft limit before that one (see http://orgmode.org/manual/Export-settings.html#Export-settings).

Thank you.
@jr0cket

In previous articles I showed how to setup Emacs Org-reveal & Reveal.js to generate your own presentations from Emacs Org-mode files. This time I’ll show you how to publish those presentations on Github Pages as I have done for my own presentations.

Github Pages are a great place for publishing your Reveal.js presentations or any static web content. For existing repositories you simply commit your content to a gh-pages branch or to the master branch of a user or organisation repository.

Github Pages are great for websites that is self-contained, in that there is no reliance on a database or other services running locally. You can even create great looking pages without any coding by using the Github authoring tool.

Existing code repositories

If you already have a repository for your code and want to add web page documentation, then you can simply add a gh-pages branch and commit your web content to that branch.

Content only repositories

If you only have content then you can use a user or organisation repository. This is a specifically named repository in the form of name.github.io where name is the exact name of your Github account or Github organisation you are part of.

In my case I created a repository named jr0cket.github.io, as my Github user account name is jr0cket.

Once created, you can type in the name of this repository into your browser and it will display any content you have committed into the repository and pushed it to Github.

Your user or org repository also forms the entry point for other project, so if you have a project called slides with web content in its gh-pages branch, you can see that content using the address: http://jr0cket.github.io/slides

Separating slide content into their own repository

As I planed to create a number of presentations, I use both an account repository as the home page and created a new repository called slides to host all my presentations.  This allows all my presentations to be easily cloned or forked by others easily without getting content that is only relevant to me on my Github pages home page.

Keeping the presentations all in one repository keeps things simple should I define my own Reveal.js themes or if there are Reveal.js updates.

I added  everything to the gh-pages branch (reveal.js, images, org & generated html files).  Then I generate the Reveal.js slides locally using org-reveal in Emacs, so I can check they look okay.  Once I am happy with the slides I commit the html and .org files to Git and push them up to Github.

Setting up a Github Pages user account repository

Creating an user repository on Github is just the same as for any other repository, except that the name must match the form name.github.io - where name is exactly the same as you Github user name.

I created a new repository called jr0cket.github.io, this has a web address (URL) of http://jr0cket.github.io

I used the Automatic Page Generator from Github to create the site without coding and with a handful of nice templates to choose from.  You can of course add your own HTML, CSS & JavaScript if you wish.  The Automatic Page Generator is in on the Settings page of your repository, under the Github pages section.  This section shows you the repository URL and a button to generate a page for you.

If you are going to use your user or org repository for your slides, then jump to the secion on “Adding Reveal.js to your repository”

Creating a repository for your Reveal.js slides

If you don’t already have a Github repository for your slides (and are not using your user or org repository), go to your account on Github and create a new repository.

git clone https://github.com/username/repository.git

Create an orphaned gh-pages branch

Github pages publishes content only from the branch gh-pages (unless you are using a user or org repository). In your local repository, create a new branch called gh-pages. According to Github, the gh-pages branch should be an orphaned branch.

cd your-local-repository
git checkout --orphan gh-pages

An orphaned branch is one that is not connected to another branch, in this case its not attached to master. Technically I don’t think gh-pages branch needs to be orphaned to publish your content, especially if there is nothing in the master branch, but this is the approach that Github recommends.

Once you have the gh-pages branch you can commit your files to that branch as normal.

git add .
git commit -m "Adding Reveal.js files for presentation"
git push origin gh-pages

Pushing your Reveal.js slides at this point will not give you the desired results, as we haven’t added the Reveal.js files to the repository.  So lets do that next.

Adding Reveal.js to your repository

You need to provide the JavaScript and CSS files from Reveal.js to make your slides display correctly.  I copy the following folders from within the reveal.js folder into the root of my slides project

cd  /path/to/revealjs/css    ~/my-slides
cd  /path/to/revealjs/js     ~/my-slides
cd  /path/to/revealjs/lib    ~/my-slides
cd  /path/to/revealjs/plugin ~/my-slides

You also need to check that the HTML for your web pages references Reveal.js files correctly.  The best way to do this is in the configuration for Emacs Org-reveal.

In my Org-reveal setup, I have defined the root for the Reveal.js files in my live-pack init.el file as follows:

(setq org-reveal-root "")

So long at this org-reveal setting is loaded, it shouldn’t matter which file you add it to in your Emacs configuration.

The HTML you generate with Org-reveal in Emacs should have references to the Reveal.js includes in the <head> section. Here is an example:

<html lang=”en”>
<head>
  <meta charset=”utf-8”/>
  <title>(My presentation title)</title>
  <meta name=”author” content=”(John Stevenson)”/>
  <link rel=”stylesheet” href=”./css/reveal.min.css”/>
  <link rel=”stylesheet” href=”./css/theme/jr0cket.css” id=”theme”/>
  <link rel=”stylesheet” href=”./css/print/pdf.css” type=”text/css” media=”print”/>
  <meta name=”description” content=”My presentation title“>
</head>

The final push

Then push the Reveal.js files to your Github repository (and any updated to your Org & html files)

git add .
git commit -m "Adding Reveal.js files for presentation"
git push origin gh-pages

Browsing your Slides

If you added your slides to a user or org repository, then you should be able to browse to http://name.github.io where name is your Github user or org name (eg. http://jr0cket.github.io).

If, like me, you created a seperate repository for all your slides, you can brows them by going to http://name.github.io/repo-name where name is your Github user name and repo-name is the name of the repository you added Reveal.js and your slides to (eg. http://jr0cket.github.io/slides).

Note that you need to add the html filename to the URL to browse your presentation, or as I have done add links to the page on jr0cket.github.io

Using Hub as an alternative way to create your Github pages repository

Hub is a command line tool for working with git repositories and Github. Hub makes it easy to create and fork repositories on Github without having to visit the Github website.

• Install Hub
• Create a folder called name.github.io on your laptop, where name is your Github user name or organisation name
• Inside that folder, initialise a git repository - git init
• Rename the master branch to gh-pages - git branch -m gh-pages

• Use hub to to create the repository on github - hub create -d "optional description of the repository"
  – If you want to specify the repository name using hub, use the command form - hub create account-name.github.io -d "optional description of the repository"

• Create and commit your content in the local repository on the gh-branch, then push the gh-pages branch to github github push -u origin gh-pages

– The -u option sets origin to be the default remote repository to and the gh-pages the default branch. So next time you do a push or pull you dont need to specify the remote repository or branch, you can simply do git push and git pull

Example Reveal.js presentations on Github pages

See my Github page for my published presentations, created with Emacs Org-mode, Org-reveal and Reveal.js.

Thank you.
@jr0cket

Creating presentations with Emacs is quick and more collaborative than with other tools I have used. Using Emacs Org-mode you can easily structure and navigate your content. Using Org-Reveal you can generate a great looking HTML5 presentation using Reveal.js from your org-mode content.

I’ll show you how to configure Emacs, Org-Reveal and Reveal.js so you can create content in plain text and generate a themed, animated slide-deck that supports syntax highlighting for lots of languages. As your content is in plan text its easy to collaborate around it with Github.

I use Emacs Live as a base configuration, although there is no dependency on anything in Emacs Live to make this setup work.

What is Reveal.js

Reveal.js is a JavaScript library for creating slides for viewing in a browser, using CSS and JavaScript. You can write your presentations in HTML or use Slid.es to live edit and host your presentation in cloud. There are a whole list of Example presentations to get an idea of what it Reveljs can do. I recommend looking at the Reveal.js presentation first. There is also a beginners tutorial for Reveal.js to help you get going.

Using Emacs we don’t need to write directly in HTML as we will generate it from our text file using Org-mode. There is a dependency on Reveal.js library with this approach.

Installing Reveal.js

1) Download the latest version of reveal.js

2) Extract somewhere sutitable, eg, ~/apps/revealjs if its just for your account or /opt/javascript/revealjs if you have multiple operating system accounts.

To see an example presentation, open the index.html from the extracted Reveal.js download in a browser.

Why use Emacs and Org-mode for presentations

Org-mode is a great way to write notes, make presentations and organise tasks. It is built into Emacs so you don’t need to do any configuration to use it. Simply create a file with a .org extension (eg. my-presentation.org) and when you open that file in Emacs it will automatically switch on org-mode.

Org-mode allow you to structure information simply and quickly. The headings and sub-headings can expand and collapse using the tab key, so you only see the level of detail you need.

The content is always a text file so you don’t have to worry about any proprietary formatting and as its text its easy to collaborate around using developer tools like Git and Github.

Configuring Emacs, Org-mode and Org-reveal

Org-reveal is a feature you add to Emacs to generate presentations using Reveal.js. I am using Emacs Live as a base configuration, so I simply added the org-reveal file to my own customisations of Emacs Live in my live-pack.

I download the Org-Reveal file from Github and placed it in my live pack config folder ~/.live-packs/jr0cket-pack/config/ox-reveal.el

Then I edited my live-pack init.el file to load org-reveal at Emacs start-up

emacs ~/.live-packs/jr0cket-pack/init.el

Add a line to call the org-reveal script download from Github, with a path relative to the config folder of the live-pack

(live-load-config-file "ox-reveal.el")

Location of Reveal.js

If you are publishing your presentation on the web then you should include a copy of the css, js and plugin folders from the Reveal.js project.

My current approach is to fork the Reveal.js project on Github (so I can keep track of updates) and create my presentations inside the reveal.js folder created when I cloned the my fork from github.

;; Fork reveal.js project on Github
;; Copy the URL from my forked repo

git clone git@github.com:jr0cket/reveal.js.git
cd reveal.js
emacs my-presentation.org

I then set the org reveal root to be relative to my presentation. In this case my generated HTML presentation will look for css, js and plugin folders in the same parent folder as my presentation (reveal.js). In my live-pack init.el file I add the following to set the reveal root to be relative.

(setq org-reveal-root "")

If you don’t set this variable to any value (empty string is considered a value here), then the stylesheet and JavaScript includes in your generated presentation will look for CSS and JavaScript resources in a folder called ./reveal.js.

Alternatively, you can set the location of Reveal.js to a specific file location. The location should be the full path to top level of the Reveal.js folder, this is also defined in my live-pack init.el file

(setq org-reveal-root "file:///var/www/revealjs/current")

If you set a global path then this is the path that will appear in your CSS and JavaScript includes in the generated HTML file.

Writing presentations with Emacs and Org-mod

Create a file for your presentation with a .org extension.

You can create a new file in Emacs just by opening a file with a new filename.

C-x C f my-presentation.org

In your new file you define slide titles using the * notation. One * for the slide heading (level 1 heading) and two *‘s for slide bullet points (level 2 heading).

You can put anything you want under the slide heading and you dont have to use bullet points :).

Generating your Reveal.js presentation

Once you have your presentation written you can generate the presentation with the command

M-x org-reveal-export-to-html

This command creates a single .html file that contains the generated presentation, except for any images you have used. The .html file will be have the same name as your org-mode file, so if you created your content in my-presentation.org then you will generate my-presentation.html

If your links and images are all correctly referenced in your presentation, then simply opening my-presentation.html file in a browser will show you the end result.

Summary

You have seen how to set up Emacs, Org-reveal and Reveal.js so you can create great presentation without having to code in HTML. The next article in the series will cover how to write presentations with Emacs and Org-mode to make use of all the graphics options in Reveal.js, whilst keeping your content as simple text.

Thank you.
@jr0cket

Org-mode is a great way to track tasks and manage all those to-do items in one place, although Org-mode has a very simple workflow by default (TODO | DONE). To track your tasks in more detail you can define extra stages or create a completely workflow.

Previously I covered how to set up Org-mode & Org-capture for the built in workflow. In this article I show how to configure Org-mode to use my own custom workflow or define your own multiple workflows should the need arise.

My Kanban workflow

I like to organise my work using Kanban, an agile technique that focuses on getting work done by managing workload and learning through fast feedback. To implement this Kanban approach I define 4 stages for my task workflow:

Emacs Org-mode for managing TODO’s using a Kanban style workflow

TODO - tasks I have not started yet. If I have an idea for a task, I can make a quick note and get back to what I was doing without loosing focus or worrying about forgetting to do something.

DOING - tasks I have started working on. I try to keep the number of tasks I am doing as low as possible so I am not task switching. This helps me get things done

BLOCKED - tasks that I started working on but cant continue with for some unexpected reason. I wont start working on these until I have more time set aside to unblock them. If I block a task with sub-tasks then I will not work on any of those sub-tasks either (I have not seen anything in org-mode to automatically block and unblock sub-tasks if its parent is blocked or unblocked, that would be useful).

REVIEW - tasks I have completed but want to check if there something I can learn or share from the experience of doing that task. This can help me define other tasks related to the one I just completed.

DONE - tasks that are completed. I keep the done tasks around for the week so I have a feeling of accomplishment and avoid repeating myself.

ARCHIVE - an optional stage to put tasks in if I want a longer term record of completing that task

Defining additional task stages

You can create a new workflow for your tasks by defining setting a sequence of text strings to the variable org-todo-keywords

I am using Emacs Live as a base configuration, so I put all my Org-mode configurations into a file called:

~/.live-packs/jr0cket-pack/config/org-mode.el

If you are not using Emacs Live you can place them in ~/.emacs.d/init.el.

Here is an example that implements my Kanban workflow:

(setq org-todo-keywords 
  '((sequence "TODO" "DOING" "BLOCKED" "REVIEW" "|" "DONE" "ARCHIVED")))

The vertical bar | defines the possible end states for your task. Org-mode can be configured to add content to your task upon entering an end state, such as setting a CLOSED variable to the current date and time stamp. This is useful if you want track your time spent on tasks. I will cover this in a follow on article, or see the section on Progress Logging of the Orgmode tutorial.

Defining multiple workflows

You can also define multiple workflows so long as all the task stage names are unique. Here is an example of multiple workflows from the org-mode.org website:

(setq org-todo-keywords  '((sequence "TODO" "|" "DONE")
  (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED")
  (sequence "|" "CANCELED")))

I haven’t found a use for this approach as yet, but will add it to my TODO list to investigate.

Making workflow stages more distinct with colour

The default colours for Org-mode tasks are pink for TODO and Green for DONE. As we are creating additional steps it helps me scan my task states if they are colour coded.

Here is an example of defining colours for each of the states of my Kanban workflow. Most of the colours are defined using the text of the name. The org-warning is used to set the TODO stage to the standard org-mode colour for TODO.

1
2
3
4
5
6
7
8

;; Setting Colours (faces) for todo states to give clearer view of work 
(setq org-todo-keyword-faces
  '(("TODO" . org-warning)
   ("DOING" . "yellow")
   ("BLOCKED" . "red")
   ("REVIEW" . "orange")
   ("DONE" . "green")
   ("ARCHIVED" .  "blue"))) **</span>

More Org-mode customisation to consider

There are lots more customisations that can be made to Org-mode to help you manage tasks. Here are some aspects I am considering next.

Creating more templates for Org-capture

By default Org-capture only has one template, the task template. This task template only a time stamp of when it was created and a link to the file. All the TODO items created with this template go under the main heading of Tasks, so I could create templates for other headings such as Personal, Financial, Household, etc.

Triggering actions on Org-mode stages

When I mark my tasks as done, I’d like to have that tasked automatically date stamped so I know when I completed it. This would add a CLOSED parameter to the task in question. If I also have time stamps for each of the states then I can track my cycle time and check to see if I am keeping too many tasks in the DOING state.

A lot more features of Org-mode can be found at the excellent Orgmode.org website.

Thank you.
@jr0cket

Emacs Org-mode has a feature called Org-capture that makes it easy to keep track of all the to-do’s that crop up as we work on projects. With Org-capture you can make comments across all your files and projects and link to them all from one place.

Here is how to configure Emacs Org-capture so you can quickly create new tasks relevant to specific files and easily manage them all in one place. If you are not familiar with Emacs Org-mode, take a look at my article: Manage your developer life with Org-mode.

I use Emacs Live as a base configuration for Emacs, although everything here will work with any setup as Org-mode and Org-capture are both part of Emacs itself. If you are not using Emacs live, you can place the configurations in your ~/.emacs.d/init.el file rather that the locations specified here.

Using Org-capture todo file to track tasks

Org-capture creates a list of all those tasks you want to do across all the text files you are working with in a single file, by default this file is called .notes and lives in the root folder of your account. However, the file managing your tasks should really have a .org extension so that Emacs automatically puts it into org-mode when its loaded.

You should also consider creating your todo list file where it is easy to manage with Git or a synchronisation service like Dropbox.

Managing tasks using Org-mode and Org-capture

Define where your tasks are kept

Define a variable called org-gefault-notes-file to set the path and file name for the todo file.

I put this variable definition in a new file I created to hold all my Org-mode configurations:

~/.live-packs/jr0cket-pack/config/org-mode.el

Then I edited this file and add the following definition for the todo file:

;; Define the location of the file to hold tasks
(setq org-default-notes-file "~/.todo-list.org")

Calling the custom org-mode settings the Emacs Live way

As I am using Emacs Live, I follow the convention of placing sets of configurations into their own file and calling that from my live-pack init.el. Editing my init.el file I added:

~/.live-packs/jr0cket-pack/init.el

and added a new line to load in the configuration from the org-mode.el file:

(live-load-config-file "org-mode.el")

Adding key bindings for org-capture

I set up a keyboard binding for org-capture using C-c c (control key and c, followed by c). I opened an existing binding file I have in my live pack

~/.live-packs/jr0cket-pack/config/bindings.el

and added a definition to call org-capture

(define-key global-map "C-c c" 'org-capture)

Create a notes.org file

Create the file that will hold all your tasks by either opening and saving a file of that name in Emacs or using the command:

touch ~/.todo-list.org

Emacs is now setup to capture all your todos via Org-capture, so lets look at how we use Org-capture

Creating a task using Org-capture

Open up a source code file or other text file you want to work on. Create a comment in that file about a TODO / task you want to do. With the cursor still on your comment, use the org-capture command or the keyboard combo:

M-x org-capture
C-c c

You are prompted to choose a template for the type of entry you want to create. By default there is only one called task. Press the letter t to select the task template.

The cursor will now be in the Org-mode task file you created earlier allowing you to type in a descriptoin of the task. Updated the task list with this new task using the keyboard combo

C-c C-c

You can save the tasks file as usual with C-x C-s.

Following links

To open the file that your task links too, or open a web addresses you have added to the task, place the cursor anyware on the link and use

C-c C-o

Adding TODO’s manually

As has been mentioned previously, org-mode manages tasks using a plain text file, so its easy to add your own tasks by manually editing the file. You can indicate a task using the * notation.

1
2
3

* Level 1 heading
** Level 2 heading
*** Level 3 heading and so ....

By default the org-capture function has only one template, Tasks. So all todo’s created with org-capture will be level 2 headings under * Tasks…

** description of task

Navigating and using your org-mode task list

When ~/.todo-list.org file is in org mode, you may only see the text Tasks.... The three dots after Tasks indicates that this is a heading that contains more underneath. Using the Tab key you can expand the contents and repeatedly tabbing will cycle through different levels of expansion. To work on all headings at once, you can use the Shift-Tab key combination.

M - Enter

• creates another line in the same style as the current one the cursor is on. If you do Alt-Enter at the end of a Task line, a new task is created. At the end of a list line, a new list item is created, etc.

Shift- left/right arrows

• on a TODO text cycles through the states of the task workflow

M - left/right arrows

• promotes or demotes the task, giving an quick way to create sub-tasks. A task line must start at the beginning of the line. If you indenting a task line with spaces means it is no longer recognised as a task.

M-Shift- left/right arrows

• promotes / demotes a whole structure. For example, if there is a level 2 heading with several level 3 headings underneath, then promoting the level 2 heading to level 1 also promotes the level 3 headings to level 2.

M-Shift- up/down arrows

• move tasks and list items up or down within the same level

Shift - up/down arrows

• when on task ** will cycle through the priority of a tasks [A, B, C, none]

In Summary

Emacs Org-mode is a great way to organise your busy developer life - and life in general if you are that way inclined. As Org-mode is a part of Emacs already, then all you need to do is add a couple of lines of configuration and you are off.

As any Org-mode file is just a text file underneath, then you are not trapped into a format you cannt use anywhere else.

Hope you have a great time organising yourself with Org-mode.

Thank you.
@jr0cket

As a busy developer I end up working on several projects, documents & books at the same time.  I want a simple way to capture notes where I don’t have to worry about formatting.  I also want to keep a track on all the things I am working on.  As I do most of my coding & writing with Emacs, then I was sure it had something that could help.

Enter Org-mode

Org-mode is a really simple and beautiful way to take notes, create presentations, organise thoughts and help you manage tasks across all your work.  The latest versions of Emacs (23.x / 24.x) have Org-mode built in, so you can use it straight away with M-x org-mode.

Org-mode documents are plain text, so they are easy to write and understand even outside of Emacs.  The magic is happens when Org-mode interacts with that text.  Org-mode understands the structure of the text and lets you easily organise everything into something useful.

I have written a simple guide to configuring Org-mode and Org-capture, as well as a guide to creating your own task workflow for Org-mode.

Here is a quick YouTube video overview of Org-mode for Emacs by Richard Dillon, to understand the keyboard short-cuts used (key bindings) then see his Org-mode notes on Github.  Or if you are already hooked on the idea of Org-mode then see the In-depth guide at the end of this article.

Hack Emacs: Introduction to Org-mode

You can also take a look at Carsten Dominik talking about Org-mode from the Google Tech Talks back in 2008, the content is still relevant.

Using Org-capture to track tasks

Org-capture provides an easy way to create a list of all those tasks you want to do across all the text files you are working with.  You create a comment in the file you are working in then with the cursor over that comment you create a new task using org-capture. This opens up a file that holds your current tasks and using a template it creates a task that links back to the file where you made your comment.  When you open this link it takes you back to the file and to the exact position you created the task from.

I will show you how to set up and use org-capture with Emacs and Emacs live in the next article of this series.

Creating presentations for developers

You can easily create an interactive presentation with org-mode and more importantly for developers interact with real source code in a tool that knows how to process that code.  If you want to publish this you can put your .org file on Github or export your presentation as HTML and other formats.

so you dont need to spend time on creating fancy spinning presentations with JavaScript or yet another boring power point presentation and fill it with static screen shots.

Learning Org-mode

The best place to start learning Org-mode is its website: http://orgmode.org/.  I found the compact guide a great introduction and it got me going quickly.  I will also be writing a few follow-on articles on specific topics like task management and presentations.

You can also watch the Emacs Org-mode In-depth video, again by Richard Dillon

Emacs Org-mode in depth

Thank you.

Emacs is a really powerful tool for Clojure development, although without a guiding hand it can be a bit of a learning curve. Using the Emacs Live its really simple to get a fully featured development environment for Clojure. I will show you how to get Emacs Live installed and how to start using it for Clojure.

I also recommend using EmacsForOSX if you are on a Mac.

Emacs Live is a collection of packages for Clojure that include:

• Clojure mode - language support
• nREPL - interactive environment
• Magit - manage git repositories
• auto-complete - tab complete expression names & show documentation
• undo-tree - undo and redo on steroids with a branching history
• yasnippets - abbreviations automatically expand into function templates

Installing Emacs Live

Emacs Live required Emacs 24 or greater, everything else is self contained.

You could just clone the github repository, but the provided install script makes sure everything is set up correctly and also creates a separate folder for your own personal settings. This allows you to tweak Emacs Live to your own style without it getting clobbered by any updates.

Run the following in a terminal window (Mac or Linux):

Before anything is installed, the script will move any old Emacs configuration to ~/.emacs.d to a folder called ~/.emacs.d-old.

Once all the Emacs Live configuration files are installed, the script asks you if you want to create your own personal configuration. If so, a new folder will be created called
~/.live-packs/your-current-username-pack.

How to tweak Emacs Live

Its really easy to add your own key bindings and other configurations to Emacs Live, using the personal pack the script created for you. The personal pack has an init.el file in which you can add short simple configurations or load in longer configurations from the config or lib folders.

Key bindings

Emacs live makes several changes to the default key bindings of Emacs. If you want the default key bindings back then you can simply switch off the Emacs Live key bindings by adding the following to the file ~/.emacs-live.el

(live-ignore-packs '(live/bindings-pack))

Alternatively, you can learn to love the Emacs Live bindings, or tweak a few in your own personal pack. I have added a keybinding for launching the Clojure repl and a pair of key bindings for changing the font size, making it easier to change fonts when giving a demo.

To make the change in my personal pack, I added the following to the file ~/.live-packs/jstevenson-pack/config/bindings.el

1
2
3
4
5
6

;; Simpler key bindings for making text in buffers bigger and smaller
(define-key global-map (kbd "C-+") 'text-scale-increase)
(define-key global-map (kbd "C--") 'text-scale-decrease)

;; Launch Clojure repl via Leiningen - M-x nrepl-jack-in
(global-set-key (kbd "C-c C-j") 'nrepl-jack-in)

Loading in bigger changes

To keep your init.el file easy to work with, larger customisations can be defined in their own .el files under the config diretory. Then simply add a line to load in these config files in the file ~/.live-packs/jstevenson-pack/config/init.el

See the example where I tweaked the mode line for Emacs when developing Clojure

Upgrading Emacs Live

As all the configuration files are hosted on Github then a simple git pull will bring in any new version. As the install script clones the github repository, the remote github repository is already set up.

From inside your ~/.emacs.d folder you can simple do a git pull when you know there is an update (notices are posted to the Emacs Live Google group).

If you want to know if you are on the latest version or how many versions you are behind, you can use git fetch to get all the latest changes without applying them. The output of git fetch will list any versions that have been created since you installed.

Just the Docs

Emacs Live has documentation using the Emacs Live theme on the Github pages for the Emacs Live project.

In Summary

For a developer new to Emacs and Clojure development, getting a great environment to work in is easy. Learning how to use that environment well will take practice, but this is the case with any tools. Muscle memory will kick in pretty quickly, so the more you use Emacs the more natural it will feel.

Thank you.
@jr0cket

Emacs is fun to configure and if you have the basics of LISP or Clojure then its pretty easy too. After reading how to replace the text on the modeline I decided to customise my mode-line to make it more efficient for Clojure development. I’ll cover how I tweaked the mode line and added this customisation to my Emacs Live based configuration.

Instead of a long list of Major and Minor modes that are active, I now have symbols representing those modes.

In the screen-shot you can see I have the following modes running

λ Clojure mode
τ undo-tree
γ yas
υ volatile highlights
ηζ nREPL minor mode
α auto-complete
φ paredit

Some other modes are active, but hidden with a null string as I am assuing they are running all the time.

Configuring Emacs Live

Adding these to the Emacs Live configuration I use is easy, assuming you used the “bro-grammer” script provided by +Sam Aaron. This script creates a ~/.live-pack folder where you can add your own keybindings and configuration without it getting hit by Emacs Live updates.

I created a file called clean-mode-line.el, based on the one in the Mastering Emacs article. The file is located in my personal live-packs folder at:

1

~/.live-packs/jr0cket-pack/config/clean-mode-line.el

The code for the mode-line tweaks is a Github Gist:

To use this new mode-line tweak, we ask Emacs Live to load the configuration in clean-mode-lime.el. To do this, edit the init.el file in your live pack

1

~/.live-packs/jr0cket-pack/init.el 

Then add the following code:

Emacs Tweaked

When you open a Clojure document, the mode line now displays the major and minor modes as symbols.

Starting the Clojure REPL using M-x nrepl-jack-in gives you a similar modeline, this time with the major mode being nrepl-mode.

Switching back to a Clojure file after running nREPL shows Clojure as the major mode and nREPL running as the minor mode.

In Summary

The custom mode line was really easy to set up, thanks to the great info in the Matering Emacs article. The tricky part was finding the specific name for the nREPL minor mode that was running. Other than that it took a couple of minutes, most of which was deciding which symbols to use. I added a few others at the end of the file in case I change my mind or you want to use something more meaningful to yourself.

I havent tried this with Swank, but I assume that all it would take is adding of the swank mode to the clean-mode-line.el file.

When I get round to using other modes, I will see if I can add other symbols to my configuration where it makes sense. Let me know if you find this useful and what symbols you use.

Thank you.
@jr0cket

In part one I showed how easy it is to version a project using Git from within Emacs, using the Magit package. This time we look at the git log within Magit.

Working with the log gives you a lot more detail about your changes, helps you compare local and remote repo commits. All of which helps you understand when you should push your code.

Git logs with Magit

On the command line you can use git log to see your change history, although it can be a bit fiddly to set up git to give you a pretty view of those logs. In Magit you can just get on a explore the logs

Inside the Magit buffer, press l to show the log menu and then either l for the short for log or L for the long form of the log.

l l - short log
l L - long log

Selecting the short log details allows you to see more commits, but you only see the commit message and not the files that have changes.

In the following examples both the remote (github repository) and local repository are at the same commit - e447b51. So you can easily tell if there are any local commits you have not pushed to Github.

Selecting the long log output, l L, you see more details of each commit, including the files changed, author and timestamp.

To see the changes within a commit, move the cursor over a commit number in the log and press space. This brings up another buffer which you can scroll through. You don’t even need to switch to this new buffer as if you keep pressing space it will scroll through the text of the change.

The magit log also has a margin that shows the name and relative time of each commit. This can be very useful information to have at hand, although it does take up more space in the buffer.

To toggle the magit log margin, use h or M-x magit-log-toggle-margin

Comparing Commits (diff) with Magit

In the following example, the local repository is ahead of the Github repository by one commit. The magit log can be used to compare commits.

Move the cursor over the first commit and press . (full stop). Then put the cursor over the second commit and press =.

To exit buffer that opened the diff, simply press q in the Magit buffer.

Summary of Magit log

I tend to just use the short form of the log and compare commits every now and again. If I havent pushed a few commits up to Github for a while, its a handy way to check if I should push and what I am pushing.

Of course if I write good commit messages and commit often to my local repo, then its much easier to tell what I am pushing from just the short log.

Thank you.
@jr0cket