vim_extended: change the patch URLs to diff the features against vim-with-runtime

[vim_extended.git] / README_gitrepo.txt

General information
===================

This README describes the usage of two git repositories for Vim. Since they
are related and hence the proceeding often overlaps, it makes sense to keep
them documented in a common README file. Furthermore they have the same
maintainer.

Although this file is meant to be readable in plain text, for consistency
regarding the formatting it was written keeping AsciiDoc syntax in mind.
Because of this it is now possible to convert it to HTML with a few errors,
which don't seem to affect the output:

        $ asciidoc -o readme_gitrepo.htm README_gitrepo.txt

Maintainer: Markus Heidelberg <markus.heidelberg@web.de>


Vim mainline
------------

This is a git repository of the official Vim sources from vim.org.
Additionally it offers a branch with the source tree including the latest
runtime and message files.

http://repo.or.cz/w/vim_mainline.git


Vim extended
------------

This is a git repository, which is meant to be an extension to the official
Vim from vim.org. It includes various extensions and features at a central
place that didn't yet get into the official version or even won't ever. Most
features had been sent as patches to the Vim mailing list.

See also the `Vim patches` site:
http://groups.google.com/group/vim_dev/web/vim-patches

Please note that there is no official support for this from Bram. The patches
will most likely work and they appear to do so for several people. However,
you might get unlucky and stuff breaks. At worst, you could lose your data.
So please be aware of this before going down this road.

Authors of such features are encouraged to develop directly on this repository
and push access would gladly be granted. That way more attention will be paid
to their features, which will lead to more testers and bug reports to get it
stable. This will raise the possibility to get it into the official Vim or at
least helps the feature to not get lost as a patch in the mailing list
archives.

http://repo.or.cz/w/vim_extended.git


For users
=========

Git configuration
-----------------

This will only cover some helpful settings, which you probably don't see while
getting started with git. Still, you should read the docs if you want to work
with git.

Enable colors:

        $ git config --global color.ui auto

Set your favorite editor for commit messages, interactive add/rebase and more:

        $ git config --global core.editor vim

Set your favorite merge tool for use with `git-mergetool`:

        $ git config --global merge.tool vimdiff
        $ git config --global merge.tool gvimdiff


The 'master' branch
-------------------

The master branch contains the latest runtime and message files and, at the
time of this writing, each feature branch for vim_extended. This may change if
features under active development are included in this repository.
Most of these steps are also valid or mandatory when creating a custom branch.

Get the whole repository over the git or HTTP protocol:

        $ git clone git://repo.or.cz/vim_mainline.git
        $ git clone http://repo.or.cz/r/vim_mainline.git

        $ git clone git://repo.or.cz/vim_extended.git
        $ git clone http://repo.or.cz/r/vim_extended.git

Enter the cloned and checked out repository:

        $ cd vim_mainline

        $ cd vim_extended

Choose Vim features, install path, ...
and commit your changes, since git refuses to merge files with local changes:

        $ vim src/Makefile src/feature.h
        $ git add src/Makefile src/feature.h
        $ git commit

Build and install as usual:

        $ make
        $ make install

Get updates from the repository and merge them into your local branch:

        $ git pull

Get updates from the repository and rebase your changes on top of them.
You might prefer this, because it makes all your changes to sit on top of the
history then:

        $ git pull --rebase

After the merge or rebase, solve possible conflicts by hand or with
`git-mergetool` which opens 3 windows with the base, local and remote version
of the file:

        $ git mergetool
        $ git commit


Creating a custom branch (vim_extended)
---------------------------------------

Normally, you don't need anything from this section as you already have the
full functionality of vim_extended when using the 'master' branch as described
above. In case you have problems with specific features, if a feature isn't
merged into 'master' or if you simply are interested in mixing your own Vim
this section is for you.
Most of the steps from the section before ("The 'master' branch") are also
valid or mandatory when creating a custom branch, if there is no corresponding
description in this section.

List all branches (local and remote):

        $ git branch -a

