On Tue, Feb 03, 2015 at 12:25:01PM +0000, Julian Foad wrote:
> Stefan Sperling wrote:
> > Below is a full log message for the entire changeset.
>
> This proposed log message seems to contain the documentation of the feature. Can we put the documentation somewhere more widely accessible?
>
> - in the book?
> - in the issue tracker [3]?
>
> or at least document it here in email to begin with and then it can be copied into such a place.
>
>
> > [[[
> > Add a '--pin-externals' option to 'svn copy'.
> > This option enables automated pinning of URLs in svn:externals properties
> > during copy operations (issue #1258).
> >
> > --pin-externals : pin externals with no explicit revision to their
> > last-changed revision (recommended when tagging)
>
> On the branch this help text now says:
>
> --pin-externals : pin externals with no explicit revision to their
> current revision (recommended when tagging)
>
> Would this be slightly better?
>
> pin each external with no explicit revision to the
> copied revision (recommended when tagging)
I think "copied revision" is misleading. The revision number of the copied tree
has no relation to the revision numbers which externals will be pinned to.
Externals generally point at other repositories and therefore use a distinct
revision number space.
We now pin externals to their HEAD revision if the copy source is a URL.
If the copy source is a WC, we pin externals to the revision they were
found to be checked out with in the WC (and it's an error if an external
is not checked out in the WC and the --pin-external option is used!).
> > This feature makes the svncopy.pl contrib script unnecessary.
>
> Perhaps now adjust svncopy.pl's help text to mention that its '--pin-externals' option is similar to 'svn copy --pin-externals'?
Good suggestion.
>
> To be clear, this makes the use of svncopy.pl unnecessary for this purpose.
> There is another mode of svncopy -- 'svncopy --update-externals' -- which
> rewrites absolute externals that point within the copied subtree, which is
> largely obsolete since relative externals were introduced, but which is not
> directly replaced by this new feature.
Hmm. Perhaps we should just remove the entire script for 1.9?
> > Externals are "pinned" by adding a peg revision to the external's
> > source URL.
> > For example, the external definition:
> > ^/foo/bar ext_bar
> > might become:
> > ^/foo/bar_at_400 ext_bar
> >
> > An external that is already pinned is left as-is.
>
>
> Could you expand this to mention both peg rev and operative rev, and both the old and new formats? For deciding whether the external
> definition needs to be adjusted, after reading the book [1,2] I
> understand that the question "is it pinned?" translates to "is a peg
> revision OR an operative revision specified?".
The example is now outdated after feedback from Branko and Bert
was incorporated into the branch.
We currently "pin" by adding a peg revision: ^/foo/bar_at_400 ext_bar
Pinning won't work with exernals which have been deleted in HEAD at
the time the copy is made or the external is checked out into a copy
source WC. In this situation a non-pinned external is already broken
and we decided not to make any attempt of mending it because we'd have
to make a guess as to which path at which revision the user wants.
Adding a peg revision to pinned externals has the advantage that tags
with pinned externals will check out correctly even if an external
they refer to is deleted from HEAD in the future.
Any -rN present in the externals definition is left as-is, since by
definition -rN should be older than HEAD or a checked out copy of
the external. Also, the kind of revision specification is left as-is,
which is important in case a date is used in the definition:
# in a working copy of ^/trunk
$ svn ps svn:externals -- "-r{2015-02-04} ^/branch/epsilon ext" .
property 'svn:externals' set on '.'
$ svn up
Updating '.':
Fetching external item into 'ext':
A ext/zeta
Updated external to revision 2.
At revision 2.
$ svn ci -mm
Sending .
Committing transaction...
Committed revision 3.
$ svn cp -m tag --parents --pin-externals ^/trunk ^/tags/1.0
Committing transaction...
Committed revision 4.
$ svn pl -v -R ^/tags/1.0
Properties on 'file:///tmp/svn-sandbox/repos/tags/1.0':
svn:externals
-r{2015-02-03T23:00:00.000000Z} ^/branch/epsilon_at_3 ext
Such a tag will keep checking out newer revisions of the external until
time has progressed beyond the specified day. Generally, using dates in
externals is a bad idea since dates are fairly fuzzy unless they use
sub-second granularity.
> When we change the definition to make it pinned, we add a peg
> revision. The example shows the new format (URL first).
> If the definition is in the old (PATH URL) format, do we change it to
> "PATH -rX URL" to keep using the old syntax with a peg rev, or convert to new syntax
> "URL_at_X PATH"? I think keeping the old format would be better, in that
> old (pre-1.5) clients may possibly still be using the repository and they would
> break if we changed to the new syntax.
Good point. But I don't think it's possible to retain compat with the old
syntax for the purposes of --pin-externals because the old syntax did not
support peg revisions (which is why the new syntax was invented).
And unfortunately the parsed external representation doesn't convey which
syntax was used in the property. I think this limitation is acceptable
since the new format has been supported since 1.5 and even Debian is now
shipping a more recent Subversion client than that :)
Received on 2015-02-03 14:50:43 CET