Differences between revisions 8 and 11 (spanning 3 versions)
⇤ ← Revision 8 as of 2006-02-08 23:14:13 →
Size: 1325
Editor: DanielSantaCruz
Comment:
← Revision 11 as of 2006-02-16 19:17:26 → ⇥
Size: 5430
Editor: DanielSantaCruz
Comment:
Deletions are marked like this. Additions are marked like this.
Line 5: Line 5:
This page will need to be moved to a more permanent place once this tutorial is completed. Please help me with a good name for the page! The text below this line needs to be moved to a more permanent place once this tutorial is completed. Please help me with a good name for the page!
Line 9: Line 9:
Outline:
 * Why the heck would I want to use mq?
 * How is mq a "stack"? (are there really 2 stacks?)
 * Tutorial on using mq:
   * Installing mq
   * Getting a repo to do work on (use hg for a sample!)
   * Initializing mq on that repo (make it versioned)
   * Creating and editing a patch
     * qnew seems to push the patch to the repo stack.
     * qrefresh refreshes the patch, not only in the patches folder, but also in the repo.
     * use qnew -m "message" to control the message that will be used when commiting this patch to the repo.
   * Creating another patch
   * Version my patches so far (qcommit)
   * Spliting the previous patch (edit patch to leave out 2nd patch and do something like: patch -p1 -R < p1b ; hg qrefresh; hg qnew -M "foo" p1b ; patch -p1 < p1b)
   * Propagating my patches (push all patches we wish to "publish", hg mail that)
   * Pointers to other docos: MqExtension, see the {{{hgext/mq-howto}}} file.
Line 26: Line 10:
 * Questions:
   * Why does qrefresh take out the {{{[mq]:}}} substring from the changeset message in the repo?		 [[TableOfContents]]

== Why the heck would I want to use mq? ==

Show how mq is a solution to a problem and not a solution looking for a problem. The quilt pdf paper seems to be a good starting point.

== Installing mq ==

Follow the instructions in MqExtensionInstallHowTo

== What is all this talk about a stack? ==

Before we begin this tutorial, there are 3 things to keep track of when using the mq extension: the {{{localRepository}}}, the {{{mqPatches}}}, and the {{{workingDirectory}}}. When the mq documentation talks about a stack, it refers to the {{{localRepository}}} as a stack on which one can push/pop patches. {{{mqPatches}}} works like a queue, where the first patch you create would be the first patch to be pushed to the {{{localRepository}}} stack.

== Working with mq ==

<maybe put a table of contents here?>

=== Get a repository to do work on ===
This can be done by either initializing a brand new Mercurial repository yourself (ie. using {{{hg init}}}) or by cloning an existing repository. For this tutorial we will use the same repository used in the ['Mercurial'] ['Tutorial'].

{{{
hg clone http://www.selenic.com/repo/hello
}}}

=== Indicate that you want to use mq on this repository ===
mq provides the {{{qinit}}} command to initialize mq on a given repository. To start using mq on our recently cloned repository use:

{{{
cd hello
hg qinit -c
}}}

You can type {{{hg help qinit}}} to see help on the specifics of the command. Here we are telling mq to not only initialize an mq queue, but also to keep itself versioned with ['Mercurial']. This mq does by creating a new repository for use by itself under {{{hello/.hg/patches}}}.

=== Creating and editing a patch ===
Now we are ready to start hacking the {{{hello}}} code away. The first step in to create a "patch holder" which will contain the changes that we make. To do this execute:

{{{
hg qnew -m "Change language of salutation" newHelloString
}}}

The {{{-m}}} flag allows you to pass the message to be used in the changeset. This is the same message that would be placed if you did a {{{hg commit -m}}}.

Let's now edit {{{hello.c}}} and change line 14 so that you end up with a file that looks like this:

{{{#!cplusplus start=12
int main(int argc, char **argv)
{
        printf("Howdy there!\n");
        return 0;
}
}}}

At this point our changes are only recorded in the {{{workingDirectory}}}. To verify this we can execute {{{hg status}}} and see that the {{{hello.c}}} file has been marked as modified. We will record the changes into our current patch ({{{newHelloString}}}) by executing {{{hg qrefresh}}}. If we run {{{hg status}}} again, we will see that there are no pending changes in our {{{workingDirectory}}}. Let's ask mq what patches it has push on top of the repository stack by running {{{hg qapplied}}}. mq tells us that it has applied {{{newHelloString}}}, and we can verify this by running {{{hg log}}} and noticing that the repository has that patch in it's history. [Hmmm... where do we need to talk about push/pop?]

=== Dealing with more than one patch on our patch queue ===

We now realize that our {{{hello.c}}} file needs to be able to tell us who it is, and in good form, we don't want to mix our changes to the salutation with this new modification (the why of this is beyond the scope of this tutorial). So we create a new patch and make the changes:

{{{
hg qnew -m "Have hello say who he is" sayName
}}}

... edit {{{hello.c}}} and add line 15 below to it

{{{#!cplusplus start=12
int main(int argc, char **argv)
{
        printf("Howdy there!\n");
        printf("My name is 'hello.c'!!!\n");
        return 0;
}
}}}

Lets commit our changes to the mq queue by running {{{hg qrefresh}}}. We can now see that mq has applied the last two patches to the repository by running both {{{hg qapplied}}} and {{{hg log}}}.

=== Versioning our patch set ===

Put documentation on how to do this.

=== Synchronizing with upstream ===

