README 5.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180
  1. -*- mode:org -*-
  2. #+Title: Org Merge Driver
  3. * Introduction
  4. This is Org Merge Driver, a program for merging changes to Org mode
  5. files.
  6. This project is currently being developed under Google Summer of Code
  7. 2012 for the Gnu organization.
  8. - The project page can be found [[http://orgmode.org/worg/org-contrib/gsoc2012/student-projects/git-merge-tool/index.html][here]].
  9. - The homepage of Org-mode is [[http://orgmode.org][here]].
  10. * Obtaining the source code
  11. The source code may be obtained from the GIT repository hosted at
  12. Orgmode.org.
  13. #+begin_src sh
  14. git clone git://orgmode.org/org-merge-driver.git
  15. #+end_src
  16. * Compiling
  17. Compiling this program requires that you have autotools installed. To
  18. compile this program, you should only have to run:
  19. #+begin_src sh
  20. autoreconf --install && ./configure && make
  21. #+end_src
  22. If this fails because of missing dependencies, please see [[Dependencies][dependencies]]
  23. below.
  24. * Quick Start
  25. ** Using and Installation
  26. ** Git users:
  27. 1. Add to your git configuration located in either
  28. ${GIT_DIR}/.git/config (for repository local configuration) or
  29. ~/.gitconfig (for global configuration) the following lines:
  30. #+begin_src sh
  31. [merge "merge-orgmode"]
  32. name = Org Mode merge driver
  33. driver = /usr/local/bin/org-merge-driver -- %O %A %B %A
  34. #+end_src
  35. 2. In every work tree you wish to you the org-merge-driver, make a
  36. .gitattributes file or .git/info/attributes if you don't want to have
  37. the file committed with the project. Add the following line to this
  38. file:
  39. #+begin_src
  40. *.org merge=merge-orgmode
  41. #+end_src
  42. (See "man 5 gitattributes" for more info.)
  43. ** Bazaar users:
  44. 1. Install the [[http://doc.bazaar.canonical.com/plugins/en/index.html][extmerge bzr plug-in]]
  45. 2. Add to your ~/.bazaar/bazaar.conf the line
  46. #+begin_src sh
  47. external_merge = org-merge-driver -- %b %T %o %T
  48. #+end_src
  49. 3. Then, to merge a conflict in a ChangeLog file, use
  50. #+begin_src sh
  51. bzr extmerge --all --verbose
  52. #+end_src
  53. ** Mercurial users:
  54. 1. Add to your $HOME/.hgrc the lines
  55. #+begin_src sh
  56. [merge-patterns]
  57. ,**.org = org-merge-driver
  58. [merge-tools]
  59. org-merge-driver.executable = /usr/local/bin/org-merge-driver
  60. org-merge-driver.args = -- $base $local $other $local
  61. #+end_src
  62. See [[http://www.selenic.com/mercurial/hgrc.5.html][Configuration files for Mercurial]], section merge-tools for
  63. reference.
  64. * Options
  65. This program currently supports the following options:
  66. | Short | Long | Description |
  67. |-------+---------------------+-------------------------------------|
  68. | -m, | --rmargin=COLUMN | Set the right margin of headings |
  69. | -N, | --notabs | Use only spaces in the output |
  70. | -p, | --priority=PRIORITY | Specify an accepted prority |
  71. | -t, | --todo=STATE | Specify an accepted todo state. |
  72. | -T, | --usetabs | Use tabs in the output, unused. |
  73. | -W, | --tabwidth=WIDTH | The width of tabs in spaces, unused |
  74. | -?, | --help | Give this help list |
  75. | | --usage | Give a short usage message |
  76. | -V, | --version | Print program version |
  77. ** "TODO" States
  78. If you have defined TODO states, you can describe them with this
  79. command. The defaults are set to "TODO" and "DONE". Declaring a single
  80. todo state causes the default set of todo states to be
  81. discarded. Because of this, you must declare all TODO states used.
  82. At this time, Todo states can only be configured on the command line.
  83. #+begin_example
  84. org-merge-driver -tDONE --todo=TODO
  85. #+end_example
  86. ** Priority Cookies
  87. If you have defined more priority states system-wide, you can describe
  88. them with this command. The defaults are set to 'A', 'B', and 'C'. You
  89. must declare all priority states used (all defaults are immediately
  90. overridden). Currently, priority cookies may only be a single ASCII
  91. character.
  92. #+begin_example
  93. org-merge-driver -pA -pB --priority=C
  94. #+end_example
  95. ** Right Margin
  96. Org-merge-driver will attempt to minimize reformatting, but it is
  97. sometimes necessary for org-merge-driver to realign text on the right
  98. margin of the text. This can happen after merging lists of heading
  99. TAGS.
  100. You can set the preferred right margin value (in spaces) with the
  101. =--rmargin== command. If the margin is not large enough to fit a line
  102. of text, it will extend past the margin. The default margin value is
  103. 77 spaces.
  104. #+begin_example
  105. org-merge-driver -m77
  106. #+end_example
  107. ** Specify Input and Out Files
  108. To perform a merge, org-merge-driver requires three files -- your copy
  109. of a file, a remotely updated file, and a common ancestor file. These
  110. are given to org-merge-driver in the order ancestor, local, remote.
  111. To ensure that the file names are not confused with command line
  112. options, you can seperate them from the rest of the arguments with
  113. =--=.
  114. By default, org-merge-driver prints the merged file to stdout. To
  115. have the output printed to a file, specify a fourth file on the
  116. command line.
  117. #+begin_example
  118. org-merge-driver -- ancestor.org local-update.org remote-update.org output.org
  119. #+end_example
  120. * Dependencies
  121. To compile org-merge-driver, you may need: [[http://www.gnu.org/software/gnulib/][Gnulib]], [[http://flex.sourceforge.net/][Flex]] (not lex) and
  122. GNU Autotools installed. Install Flex and autotools using your desired
  123. package manager. To obtain gnulib follow the instructions below.
  124. ** To obtain Gnulib:
  125. You must obtain Gnulib by it's source code, there is no binary
  126. distribution. Through git or cvs:
  127. #+begin_src sh
  128. git clone git://git.savannah.gnu.org/gnulib.git
  129. # or
  130. cvs -d :pserver:anonymous@pserver.git.sv.gnu.org:/gnulib.git co -d gnulib HEAD
  131. #+end_src
  132. ** Reimporting gnulib-tool dependencies
  133. #+begin_src sh
  134. cd $(top_srcdir)
  135. /PATH/TO/GNULIB/gnulib-tool --add-import
  136. #+end_src
  137. ** Compiling
  138. To compile, run:
  139. #+begin_src sh
  140. autoreconf -i
  141. ./configure && make
  142. #+end_src