[RFC PATCH] Rename "bury" back to "sink".

[RFC PATCH] Rename "bury" back to "sink".

[Yann Dirson]

Signed-off-by: Yann Dirson <ydirson@altern.org>
---

Well, it looks like the voices we heard on this naming issue were
quite equally cast towards each of the 2 name.

Let my vote be to get back to "sink", so the user can easily pair the
command with "float".  I expect that any previously-silent majoity
prefering "bury" will talk now, before Catalin decides if he wants
this patch in the next release :)

Oh, this patch reminds me we still have to activate rename
detection...

 Documentation/stg-bury.txt    |   49 -------------------------------
 Documentation/stg-sink.txt    |   49 +++++++++++++++++++++++++++++++
 Documentation/stg.txt         |    4 +--
 contrib/stgit-completion.bash |    4 +--
 stgit/commands/bury.py        |   65 -----------------------------------------
 stgit/commands/sink.py        |   65 +++++++++++++++++++++++++++++++++++++++++
 stgit/main.py                 |    4 +--
 7 files changed, 120 insertions(+), 120 deletions(-)

diff --git a/Documentation/stg-bury.txt b/Documentation/stg-bury.txt
deleted file mode 100644
index 22ab548..0000000
--- a/Documentation/stg-bury.txt
+++ /dev/null
@@ -1,49 +0,0 @@
-stg-bury(1)
-===========
-Yann Dirson <ydirson@altern.org>
-v0.13, April 2007
-
-NAME
-----
-stg-bury - stgdesc:bury[]
-
-SYNOPSIS
---------
-[verse]
-'stg' bury [--to=<target>] [--nopush] [<patches>]
-
-DESCRIPTION
------------
-
-This is the opposite operation of stglink:float[]: move the specified
-patches down the stack.  It is for example useful to group stable
-patches near the bottom of the stack, where they are less likely to be
-impacted by the push of another patch, and from where they can be more
-easily committed or pushed.
-
-If no patch is specified on command-line, the current patch is buried.
-By default patches are buried at the bottom of the stack, but the
-'--to' option allows to bury under any applied patch.
-
-Buring internally involves popping all patches (or all patches
-including <target patch>), then pushing the patches to bury, and then
-(unless '--nopush' is also given) pushing back into place the
-formerly-applied patches.
-
-
-OPTIONS
--------
-
---to=<TARGET>::
--t <TARGET>::
-	Specify a target patch to bury the patches below, instead of
-	buring at the bottom of the stack.
-
---nopush::
--n::
-	Do not push back on the stack the formerly-applied patches.
-	Only the patches to bury are pushed.
-
-StGIT
------
-Part of the StGIT suite - see gitlink:stg[1].
diff --git a/Documentation/stg-sink.txt b/Documentation/stg-sink.txt
new file mode 100644
index 0000000..0f569be
--- /dev/null
+++ b/Documentation/stg-sink.txt
@@ -0,0 +1,49 @@
+stg-sink(1)
+===========
+Yann Dirson <ydirson@altern.org>
+v0.13, April 2007
+
+NAME
+----
+stg-sink - stgdesc:sink[]
+
+SYNOPSIS
+--------
+[verse]
+'stg' sink [--to=<target>] [--nopush] [<patches>]
+
+DESCRIPTION
+-----------
+
+This is the opposite operation of stglink:float[]: move the specified
+patches down the stack.  It is for example useful to group stable
+patches near the bottom of the stack, where they are less likely to be
+impacted by the push of another patch, and from where they can be more
+easily committed or pushed.
+
+If no patch is specified on command-line, the current patch gets sunk.
+By default patches are sunk to the bottom of the stack, but the
+'--to' option allows to place them under any applied patch.
+
+Sinking internally involves popping all patches (or all patches
+including <target patch>), then pushing the patches to sink, and then
+(unless '--nopush' is also given) pushing back into place the
+formerly-applied patches.
+
+
+OPTIONS
+-------
+
+--to=<TARGET>::
+-t <TARGET>::
+	Specify a target patch to place the patches below, instead of
+	sinking them to the bottom of the stack.
+
+--nopush::
+-n::
+	Do not push back on the stack the formerly-applied patches.
+	Only the patches to sink are pushed.
+
+StGIT
+-----
+Part of the StGIT suite - see gitlink:stg[1].
diff --git a/Documentation/stg.txt b/Documentation/stg.txt
index cf28b02..af57c37 100644
--- a/Documentation/stg.txt
+++ b/Documentation/stg.txt
@@ -137,8 +137,8 @@ stglink:goto[]::
 	stgdesc:goto[]
 stglink:float[]::
 	stgdesc:float[]
