vim_mainline and vim_extended are discontinued
[vim_extended.git] / README_gitrepo.txt
1 General information
2 ===================
4 This README describes the usage of two git repositories for Vim. Since they
5 are related and hence the proceeding often overlaps, it makes sense to keep
6 them documented in a common README file. Furthermore they have the same
7 maintainer.
9 Although this file is meant to be readable in plain text, for consistency
10 regarding the formatting it was written keeping AsciiDoc syntax in mind.
11 Because of this it is now possible to convert it to HTML with a few errors,
12 which don't seem to affect the output:
14         $ asciidoc -o readme_gitrepo.htm README_gitrepo.txt
16 Maintainer: Markus Heidelberg <>
19 Vim mainline
20 ------------
22 This is a git repository of the official Vim sources from
23 Additionally it offers a branch with the source tree including the latest
24 runtime and message files.
29 Vim extended
30 ------------
32 This is a git repository, which is meant to be an extension to the official
33 Vim from It includes various extensions and features at a central
34 place that didn't yet get into the official version or even won't ever. Most
35 features had been sent as patches to the Vim mailing list.
37 See also the `Vim patches` site:
40 Please note that there is no official support for this from Bram. The patches
41 will most likely work and they appear to do so for several people. However,
42 you might get unlucky and stuff breaks. At worst, you could lose your data.
43 So please be aware of this before going down this road.
45 Authors of such features are encouraged to develop directly on this repository
46 and push access would gladly be granted. That way more attention will be paid
47 to their features, which will lead to more testers and bug reports to get it
48 stable. This will raise the possibility to get it into the official Vim or at
49 least helps the feature to not get lost as a patch in the mailing list
50 archives.
55 For users
56 =========
58 Git configuration
59 -----------------
61 This will only cover some helpful settings, which you probably don't see while
62 getting started with git. Still, you should read the docs if you want to work
63 with git.
65 Enable colors:
67         $ git config --global color.ui auto
69 Set your favorite editor for commit messages, interactive add/rebase and more:
71         $ git config --global core.editor vim
73 Set your favorite merge tool for use with `git-mergetool`:
75         $ git config --global merge.tool vimdiff
76         $ git config --global merge.tool gvimdiff
79 The 'master' branch
80 -------------------
82 The master branch contains the latest runtime and message files and, at the
83 time of this writing, each feature branch for vim_extended. This may change if
84 features under active development are included in this repository.
85 Most of these steps are also valid or mandatory when creating a custom branch.
87 Get the whole repository over the git or HTTP protocol:
89         $ git clone git://
90         $ git clone
92         $ git clone git://
93         $ git clone
95 Enter the cloned and checked out repository:
97         $ cd vim_mainline
99         $ cd vim_extended
101 Choose Vim features, install path, ...
102 and commit your changes, since git refuses to merge files with local changes:
104         $ vim src/Makefile src/feature.h
105         $ git add src/Makefile src/feature.h
106         $ git commit
108 Build and install as usual:
110         $ make
111         $ make install
113 Get updates from the repository and merge them into your local branch:
115         $ git pull
117 Get updates from the repository and rebase your changes on top of them.
118 You might prefer this, because it makes all your changes to sit on top of the
119 history then:
121         $ git pull --rebase
123 After the merge or rebase, solve possible conflicts by hand or with
124 `git-mergetool` which opens 3 windows with the base, local and remote version
125 of the file:
127         $ git mergetool
128         $ git commit
131 Creating a custom branch (vim_extended)
132 ---------------------------------------
134 Normally, you don't need anything from this section as you already have the
135 full functionality of vim_extended when using the 'master' branch as described
136 above. In case you have problems with specific features, if a feature isn't
137 merged into 'master' or if you simply are interested in mixing your own Vim
138 this section is for you.
139 Most of the steps from the section before ("The 'master' branch") are also
140 valid or mandatory when creating a custom branch, if there is no corresponding
141 description in this section.
143 List all branches (local and remote):
145         $ git branch -a
147 Create and check out your own custom branch 'custom',
148 based on 'vim' or 'vim-with-runtime':
150         $ git checkout -b custom origin/vim
152         $ git checkout -b custom origin/vim-with-runtime
154 Merge the feature branches you'd like to use:
156         $ git merge origin/feat/rel-line-numbers
157         $ git merge origin/feat/float-point-ext
159 NOTE: Don't merge multiple branches at the same time (octopus merge strategy).
160       This may work without problems, but conflicts are more likely and could
161       have been avoided with seperate merges. Furthermore appearing conflicts
162       cannot be solved without significant effort.
164 So do *NOT* do this:
166         $ git merge origin/feat/rel-line-numbers origin/feat/float-point-ext
168 If more than one feature has filled the extra_patches[] array from
169 src/version.c, merge conflicts will arise. These are trivial to solve by
170 concatenating the various description lines and won't arise a second time when
171 merging these branches again.
172 Of course merge conflicts can appear not only in this case and are normally
173 not solved by concatenating both sides (base and remote) of the merge.
175 Get updates from the repository and merge them into your local branch:
177 Since you have more than one remote upstream branch to merge into your custom
178 branch, simply doing `git pull` is not sufficient, since this would only merge
179 'vim' or 'vim-with-runtime', depending on how you initially created 'custom'.
181 What you have to do is firstly to download the new objects and update the
182 remote branches:
184         $ git fetch
186 Then merge the feature branches:
188         $ git merge origin/feat/rel-line-numbers
189         $ git merge origin/feat/float-point-ext
191 And finally merge 'vim-with-runtime' for getting the latest runtime files, if
192 'custom' is based on it:
194         $ git merge origin/vim-with-runtime
196 If 'custom' is based on 'vim', you don't have to merge, since all the commits
197 are already included in the feature branches. Merging won't hurt, though.
199 NOTE: The order of the merges can be important, you should merge the feature
200       branches before 'vim-with-runtime'. If a feature conflicts with new Vim
201       patches, the conflict will already be solved in its branch. If you
202       firstly merge the feature branch, you won't get confronted with this
203       conflict.
206 For developers
207 ==============
209 This chapter is mainly intended for documenting the procedure to set up and
210 maintain the git repositories for Vim, especially the creation and integration
211 of the latest runtime files. It helps not forgetting the details and can be
212 reading for interested people.
215 The source tree
216 ---------------
218 Applying the latest official patches
219 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
221 To update the 'vim' branch to the latest patchlevel, there is a script
222 available in the 'stuff' branch, which automatically fetches the patch files
223 with `wget` and applies them. Author name/email/date for git are extracted
224 from the patch file and are also used for the committer identity. You don't
225 even have to save the script but can just use this commmand:
227         $ git show origin/ | sh
230 The runtime files
231 -----------------
233 Getting the latest runtime files
234 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
236 The latest runtime files in the 'vim-runtime' branch are fetched via rsync
237 with the following command:
239         $ rsync -avzcP --delete \
240                 --exclude="/dos/" \
241                 --include="/spell/en.*.spl" \
242                 --exclude="/spell/*.spl" \
243                 --include="/spell/en.*.sug" \
244                 --exclude="/spell/*.sug" \
245        runtime
247 Therefore, a script is available in the 'stuff' branch, which automatically
248 commits and shows the changes after updating. You don't even have to save the
249 script but can just use this commmand:
251         $ git show origin/ | sh
254 Merging the 'vim-runtime' branch
255 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
257 To merge the 'vim-runtime' branch, which contains the latest runtime files,
258 into your custom branch yourself, you have to follow a special procedure.
259 Because 'vim-runtime' and 'vim' don't have a common ancestor, you can't simply
260 merge the 'vim-runtime' branch like the feature branches. That would only be
261 possible if the runtime/ directory of 'vim' was empty, more exactly: if it
262 doesn't include conflicting paths (equal filenames).
264 Basically, what you have to do initially is to artificially create a common
265 ancestor and then merge the runtime files from 'vim' and 'vim-runtime':
267 <1> Merge 'vim-runtime' without modifying the runtime files, neither in the
268     index, nor in the working tree.
270         $ git merge -s ours --no-commit origin/vim-runtime
271         Automatic merge went well; stopped before committing as requested
273 <2> Perform a 3-way merge with the current 'HEAD' as `base` and `local` branch
274     and 'vim-runtime' as `remote` branch. Update the working tree after the
275     merge has processed the index. All the files only available in 'vim' are
276     in `unmerged` state afterwards, all the files only available or modified
277     in 'vim-runtime' in `new file` resp. `modified` state. You can verify this
278     with `git-status`.
279     Normally the runtime files of the 'vim-runtime' branch (from rsync) are
280     always newer than the runtime files of the 'vim' branch. If this is not
281     the case, e.g. the latest runtime files are not yet updated after an
282     official patch containing runtime changes, this command will overwrite the
283     changes the patch introduces and use the older files from 'vim-runtime'.
284     But as soon as the changes are available in 'vim-runtime', your custom
285     branch that merged the runtime branch will always contain the latest
286     files, whether they are introduced with the official patches or the latest
287     runtime files.
288     Using 'HEAD' both for `base` and `local` branch also helps with
289     circumventing merge conflicts.
290     So this may only be a little problem when starting your custom runtime
291     merge, but it's the easiest solution to merge the runtime files without
292     getting frustrated by merge conflicts.
294         $ git read-tree -u -m HEAD HEAD origin/vim-runtime
296 <3> Merge the files that are in `unmerged` state. Since git thinks the
297     unmerged files are deleted in 'vim-runtime', we have to use a custom merge
298     program ``. This will prevent the merge process
299     from deleting the files only available in the 'vim' branch and
300     additionally output a message for every file that is affected. This has
301     the drawback that files which are actually deleted in 'vim-runtime' and
302     not just unavailable aren't deleted in the result of the initial merge.
303     This should only be a small problem compared to the gain of the ease of
304     the automatic merge.
305     After these steps, there should be no unmerged files left, any more.
307         $ git merge-index -a
308         handled and kept by runtime/
309         [...]
311 <4> Record the result to the repository, this creates a merge commit.
313         $ git commit
315 All the following merges just need this ordinary command:
317         $ git merge origin/vim-runtime
320 There is a merge strategy `subtree` which was tried first, but it caused some
321 problems:
323 * The runtime/ directory wasn't empty, so using `git-read-tree` with 1 tree as
324   described in howto/using-merge-subtree.txt didn't work.
326 * The options `-m` and `--prefix=runtime/` of `git-read-tree` are mutually
327   exclusive, so this attempt didn't work.
329 And it didn't offer advantages, but rather disadvantages:
331 * You have overhead due to copying files from ./runtime/ to ./ and vice versa
332   when switching branches.
334 * You have to remember using `git-merge` with the `-s subtree` option
335   everytime you merge 'vim-runtime'.
337 * It's simply not necessary. Since the runtime files don't belong to another
338   project, but to Vim, we have the freedom to save the runtime files in the
339   runtime/ subdirectory.
342 Creating a custom runtime branch
343 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
345 You can also create your custom runtime branch from scratch, without the use
346 of the provided 'vim-runtime' branch.
348 Set the current HEAD to a new, not yet existing branch:
350         $ git symbolic-ref HEAD refs/heads/custom-runtime
352 Remove/unstage all files from the index:
354         $ git rm --cached -r .
356 Remove all files from the working directory:
358         $ git clean -f -d -x
360 Now you can add the runtime files and do your initial commit. This will also
361 create the branch 'custom-runtime'.
364 The message files
365 -----------------
367 Creating the 'vim-messages' branch, getting the latest message files with
368 translated Vim messages and merging the branch into your custom branch works
369 in the same manner as for the runtime files, which is described in the section
370 "The runtime files".
372 You merely have to pay attention to the differences. It should suffice to
373 substitute
375 * the `vim-runtime` branch with `vim-messages`
377 * the `runtime/` directory with `src/po/`
379 * the rsync server path `` with
380   ``
382 * the update script `` with ``
384 * the merge program  `` with
385   ``
387 * the remaining words `runtime` with `message(s)` in the text
390 ////////////////
391 vim: ft=asciidoc
392 ////////////////