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
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 <markus.heidelberg@web.de>
22 This is a git repository of the official Vim sources from vim.org.
23 Additionally it offers a branch with the source tree including the latest
24 runtime and message files.
26 http://repo.or.cz/w/vim_mainline.git
32 This is a git repository, which is meant to be an extension to the official
33 Vim from vim.org. 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:
38 http://groups.google.com/group/vim_dev/web/vim-patches
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
52 http://repo.or.cz/w/vim_extended.git
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
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
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://repo.or.cz/vim_mainline.git
90 $ git clone http://repo.or.cz/r/vim_mainline.git
92 $ git clone git://repo.or.cz/vim_extended.git
93 $ git clone http://repo.or.cz/r/vim_extended.git
95 Enter the cloned and checked out repository:
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
108 Build and install as usual:
113 Get updates from the repository and merge them into your local branch:
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
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
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):
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.
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
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
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.
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/stuff:update-vim.sh | sh
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 \
241 --include="/spell/en.*.spl" \
242 --exclude="/spell/*.spl" \
243 --include="/spell/en.*.sug" \
244 --exclude="/spell/*.sug" \
245 ftp.nluug.nl::Vim/runtime/ 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/stuff:update-vim-runtime.sh | 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
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
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 `git-merge-vim-runtime.sh`. 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
305 After these steps, there should be no unmerged files left, any more.
307 $ git merge-index git-merge-vim-runtime.sh -a
308 handled and kept by git-merge-vim-runtime.sh: runtime/doc.info
311 <4> Record the result to the repository, this creates a merge 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
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:
360 Now you can add the runtime files and do your initial commit. This will also
361 create the branch 'custom-runtime'.
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
372 You merely have to pay attention to the differences. It should suffice to
375 * the `vim-runtime` branch with `vim-messages`
377 * the `runtime/` directory with `src/po/`
379 * the rsync server path `ftp.nluug.nl::Vim/runtime/` with
380 `ftp.nluug.nl::Vim/messages/`
382 * the update script `update-vim-runtime.sh` with `update-vim-messages.sh`
384 * the merge program `git-merge-vim-runtime.sh` with
385 `git-merge-vim-messages.sh`
387 * the remaining words `runtime` with `message(s)` in the text