Index: publish/quick-start.html =================================================================== --- publish/quick-start.html (revision 1809846) +++ publish/quick-start.html (working copy) @@ -17,62 +17,430 @@

Apache Subversion: Quick Start

-
-

Graphical user interface (GUI) clients - -

+ -

If you are not familiar with Subversion, you may be better served by a -graphical client. (The Subversion project only maintains a command-line-based -clients, but a number of third parties maintain graphical clients that build on -our API (for programmers).) We do not maintain -a list of such clients; instead, we recommend you do a Web search for -Subversion GUI client. - -

- -
-

Make an existing directory a working copy of a new repository - -

- -

The following commands will convert a ./my-directory/ containing -files into a working copy of a newly-created repository:

- -

On Unix:

- +
+

+ Installing the SVN client + +

+

+ Install the svn client to start collaborating on a project + that is using Subversion as its version control system. +

+

+ To install the client program, you can build it yourself from a source + code release or download a binary package. The list of sites where you + can obtain a pre-built Subversion client is available at the + official binary packages page. If you want + to compile the software for yourself, grab the source at the + Source Code page. +

+

+ Right after you install the client you should be able to test it by + issuing the svn command. You should see the following output: +

-$ 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.
 
+

+ Now you can start using the command line client to interact with the + remote repository. +

+
+

+ 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 Subversion GUI client. +

+
+
-

On Windows:

+
+

+ Terminology + +

+
+

+ What is a Repository? + +

+

+ 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 mod_dav_svn 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. +

+

+ Repository URL examples: +

+
    +
  • + Apache HTTP Server: https://svn.example.com/repos/MyRepo/MyProject/trunk +
  • +
  • + svnserve: svn://svn.example.com/repos/MyRepo/MyProject/branches/MyBranch +
  • +
  • + Direct access (Unix-style): file://var/svn/repos/MyRepo/MyProject/tags/1.1.0 +
  • +
  • + Direct access (Windows-style): file:///C:/Repositories/MyRepo/trunk/MyProject +
  • +
+
+
+

+ What is a Working Copy? + +

+

+ 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. +

+

+ 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 .svn at its root. The + administrative directory contains metadata necessary for Subversion to + manage the version-control capabilities. +

+

+ There can be as much working copies from the same repository or project + as you want with any combination of local modifications. +

+
+
+
+

+ Basic tasks + +

+
+

+ Importing data into the repository + +

+

+ In case you want to import existing non-versioned data into an SVN + repository, you should run the + + svn import command. Here is an example: +

-> 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"
 
- -

See also quickstart instructions in The Subversion Book.

- -
- -
+
+
+

+ Checking out a working copy + +

+

+ 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 svn 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 + + svn checkout command. Here is an example: +

+
+$ svn checkout https://svn.example.com/repos/MyRepo/MyProject/trunk MyWorkingCopy
+
+

+ 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). +

+

+ 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. +

+
+
+

+ Updating a working copy + +

+

+ 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 + + svn update command in your working copy. As a result, + your working copy will sync with the repository and download the + changes made by your colleagues. +

+

+ It is a good practice to update your working copy before committing + local modifications to the repository. +

+
+
+

+ Making changes in your local working copy + +

+

+ 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. +

+
+

+ Modifying existing files + +

+

+ 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. +

+
+

+ Committing your changes to the repository + +

+

+ In order to publish the changes you made in your working copy, you + should run the + + svn commit command. +

+
+

+ Review your changes before committing them! Use the + + svn status and + + svn diff commands to review the changes. +

+
+

+ Here is an example of the commit command: +

+
+$ svn commit -m "My Descriptive Log Message"
+
+

+ Note the -m (--message) 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. +

+
+
+
+

+ Performing file and directory operations + +

+

+ 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 svn + commands. +

+

+ 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. +

+
+

+ Adding new files and directories + +

+

+ 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 + + svn add command: +

+
+$ svn add foo.cs
+
+
+
+

+ Moving and renaming files and directories + +

+

+ Move and rename files and directories using the + + svn move or svn rename command: +

+
+$ svn move foo.cs bar.cs
+
+

+ The command svn rename is an alias for the + svn move. +

+
+
+

+ Copying files and directories + +

+

+ Copy files and directories using the + + svn copy command: +

+
+$ svn copy foo.cs bar.cs
+
+
+
+

+ Deleting files and directories + +

+

+ Delete files and directories using the svn delete + + svn delete command: +

+
+$ svn delete foo.cs
+
+
+
+

+ Reverting or discarding local changes + +

+

+ Discard your local uncommitted changes using the + + svn revert command: +

+
+$ svn revert foo.cs
+
+
+

+ Discarded uncommitted changes will be lost forever. You will not be + able to recover the reverted changes. Use svn revert with + caution! +

+
+
+
+
+

+ Branching and tagging + +

+

+ You should use the svn copy 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. +

+

+ The command svn copy 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 + + "Cheap Copies" 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. +

+
+

+ Creating a branch using direct URL to URL copy + +

+

+ 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: +

+
+$ svn copy https://example.com/MyRepo/trunk https://example.com/MyRepo/branches/MyNewBranch -m "Creating a new branch"
+
+
+
+
+

+ Getting more help + +

+

+ If you are new to Apache Subversion (SVN), read Version Control with + Subversion book (SVNBook). SVNBook is the Bible of SVN and must-read + for Subversion users and administrators. You can find SVNBook 1.8 at + http://svnbook.red-bean.com/en/1.8/ +

+
+ +