Hello Johan,
Thank you for taking the time to review this patch. :)
I think that I addressed most of your comments and suggestions in the
attached patch svn-updated-quick-start-v3.patch.txt. I've attached an
interdiff to v2 patch, too.
Here is a modified log message.
Log Message:
[[[
* publish/quick-start.html:
Reworking the SVN Quick Start page as discussed on dev_at_s.a.o [1]
[1] https://lists.apache.org/thread.html/da5b9f351a1bf2456aeb85e24ed88ff30b544a70995638af684684f1@%3Cdev.subversion.apache.org%3E
Patch by: Pavel Lyalyakin <pavel.lyalyakin[_at_]visualsvn.com>
]]]
On Tue, Sep 26, 2017 at 3:05 AM, Johan Corveleyn <jcorvel_at_gmail.com> wrote:
>
> On Fri, Sep 22, 2017 at 6:57 PM, Pavel Lyalyakin
> <pavel.lyalyakin_at_visualsvn.com> wrote:
> > Hello,
> >
> > It appears that the current SVN Quick Start page[1] is kind of desolate; there
> > is a discussion about updating it[2]. I want to volunteer for this task and I am
> > attaching a patch. :)
> >
> > My idea is to provide novice SVN end users with a quick reference on the most
> > basic concepts and operations:
> > * checkout a working copy,
> > * update the working copy,
> > * modify the data in the working copy and commit it,
> > * make a branch or tag.
> >
> > A user who needs help on how to begin working with SVN does not have to dive
> > into the SVNBook. Yes, he will read the SVNBook some time later to learn more
> > about basic operations and to find out about the magic of the complex ones. But
> > not on his first day when the only commands he needs are `svn checkout` and
> > `svn commit`.
> >
> > Log Message:
> > [[[
> > * publish/quick-start.html:
> > Reworking the SVN Quick Start page as discussed in
> > https://lists.apache.org/thread.html/da5b9f351a1bf2456aeb85e24ed88ff30b544a70995638af684684f1@%3Cdev.subversion.apache.org%3E
> > ]]]
> >
> > [1]: https://subversion.apache.org/quick-start
> > [2]: https://lists.apache.org/thread.html/da5b9f351a1bf2456aeb85e24ed88ff30b544a70995638af684684f1@%3Cdev.subversion.apache.org%3E
>
> Hi Pavel,
>
> Thanks again for taking this on. I'll try to give some feedback below.
>
>
> > Index: publish/quick-start.html
> > ===================================================================
> > --- publish/quick-start.html (revision 1808237)
> > +++ publish/quick-start.html (working copy)
> > @@ -17,62 +17,433 @@
> >
> > <h1>Apache Subversion: Quick Start</h1>
> >
> > -<div class="h2" id="gui">
> > -<h2>Graphical user interface (GUI) clients
> > - <a class="sectionlink" href="#gui"
> > - title="Link to this section">¶</a>
> > -</h2>
> > +<ul>
> > + <li>
> > + Installing the SVN client
> > + </li>
> > + <li>
> > + Understanding the terms
>
> I think "terms" can have the meaning of "terms of the agreement", or
> "terms of the license". I think "terminology" is better. Maybe just
> call this section "Terminology" (without the "understanding the ...").
I like "Terminology" without "Understanding ...". Fixed in v3 patch.
> > + </li>
> > + <li>
> > + Basic tasks
> > + </li>
> > + <li>
> > + Branching and tagging
> > + </li>
> > + <li>
> > + Getting more help
> > + </li>
> > +</ul>
> >
> > -<p>If you are not familiar with Subversion, you may be better served by a
> > -graphical client. (The Subversion project only maintains a command-line-based
> > -clients, but a number of third parties maintain graphical clients that build on
> > -our API (for programmers).) We do not maintain
> > -a list of such clients; instead, we recommend you do a Web search for
> > -<tt>Subversion GUI client</tt>.
> > -
> > -</div>
> > -
> > -<div class="h2" id="bootstrap">
> > -<h2>Make an existing directory a working copy of a new repository
> > - <a class="sectionlink" href="#bootstrap"
> > - title="Link to this section">¶</a>
> > -</h2>
> > -
> > -<p>The following commands will convert a <tt>./my-directory/</tt> containing
> > -files into a working copy of a newly-created repository:</p>
> > -
> > -<p>On Unix:</p>
> > -
> > + <div class="h2" id="installing-the-client">
> > + <h2>
> > + Installing the SVN client
> > + <a class="sectionlink" href="#installing-the-client"
> > + title="Link to this section">¶</a>
> > + </h2>
> > + <p>
> > + Install the <tt>svn</tt> client to start collaborating on the project
>
> "the project" -> "a project"
Fixed in v3 patch.
> > + that is using Subversion as its version control system.
> > + </p>
> > + <p>
> > + To install the client program, you can build it yourself from a source
> > + code release or download a binary package. The list of sites where you
> > + can obtain a pre-built Subversion client is available at the
> > + official binary packages page. If you want
> > + to compile the software for yourself, grab the source at the
> > + Source Code page.
> > + </p>
> > + <p>
> > + Right after you install the client you should be able to test it by
> > + issuing the svn command. You should see the following output:
> > + </p>
> > <pre>
> > -$ mkdir -p $HOME/.svnrepos/
> > -$ svnadmin create ~/.svnrepos/my-repos
> > -$ svn mkdir -m "Create directory structure."
> > file://$HOME/.svnrepos/my-repos/trunk
> > file://$HOME/.svnrepos/my-repos/branches
> > file://$HOME/.svnrepos/my-repos/tags
> > -$ cd my-directory
> > -$ svn checkout file://$HOME/.svnrepos/my-repos/trunk ./
> > -$ svn add --force ./
> > -$ svn commit -m "Initial import"
> > -$ svn up
> > +$ svn
> > +Type 'svn help' for usage.
> > </pre>
> > + <p>
> > + Now you can start using the command line client to interact with the
> > + remote repository.
> > + </p>
> > + <div class="notice">
> > + <p>
> > + If you are not familiar with Subversion, you may be better served by a
> > + graphical client. We do not maintain a list of such clients; instead,
> > + we recommend you do a Web search for <tt>Subversion GUI</tt> client.
> > + </p>
> > + </div>
> > + </div>
> >
> > -<p>On Windows:</p>
> > + <div class="h2" id="understanding-the-terms">
> > + <h2>
> > + Understanding the terms
> > + <a class="sectionlink" href="#understanding-the-terms"
> > + title="Link to this section">¶</a>
> > + </h2>
>
> So let's say "Terminology" here.
Fixed in v3 patch.
> > + <div class="h3" id="what-is-a-repository">
> > + <h3>
> > + What is a Repository?
> > + <a class="sectionlink" href="#what-is-a-repository"
> > + title="Link to this section">¶</a>
> > + </h3>
> > + <p>
> > + The repository is a version control database that often resides on a
> > + server and is usually exposed either by Apache HTTP Server
> > + (mod_dav_svn) or svnserve server.
>
> I'd say "by *an* Apache HTTP Server (*through the mod_dav_svn module*)
> or *by an* svnserve server".
Fixed in v3 patch.
> > The repository acts as a single
> > + source of truth and – as a central storage – it contains the complete
> > + history of changes of the versioned data in form of revisions.
> > + </p>
> > + <p>
> > + Repository URL examples:
> > + </p>
> > + <ul>
> > + <li>
> > + Apache HTTP Server:
> > <tt>https://svn.example.com/repos/MyRepo/MyProject/trunk</tt>
> > + </li>
> > + <li>
> > + svnserve: <tt>svn://svn.example.com/repos/MyRepo/MyProject/trunk</tt>
> > + </li>
> > + <li>
> > + Direct access (Unix-style):
> > <tt>file://var/svn/repos/MyRepo/MyProject/trunk</tt>
> > + </li>
> > + <li>
> > + Direct access (Windows-style):
> > <tt>file:///C:/Repositories/MyRepo/MyProject/trunk</tt>
> > + </li>
> > + </ul>
>
> Maybe not all of these examples should have the "MyProject/trunk",
> because there is a lot of diversity out there. Maybe throw a
> "/trunk/MyProject" in there, and a "/branches/mybranch" or
> "/tags/1.1.0"?
Yes, let's provide different URL examples. Fixed in v3 patch.
> > + </div>
> > + <div class="h3" id="what-is-a-working-copy">
> > + <h3>
> > + What is a Working Copy?
> > + <a class="sectionlink" href="#what-is-a-working-copy"
> > + title="Link to this section">¶</a>
> > + </h3>
> > + <p>
> > + The working copy is your local and private workspace that you use to
> > + interact with the central Subversion repository. You use the working
> > + copy to modify the contents of your project and fetch changes committed
> > + by others.
> > + </p>
> > + <p>
> > + The working copy contains your project's data and looks and acts like a
> > + regular directory on your local file system, but with one major
> > + difference - the working copy tracks the status and changes of files
> > + and directories within. You can think of the working copy as of a
> > + regular directory with version-control capabilities.
> > + </p>
>
> Maybe add a sentence to explain that Subversion keeps metadata in a
> .svn directory in the root of the working copy, to manage those
> version-control capabilities. (in case people start wondering how it
> works, and how it's physically different from a regular directory).
Yes, I agree that it makes sense to mention ".svn" directory here.
Fixed in v3 patch.
[[[
A working copy has an administrative directory named <tt>.svn</tt> at
its root. The administrative directory contains metadata necessary for
Subversion to manage the version-control capabilities.
]]]
> > + <p>
> > + There can be as much working copies from the same repository or project
> > + as you want with any combination of local modifications.
> > + </p>
> > + </div>
> > + </div>
> >
> > + <div class="h2" id="basic-tasks">
> > + <h2>
> > + Basic tasks
> > + <a class="sectionlink" href="#basic-tasks"
> > + title="Link to this section">¶</a>
> > + </h2>
> > + <div class="h3" id="importing-data">
> > + <h3>
> > + Importing data into the repository
> > + <a class="sectionlink" href="#importing-data"
> > + title="Link to this section">¶</a>
> > + </h3>
> > + <p>
> > + In case you want to import an existing non-versioned data to SVN
>
> Grammar tweak: drop the "an" before "existing", and add "an" before
> SVN (and I'd say "*into* an SVN repository").
Fixed in v3 patch.
> > + repository, you should run the
> > + <a href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.import.html">
> > + <tt>svn import</tt></a> command. Here is an example:
> > + </p>
> > <pre>
> > -> mkdir C:\repos
> > -> svnadmin create C:\repos\my-repos
> > -> svn mkdir -m "Create directory structure."
> > "file:///C:/repos/my-repos/trunk" "file:///C:/repos/my-repos/branches"
> > "file:///C:/repos/my-repos/tags"
> > -> cd my-directory
> > -> svn checkout "file:///C:/repos/my-repos/trunk" ./
> > -> svn add --force ./
> > -> svn commit -m "Initial import"
> > -> svn up
> > +$ svn import https://svn.example.com/repos/MyRepo/MyProject/trunk -m
> > "Initial project import"
> > </pre>
> > -
> > -<p>See also <a
> > -href="http://svnbook.red-bean.com/nightly/en/svn.intro.quickstart.html"
> > ->quickstart instructions in The Subversion Book</a>.</p>
> > -
> > -</div> <!-- bootstrap -->
> > -
> > -</div> <!-- #site-content -->
> > + </div>
> > + <div class="h3" id="checking-out-a-working-copy">
> > + <h3>
> > + Checking out a working copy
> > + <a class="sectionlink" href="#checking-out-a-working-copy"
> > + title="Link to this section">¶</a>
> > + </h3>
> > + <p>
> > + To begin making modifications to your project's data, you have to
> > + create a local copy of the versioned project. You can use the command
> > + line <tt>svn</tt> client or any GUI-based client that you prefer. Your
> > + local copy of the project is called a working copy and
> > + you create it by issuing the
> > + <a href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.checkout.html">
> > + <tt>svn checkout</tt></a> command. Here is an example:
> > + </p>
> > +<pre>
> > +$ svn checkout https://svn.example.com/repos/MyRepo/MyProject/trunk
> > +</pre>
> > + <p>
> > + As a result, you will get a working copy of the trunk of a project
> > + called MyProject that resides in MyRepo repository. The working copy
> > + will be located in MyProject directory on your computer. Note that
>
> I think it will be located in a "trunk" directory on your computer.
> Unless you do:
> svn checkout https://svn.example.com/repos/MyRepo/MyProject/trunk MyProject
Yes, the command was missing MyProject path.
> Though that might be a bit confusing, people might think the
> "MyProject" argument is somehow special, while it's just the target
> directory. Maybe something like "MyWork"? Or just say here that it'll
> be located in a directory "trunk" (last path component as default
> target dir)?
What about "MyWorkingCopy"? It should make it clearer I think.
[[[
svn checkout https://svn.example.com/repos/MyRepo/MyProject/trunk MyWorkingCopy
]]]
Fixed in v3 patch.
> > + instead of checking out the trunk, you can check out some branch
> > + or a tag (assuming they already exist in the repository).
> > + </p>
> > + <p>
> > + You can get the working copy of the whole repository MyRepo, too. But
> > + you should refrain from doing so. Generally speaking, you do not need
> > + to have a working copy of the whole repository for your work because
> > + your working copy can be instantly switched to another development
> > + branch. Moreover, Subversion repository can contain a number of
> > + unrelated projects and it is better to have a dedicated working copy
> > + for each of them, not a single working copy for all of the projects.
>
> Not to mention the repository database stores all different variations
> of the code (branches, tags) in an efficient way. It's usually not a
> good idea to check out all branches and tags onto a local disk as real
> directories. Dunno if we should mention that here though ...
I would skip that for now.
> > + </p>
> > + </div>
> > + <div class="h3" id="updating-a-working-copy">
> > + <h3>
> > + Updating a working copy
> > + <a class="sectionlink" href="#updating-a-working-copy"
> > + title="Link to this section">¶</a>
> > + </h3>
> > + <p>
> > + You are not the only person working on the project, right? This means
> > + that your colleagues are also making modifications to the project's
> > + data. To stay up to date and to fetch the modifications committed by
> > + others, you should run the
> > + <a href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.update.html">
> > + <tt>svn update</tt></a> command in your working copy. As a result,
> > + your working copy will sync with the repository and download the
> > + changes made by your colleagues.
> > + </p>
> > + <p>
> > + It is a rule to update your working copy before committing local
> > + modifications to the repository.
>
> No, I wouldn't say that. Maybe you could say that's "good practice" (I
> think in general it is, though it depends I guess).
Fixed in v3 patch. We may also use "common practice" instead of "good practice".
> > + </p>
> > + </div>
> > + <div class="h3" id="making-changes">
> > + <h3>
> > + Making changes in your local working copy
> > + <a class="sectionlink" href="#making-changes"
> > + title="Link to this section">¶</a>
> > + </h3>
> > + <p>
> > + Most of the time, you are going to perform modifications to the
> > + project's data by modifying the contents of the working copy. As soon
> > + as you are satisfied with the modifications and you've reviewed them
> > + thoroughly, you are ready to publish them to the central repository.
>
> Maybe you can already mention the word "commit" in that sentence?
> Perhaps just say: "..., you are ready to commit them to the central
> repository."
Yes, let's change "publish" to "commit" here. Fixed in v3 patch.
> > + </p>
> > + <div class="h4" id="modifying-existing-files">
> > + <h4>
> > + Modifying existing files
> > + <a class="sectionlink" href="#modifying-existing-files"
> > + title="Link to this section">¶</a>
> > + </h4>
> > + <p>
> > + Modify the files as you usually do using your favorite text
> > + processor, graphics editor, audio editing software, IDE, etc. As
> > + soon as you save the changes to disk, Subversion will recognize them
> > + automatically.
> > + </div>
> > + <div class="h4" id="committing-changes">
> > + <h4>
> > + Committing your changes to the repository
> > + <a class="sectionlink" href="#committing-changes"
> > + title="Link to this section">¶</a>
> > + </h4>
> > + <p>
> > + In order to publish the changes you made in your working copy, you
> > + should run the
> > + <a href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.commit.html">
> > + <tt>svn commit</tt></a> command.
> > + </p>
> > + <div class="notice">
> > + <p>
> > + Review your changes before committing them! Use the
> > + <a
> > href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.status.html">
> > + <tt>svn status</tt></a> and
> > + <a
> > href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.diff.html">
> > + <tt>svn diff</tt></a> commands to review the changes.
> > + </p>
> > + </div>
> > + <p>
> > + Here is an example of the commit command:
> > + </p>
> > +<pre>
> > +$ svn commit -m "My Descriptive Log Message"
> > +</pre>
> > + <p>
> > + Note the <tt>-m (--message)</tt> option. You must always include
> > + descriptive commit log message. The log message has to help others
> > + to understand why you made this commit, it has to contain a summary
> > + of the changes you made.
>
> The imperatives are a bit strong here. Perhaps rephrase it to: "You
> should always include a descriptive commit log message. It should help
> others (including your future self) understand why you made this
> commit. Apart from the "why" it's a good idea to include a summary of
> your changes in the log message."
>
> Or something like that.
Fixed in v3 patch.
> > + </p>
> > + </div>
> > + </div>
> > + <div class="h3" id="performing-file-operations">
> > + <h3>
> > + Performing file operations
> > + <a class="sectionlink" href="#performing-file-operations"
> > + title="Link to this section">¶</a>
> > + </h3>
>
> Hmmm, this is not only about files, is it? Maybe you should name this
> section "Performing tree changes", or "Performing file and directory
> operations".
"Performing file and directory operations" sounds better IMO. Fixed in v3 patch.
> > + <p>
> > + You can perform any actions with your project's data within the working
> > + copy, but operations that involve copying, moving, renaming and
> > + deleting must be performed using the corresponding <tt>svn</tt>
> > + commands.
> > + </p>
> > + <div class="h4" id="adding-new-files">
> > + <h4>
> > + Adding new files
> > + <a class="sectionlink" href="#adding-new-files"
> > + title="Link to this section">¶</a>
> > + </h4>
> > + <p>
> > + Put new files to the working copy and Subversion will recognize them
> > + as unversioned. It will not automatically start tracking the new
> > + files unless you run the
> > + <a href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.add.html">
> > + <tt>svn add</tt></a> command:
>
> I think you can replace "files" with "files and directories" in the
> above paragraph and title to make it a bit more general.
>
> Also, I think "recognize them as unversioned" is a bit confusing (the
> word "recognize" gives the impression that Subversion handles them
> somehow). Maybe "Subversion will *see* them as 'unversioned'" (quoting
> the word unversioned to point out it's a defined term).
Fixed in v3 patch.
> > + </p>
> > +<pre>
> > +$ svn add foo.cs
> > +</pre>
> > + </div>
> > + <div class="h4" id="moving-and-renaming-files-and-directories">
> > + <h4>
> > + Moving and renaming files and directories
> > + <a class="sectionlink"
> > href="#moving-and-renaming-files-and-directories"
> > + title="Link to this section">¶</a>
> > + </h4>
> > + <p>
> > + Move and rename files and directories using the
> > + <a href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.move.html">
> > + <tt>svn move</tt></a> or <tt>svn rename</tt> command:
> > + </p>
> > +<pre>
> > +$ svn move foo.cs bar.cs
> > +</pre>
> > + <p>
> > + The command <tt>svn rename</tt> is an alias for the
> > + <tt>svn move</tt>.
> > + </p>
>
> Maybe a small word of warning should be put here: if you move a file
> or directory with regular filesystem commands, Subversion will not
> know about the move, and will just see an unrelated add and delete. To
> get good results Subversion should be made aware of moves, so it can
> track them in its metadata (this is a definite difference from the
> heuristic-tracking DVCS'es ... Subversion requires explicit tracking
> of tree changes).
Let's put this under (#performing-file-and-dir-operations) /
(#performing-file-operations) secition. This note applies to all tree
changes and I don't think that we should repeat this information in
every child section.
> > + </div>
> > + <div class="h4" id="copying-files-and-directories">
> > + <h4>
> > + Copying files and directories
> > + <a class="sectionlink" href="#copying-files-and-directories"
> > + title="Link to this section">¶</a>
> > + </h4>
> > + <p>
> > + Copy files and directories using the
> > + <a href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.copy.html">
> > + <tt>svn copy</tt></a> command:
> > + </p>
> > +<pre>
> > +$ svn copy foo.cs bar.cs
> > +</pre>
>
> The above is a bit tricky, as 'svn copy' also creates a branch of the
> copied item, and the line of history is split (or put another way: the
> copied item is linked to the same pre-copy history). It's a bit
> difficult to explain all this in a quick start guide, unless you have
> some ideas.
>
> Maybe it's good as it is, but OTOH I've seen that often users are
> surprised by this (and really just wanted to copy the file contents,
> but not make it historically related to the original file).
>
> Maybe we should just drop this section "copying files and directories"
> for now? ('svn copy' is also mentioned later on in the "branching"
> section)
I'm not sure about that. I think that it is good to mention `svn copy`
command here and not mention pre-copy history link. If a user makes a
copy with regular `cp` command, he will get an unversioned file or
directory in his working copy and this may be an issue.
> > + </div>
> > + <div class="h4" id="deleting-files-and-directories">
> > + <h4>
> > + Deleting files and directories
> > + <a class="sectionlink" href="#deleting-files-and-directories"
> > + title="Link to this section">¶</a>
> > + </h4>
> > + <p>
> > + Delete files and directories using the svn delete
> > + <a href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.delete.html">
> > + <tt>svn delete</tt></a> command:
> > + </p>
> > +<pre>
> > +$ svn delete foo.cs
> > +</pre>
>
> Maybe here too, a small warning that if you delete files or
> directories with regular filesystem commands, Subversion will not know
> about the delete. It will regard the item as "missing" (having
> metadata but no corresponding file), and will bring it back on the
> next 'svn update'.
>
> > + </div>
> > + <div class="h4" id="reverting-local-changes">
> > + <h4>
> > + Reverting or discarding local changes
> > + <a class="sectionlink" href="#reverting-local-changes"
> > + title="Link to this section">¶</a>
> > + </h4>
> > + <p>
> > + Revert your local uncommitted changes using the
>
> ^^ Maybe say "Discard your local ...", so it's immediately clear what
> 'svn revert' does.
Fixed in v3 patch.
> > + <a href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.revert.html">
> > + <tt>svn revert</tt></a> command:
> > + </p>
> > +<pre>
> > +$ svn revert foo.cs
> > +</pre>
> > + <div class="notice">
> > + <p>
> > + Discarded uncommitted changes will be lost forever. You
> > will not be
> > + able to recover the reverted changes. Use <tt>svn revert</tt> with
> > + caution!
> > + </p>
> > + </div>
> > + </div>
> > + </div>
> > + <div class="h3" id="branching-and-tagging">
> > + <h3>
> > + Branching and tagging
> > + <a class="sectionlink" href="#branching-and-tagging"
> > + title="Link to this section">¶</a>
> > + </h3>
> > + <p>
> > + You should use the <tt>svn copy</tt> command to create branches and
> > + tags. This is the same command that is used to copy items in your
> > + working copy and in the repository.
>
> ... if you want them to be historically related (?)
Yes, let's add this. Fixed in v3 patch.
> > + </p>
> > + <p>
> > + The command <tt>svn copy</tt> is used for branching because, branch is
> > + technically a copy of the source you copy from. However, this is not
> > + an ordinary copy are familiar with when copying files on your local
> > + file system.
>
> There's a word missing in the above sentence.
Oops, my bad. Fixed in v3 patch.
> > Branches in Subversion are so called
> > + <a href="http://svnbook.red-bean.com/en/1.8/svn.branchmerge.using.html#svn.branchmerge.using.create">
> > + "Cheap Copies"</a> that are similar to symlinks.
>
> The "cheap copy" reference is only valid for the repository
> (back-end). So you should throw the word "repository" somewhere in
> that sentence :-).
Fixed in v3 patch.
> > Therefore, creating a
> > + new branch takes minimal time to complete and takes practically no
> > + space in the Subversion repository. You can create branches and use
> > + them for any change you want regardless of the change's size and scope.
> > + </p>
> > + <div class="h4" id="url-to-url-copy">
> > + <h4>
> > + Creating a branch using direct URL to URL copy
> > + <a class="sectionlink" href="#url-to-url-copy"
> > + title="Link to this section">¶</a>
> > + </h4>
> > + <p>
> > + Branching in Subversion is simple. In the simplest form, creating a
> > + new branch requires you to run the command against the remote
> > + repository's URLs. For example, let's create a new branch out of the
> > + mainline trunk:
> > + </p>
> > +<pre>
> > +$ svn copy https://example.com/MyRepo/trunk
> > https://example.com/MyRepo/branches/MyNewBranch -m "Creating a new
> > branch"
> > +</pre>
> > + </div>
> > + <div class="h4" id="WC-copy">
> > + <h4>
> > + Creating a branch through a working copy
> > + <a class="sectionlink" href="#WC-copy"
> > + title="Link to this section">¶</a>
> > + </h4>
> > + <p>
> > + When you interact with the remote central repository using your
> > + private local workspace - the working copy - you can use
> > + repository-relative URL instead of direct URL to URL copy to create
> > + a new branch:
> > + </p>
> > +<pre>
> > +$ svn copy "^/MyRepo/trunk" "^/MyRepo/branches/MyNewBranch" -m
> > "Creating a new branch"
> > +</pre>
>
> Hmmm, that's not what I consider "Creating a branch through a working
> copy". It's good to mention the repository-relative URL syntax
> somewhere. But I thought that section was about "Creating a branch
> *from* a working copy". Like:
>
> $ svn copy MyWork https://example.com/MyRepo/branches/OtherBranch -m "blabla"
>
> (potentially putting uncommitted changes directly in the branch).
> Though I'm not sure we should mention that here, and I think it's more
> often used for tags than for branches (creating a tag from a working
> copy that's been used for a build, so you have a snapshot of the exact
> sources that were used by your buildscripts).
>
> I think it might be better to drop #WC-copy, and perhaps add a section
> about the repository-relative url's (?). Not sure.
I would add a section about repository-relative URLs as a Tip or Note,
but not a whole section.
I've dropped #WC-copy in v3 patch. I think that we should mention it
in a Tag-specific section. The current version of the document does
not have it, though.
> Also, somewhere here you should probably mention that tags are very
> similar to branches (just another copy on the repository) ... the only
> thing discerning them is convention or policy (possibly enforced
> technically by the SVN administrator) to make tags read-only.
>
> > + </div>
> > + </div>
> > + <div class="h2" id="more-help">
> > + <h2>
> > + Getting more help
> > + <a class="sectionlink" href="#more-help"
> > + title="Link to this section">¶</a>
> > + </h2>
> > + <p>
> > + If you are new to Apache Subversion (SVN), read Version Control with
> > + Subversion book (SVNBook). SVNBook is the Bible of SVN and must-read
> > + for Subversion users and administrators. You can find SVNBook 1.8 at
> > + http://svnbook.red-bean.com/en/1.8/
> > + </p>
> > + </div>
> > + </div>
> > + </div> <!-- #site-content -->
> > </body>
> > </html>
>
>
> All in all, nice work!
>
> I think, now we got this far to explain branches, we should really
> also explain some basic 'merge' commands, very briefly (the two main
> usages: "complete" merges and "cherry-pick" merges, i.e. numbers 1 and
> 2 from 'svn help merge'). Also, I still would like to have a small
> section "Creating your own local repository" as a replacement of the
> current Quickstart guide. But those can happen in other commits /
> patches for sure.
Sure, I am going to continue with this task. The current version of
the document (as it is in v3 patch) is missing several important
sections that I thing about adding:
* Viewing the history of changes: provide `svn log` examples.
* Merging: automatic reintegration merges and cherry-picking.
* Tagging: we should provide tagging examples.
* Creating your own local repository: a quick guide on this task with
a link to SVNBook's High-Speed Tutorial.
> --
> Johan
--
With best regards,
Pavel Lyalyakin
VisualSVN Team
Received on 2017-09-27 17:09:36 CEST