The Vim Mercurial repository
Vim is available through Mercurial.
This is a mirror of the official repository at GitHub.
You can use this if you prefer Mercurial over git.
You can obtain Vim for the first time with this command:
hg clone https://hg.256bit.org/vim
And update to the latest version with:
cd vim
hg pull
hg update
If you don't know how to use Mercurial, you'll probably want to look at the
Guide.
Either of the two sites should work. 256bit.org is a single server
maintained by Christian Brabandt.
Build and install Vim as usual. If you are happy with the defaults:
cd src
make distclean # if you build Vim before
make
sudo make install
If you have local changes you may need to merge.
If you are sure you can discard local changes (e.g. if you were just trying a
patch),you can use:
hg update -C
Browsing the Vim sources
You can browse the Mercurial repository online. This shows the most recent version of the files, including runtime files.
Your own patches on top of the distributed version
Mercurial queues (mq) is an extension to Mercurial, that allows to maintain
patches on top of an existing Mercurial repository (that are committed on top of
the repository) and they can be refreshed, reordered and removed thus making
the changes mutable (as opposed to the immutable commits in the repository).
This allows for a flexible development (but is not strictly necessary for
creating patches).
Make sure, you have Mercurial installed (On Debian, you can use apt-get install Mercurial to have it installed).
1. Clone the repository
~/code $ hg clone https://hg.256bit.org/vim
This will checkout the Vim source code into ~/code/vim
To make developing easier, I recommend to enable the mq extension. For that
edit the hgrc config file and enable the mq extension. Also make sure, you are
using git extended diff mode.
~/code/vim $ vim .hg/hgrc
[extensions]
mq=
[diff]
git = True
2. Create a new patch
2.1 Simple case
For single changes you can simply make your changes, to all files in the
repository. When you are done, you can create a patch using hg diff.
~/code/vim $ [edit files]
~/code/vim $ hg diff > fix_annoying_bug.diff
Now send your patch file (fix_annoying_bug.diff) to the vim_dev list (but see
below).
If you are trying to change several things, it might be easier to use the mq
extension for handling those patches independently.
2.2 Using the Mq extension
Let's say you want to add some new fancy feature to your local copy of Vim.
First start by creating a new empty patch.
~/code/vim/src $ hg qnew my_fancy_feature
Now go ahead and make the changes to the source code as needed. Once you are
finished, you must "refresh" your top-level patch. Do this by
~/code/vim/src $ hg qrefresh
All changes that have been accumulated to the current repository will be stored
in the current top level patch and the repository will be clean again. Note,
how hg diff does not notice any changes anymore.
Once you develop, you might notice a small bug (or even a typo), that needs to
be fixed but does not belong to the current work of adding your fancy feature.
So you save your work, refresh the current patch and fix that small bug with a
new patch:
~/code/vim $ hg qrefresh
~/code/vim $ hg qpop
popping my_fancy_feature
patch queue now empty
~/code/vim $ hg qnew fix_typo
[... fix bug ...]
~/code/vim $ hg qrefresh
Now you can extract that patch and send it to the vim-dev mailinglist to have
the patch reviewed and put into the todo list of Bram (but see below):
~/code/vim $ hg qdiff > $(hg qtop).diff
... send patch to Bram, continue working on your new feature
~/code/vim $ hg qpush
applying my_fancy_feature
now at: my_fancy_feature
As you work on your new patch, you might want to add another feature, that
you think is missing. So go ahead and create a new patch.
As you create patches you'll start creating a patch queue, each patch being
applied on the result of the previous patch. To move between those patches, you
can use the qpush (push next patch on the stack) and qpop commands (remove
current patch from stack and continue working on the previous patch).
It is dangerous to pull changes from the central vim repository and
update your working copy at the same time (-u flag), while there are
still patches applied. Instead, make sure to pop all patches, update the
repository and push your patches again:
~/code/vim $ hg qpop -a
popping my_fancy_feature
patch queue now empty
~/code/vim $ hg pull -u
~/code/vim $ hg qpush my_fancy_feature
After the last step, you might need to fix merge conflicts, that happened
because of changes to the Vim repository and your patch changing the same file.
If you have changed the patch, you need to qrefresh your patch, so it will
apply cleanly on top of the changes to the Vim repository.
Before publishing your patches
A few comments to help have your patch be easily accepted:
Make sure your patch actually works
The code should be readable
Simple things first, don't try to fix everything in one single patch but rather create several small patches (This allows for easier review)
Make sure the all tests still pass (make test) and if possible add new tests for your feature/bugfix (look into src/testdir directory for existing tests and extend them if possible). For newly created testfiles, give it meaningful names.
Try hard not to break anything (compile with different features, test, watch out for warnings (uncomment #FLAGS = -g -DDEBUG -Wall -Wshadow -Wmissing-prototypes in the src directory Makefile. Yes this could be the first patch in your patch queue)
test your patch by running under valgrind and make sure, it doesn't leak memory.
Document your changes (also update the runtime documentation that comes with Vim and any related vim script e.g. optwin.vim, syntax or filetype plugins).
Try to follow the advises given in develop.txt (:h develop.txt)
Come up with a good usecase for your new feature (e.g. make Bram want to include your feature ;))
If possible try not to introduce new options ;)
After publishing your patches
When you send out your patch and don't get immediate feedback, don't
despair. Bram is overloaded with work so just be patient. Usually your patch
will be included into the todo list (:h todo.txt) and will be included into Vim
eventually.
React to feedback and try to fix all mentioned issues. Beware, discussions
might wander away from your original topic you originally addressed, don't let
that scare you away!
While the patch is pending, update the Vim repository as new patches are
sent out, keep your patch in sync and fix merge conflicts that may occur. After
a reasonable time, resend your resynced patch again.
MQ commands
When the mq extension is enabled, mercurial enables several new commands, all
starting with q Here are some useful commands:
hg qpush (push next patch on the stack)
hg qpop (pop patch from the stack)
hg qnew (create new empty patch in the stack)
hg qimport (import existing patch as new mq patch)
hg qrefresh (update current parent with the changes in the work tree)
hg qdiff (displays the diff between the work tree and the current patch)
hg qtop (displays the name of the current changeset)
hg qseries (displays the list of patches available)
hg qdelete (deletes an unapplied patch from the queue. Can not be restored)
Caution:
Don't use MQ in a repository anyone might pull from
(unless you hide your mq changesets away using the secret phase).
Create new patches from a clean working tree (changes will otherwise be
contained into that new patch which might be undesired).
before pulling in new changes into the repository make sure to pop all
current patches (e.g. do hg qpop -a; hg fetch; hg qpush -a)
Thanks to Christian Brabandt for writing the original version of this text.
If you have suggestions for improvement of this page please send a message to
the vim-dev maillist.
|
