You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@subversion.apache.org by Max Bowsher <ma...@ukf.net> on 2005/11/02 13:01:03 UTC

[RFC] 'basic/additional command set' - adding svn subcommands without destroying our learning curve

The need to keep our basic command set small, to avoid svn becoming daunting 
to new users, and making the learning curve intolerably steep, is not a new 
issue.

I agree with it, but taken alone, it stops us adding useful utility 
subcommands - the sort of thing I am thinking of:
  svn purge: Remove unversioned files from a WC
  svn sync: 'svn add' all unversioned files, 'svn rm' all missing files

These are minor issues - implementable as scripts easily enough - but 
despite being periodically requested, we've held off implementing them for 
the reason mentioned above.

Whilst scripts are useful in the short-term, it seems very wrong that 
everyone needing these has to write/install scripts whereever they need 
these operations - there is also the problem of Windows, where scripting is 
far more difficult.

To break the deadlock between the opposing motivations of 'keep svn simple', 
and 'add useful utilities', I'd like to propose that we introduce the notion 
of a basic and an additional command set. Practically, all this means is 
splitting commands between `svn --help` and `svn --help-additional`, and 
dividing our documentation of commands in the same way.

I think this will give us a way to add less-used, but still very useful 
functionality to svn, whilst sidestepping the elevated learning curve which 
has dissuaded us from doing so in the past.

Thoughts?

Max.


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: [RFC] 'basic/additional command set' - adding svn subcommands without destroying our learning curve

Posted by Greg Hudson <gh...@MIT.EDU>.
On Wed, 2005-11-02 at 13:01 +0000, Max Bowsher wrote:
> To break the deadlock between the opposing motivations of 'keep svn simple', 
> and 'add useful utilities', I'd like to propose that we introduce the notion 
> of a basic and an additional command set. Practically, all this means is 
> splitting commands between `svn --help` and `svn --help-additional`, and 
> dividing our documentation of commands in the same way.

We might give it a more descriptive name, like --help-utilities.

I could live with this, but we should come up with some pretty clear
criteria for separating basic commands from utilities.  I'm not sure if
I can quite nail it down myself.  Certainly, I think it should be
possible in principle to implement all utility operations in terms of
core operations, although our implementation might be more efficient.

To me, "import" and "export" should remain basic commands.  import can
be done with co/add/commit, but it's not quite the same operation;
export can't be done at all without violating the abstraction barrier.

Some new command proposals would still have to be basic commands.  For
instance, we've talked about having non-broken partial checkout support,
and making it possible to add or remove a subtree from a partial
checkout.  The removal command can't be a utility command since there's
no way to do it terms of today's basic operations.


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: [RFC] 'basic/additional command set' - adding svn subcommands without destroying our learning curve

Posted by David James <ja...@gmail.com>.
On 11/2/05, David James <ja...@gmail.com> wrote:
> svn export is extremely useful, but you can easily replicate it using
> shell commands. For example:
>  svn co $REPO $WC
>  find $WC -name .svn | xargs rm -rf
>
> For svn import:
> [snip typos]

