Difference between revisions of "Managing Local Changes with Mercurial Queues"
From gem5
(→Basic MQ commands) |
(→Mercurial Queues) |
||
Line 21: | Line 21: | ||
* Keep your local changes cleanly separated from upstream changes. | * Keep your local changes cleanly separated from upstream changes. | ||
* Prevent changes from being recorded in the project history until they are ready. | * Prevent changes from being recorded in the project history until they are ready. | ||
+ | |||
+ | === Basic MQ commands === | ||
+ | ===== Help Command ===== | ||
+ | * <code>hg help mq</code> --- Gives a list of mercurial queue commands and a brief description of each. | ||
+ | ===== Creating and handling patches ===== | ||
+ | * <code>hg qnew change1.patch -m "commit message"</code> --- Create a new patch named "change1.patch" with a commit message. | ||
+ | * <code> hg qpop</code> --- Pop topmost patch off the queue. | ||
+ | * <code> hg qpush</code> --- Push next patch in the series onto the queue. | ||
+ | * <code> hg qrefresh</code> --- Add any local changes to the topmost patch. | ||
+ | |||
+ | ===== Checking the status of patches in the queue ===== | ||
+ | * <code>hg qapplied</code> --- List all applied patches in the queue. | ||
+ | * <code>hg qseries</code> --- List all patches in the current series (this includes even patches that aren't applied). | ||
+ | * <code>hg qdiff</code> --- Display the diff for the applied patch at the top of the queue | ||
+ | ===== Adding patches from other queues ===== | ||
+ | * <code>hg qimport -e pre_existing.patch</code> --- Adds a pre-existing patch called "pre_existing.patch" to the local queue. | ||
== Example Mercurial Queue Use == | == Example Mercurial Queue Use == |
Revision as of 15:03, 9 March 2013
Repository Management Problem
gem5 users typically opt to freeze their repository at a particular changeset when starting a new research project. This approach has several downsides:
- It discourages users from contributing back any useful changes they may develop.
- If a useful change is added upstream, it's a long, tedious process to update.
If a user chooses to keep their local repository up-to-date with the source tree they typically use named branches and merge any upstream changes into their branches. This approach also has its downsides:
- If any local change needs to be updated, it requires a separate commit.
- If you have several small, unrelated changes, separate branches must be maintained.
- Upstream changes must be merged into the local branches.
A powerful tool that overcomes these problems is the mercurial queue extension.
Mercurial Queues
The mercurial queue extension is a powerful tool that allows you to:
- Manage small changes easily as a set of well-defined patches.
- Edit previous patches without having a new commit.
- Keep your local changes cleanly separated from upstream changes.
- Prevent changes from being recorded in the project history until they are ready.
Basic MQ commands
Help Command
-
hg help mq
--- Gives a list of mercurial queue commands and a brief description of each.
Creating and handling patches
-
hg qnew change1.patch -m "commit message"
--- Create a new patch named "change1.patch" with a commit message. -
hg qpop
--- Pop topmost patch off the queue. -
hg qpush
--- Push next patch in the series onto the queue. -
hg qrefresh
--- Add any local changes to the topmost patch.
Checking the status of patches in the queue
-
hg qapplied
--- List all applied patches in the queue. -
hg qseries
--- List all patches in the current series (this includes even patches that aren't applied). -
hg qdiff
--- Display the diff for the applied patch at the top of the queue
Adding patches from other queues
-
hg qimport -e pre_existing.patch
--- Adds a pre-existing patch called "pre_existing.patch" to the local queue.
Example Mercurial Queue Use
Enable the MQ extension
To enable the mercurial queue extension, simply add the following to your .hgrc file:
[extensions]
hgext.mq =
Simple workflow with MQs
Here is a simple example outlining basic MQ usage:
# clone a clean copy of gem5 hg clone http://repo.gem5.org/gem5 # initialize a new mercurial queue cd ./gem5 hg init --mq # make some local changes and turn them into a patch hg qnew change1.patch -m "cpu: made some changes to the cpu model" # we have some more changes that we want to turn into a separate patch hg qnew change2.patch -m "cache: made some changes to the cache" # now you want to make some more changes and include them in change1 # make sure change1 is at the top of the queue hg qtop >>> change2.patch # it's not, so we have to pop change2 off the queue hg qpop hg qtop >>> change1.patch # now it's the top patch. make the necessary changes and update hg qrefresh # re-apply change2 hg qpush # let's check that all of our patches are applied hg qapplied >>> change1.patch >>> change2.patch