-stglink:bury[]::
-	stgdesc:bury[]
+stglink:sink[]::
+	stgdesc:sink[]
 stglink:applied[]::
 	stgdesc:applied[]
 stglink:unapplied[]::
diff --git a/contrib/stgit-completion.bash b/contrib/stgit-completion.bash
index 3c3bf92..760fc2f 100644
--- a/contrib/stgit-completion.bash
+++ b/contrib/stgit-completion.bash
@@ -15,7 +15,6 @@ _stg_commands="
     applied
     assimilate
     branch
-    bury
     delete
     diff
     clean
@@ -46,6 +45,7 @@ _stg_commands="
     rm
     series
     show
+    sink
     status
     sync
     top
@@ -190,13 +190,13 @@ _stg ()
         # repository commands
         id)     _stg_patches $command _all_patches ;;
         # stack commands
-        bury)   _stg_patches $command _all_patches ;;
         float)  _stg_patches $command _all_patches ;;
         goto)   _stg_patches $command _all_other_patches ;;
         hide)   _stg_patches $command _all_patches ;;
         pop)    _stg_patches $command _applied_patches ;;
         push)   _stg_patches $command _unapplied_patches ;;
         series) _stg_patches $command _all_patches ;;
+        sink)   _stg_patches $command _all_patches ;;
         unhide) _stg_patches $command _all_patches ;;
         # patch commands
         delete) _stg_patches $command _all_patches ;;