Here's a better implementation of svn import:
 svn co $REPO $DIR
 svn add $DIR/*
 svn commit -m "Initial import" $DIR

(Note: the above implementation makes "$DIR" a WC, which is slightly
different from the behaviour of "svn import", but is usually what I
want anyway.)

Cheers,

David

--
David James -- http://www.cs.toronto.edu/~james

Re: [RFC] 'basic/additional command set' - adding svn subcommands without destroying our learning curve

Posted by Vincent Lefevre <vi...@vinc17.org>.
On 2005-11-02 12:34:00 -0800, Garrett Rooney wrote:
> On 11/2/05, David James <ja...@gmail.com> wrote:
> > svn export is extremely useful, but you can easily replicate it using
> > shell commands. For example:
> >   svn co $REPO $WC
> >   find $WC -name .svn | xargs rm -rf
> 
> I'm aware of this, but it requires you to have the space lying around
> for all the contents of the .svn directories, thus the "double the
> amount of disk space you use" in my email.

And even if you have the space, it is slower, isn't it?

-- 
Vincent Lefèvre <vi...@vinc17.org> - Web: <http://www.vinc17.org/>
100% accessible validated (X)HTML - Blog: <http://www.vinc17.org/blog/>
Work: CR INRIA - computer arithmetic / SPACES project at LORIA

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: [RFC] 'basic/additional command set' - adding svn subcommands without destroying our learning curve

Posted by Garrett Rooney <ro...@electricjellyfish.net>.
On 11/2/05, David James <ja...@gmail.com> wrote:
> On 11/2/05, Garrett Rooney <ro...@electricjellyfish.net> wrote:
> > On 11/2/05, David James <ja...@gmail.com> wrote:
> >
> > > svn import and svn export are both very handy, but you can get away
> > > without them if you have a good shell. Perhaps we should count export
> > > and import as "additional commands"?
> >
> > I don't buy that, at least for export, since you can't do without it
> > unless you're willing to double the amount of disk space you use.
>
> svn export is extremely useful, but you can easily replicate it using
> shell commands. For example:
>   svn co $REPO $WC
>   find $WC -name .svn | xargs rm -rf

I'm aware of this, but it requires you to have the space lying around
for all the contents of the .svn directories, thus the "double the
amount of disk space you use" in my email.  It may just be
temporarily, but it is still a potential problem.  The original svn
export command actually did literally that (checkout + delete .svn
dirs), but we rewrote it for just this reason.

-garrett

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org


Re: [RFC] 'basic/additional command set' - adding svn subcommands without destroying our learning curve

Posted by David James <ja...@gmail.com>.
On 11/2/05, Garrett Rooney <ro...@electricjellyfish.net> wrote:
> On 11/2/05, David James <ja...@gmail.com> wrote:
>
> > svn import and svn export are both very handy, but you can get away
> > without them if you have a good shell. Perhaps we should count export
> > and import as "additional commands"?
>
> I don't buy that, at least for export, since you can't do without it
> unless you're willing to double the amount of disk space you use.

svn export is extremely useful, but you can easily replicate it using
shell commands. For example:
  svn co $REPO $WC
  find $WC -name .svn | xargs rm -rf

For svn import:
  svn co $REPO $WC
  cp -r $DIR/* $WC
  find $WC -type f | grep -v .svn | xargs svn add
  svn commit -m "Initial import" $WC

Cheers,

David

--
David James -- http://www.cs.toronto.edu/~james

Re: [RFC] 'basic/additional command set' - adding svn subcommands without destroying our learning curve

Posted by Garrett Rooney <ro...@electricjellyfish.net>.
On 11/2/05, David James <ja...@gmail.com> wrote:

> svn import and svn export are both very handy, but you can get away
> without them if you have a good shell. Perhaps we should count export
> and import as "additional commands"?

I don't buy that, at least for export, since you can't do without it
unless you're willing to double the amount of disk space you use.

-garrett

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org


Re: [RFC] 'basic/additional command set' - adding svn subcommands without destroying our learning curve

Posted by David James <ja...@gmail.com>.
On 02 Nov 2005 08:17:28 -0500, C. Michael Pilato <cm...@collab.net> wrote:
> > To break the deadlock between the opposing motivations of 'keep svn
> > simple', and 'add useful utilities', I'd like to propose that we
> > introduce the notion of a basic and an additional command
> > set. Practically, all this means is splitting commands between `svn
> > --help` and `svn --help-additional`, and dividing our documentation of
> > commands in the same way.
> >
> > I think this will give us a way to add less-used, but still very
> > useful functionality to svn, whilst sidestepping the elevated learning
> > curve which has dissuaded us from doing so in the past.
> >
> > Thoughts?
>
> +1 on the concept.
Same here.

> Is there a well-defined rule that will keep us from endlessly debating
> every subcommand's status from here on out (like, "the subcommand
> could be written as a composition of other existing subcommands plus
> some shell scripting")?  Do any of the current subcommands meet your
> criteria for demotion from a standard command to a "useful utility"?
svn import and svn export are both very handy, but you can get away
without them if you have a good shell. Perhaps we should count export
and import as "additional commands"?

Cheers,

David



--
David James -- http://www.cs.toronto.edu/~james

Re: [RFC] 'basic/additional command set' - adding svn subcommands without destroying our learning curve

Posted by "C. Michael Pilato" <cm...@collab.net>.
"Max Bowsher" <ma...@ukf.net> writes:

> The need to keep our basic command set small, to avoid svn becoming
> daunting to new users, and making the learning curve intolerably
> steep, is not a new issue.
> 
> I agree with it, but taken alone, it stops us adding useful utility
> subcommands - the sort of thing I am thinking of:
>   svn purge: Remove unversioned files from a WC
>   svn sync: 'svn add' all unversioned files, 'svn rm' all missing files
> 
> These are minor issues - implementable as scripts easily enough - but
> despite being periodically requested, we've held off implementing them
> for the reason mentioned above.
> 
> Whilst scripts are useful in the short-term, it seems very wrong that
> everyone needing these has to write/install scripts whereever they
> need these operations - there is also the problem of Windows, where
> scripting is far more difficult.
> 
> To break the deadlock between the opposing motivations of 'keep svn
> simple', and 'add useful utilities', I'd like to propose that we
> introduce the notion of a basic and an additional command
> set. Practically, all this means is splitting commands between `svn
> --help` and `svn --help-additional`, and dividing our documentation of
> commands in the same way.
> 
> I think this will give us a way to add less-used, but still very
> useful functionality to svn, whilst sidestepping the elevated learning
> curve which has dissuaded us from doing so in the past.
> 
> Thoughts?

+1 on the concept.

Is there a well-defined rule that will keep us from endlessly debating
every subcommand's status from here on out (like, "the subcommand
could be written as a composition of other existing subcommands plus
some shell scripting")?  Do any of the current subcommands meet your
criteria for demotion from a standard command to a "useful utility"?

-- 
C. Michael Pilato <cm...@collab.net>
CollabNet   <>   www.collab.net   <>   Distributed Development On Demand

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: [RFC] 'basic/additional command set' - adding svn subcommands without destroying our learning curve

Posted by Steve Williams <st...@kromestudios.com>.
Michael Sweet wrote:
>>Svnadmin is for repository management. The proposed "purge" command is 
>>for working copy management, so it doesn't belong in svnadmin.
> 
> As I understand it, "purge" would remove all revisions of a file from
> the repository, possibly leaving the WC file alone.  I would argue
> that removing a file and its history from a repo without the
> possibility of recovery falls under repository management, not WC
> management.  A WC operation can be "undone" by reverting a change,
> a repo operation can't.

The 'purge' as described in the original post removes all unversioned 
files from a WC.  You're probably thinking of the 'obliterate' command 
that has been proposed here before.

-- 
Sly


This message and its attachments may contain legally privileged or confidential information. This message is intended for the use of the individual or entity to which it is addressed. If you are not the addressee indicated in this message, or the employee or agent responsible for delivering the message to the intended recipient, you may not copy or deliver this message or its attachments to anyone. Rather, you should permanently delete this message and its attachments and kindly notify the sender by reply e-mail. Any content of this message and its attachments, which does not relate to the official business of the sending company must be taken not to have been sent or endorsed by the sending company or any of its related entities. No warranty is made that the e-mail or attachment(s) are free from computer virus or other defect.

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: [RFC] 'basic/additional command set' - adding svn subcommands without destroying our learning curve

Posted by Michael Sweet <mi...@easysw.com>.
Branko Čibej wrote:
> ...
>>>    svn util purge
>>
>> Slightly off-topic, but when you do implement a "purge" command,
>> would it make more sense to be part of svnadmin since there is no
>> way to "undo" the purge?
> Svnadmin is for repository management. The proposed "purge" command is 
> for working copy management, so it doesn't belong in svnadmin.

As I understand it, "purge" would remove all revisions of a file from
the repository, possibly leaving the WC file alone.  I would argue
that removing a file and its history from a repo without the
possibility of recovery falls under repository management, not WC
management.  A WC operation can be "undone" by reverting a change,
a repo operation can't.

I know I will want to limit access to "purge" to administrative
users only, since I don't want to get a call asking if I can
restore all of the files a user purged "by accident".  Sure, I'll
have backups of the repo itself, but I'd rather make it harder
rather than easier to purge files from a repo.  Putting the purge
command in svnadmin would immediately "hide" the command from users
that only know to use svn, and it would also make it clear that
"purge" is a serious operation that should only be done by someone
that is managing the repository.

-- 
______________________________________________________________________
Michael Sweet, Easy Software Products           mike at easysw dot com
Internet Printing and Publishing Software        http://www.easysw.com

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org


Re: [RFC] 'basic/additional command set' - adding svn subcommands without destroying our learning curve

Posted by Branko Čibej <br...@xbc.nu>.
Michael Sweet wrote:
> Branko Čibej wrote:
>> Max Bowsher wrote:
>>> The need to keep our basic command set small, to avoid svn becoming 
>>> daunting to new users, and making the learning curve intolerably 
>>> steep, is not a new issue.
>>>
>>> I agree with it, but taken alone, it stops us adding useful utility 
>>> subcommands - the sort of thing I am thinking of:
>>>  svn purge: Remove unversioned files from a WC
>>>  svn sync: 'svn add' all unversioned files, 'svn rm' all missing files
>>>
>>> These are minor issues - implementable as scripts easily enough - 
>>> but despite being periodically requested, we've held off 
>>> implementing them for the reason mentioned above.
>> If we decide to go with this idea, then I suggest we have *one* 
>> utility command. To illustrate, your examples above would become:
>>
>>    svn util purge
>
> Slightly off-topic, but when you do implement a "purge" command,
> would it make more sense to be part of svnadmin since there is no
> way to "undo" the purge?
Svnadmin is for repository management. The proposed "purge" command is 
for working copy management, so it doesn't belong in svnadmin.

-- Brane


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: [RFC] 'basic/additional command set' - adding svn subcommands without destroying our learning curve

Posted by Michael Sweet <mi...@easysw.com>.
Branko Čibej wrote:
> Max Bowsher wrote:
>> The need to keep our basic command set small, to avoid svn becoming 
>> daunting to new users, and making the learning curve intolerably 
>> steep, is not a new issue.
>>
>> I agree with it, but taken alone, it stops us adding useful utility 
>> subcommands - the sort of thing I am thinking of:
>>  svn purge: Remove unversioned files from a WC
>>  svn sync: 'svn add' all unversioned files, 'svn rm' all missing files
>>
>> These are minor issues - implementable as scripts easily enough - but 
>> despite being periodically requested, we've held off implementing them 
>> for the reason mentioned above.
> If we decide to go with this idea, then I suggest we have *one* utility 
> command. To illustrate, your examples above would become:
> 
>    svn util purge

Slightly off-topic, but when you do implement a "purge" command,
would it make more sense to be part of svnadmin since there is no
way to "undo" the purge?

Anyways, I like the idea of grouping "utility" commands as subcommands
under a main "util" command, but I'm slightly concerned that it could
end up as a "command junkyard".  Seems like either way you go, you'll
want to define the criteria for adding new commands/subcommands to
minimize command bloat.

-- 
______________________________________________________________________
Michael Sweet, Easy Software Products           mike at easysw dot com
Internet Printing and Publishing Software        http://www.easysw.com

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org


Re: [RFC] 'basic/additional command set' - adding svn subcommands without destroying our learning curve

Posted by Branko Čibej <br...@xbc.nu>.
Max Bowsher wrote:
> The need to keep our basic command set small, to avoid svn becoming 
> daunting to new users, and making the learning curve intolerably 
> steep, is not a new issue.
>
> I agree with it, but taken alone, it stops us adding useful utility 
> subcommands - the sort of thing I am thinking of:
>  svn purge: Remove unversioned files from a WC
>  svn sync: 'svn add' all unversioned files, 'svn rm' all missing files
>
> These are minor issues - implementable as scripts easily enough - but 
> despite being periodically requested, we've held off implementing them 
> for the reason mentioned above.
If we decide to go with this idea, then I suggest we have *one* utility 
command. To illustrate, your examples above would become:

    svn util purge
    svn util sync

Yes, this means have to make our command-line parsing slightly smarter, 
but that's just for the one command. The nice thing is that you don't 
need another --help option; "svn --help" will list all the current 
commands, including "util". Then,

    svn help util (or svn --help util, they're equivalent)

will list the util subcommands, and

    svn util help foo  (or svn --help util foo, equivalent again)

will describe the utility subcommand.

-- Brane


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: [RFC] 'basic/additional command set' - adding svn subcommands without destroying our learning curve

Posted by Julian Foad <ju...@btopenworld.com>.
Greg Hudson wrote:
> On Thu, 2005-11-03 at 15:19 +0000, Julian Foad wrote:
> 
>>I feel it would be very helpful for our basic "svn help" output to categorise 
>>the commands and give information about them, as has been proposed before.  (I 
>>don't find an alphabetical listing to be of much help.)
> 
> I resubmit http://svn.haxx.se/dev/archive-2005-07/0474.shtml as a
> counterargument.

There you said:
> But more importantly, any categorization will make it harder to look up
> a command by candidate name. If I can't remember whether it's "svn
> resolve" or "svn resolved", I can find that out in about two seconds
> with the current "svn help" output. With categorized output, I have to
> read over all the categories first and guess which category the
> developers thought resolve/resolved fit into.

I don't buy that.  For one thing, I don't see that as being a particularly 
common usage.  I see "svn help" being used mainly to discover half-remembered 
abilities like "What was that command that lets me discard the results of this 
conflicted merge?"  For another, I don't envisage there being so many 
categories or commands that you can't skim through them in about two seconds. 
For another, you can easily pipe the categorised output through "sort" to get 
back your alphabetical list (with the various category headers bunched together 
at the top or bottom of the output).

You may want to make sortability a design criterion for that reason.  That 
would just restrict our choice of text layout; that's fine by me.


>  I don't think version control commands naturally
> categorize.

Of course they do, to some extent.  OK, not cleanly; there may be some overlap 
and ambiguity, but that's the case in all complex systems.  That doesn't mean 
we can't do something useful.

> I can live with basic/additional since the best alternative is to make
> the additional command not exist at all.

Well, why do you think we can categorise them into "basic" and "additional" but 
not anything better?  I haven't yet seen or thought of any reasonable basis on 
which to make that distinction.  It's fairly obvious for some commands, but not 
for many.

>  (I don't want to see us adding
> "purge" and "sync" and "trackdown" and svnversion and so on to the basic
> command set until ours looks like arch's.)

For those who are not aware, I believe this refers to the huge command set that 
Arch has.

>  If there are slightly
> specialized utility commands which are harder to find, that's arguably a
> better solution than having those specialized utilities scripted by each
> user or dumped into contrib.

I agree that's better.

I think it's time people came up with some concrete proposals for dividing up 
the commands, including the definition of the categories and the list of 
commands in each.

Note that we could have categories that overlap; that wouldn't necessarily be 
ugly or confusing if presented appropriately.

- Julian

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: [RFC] 'basic/additional command set' - adding svn subcommands without destroying our learning curve

Posted by Greg Hudson <gh...@MIT.EDU>.
On Thu, 2005-11-03 at 15:19 +0000, Julian Foad wrote:
> I feel it would be very helpful for our basic "svn help" output to categorise 
> the commands and give information about them, as has been proposed before.  (I 
> don't find an alphabetical listing to be of much help.)

I resubmit http://svn.haxx.se/dev/archive-2005-07/0474.shtml as a
counterargument.  I don't think version control commands naturally
categorize.

I can live with basic/additional since the best alternative is to make
the additional command not exist at all.  (I don't want to see us adding
"purge" and "sync" and "trackdown" and svnversion and so on to the basic
command set until ours looks like arch's.)  If there are slightly
specialized utility commands which are harder to find, that's arguably a
better solution than having those specialized utilities scripted by each
user or dumped into contrib.


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: [RFC] 'basic/additional command set' - adding svn subcommands without destroying our learning curve

Posted by Julian Foad <ju...@btopenworld.com>.
Max Bowsher wrote:
> 
> To break the deadlock between the opposing motivations of 'keep svn 
> simple', and 'add useful utilities', I'd like to propose that we 
> introduce the notion of a basic and an additional command set. 
> Practically, all this means is splitting commands between `svn --help` 
> and `svn --help-additional`, and dividing our documentation of commands 
> in the same way.

My feeling is that categorising commands in any way is very tricky.  As others 
have said, the categories need to be clearly defined and easily understood.  A 
split between "basic" and "additional" has no real meaning that I can discern; 
something more meaningful like "uses wc only", "uses repos only", and "uses wc 
and repos" has a better chance (though that idea is probably too complex 
because many commands overlap multiple categories).

It would be valuable to look for precedents in other software, and discuss 
whether the approaches chosen seem to work.

I feel it would be very helpful for our basic "svn help" output to categorise 
the commands and give information about them, as has been proposed before.  (I 
don't find an alphabetical listing to be of much help.)  This might go a long 
way toward making the command set easier to learn even if all of the commands 
are listed.  In fact, this is only a slight variant on your suggestion; whether 
to provide help commands that only display a sub-set of the information is then 
a secondary question.  The basic difference in what I am suggesting here is 
that we need not assume that the "lesser" commands need to be hidden, either in 
the help or in their invocation syntax, as long as the "most wanted" commands 
are easily identifiable in the help.

- Julian

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org