update-vim-runtime: take Bram as author and committer

[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 including merely the latest runtime files,
which can be merged into the source tree. For convenience the resulting tree
is already available as a separate branch.

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 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.

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


Basic use
=========

Git tips
--------

This will only cover some helpful commands/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 merge tool for use with `git-mergetool`:

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

List all branches (remote and local):

        $ git branch -a


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

The master branch contains the latest runtime 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.

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

Edit, build and install as usual:

        $ vim; make; make install

Get updates from the repository:

        $ git pull


Advanced use
============

Normally, you don't need anything from this part of the README as you already
have the full functionality of vim_extended resp. vim_mainline when using the
'master' branch as described in "Basic use" 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.


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

Create and check out your own custom branch 'custom',
based von '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 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

After the merge, 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

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.


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'.


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

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