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 [email protected] [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 <[email protected]> wrote:
>
> On Fri, Sep 22, 2017 at 6:57 PM, Pavel Lyalyakin
> <[email protected]> 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>
> > + <a href="#installing-the-client">Installing the SVN client</a>
> > + </li>
> > + <li>
> > + <a href="#understanding-the-terms">Understanding the terms</a>
>
> 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>
> > + <a href="#basic-tasks">Basic tasks</a>
> > + </li>
> > + <li>
> > + <a href="#branching-and-tagging">Branching and tagging</a>
> > + </li>
> > + <li>
> > + <a href="#more-help">Getting more help</a>
> > + </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
> > -<a href="/docsapi/latest/">our API (for programmers)</a>.) 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
> > + <a href="/packages.html">official binary packages page</a>. If you
> > want
> > + to compile the software for yourself, grab the source at the
> > + <a href="/source-code.html">Source Code</a> 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
> > + <a
> > href="http://svnbook.red-bean.com/en/1.8/";>http://svnbook.red-bean.com/en/1.8/</a>
> > + </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
Index: publish/quick-start.html
===================================================================
--- publish/quick-start.html (revision 1809846)
+++ publish/quick-start.html (working copy)
@@ -17,62 +17,430 @@
<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>
+ <a href="#installing-the-client">Installing the SVN client</a>
+ </li>
+ <li>
+ <a href="#terminology">Terminology</a>
+ </li>
+ <li>
+ <a href="#basic-tasks">Basic tasks</a>
+ </li>
+ <li>
+ <a href="#branching-and-tagging">Branching and tagging</a>
+ </li>
+ <li>
+ <a href="#more-help">Getting more help</a>
+ </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
-<a href="/docsapi/latest/">our API (for programmers)</a>.) 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 a project
+ 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
+ <a href="/packages.html">official binary packages page</a>. If you want
+ to compile the software for yourself, grab the source at the
+ <a href="/source-code.html">Source Code</a> 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="terminology">
+ <h2>
+ Terminology
+ <a class="sectionlink" href="#terminology"
+ title="Link to this section">¶</a>
+ </h2>
+ <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 an Apache HTTP Server
+ (through the <tt>mod_dav_svn</tt> module) or by an svnserve server.
+ 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/branches/MyBranch</tt>
+ </li>
+ <li>
+ Direct access (Unix-style):
<tt>file://var/svn/repos/MyRepo/MyProject/tags/1.1.0</tt>
+ </li>
+ <li>
+ Direct access (Windows-style):
<tt>file:///C:/Repositories/MyRepo/trunk/MyProject</tt>
+ </li>
+ </ul>
+ </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. 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>
+ <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 existing non-versioned data into an SVN
+ 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
MyWorkingCopy
+</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 MyWorkingCopy directory on your computer. Note that
+ 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.
+ </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 good practice to update your working copy before committing
+ local modifications to the repository.
+ </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 commit them to the central repository.
+ </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 should always include
+ a descriptive commit log message. It should help others including
+ yourself understand the reason why you made this commit. It is a
+ good idea to include a summary of your changes in the log message,
+ too.
+ </p>
+ </div>
+ </div>
+ <div class="h3" id="performing-file-and-dir-operations">
+ <h3>
+ Performing file and directory operations
+ <a class="sectionlink" href="#performing-file-and-dir-operations"
+ title="Link to this section">¶</a>
+ </h3>
+ <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>
+ <p>
+ Subversion does not use heurisic-tracking for tree changes in a working
+ copy. Subversion requires explicit tracking of tree changes. If you
+ perform a tree changes such as move or copy with regular filesystem
+ commands, Subversion will not know about this operation. To track tree
+ changes Subversion should be made aware of them.
+ </p>
+ <div class="h4" id="adding-new-files-and-directories">
+ <h4>
+ Adding new files and directories
+ <a class="sectionlink" href="#adding-new-files-and-directories"
+ title="Link to this section">¶</a>
+ </h4>
+ <p>
+ Put new files or directories to the working copy and Subversion will
+ see 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:
+ </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>
+ </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>
+ </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>
+ </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>
+ Discard your local uncommitted changes using the
+ <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 when you want them to be
+ historically related.
+ </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, it is not
+ an ordinary copy that you are familiar with when copying files on your
+ local file system. Branches in Subversion repositories 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. 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>
+ <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
+ <a
href="http://svnbook.red-bean.com/en/1.8/";>http://svnbook.red-bean.com/en/1.8/</a>
+ </p>
+ </div>
+ </div>
+ </div> <!-- #site-content -->
</body>
</html>
@@ -19 +19 @@ Index: publish/quick-start.html
-+ <a href="#understanding-the-terms">Understanding the terms</a>
++ <a href="#terminology">Terminology</a>
@@ -59 +59 @@ Index: publish/quick-start.html
-+ Install the <tt>svn</tt> client to start collaborating on the project
++ Install the <tt>svn</tt> client to start collaborating on a project
@@ -100 +100 @@ Index: publish/quick-start.html
-+ <div class="h2" id="understanding-the-terms">
++ <div class="h2" id="terminology">
@@ -102,2 +102,2 @@ Index: publish/quick-start.html
-+ Understanding the terms
-+ <a class="sectionlink" href="#understanding-the-terms"
++ Terminology
++ <a class="sectionlink" href="#terminology"
@@ -114,4 +114,5 @@ Index: publish/quick-start.html
-+ server and is usually exposed either by Apache HTTP Server
-+ (mod_dav_svn) or svnserve server. 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.
++ server and is usually exposed either by an Apache HTTP Server
++ (through the <tt>mod_dav_svn</tt> module) or by an svnserve server.
++ 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.
@@ -127 +128 @@ Index: publish/quick-start.html
-+ svnserve:
<tt>svn://svn.example.com/repos/MyRepo/MyProject/trunk</tt>
++ svnserve:
<tt>svn://svn.example.com/repos/MyRepo/MyProject/branches/MyBranch</tt>
@@ -130 +131 @@ Index: publish/quick-start.html
-+ Direct access (Unix-style):
<tt>file://var/svn/repos/MyRepo/MyProject/trunk</tt>
++ Direct access (Unix-style):
<tt>file://var/svn/repos/MyRepo/MyProject/tags/1.1.0</tt>
@@ -133 +134 @@ Index: publish/quick-start.html
-+ Direct access (Windows-style):
<tt>file:///C:/Repositories/MyRepo/MyProject/trunk</tt>
++ Direct access (Windows-style):
<tt>file:///C:/Repositories/MyRepo/trunk/MyProject</tt>
@@ -154 +155,4 @@ Index: publish/quick-start.html
-+ regular directory with version-control capabilities.
++ regular directory with version-control capabilities. 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.
@@ -176 +180 @@ Index: publish/quick-start.html
-+ In case you want to import an existing non-versioned data to SVN
++ In case you want to import existing non-versioned data into an SVN
@@ -217 +221 @@ Index: publish/quick-start.html
-+$ svn checkout https://svn.example.com/repos/MyRepo/MyProject/trunk
++$ svn checkout https://svn.example.com/repos/MyRepo/MyProject/trunk
MyWorkingCopy
@@ -222 +226 @@ Index: publish/quick-start.html
-+ will be located in MyProject directory on your computer. Note that
++ will be located in MyWorkingCopy directory on your computer. Note
that
@@ -253,2 +257,2 @@ Index: publish/quick-start.html
-+ It is a rule to update your working copy before committing local
-+ modifications to the repository.
++ It is a good practice to update your working copy before committing
++ local modifications to the repository.
@@ -267 +271 @@ Index: publish/quick-start.html
-+ thoroughly, you are ready to publish them to the central repository.
++ thoroughly, you are ready to commit them to the central repository.
@@ -309,4 +313,5 @@ Index: publish/quick-start.html
-+ 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.
++ Note the <tt>-m (--message)</tt> option. You should always include
++ a descriptive commit log message. It should help others including
++ yourself understand the reason why you made this commit. It is a
++ good idea to include a summary of your changes in the log message,
++ too.
@@ -316 +321 @@ Index: publish/quick-start.html
-+ <div class="h3" id="performing-file-operations">
++ <div class="h3" id="performing-file-and-dir-operations">
@@ -318,2 +323,2 @@ Index: publish/quick-start.html
-+ Performing file operations
-+ <a class="sectionlink" href="#performing-file-operations"
++ Performing file and directory operations
++ <a class="sectionlink" href="#performing-file-and-dir-operations"
@@ -328 +333,8 @@ Index: publish/quick-start.html
-+ <div class="h4" id="adding-new-files">
++ <p>
++ Subversion does not use heurisic-tracking for tree changes in a
working
++ copy. Subversion requires explicit tracking of tree changes. If you
++ perform a tree changes such as move or copy with regular filesystem
++ commands, Subversion will not know about this operation. To track
tree
++ changes Subversion should be made aware of them.
++ </p>
++ <div class="h4" id="adding-new-files-and-directories">
@@ -330,2 +342,2 @@ Index: publish/quick-start.html
-+ Adding new files
-+ <a class="sectionlink" href="#adding-new-files"
++ Adding new files and directories
++ <a class="sectionlink" href="#adding-new-files-and-directories"
@@ -335,2 +347,2 @@ Index: publish/quick-start.html
-+ Put new files to the working copy and Subversion will recognize them
-+ as unversioned. It will not automatically start tracking the new
++ Put new files or directories to the working copy and Subversion will
++ see them as "unversioned". It will not automatically start
tracking the new
@@ -401 +413 @@ Index: publish/quick-start.html
-+ Revert your local uncommitted changes using the
++ Discard your local uncommitted changes using the
@@ -426 +438,2 @@ Index: publish/quick-start.html
-+ working copy and in the repository.
++ working copy and in the repository when you want them to be
++ historically related.
@@ -429,4 +442,4 @@ Index: publish/quick-start.html
-+ 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. Branches in Subversion are so called
++ The command <tt>svn copy</tt> is used for branching because branch is
++ technically a copy of the source you copy from. However, it is not
++ an ordinary copy that you are familiar with when copying files on your
++ local file system. Branches in Subversion repositories are so called
@@ -455,16 +467,0 @@ Index: publish/quick-start.html
-+ <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>
-+ </div>
