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:

Add to your git configuration located in either ${GIT_DIR}/.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
```
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:

Install the extmerge bzr plug-in

Add to your ~/.bazaar/bazaar.conf the line

external_merge = org-merge-driver -- %b %T %o %T

Then, to merge a conflict in a ChangeLog file, use

bzr extmerge --all --verbose

4.4. Mercurial users:

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