Create and check out your own custom branch 'custom',
based on 'vim' or 'vim-with-runtime':

        $ git checkout -b custom origin/vim

        $ git checkout -b custom origin/vim-with-runtime

Merge the feature branches you'd like to use:

        $ git merge origin/feat/rel-line-numbers
        $ git merge origin/feat/float-point-ext

NOTE: Don't merge multiple branches at the same time (octopus merge strategy).
      This may work without problems, but conflicts are more likely and could
      have been avoided with seperate merges. Furthermore appearing conflicts
      cannot be solved without significant effort.

So do *NOT* do this:

        $ git merge origin/feat/rel-line-numbers origin/feat/float-point-ext

If more than one feature has filled the extra_patches[] array from
src/version.c, merge conflicts will arise. These are trivial to solve by
concatenating the various description lines and won't arise a second time when
merging these branches again.
Of course merge conflicts can appear not only in this case and are normally
not solved by concatenating both sides (base and remote) of the merge.

Get updates from the repository and merge them into your local branch:

Since you have more than one remote upstream branch to merge into your custom
branch, simply doing `git pull` is not sufficient, since this would only merge
'vim' or 'vim-with-runtime', depending on how you initially created 'custom'.

What you have to do is firstly to download the new objects and update the
remote branches:

        $ git fetch

Then merge the feature branches:

        $ git merge origin/feat/rel-line-numbers
        $ git merge origin/feat/float-point-ext

And finally merge 'vim-with-runtime' for getting the latest runtime files, if
'custom' is based on it:

        $ git merge origin/vim-with-runtime

If 'custom' is based on 'vim', you don't have to merge, since all the commits
are already included in the feature branches. Merging won't hurt, though.

NOTE: The order of the merges can be important, you should merge the feature
      branches before 'vim-with-runtime'. If a feature conflicts with new Vim
      patches, the conflict will already be solved in its branch. If you
      firstly merge the feature branch, you won't get confronted with this
      conflict.


For developers
==============

This chapter is mainly intended for documenting the procedure to set up and
maintain the git repositories for Vim, especially the creation and integration
of the latest runtime files. It helps not forgetting the details and can be
reading for interested people.


The source tree
---------------

Applying the latest official patches
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To update the 'vim' branch to the latest patchlevel, there is a script
available in the 'stuff' branch, which automatically fetches the patch files
with `wget` and applies them. Author name/email/date for git are extracted
from the patch file and are also used for the committer identity. You don't
even have to save the script but can just use this commmand:

        $ git show origin/stuff:update-vim.sh | sh


The runtime files
-----------------

Getting the latest runtime files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The latest runtime files in the 'vim-runtime' branch are fetched via rsync
with the following command:

        $ rsync -avzcP --delete \
                --exclude="/dos/" \
                --include="/spell/en.*.spl" \
                --exclude="/spell/*.spl" \
                --include="/spell/en.*.sug" \
                --exclude="/spell/*.sug" \
                ftp.nluug.nl::Vim/runtime/ runtime

Therefore, a script is available in the 'stuff' branch, which automatically
commits and shows the changes after updating. You don't even have to save the
script but can just use this commmand:

        $ git show origin/stuff:update-vim-runtime.sh | sh


Merging the 'vim-runtime' branch
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To merge the 'vim-runtime' branch, which contains the latest runtime files,
into your custom branch yourself, you have to follow a special procedure.
Because 'vim-runtime' and 'vim' don't have a common ancestor, you can't simply
merge the 'vim-runtime' branch like the feature branches. That would only be
possible if the runtime/ directory of 'vim' was empty, more exactly: if it
doesn't include conflicting paths (equal filenames).

Basically, what you have to do initially is to artificially create a common
ancestor and then merge the runtime files from 'vim' and 'vim-runtime':

<1> Merge 'vim-runtime' without modifying the runtime files, neither in the
    index, nor in the working tree.

        $ git merge -s ours --no-commit origin/vim-runtime
        Automatic merge went well; stopped before committing as requested

