vim_mainline and vim_extended are discontinued
[vim_extended.git] / README_gitrepo.txt
1 General information
2 ===================
3
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.
8
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:
13
14         $ asciidoc -o readme_gitrepo.htm README_gitrepo.txt
15
16 Maintainer: Markus Heidelberg <markus.heidelberg@web.de>
17
18
19 Vim mainline
20 ------------
21
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.
25
26 http://repo.or.cz/w/vim_mainline.git
27
28
29 Vim extended
30 ------------
31
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.
36
37 See also the `Vim patches` site:
38 http://groups.google.com/group/vim_dev/web/vim-patches
39
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.
44
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.
51
52 http://repo.or.cz/w/vim_extended.git
53
54
55 For users
56 =========
57
58 Git configuration
59 -----------------
60
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.
64
65 Enable colors:
66
67         $ git config --global color.ui auto
68
69 Set your favorite editor for commit messages, interactive add/rebase and more:
70
71         $ git config --global core.editor vim
72
73 Set your favorite merge tool for use with `git-mergetool`:
74
75         $ git config --global merge.tool vimdiff
76         $ git config --global merge.tool gvimdiff
77
78
79 The 'master' branch
80 -------------------
81
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.
86
87 Get the whole repository over the git or HTTP protocol:
88
89         $ git clone git://repo.or.cz/vim_mainline.git
90         $ git clone http://repo.or.cz/r/vim_mainline.git
91
92         $ git clone git://repo.or.cz/vim_extended.git
93         $ git clone http://repo.or.cz/r/vim_extended.git
94
95 Enter the cloned and checked out repository:
96
97         $ cd vim_mainline
98
99         $ cd vim_extended
100
101 Choose Vim features, install path, ...
102 and commit your changes, since git refuses to merge files with local changes:
103
104         $ vim src/Makefile src/feature.h
105         $ git add src/Makefile src/feature.h
106         $ git commit
107
108 Build and install as usual:
109
110         $ make
111         $ make install
112
113 Get updates from the repository and merge them into your local branch:
114
115         $ git pull
116
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:
120
121         $ git pull --rebase
122
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:
126
127         $ git mergetool
128         $ git commit
129
130
131 Creating a custom branch (vim_extended)
132 ---------------------------------------
133
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.
142
143 List all branches (local and remote):
144
145         $ git branch -a
146
147 Create and check out your own custom branch 'custom',
148 based on 'vim' or 'vim-with-runtime':
149
150         $ git checkout -b custom origin/vim
151
152         $ git checkout -b custom origin/vim-with-runtime
153
154 Merge the feature branches you'd like to use:
155
156         $ git merge origin/feat/rel-line-numbers
157         $ git merge origin/feat/float-point-ext
158
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.
163
164 So do *NOT* do this:
165
166         $ git merge origin/feat/rel-line-numbers origin/feat/float-point-ext
167
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.
174
175 Get updates from the repository and merge them into your local branch:
176
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'.
180
181 What you have to do is firstly to download the new objects and update the
182 remote branches:
183
184         $ git fetch
185
186 Then merge the feature branches:
187
188         $ git merge origin/feat/rel-line-numbers
189         $ git merge origin/feat/float-point-ext
190
191 And finally merge 'vim-with-runtime' for getting the latest runtime files, if
192 'custom' is based on it:
193
194         $ git merge origin/vim-with-runtime
195
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.
198
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.
204
205
206 For developers
207 ==============
208
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.
213
214
215 The source tree
216 ---------------
217
218 Applying the latest official patches
219 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
220
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:
226
227         $ git show origin/stuff:update-vim.sh | sh
228
229
230 The runtime files
231 -----------------
232
233 Getting the latest runtime files
234 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
235
236 The latest runtime files in the 'vim-runtime' branch are fetched via rsync
237 with the following command:
238
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                 ftp.nluug.nl::Vim/runtime/ runtime
246
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:
250
251         $ git show origin/stuff:update-vim-runtime.sh | sh
252
253
254 Merging the 'vim-runtime' branch
255 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
256
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).
263
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':
266
267 <1> Merge 'vim-runtime' without modifying the runtime files, neither in the
268     index, nor in the working tree.
269
270         $ git merge -s ours --no-commit origin/vim-runtime
271         Automatic merge went well; stopped before committing as requested
272
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.
293
294         $ git read-tree -u -m HEAD HEAD origin/vim-runtime
295
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
304     the automatic merge.
305     After these steps, there should be no unmerged files left, any more.
306
307         $ git merge-index git-merge-vim-runtime.sh -a
308         handled and kept by git-merge-vim-runtime.sh: runtime/doc.info
309         [...]
310
311 <4> Record the result to the repository, this creates a merge commit.
312
313         $ git commit
314
315 All the following merges just need this ordinary command:
316
317         $ git merge origin/vim-runtime
318
319
320 There is a merge strategy `subtree` which was tried first, but it caused some
321 problems:
322
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.
325
326 * The options `-m` and `--prefix=runtime/` of `git-read-tree` are mutually
327   exclusive, so this attempt didn't work.
328
329 And it didn't offer advantages, but rather disadvantages:
330
331 * You have overhead due to copying files from ./runtime/ to ./ and vice versa
332   when switching branches.
333
334 * You have to remember using `git-merge` with the `-s subtree` option
335   everytime you merge 'vim-runtime'.
336
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.
340
341
342 Creating a custom runtime branch
343 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
344
345 You can also create your custom runtime branch from scratch, without the use
346 of the provided 'vim-runtime' branch.
347
348 Set the current HEAD to a new, not yet existing branch:
349
350         $ git symbolic-ref HEAD refs/heads/custom-runtime
351
352 Remove/unstage all files from the index:
353
354         $ git rm --cached -r .
355
356 Remove all files from the working directory:
357
358         $ git clean -f -d -x
359
360 Now you can add the runtime files and do your initial commit. This will also
361 create the branch 'custom-runtime'.
362
363
364 The message files
365 -----------------
366
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".
371
372 You merely have to pay attention to the differences. It should suffice to
373 substitute
374
375 * the `vim-runtime` branch with `vim-messages`
376
377 * the `runtime/` directory with `src/po/`
378
379 * the rsync server path `ftp.nluug.nl::Vim/runtime/` with
380   `ftp.nluug.nl::Vim/messages/`
381
382 * the update script `update-vim-runtime.sh` with `update-vim-messages.sh`
383
384 * the merge program  `git-merge-vim-runtime.sh` with
385   `git-merge-vim-messages.sh`
386
387 * the remaining words `runtime` with `message(s)` in the text
388
389
390 ////////////////
391 vim: ft=asciidoc
392 ////////////////