[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Overhaul the help for "svn merge"

From: Julian Foad <julianfoad_at_btopenworld.com>
Date: 2007-11-18 03:19:26 CET

(Trunk@27901, 2007-11-17)

> $ svn help merge
> merge: Apply the differences between two sources to a working copy path.

Only in certain cases. How about, "Merge changes from the repository into a
working copy."?

> usage: 1. merge sourceURL1[@N] sourceURL2[@M] [WCPATH]
> 2. merge sourceWCPATH1@N sourceWCPATH2@M [WCPATH]
> 3. merge [[-c M]... | [-r N:M]...] [SOURCE[@REV] [WCPATH]]

We need to clearly distinguish merge-tracking (new, "normal"?) usage from
patch-like ("--ignore-ancestry"?) usage. I'm not sure whether that would be by
separating their usage descriptions here, though.

> 1. In the first form, the source URLs are specified at revisions
> N and M. These are the two sources to be compared. The revisions
> default to HEAD if omitted.
>
> 2. In the second form, the URLs corresponding to the source working
> copy paths define the sources to be compared. The revisions must
> be specified.

I'm not familiar with how this works. Do cases 1 and 2 always imply patch-like
("--ignore-ancestry"?) behaviour even when the two given source URLs or paths
are the same?

> 3. In the third form, SOURCE can be a URL, or working copy item
> in which case the corresponding URL is used.
> If not specified, the copy source URL of SOURCE is used.

I don't understand that sentence.

> If the WCPATH cannot be determined automatically, an error
> is displayed asking for an explicit SOURCE.

Eww, "determined automatically" implies magic. Instead, "If the WCPATH can be
determined from/by XYZ then SOURCE is optional."

> This URL in revision REV is compared as it
> existed between revisions N and M. If REV is not specified, HEAD
> is assumed. '-c M' is equivalent to '-r <M-1>:M', and '-c -M'
> does the reverse: '-r M:<M-1>'. If neither N nor M is specified,
> they default to OLDEST_CONTIGUOUS_REV_OF_SOURCE_AT_URL and HEAD.
> Multiple '-c' and/or '-r' may be specified and mixing of forward
> and reverse ranges is allowed, however the ranges are compacted
> to their minimum representation before merging begins (which may
> result in a no-op).

How about the following replacement for the whole of syntax 3:

   In the third form, the SOURCE item in the repository can be
   identified by URL[@REV] (REV defaults to HEAD), or by a WC path
   (defaults to ".").
   The changes to consider merging from the source item are given
   by '-c' and/or '-r' options, any of which may be reverse ranges.
   If none are given then the range to consider is from the oldest
   incarnation of SOURCE that exists contiguously at its peg URL
   to the newest incarnation of SOURCE that exists contiguously at its peg URL ###?
   Of the changes to consider, those that are eligible for merging
   are merged, or with '--ignore-ancestry' all are merged.

On 2007-10-16, Kamesh Jayachandran wrote:
> In fact merge source url can be optional(if invoked with -g),
> it defaults to copy source of the target if one exists or
> the first merge source from its (svn:mergeinfo).

Can someone confirm that the behaviour is no longer dependent on "the first
merge source"?

- Julian

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Sun Nov 18 03:19:48 2007

This is an archived mail posted to the Subversion Dev mailing list.