Support via Liberapay, GitHub or PayPal

Org Merge Driver

1. Introduction

This is Org Merge Driver, a program for merging changes to Org mode files.

This project is currently being developed under Google Summer of Code 2012 for the Gnu organization.

  • The project page can be found here.
  • The homepage of Org-mode is here.

2. Obtaining the source code

The source code may be obtained from the GIT repository hosted on https://git.sr.ht.

git clone https://git.sr.ht/~bzg/org-merge-driver

3. Compiling

Compiling this program requires that you have autotools installed. To compile this program, you should only have to run:

autoreconf --install && ./configure && make

If this fails because of missing dependencies, please see dependencies below.

4. Quick Start

4.1. Using and Installation

4.2. Git users:

  1. Add to your git configuration located in either ${GITDIR}/.git/config (for repository local configuration) or ~/.gitconfig (for global configuration) the following lines:

    [merge "merge-orgmode"]
       name = Org Mode merge driver
       driver = /usr/local/bin/org-merge-driver -- %O %A %B %A
    
  2. In every work tree you wish to you the org-merge-driver, make a .gitattributes file or .git/info/attributes if you don't want to have the file committed with the project. Add the following line to this file:

    *.org merge=merge-orgmode
    

    (See "man 5 gitattributes" for more info.)

4.3. Bazaar users:

  1. Install the extmerge bzr plug-in
  2. Add to your ~/.bazaar/bazaar.conf the line

    external_merge = org-merge-driver -- %b %T %o %T
    
  3. Then, to merge a conflict in a ChangeLog file, use
bzr extmerge --all --verbose

4.4. Mercurial users:

  1. Add to your $HOME/.hgrc the lines
[merge-patterns]
**.org = org-merge-driver

[merge-tools]
org-merge-driver.executable = /usr/local/bin/org-merge-driver
org-merge-driver.args = -- $base $local $other $local

See Configuration files for Mercurial, section merge-tools for reference.

5. Options

This program currently supports the following options:

Short Long Description
-m, –rmargin=COLUMN Set the right margin of headings
-N, –notabs Use only spaces in the output
-p, –priority=PRIORITY Specify an accepted prority
-t, –todo=STATE Specify an accepted todo state.
-T, –usetabs Use tabs in the output, unused.
-W, –tabwidth=WIDTH The width of tabs in spaces, unused
-?, –help Give this help list
  –usage Give a short usage message
-V, –version Print program version

5.1. "TODO" States

If you have defined TODO states, you can describe them with this command. The defaults are set to "TODO" and "DONE". Declaring a single todo state causes the default set of todo states to be discarded. Because of this, you must declare all TODO states used.

At this time, Todo states can only be configured on the command line.

org-merge-driver -tDONE --todo=TODO

5.2. Priority Cookies

If you have defined more priority states system-wide, you can describe them with this command. The defaults are set to 'A', 'B', and 'C'. You must declare all priority states used (all defaults are immediately overridden). Currently, priority cookies may only be a single ASCII character.

org-merge-driver -pA -pB --priority=C

5.3. Right Margin

Org-merge-driver will attempt to minimize reformatting, but it is sometimes necessary for org-merge-driver to realign text on the right margin of the text. This can happen after merging lists of heading TAGS.

You can set the preferred right margin value (in spaces) with the --rmargin= command. If the margin is not large enough to fit a line of text, it will extend past the margin. The default margin value is 77 spaces.

org-merge-driver -m77

5.4. Specify Input and Out Files

To perform a merge, org-merge-driver requires three files – your copy of a file, a remotely updated file, and a common ancestor file. These are given to org-merge-driver in the order ancestor, local, remote.

To ensure that the file names are not confused with command line options, you can seperate them from the rest of the arguments with --.

By default, org-merge-driver prints the merged file to stdout. To have the output printed to a file, specify a fourth file on the command line.

org-merge-driver -- ancestor.org local-update.org remote-update.org output.org

6. Dependencies

To compile org-merge-driver, you may need: Gnulib, Flex (not lex) and GNU Autotools installed. Install Flex and autotools using your desired package manager. To obtain gnulib follow the instructions below.

6.1. To obtain Gnulib:

You must obtain Gnulib by it's source code, there is no binary distribution. Through git or cvs:

git clone git://git.savannah.gnu.org/gnulib.git
# or
cvs -d :pserver:anonymous@pserver.git.sv.gnu.org:/gnulib.git co -d gnulib HEAD

6.2. Reimporting gnulib-tool dependencies

cd $(top_srcdir)
/PATH/TO/GNULIB/gnulib-tool --add-import

6.3. Compiling

To compile, run:

autoreconf -i
./configure && make

Documentation from the orgmode.org/worg/ website (either in its HTML format or in its Org format) is licensed under the GNU Free Documentation License version 1.3 or later. The code examples and css stylesheets are licensed under the GNU General Public License v3 or later.