~bzg/org-merge-driver

org-merge-driver/README -rwxr-xr-x 5.8 KiB
b057ec03 — Andrew Young Add test drivers 10 years ago
                                                                                
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
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
-*- mode:org -*-
#+Title: Org Merge Driver
* 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 [[http://orgmode.org/worg/org-contrib/gsoc2012/student-projects/git-merge-tool/index.html][here]].
- The homepage of Org-mode is [[http://orgmode.org][here]].

* Obtaining the source code
The source code may be obtained from the GIT repository hosted at
Orgmode.org.

#+begin_src sh
  git clone git://orgmode.org/org-merge-driver.git
#+end_src

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

#+begin_src sh
  autoreconf --install && ./configure && make
#+end_src

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

* Quick Start
** Using and Installation
** Git users:
1. Add to your git configuration located in either
   ${GIT_DIR}/.git/config (for repository local configuration) or
   ~/.gitconfig (for global configuration) the following lines:

#+begin_src sh
  [merge "merge-orgmode"]
  name = Org Mode merge driver
  driver = /usr/local/bin/org-merge-driver -- %O %A %B %A
#+end_src

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:

#+begin_src
*.org merge=merge-orgmode
#+end_src

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

** Bazaar users:
1. Install the [[http://doc.bazaar.canonical.com/plugins/en/index.html][extmerge bzr plug-in]]
2. Add to your ~/.bazaar/bazaar.conf the line

#+begin_src sh
  external_merge = org-merge-driver -- %b %T %o %T
#+end_src

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

#+begin_src sh
  bzr extmerge --all --verbose
#+end_src

** Mercurial users:
1. Add to your $HOME/.hgrc the lines

#+begin_src sh
  [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
#+end_src

See [[http://www.selenic.com/mercurial/hgrc.5.html][Configuration files for Mercurial]], section merge-tools for
reference.

* 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               |

** "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.

#+begin_example
  org-merge-driver -tDONE --todo=TODO
#+end_example

** 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.

#+begin_example
  org-merge-driver -pA -pB --priority=C
#+end_example

** 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.

#+begin_example
  org-merge-driver -m77
#+end_example

** 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.

#+begin_example
  org-merge-driver -- ancestor.org local-update.org remote-update.org output.org
#+end_example

* Dependencies
To compile org-merge-driver, you may need: [[http://www.gnu.org/software/gnulib/][Gnulib]], [[http://flex.sourceforge.net/][Flex]] (not lex) and
GNU Autotools installed.  Install Flex and autotools using your desired
package manager.  To obtain gnulib follow the instructions below.

** To obtain Gnulib:
You must obtain Gnulib by it's source code, there is no binary
distribution.  Through git or cvs:
#+begin_src sh
  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
#+end_src

** Reimporting gnulib-tool dependencies
#+begin_src sh
  cd $(top_srcdir)
  /PATH/TO/GNULIB/gnulib-tool --add-import
#+end_src

** Compiling
To compile,  run:
#+begin_src sh
  autoreconf -i
  ./configure && make
#+end_src