diff --git a/stgit/commands/bury.py b/stgit/commands/bury.py
deleted file mode 100644
index b14f09e..0000000
--- a/stgit/commands/bury.py
+++ /dev/null
@@ -1,65 +0,0 @@
-
-__copyright__ = """
-Copyright (C) 2007, Yann Dirson <ydirson@altern.org>
-
-This program is free software; you can redistribute it and/or modify
-it under the terms of the GNU General Public License version 2 as
-published by the Free Software Foundation.
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU General Public License for more details.
-
-You should have received a copy of the GNU General Public License
-along with this program; if not, write to the Free Software
-Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-"""
-
-import sys, os
-from optparse import OptionParser, make_option
-
-from stgit.commands.common import *
-from stgit.utils import *
-from stgit import stack, git
-
-
-help = 'bury patches down the stack'
-usage = """%prog [-t <target patch>] [-n] [<patches>]
-
-Pop all patches (or all patches including <target patch>), then
-push the specified <patches> (the current patch by default), and
-then push back into place the formerly-applied patches (unless -n
-is also given)."""
-
-options = [make_option('-n', '--nopush',
-                       help = 'do not push the patches back after sinking',
-                       action = 'store_true'),
-           make_option('-t', '--to', metavar = 'TARGET',
-                       help = 'bury patches below TARGET patch')]
-
-def func(parser, options, args):
-    """Bury patches
-    """
-
-    check_local_changes()
-    check_conflicts()
-    check_head_top_equal()
-
-    oldapplied = crt_series.get_applied()
-    unapplied = crt_series.get_unapplied()
-    all = unapplied + oldapplied
-
-    if len(args) > 0:
-        patches = parse_patches(args, all)
-    else:
-        patches = [ crt_series.get_current() ]
-
-    crt_series.pop_patch(options.to or oldapplied[0])
-    push_patches(patches)
-
-    if not options.nopush:
-        newapplied = crt_series.get_applied()
-        def not_reapplied_yet(p):
-            return not p in newapplied
-        push_patches(filter(not_reapplied_yet, oldapplied))
diff --git a/stgit/commands/sink.py b/stgit/commands/sink.py
new file mode 100644
index 0000000..85cc70f
--- /dev/null
+++ b/stgit/commands/sink.py
@@ -0,0 +1,65 @@
+
+__copyright__ = """
+Copyright (C) 2007, Yann Dirson <ydirson@altern.org>
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License version 2 as
+published by the Free Software Foundation.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+"""
+
+import sys, os
+from optparse import OptionParser, make_option
+
+from stgit.commands.common import *
+from stgit.utils import *
+from stgit import stack, git
+
+
+help = 'send patches deeper down the stack'
+usage = """%prog [-t <target patch>] [-n] [<patches>]
+
+Pop all patches (or all patches including <target patch>), then
+push the specified <patches> (the current patch by default), and
+then push back into place the formerly-applied patches (unless -n
+is also given)."""
+
+options = [make_option('-n', '--nopush',
+                       help = 'do not push the patches back after sinking',
+                       action = 'store_true'),
+           make_option('-t', '--to', metavar = 'TARGET',
+                       help = 'sink patches below TARGET patch')]
+
+def func(parser, options, args):
+    """Sink patches down the stack.
+    """
+
+    check_local_changes()
+    check_conflicts()
+    check_head_top_equal()
+
+    oldapplied = crt_series.get_applied()
+    unapplied = crt_series.get_unapplied()
+    all = unapplied + oldapplied
+
+    if len(args) > 0:
+        patches = parse_patches(args, all)
+    else:
+        patches = [ crt_series.get_current() ]
+
+    crt_series.pop_patch(options.to or oldapplied[0])
+    push_patches(patches)
+
+    if not options.nopush:
+        newapplied = crt_series.get_applied()
+        def not_reapplied_yet(p):
+            return not p in newapplied
+        push_patches(filter(not_reapplied_yet, oldapplied))
diff --git a/stgit/main.py b/stgit/main.py
index 9c319c6..1a1f534 100644
--- a/stgit/main.py
+++ b/stgit/main.py
@@ -63,7 +63,6 @@ commands = Commands({
     'applied':          'applied',
     'assimilate':       'assimilate',
     'branch':           'branch',
-    'bury':             'bury',
     'delete':           'delete',
     'diff':             'diff',
     'clean':            'clean',
@@ -94,6 +93,7 @@ commands = Commands({
     'rm':               'rm',
     'series':           'series',
     'show':             'show',
+    'sink':             'sink',
     'status':           'status',
     'sync':             'sync',
     'top':              'top',
@@ -111,7 +111,6 @@ stackcommands = (
     'applied',
     'assimilate',
     'branch',
-    'bury',
     'clean',
     'commit',
     'float',
@@ -124,6 +123,7 @@ stackcommands = (
     'push',
     'rebase',
     'series',
+    'sink',
     'top',
     'unapplied',
     'uncommit',

Re: [RFC PATCH] Rename "bury" back to "sink".

[Jakub Narebski]

Yann Dirson wrote:

> Well, it looks like the voices we heard on this naming issue were
> quite equally cast towards each of the 2 name.
> 
> Let my vote be to get back to "sink", so the user can easily pair the
> command with "float".  I expect that any previously-silent majoity
> prefering "bury" will talk now, before Catalin decides if he wants
> this patch in the next release :)

I'm rather partial to "bury" rather than "sink", as "bury" has the
notation of going deeper (like "float" has notation of guing up, to
the surface), while "sink" does not need to. Additionally "sink" is
a noun as well as a verb.

> Oh, this patch reminds me we still have to activate rename
> detection...

True.

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [RFC PATCH] Rename "bury" back to "sink".

[Karl Hasselström]

On 2007-05-05 00:53:03 +0200, Yann Dirson wrote:

> Well, it looks like the voices we heard on this naming issue were
> quite equally cast towards each of the 2 name.
>
> Let my vote be to get back to "sink", so the user can easily pair
> the command with "float". I expect that any previously-silent
> majoity prefering "bury" will talk now, before Catalin decides if he
> wants this patch in the next release :)

Well, my vote is still for "sink"! If it is to be called "stg bury",
I'd have to vote for changing "stg float" to "stg unearth". :-)

-- 
Karl Hasselström, kha@treskal.com
      www.treskal.com/kalle

Re: [RFC PATCH] Rename "bury" back to "sink".

[Chris Shoemaker]

On Sat, May 05, 2007 at 03:13:53PM +0200, Karl Hasselström wrote:
> On 2007-05-05 00:53:03 +0200, Yann Dirson wrote:
> 
> > Well, it looks like the voices we heard on this naming issue were
> > quite equally cast towards each of the 2 name.
> >
> > Let my vote be to get back to "sink", so the user can easily pair
> > the command with "float". I expect that any previously-silent
> > majoity prefering "bury" will talk now, before Catalin decides if he
> > wants this patch in the next release :)
> 
> Well, my vote is still for "sink"! If it is to be called "stg bury",
> I'd have to vote for changing "stg float" to "stg unearth". :-)

Just my 2.5 cents:

float/sink are clearly related, while I wouldn't associate float/bury
at all.  Also, "bury" is sometimes euphemistic for "kill", so
bury/resurrect is a clear pair.  Anyway, "sink" makes perfect sense to
me.

-chris

Re: [RFC PATCH] Rename "bury" back to "sink".

[Yann Dirson]

The whole debate around burying, sinking and floating patches made me
think a bit more about this.  So we have:

float:		move specified patches to top of stack
bury/float:	move specified patches to bottom of stack or any place
		in the stack identified by a nearby patch

All in all, that all "move specified patches to a specified place".
So wouldn't it be possible to end the debate by merging those commands
into a single "stg move" command ?

Side note about the "stg move" name: yes it could possible to mistake it
for "move file" (especially as we don't have "stg mv").  My current
state of mind would be to drop add/rm/cp from stgit, and move the "stg
cp" logic to a new git-cp command.  This way, stgit would just be
about handling series of patches, with git being used for the
working-copy.  Any opinions on this ?

Now to the new command.  We could have something like:

 stg move -t base <patches>	<=> stg sink <patches>
 stg move -t <patch> <patches>	<=> stg sink -t <patch> <patches>
 stg move -t current <patches>	<=> stg float <patches>

Note the introduction of a new "curent" stg_id for the tip of the
stack.

The semantics of the arg to -t would be something like "the limit
between the patches that will end up below <patches> and those that
will end up above".  I suppose "-t current" should be the default, so
it may not even be necessary to expose "current" to the command-line.

The "conceptual algorithm" would be:
 1. stg pop <patches>
 2. stg push <patches>
 3. stg goto "where I was"

"-s [<series>]" would be allowed as an alternative to <patches>, so
"move" would be a strict superset of "float".

By default, consistently with "float", the <patches> (and hence
everything originally under the target point) will end up applied if
the target of the move was "within $applied" (ie. an applied patch or
"current" - something we could call "below the surface", hi float and
sink ;), and all patches that were applied (ie. those between the
target and the former tip) will end up being reapplied, consistently
with "sink".

If the target point is in $unapplied, then the command will be
equivalent to "stg pop <patches>" with those patches reordered at the
target (ie. no need to really execute steps 2 and 3 above).  That's no
rocket science, but a useful I have already missed, eg. when I just
want to move the patches away from my working set (nowadays we could
hide them, but that may not be always adequate).

A --dont-come-back flag of some sort will skip step 3 of the
conceptual algorithm above.  When the target will be in $applied, it
will be the equivalent of "sink --nopush".  When the target is in
$unapplied, we will "goto <last of <patches>>" after reorering the
unapplied patches.  Never missed this one till now, but who knows,
this side-effect might come handy.

Opinions ?
-- 
Yann.

PS: this RFC is known as "bury sink and float" ;)

Re: [RFC PATCH] Rename "bury" back to "sink".

[Karl Hasselström]

On 2007-05-05 22:13:07 +0200, Yann Dirson wrote:

> The whole debate around burying, sinking and floating patches made
> me think a bit more about this. So we have:
>
> float:        move specified patches to top of stack
> bury/float:   move specified patches to bottom of stack or any place
>               in the stack identified by a nearby patch
>
> All in all, that all "move specified patches to a specified place".
> So wouldn't it be possible to end the debate by merging those
> commands into a single "stg move" command ?

I like that idea.

  stg move patch1 --bottom
  stg move patch1 --top
  stg move patch1 --before other-patch
  stg move patch1 --after other-patch
  stg move patch1 --position 17 # move to absolute pos. 17 (bottom is 0)
  stg move patch1 --up 3        # move 3 steps up
  stg move patch1 --down 2      # move 2 steps down

Or something. It could also be made to work with patch ranges as well
as single patches.

> Side note about the "stg move" name: yes it could possible to
> mistake it for "move file" (especially as we don't have "stg mv").
> My current state of mind would be to drop add/rm/cp from stgit, and
> move the "stg cp" logic to a new git-cp command. This way, stgit
> would just be about handling series of patches, with git being used
> for the working-copy. Any opinions on this ?

I would be in favor; I like to think of stgit as extending rather than
providing a complete replacement for the plain git porcelain. But as I
recall, Catalin didn't share my view on this. Better let him answer
the question himself than rely on my memory, though. ;-)

> Now to the new command. We could have something like:
>
>  stg move -t base <patches>     <=> stg sink <patches>
>  stg move -t <patch> <patches>  <=> stg sink -t <patch> <patches>
>  stg move -t current <patches>  <=> stg float <patches>
>
> Note the introduction of a new "curent" stg_id for the tip of the
> stack.

Ah, I wrote my suggested syntax above before reading yours. I like
mine better, though. :-)

> "-s [<series>]" would be allowed as an alternative to <patches>, so
> "move" would be a strict superset of "float".

Another useful option would be to have --interactive open up an editor
with the patch names in it; the user could rearrange the lines any way
she pleased, and when the editor exits, the patch series is rearranged
to match.

> If the target point is in $unapplied, then the command will be
> equivalent to "stg pop <patches>" with those patches reordered at
> the target (ie. no need to really execute steps 2 and 3 above).
> That's no rocket science, but a useful I have already missed, eg.
> when I just want to move the patches away from my working set
> (nowadays we could hide them, but that may not be always adequate).

Sounds very good.

> Opinions?

Lots, as you just saw. :-)

-- 
Karl Hasselström, kha@treskal.com
      www.treskal.com/kalle

Re: [RFC PATCH] Rename "bury" back to "sink".

[David Kågedal]

Yann Dirson <ydirson@altern.org> writes:

> Side note about the "stg move" name: yes it could possible to mistake it
> for "move file" (especially as we don't have "stg mv").  My current
> state of mind would be to drop add/rm/cp from stgit, and move the "stg
> cp" logic to a new git-cp command.  This way, stgit would just be
> about handling series of patches, with git being used for the
> working-copy.  Any opinions on this ?

For this reason, and others, I think "stg reorder" would be better.
Especially if you implement Karl's suggestion of reordering all
patches in an editor.

-- 
David Kågedal

Re: [RFC PATCH] Rename "bury" back to "sink".

[Karl Hasselström]

On 2007-05-13 11:28:23 -0700, David Kågedal wrote:

> For this reason, and others, I think "stg reorder" would be better.
> Especially if you implement Karl's suggestion of reordering all
> patches in an editor.

Sounds very sane to me.

Additionally, in order to appeal to users who like living on the edge,
we should probably consider implementing "stg shuffle".

-- 
Karl Hasselström, kha@treskal.com
      www.treskal.com/kalle