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
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>
+ </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
+ 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>
+ <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. 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>
+ </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>
+ <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
+ 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
+ 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 rule 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 publish 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 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.
+ </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>
+ <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:
+ </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>
+ Revert 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.
+ </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. 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. 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>
+ </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>
