title: Best practice use of svn:externals
body: <p>Let's take three cases:</p>
  
  <ol>
  <li><p>This statement is good. 999 is a peg. This is the so-called "old format":</p>
  
  <blockquote>
    <p><code>foo -r999 http://myrepo/foo</code></p>
  </blockquote></li>
  <li><p>Alternatively, the peg can also be specified like this (in the "new format"), and is also good:</p>
  
  <blockquote>
    <p><code>http://myrepo/foo@999 foo</code></p>
  </blockquote></li>
  <li><p>But here is a complication in the "new format": <code>-r999</code> can be put in front, which changes its meaning entirely from being a peg to being an "operative version". And the actual peg becomes HEAD (i.e. no longer deterministic), according to the to <a href="http://svnbook.red-bean.com/en/1.7/svn.advanced.externals.html" rel="noreferrer">SVN Book</a>:</p>
  
  <blockquote>
    <p><code>-r999 http://myrepo/foo foo</code></p>
  </blockquote>
  
  <p>Here's why I think this format may be a very bad idea: If a rename of "bar" to "foo" happens after rev 999, what content will actually be checked out? The renamed version, bar@999. Is this really useful? And then later, another rename happens, naming "baz" to "foo". Now users will be checking out baz@999. Therefore, as time goes on, the user will never be certain that 999 refers to the same code.</p></li>
  </ol>
  
  <p>Is #3 a loophole waiting to cause trouble? Should users be warned with a bright red flag to avoid using the format of #3? Or is it actually useful, despite its non-determinism? This is almost too easy to misunderstand and to get wrong, and so it seems like a best practice needs to be specified.</p>
  
  <p>From the <a href="http://svnbook.red-bean.com/en/1.7/svn.advanced.externals.html" rel="noreferrer">SVN Book</a>, if you really dig into it, it subtly hints users to be careful:</p>
  
  <blockquote>
    <p>be careful to avoid naively relocating the -rNNN portion of the definition—the older format uses that revision as a peg revision, but the newer format uses it as an operative revision (with a peg revision of HEAD unless otherwise specified; see the section called “Peg and Operative Revisions” for a full explanation of the distinction here).</p>
  </blockquote>