<2> Perform a 3-way merge with the current 'HEAD' as `base` and `local` branch
    and 'vim-runtime' as `remote` branch. Update the working tree after the
    merge has processed the index. All the files only available in 'vim' are
    in `unmerged` state afterwards, all the files only available or modified
    in 'vim-runtime' in `new file` resp. `modified` state. You can verify this
    with `git-status`.
    Normally the runtime files of the 'vim-runtime' branch (from rsync) are
    always newer than the runtime files of the 'vim' branch. If this is not
    the case, e.g. the latest runtime files are not yet updated after an
    official patch containing runtime changes, this command will overwrite the
    changes the patch introduces and use the older files from 'vim-runtime'.
    But as soon as the changes are available in 'vim-runtime', your custom
    branch that merged the runtime branch will always contain the latest
    files, whether they are introduced with the official patches or the latest
    runtime files.
    Using 'HEAD' both for `base` and `local` branch also helps with
    circumventing merge conflicts.
    So this may only be a little problem when starting your custom runtime
    merge, but it's the easiest solution to merge the runtime files without
    getting frustrated by merge conflicts.

        $ git read-tree -u -m HEAD HEAD origin/vim-runtime

<3> Merge the files that are in `unmerged` state. Since git thinks the
    unmerged files are deleted in 'vim-runtime', we have to use a custom merge
    program `git-merge-vim-runtime.sh`. This will prevent the merge process
    from deleting the files only available in the 'vim' branch and
    additionally output a message for every file that is affected. This has
    the drawback that files which are actually deleted in 'vim-runtime' and
    not just unavailable aren't deleted in the result of the initial merge.
    This should only be a small problem compared to the gain of the ease of
    the automatic merge.
    After these steps, there should be no unmerged files left, any more.

        $ git merge-index git-merge-vim-runtime.sh -a
        handled and kept by git-merge-vim-runtime.sh: runtime/doc.info
        [...]

<4> Record the result to the repository, this creates a merge commit.

        $ git commit

All the following merges just need this ordinary command:

        $ git merge origin/vim-runtime


There is a merge strategy `subtree` which was tried first, but it caused some
problems:

* The runtime/ directory wasn't empty, so using `git-read-tree` with 1 tree as
  described in howto/using-merge-subtree.txt didn't work.

* The options `-m` and `--prefix=runtime/` of `git-read-tree` are mutually
  exclusive, so this attempt didn't work.

And it didn't offer advantages, but rather disadvantages:

* You have overhead due to copying files from ./runtime/ to ./ and vice versa
  when switching branches.

* You have to remember using `git-merge` with the `-s subtree` option
  everytime you merge 'vim-runtime'.

* It's simply not necessary. Since the runtime files don't belong to another
  project, but to Vim, we have the freedom to save the runtime files in the
  runtime/ subdirectory.


Creating a custom runtime branch
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can also create your custom runtime branch from scratch, without the use
of the provided 'vim-runtime' branch.

Set the current HEAD to a new, not yet existing branch:

        $ git symbolic-ref HEAD refs/heads/custom-runtime

Remove/unstage all files from the index:

        $ git rm --cached -r .

Remove all files from the working directory:

        $ git clean -f -d -x

Now you can add the runtime files and do your initial commit. This will also
create the branch 'custom-runtime'.


The message files
-----------------

Creating the 'vim-messages' branch, getting the latest message files with
translated Vim messages and merging the branch into your custom branch works
in the same manner as for the runtime files, which is described in the section
"The runtime files".

You merely have to pay attention to the differences. It should suffice to
substitute

* the `vim-runtime` branch with `vim-messages`

* the `runtime/` directory with `src/po/`

* the rsync server path `ftp.nluug.nl::Vim/runtime/` with
  `ftp.nluug.nl::Vim/messages/`

* the update script `update-vim-runtime.sh` with `update-vim-messages.sh`

* the merge program  `git-merge-vim-runtime.sh` with
  `git-merge-vim-messages.sh`

* the remaining words `runtime` with `message(s)` in the text


////////////////
vim: ft=asciidoc
////////////////