Time goes by and we need to synchronize with upstream. Before we do this, we need to remove our mq queue of patches from the local repository and then applied those patches after a successful pull. So we would do:

{{{
hg qpop -a
hg pull -u
hg qpush -a
}}}

== Further reading ==
 * MqExtension : mq's main page
 * {{{hgext/mq-howto}}} : file in mq's repository
 * [http://www.suse.de/~agruen/quilt.pdf quilt pdf] : more about quilt

== Other tips and tricks ==
=== Convert a patch to a permanent changeset ===
Need help here!

=== Split a patch into multiple patches ===
Need help here! cmanson hinted on irc that one can do something like this
 *** Goal OP=P1 + P2 where OP=Original Patch, P1=Patch 1, P2=Patch 2
 * Make sure OP is applied to workingDirectory
 * Copy OP to a temp patch file (OPT)
 * Edit OPT and remove things intended to stay in P1 (OPT ends up having P2)
 * in workingDirectory run:
   * {{{patch -p1 -R < OPT}}}
   * {{{hg qrefresh}}} : updates mq's OP to only have P1
   * {{{hg qnew -m "foo" P2}}}
   * {{{patch -p1 < OPT}}}
   * {{{hg qrefresh}}}

Daniel Santa Cruz (byteshack)

The text below this line needs to be moved to a more permanent place once this tutorial is completed. Please help me with a good name for the page!

Mq Tutorial

TableOfContents

Why the heck would I want to use mq?

Show how mq is a solution to a problem and not a solution looking for a problem. The quilt pdf paper seems to be a good starting point.

Installing mq

Follow the instructions in MqExtensionInstallHowTo

What is all this talk about a stack?

Before we begin this tutorial, there are 3 things to keep track of when using the mq extension: the localRepository, the mqPatches, and the workingDirectory. When the mq documentation talks about a stack, it refers to the localRepository as a stack on which one can push/pop patches. mqPatches works like a queue, where the first patch you create would be the first patch to be pushed to the localRepository stack.

Working with mq

<maybe put a table of contents here?>

Get a repository to do work on

This can be done by either initializing a brand new Mercurial repository yourself (ie. using hg init) or by cloning an existing repository. For this tutorial we will use the same repository used in the ['Mercurial'] ['Tutorial']. 

hg clone http://www.selenic.com/repo/hello

Indicate that you want to use mq on this repository

mq provides the qinit command to initialize mq on a given repository. To start using mq on our recently cloned repository use: 

cd hello
hg qinit -c

You can type hg help qinit to see help on the specifics of the command. Here we are telling mq to not only initialize an mq queue, but also to keep itself versioned with ['Mercurial']. This mq does by creating a new repository for use by itself under hello/.hg/patches.

Creating and editing a patch

Now we are ready to start hacking the hello code away. The first step in to create a "patch holder" which will contain the changes that we make. To do this execute: 

hg qnew -m "Change language of salutation" newHelloString

The -m flag allows you to pass the message to be used in the changeset. This is the same message that would be placed if you did a hg commit -m.

Let's now edit hello.c and change line 14 so that you end up with a file that looks like this: 

  12 int main(int argc, char **argv)
  13 {
  14         printf("Howdy there!\n");
  15         return 0;
  16 }

At this point our changes are only recorded in the workingDirectory. To verify this we can execute hg status and see that the hello.c file has been marked as modified. We will record the changes into our current patch (newHelloString) by executing hg qrefresh. If we run hg status again, we will see that there are no pending changes in our workingDirectory. Let's ask mq what patches it has push on top of the repository stack by running hg qapplied. mq tells us that it has applied newHelloString, and we can verify this by running hg log and noticing that the repository has that patch in it's history. [Hmmm... where do we need to talk about push/pop?]

Dealing with more than one patch on our patch queue

We now realize that our hello.c file needs to be able to tell us who it is, and in good form, we don't want to mix our changes to the salutation with this new modification (the why of this is beyond the scope of this tutorial). So we create a new patch and make the changes: 

hg qnew -m "Have hello say who he is" sayName

... edit hello.c and add line 15 below to it 

  12 int main(int argc, char **argv)
  13 {
  14         printf("Howdy there!\n");
  15         printf("My name is 'hello.c'!!!\n");
  16         return 0;
  17 }

Lets commit our changes to the mq queue by running hg qrefresh. We can now see that mq has applied the last two patches to the repository by running both hg qapplied and hg log.

Versioning our patch set

Put documentation on how to do this.

Synchronizing with upstream

Time goes by and we need to synchronize with upstream. Before we do this, we need to remove our mq queue of patches from the local repository and then applied those patches after a successful pull. So we would do: 

hg qpop -a
hg pull -u
hg qpush -a

Further reading

Other tips and tricks

Convert a patch to a permanent changeset

Need help here!

Split a patch into multiple patches

Need help here! cmanson hinted on irc that one can do something like this

  • ** Goal OP=P1 + P2 where OP=Original Patch, P1=Patch 1, P2=Patch 2
  • Make sure OP is applied to workingDirectory
  • Copy OP to a temp patch file (OPT)
  • Edit OPT and remove things intended to stay in P1 (OPT ends up having P2)
  • in workingDirectory run:

    • patch -p1 -R < OPT

    • hg qrefresh : updates mq's OP to only have P1

    • hg qnew -m "foo" P2

    • patch -p1 < OPT

    • hg qrefresh

CategoryHomepage

DanielSantaCruz (last edited 2009-05-19 19:31:00 by localhost)