Hello,
On Wed, Aug 30, 2017 at 11:22 PM, Johan Corveleyn <jcor...@gmail.com> wrote:
>
> On Tue, Aug 29, 2017 at 2:15 PM, Pavel Lyalyakin
> <pavel.lyalya...@visualsvn.com> wrote:
> > Hello,
> >
> > On Fri, Aug 25, 2017 at 2:03 PM, Johan Corveleyn <jcor...@gmail.com> wrote:
> >>
> >> [ cc -= svnbook-dev, as I guess this will not become book-material.
> >> More below ... ]
> >>
> >> On Thu, Jul 13, 2017 at 6:34 PM, C. Michael Pilato
> >> <cmpil...@red-bean.com> wrote:
> >> > On Thu, Jul 13, 2017 at 11:21 AM, Daniel Shahaf <d...@daniel.shahaf.name>
> >> > wrote:
> >> >>
> >> >> [moving from users@ ]
> >> >>
> >> >> Daniel Shahaf wrote on Fri, 30 Jun 2017 09:15 +0000:
> >> >> > I just ran into the following cheatsheet:
> >> >> >
> >> >> > http://www.chim.unifi.it/~signo/did/etc/subversion/neat.html
> >> >> >
> >> >> > It covers the normal multi-user workflow, branching, etc..
> >> >> >
> >> >> > (Kudos to the author, Giorgio Signorini, not to me.)
> >> >>
> >> >> As some of you know, the author gave us permission to incorporate that
> >> >> cheatsheet into the official documentation. Any volunteers to start the
> >> >> process?
> >> >>
> >> >> Cheers,
> >> >>
> >> >> Daniel
> >> >>
> >> > With respect to the author and the work he's done, I'm not really
> >> > interested
> >> > in us maintaining yet another collection of the same information already
> >> > covered -- in some cases multiple times, when you factor in the reference
> >> > sections -- by the book. At best this cheatsheet would be an appendix.
> >> > I'm
> >> > happy to link to the cheatsheet from from the book website, though.
> >> >
> >> > -- Mike
> >>
> >> FWIW, I think this cheatsheet is quite good and valuable (though I
> >> agree there is a lot of overlap with existing documentation),
> >> especially for newcomers. Just to have a good summary / reminder of
> >> common things you'll encounter.
> >>
> >> We have our own quickstart page: http://subversion.apache.org/quick-start
> >>
> >> How about:
> >>
> >> - Putting a link at the bottom of that page (there is already a link
> >> to the quickstart section of the book), linking to the original
> >> webpage of the author.
> >>
> >> or
> >>
> >> - Incorporating (some of) the content of that cheatsheet directly on
> >> http://subversion.apache.org/quick-start, so it's right there in front
> >> of you ...
> >>
> >>
> >> The latter option would be my personal preference (putting my user /
> >> admin hat on) -- I like having short info right in front of me in the
> >> right place -- but obviously imposes some amount of doc-maintenance
> >> work on "us".
> >>
> >> Maybe someone on this list would be willing to take this doc-task
> >> (migrating the current content, and keep an eye on keeping it up to
> >> date)?
> >>
> >> --
> >> Johan
> >
> > IMO, this doc-task has to be reworded into composing a walkthrough for SVN
> > end
> > user who wants to start performing basic version control tasks over remote
> > repository, but did not read SVNBook or other SVN-related documentation.
> > What do
> > you think?
> >
> > I feel that the cheatsheet[1] needs to be reworked or at least
> > restructured. In
> > the current state I feel that it is just personal notes that describe
> > various
> > common SVN tasks, actions and tricks. Cheatsheet or personal notes is not
> > a "quick start" guide.
>
> Hm, I guess you're right. Though I think there is also a place for
> snippets / reminders / recipes (common SVN tasks, actions and tricks),
> I suppose a good walkthrough is even better for bootstrapping new
> users.
>
> > Anyway, I like the idea of adding some of the content from the cheatsheet to
> > the quick start page[2] and I would be glad to take this task.
>
> That would be great!
I've spent some time to materialize the Quick Start document that I
think will be helpful for novice SVN users. At the moment, it provides
the most basic guidance which should be enough for "quick start".
However, it lacks "Viewing the history of changes" section that is not
ready yet. As of merging, I'd better provide a link to relevant
SVNBook sections. Merging is not a basic topic and should not be
described in a Quick Start guide, IMO.
I'm attaching two patches. I would greatly appreciate a review,
comments and suggestions. Here we go:
1. svn-quick-start-eol-native-v1.patch.txt
Log Message:
[[[
Add missing svn:eol-style=native property to publish/quick-start.html
]]]
2. svn-updated-quick-start-v1.patch.txt
Log Message:
[[[
* publish/quick-start.html:
Updating the SVN Quick Start guide as suggested in
https://lists.apache.org/thread.html/ea3462042131baac9c702fd4f19ae292c25ef20527d27db449e90f0e@%3Cdev.subversion.apache.org%3E
]]]
> > The question is: what kind of topics should the quick start page cover?
> >
> > My idea is that the page should provide task-based guidance for SVN end
> > user on
> > how to
> > * checkout a working copy,
> > * update the working copy,
> > * modify the data in the working copy and commit it,
> > * make a branch or tag,
> > * perform a simple merge.
>
> Sounds terrific.
>
> The current quickstart page focuses on "how do I quickly set up a my
> own little repository, locally (with file:///) and put some stuff in
> there". Like a beginning user / student / ... perhaps would like to
> version his own files. I think it's a good way to introduce the
> concepts of repository and working copy, and help them get started by
> versioning some of their own files locally.
SVNBook has a High-Speed Tutorial that provides such instructions:
http://svnbook.red-bean.com/en/1.8/svn.intro.quickstart.html
> Do you think you can start from that "setup", and continue with the
> topics you listed above? Or would you like to take a different angle?
I'm thinking about taking a different angle. I think that the document
should assume that a remote Subversion repository is already in place
and the user simply wants to start working with the existing versioned
data. Or he wants to import non-versioned data to the new remote
repository or repository sub-path.
In my experience, a beginning user or a student already has a
repository that he access via HTTP(S) or svnserve protocol. For
example, a first-year student gains access to his private SVN
repository and never has to use file:// schema or `svnadmin` tool.
There is another case, when a user should first request to create a
repository for him or for his project (here is an example:
http://information-technology.web.cern.ch/book/how-start-working-svn/requesting-new-svn-repository).
He won't use file:// schema and `svnadmin` in this case, too.
> > BTW, don't miss SVN-related docs on StackOverflow Documentation[3]. I'm
> > pretty
> > sure that some of the topics from that doc will be useful.
>
> Interesting! Maybe we can link to that, or look what of those topics
> we can cover as well.
>
> > [1]: http://www.chim.unifi.it/~signo/did/etc/subversion/neat.html
> > [2]: http://subversion.apache.org/quick-start
> > [3]: https://stackoverflow.com/documentation/svn/topics
> >
> > --
> > With best regards,
> > Pavel Lyalyakin
> > VisualSVN Team
>
> Thanks for taking a look at this.
>
> Cheers,
> --
> Johan
--
With best regards,
Pavel Lyalyakin
VisualSVN Team
Index: publish/quick-start.html
===================================================================
--- publish/quick-start.html (revision 1808237)
+++ publish/quick-start.html (working copy)
Property changes on: publish/quick-start.html
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Index: publish/quick-start.html
===================================================================
--- publish/quick-start.html (revision 1808237)
+++ publish/quick-start.html (working copy)
@@ -17,62 +17,423 @@
<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="#basic-tasks">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 feel
+ like compiling 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>
-<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: <tt>file://var/svn/repos/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
</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.status.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>
