[svk-commit] r3068 - in trunk/lib/SVK: Help
nobody at bestpractical.com
nobody at bestpractical.com
Mon Aug 18 11:23:49 EDT 2008
Author: falcone at bestpractical.com
Date: Mon Aug 18 11:23:19 2008
New Revision: 3068
Modified:
trunk/lib/SVK/Command/Branch.pm
trunk/lib/SVK/Help/Intro.pod
Log:
* tweak Intro to show usage of svk branch
* give a few examples of how to use svk branch in common usage
in the svk help branch docs
Modified: trunk/lib/SVK/Command/Branch.pm
==============================================================================
--- trunk/lib/SVK/Command/Branch.pm (original)
+++ trunk/lib/SVK/Command/Branch.pm Mon Aug 18 11:23:19 2008
@@ -138,7 +138,7 @@
);
} else {
$logger->info(
- loc("Project not found. use 'svk branch --setup %1' to initial.\n", $target->depotpath)
+ loc("Project not found. use 'svk branch --setup %1' to initialize.\n", $target->depotpath)
);
}
return ;
@@ -647,7 +647,7 @@
if (!$proj) {
$logger->info(
- loc("Project not found. use 'svk branch --setup mirror_path' to initial one.\n",$msg)
+ loc("Project not found. use 'svk branch --setup mirror_path' to initialize one.\n",$msg)
);
return ;
}
@@ -1038,8 +1038,8 @@
--create : create a new branch
--tag : create in the tags directory
--local : targets in local branch
- --delete : delete BRANCH(s)
- --checkout : checkout BRANCH in current directory
+ --delete [--rm|del]: delete BRANCH(s)
+ --checkout [--co] : checkout BRANCH in current directory
--switch : switch the current checkout to another branch
(can be paired with --create)
--merge : automatically merge all changes from BRANCH1, BRANCH2,
@@ -1052,6 +1052,7 @@
--from-tag TAG : specify the source tag name
-C [--check-only] : try a create, move or merge operation but make no
changes
+ --export : used with --checkout to create a detached copy
=head1 DESCRIPTION
@@ -1061,6 +1062,133 @@
directory layout for your project or specifically tell SVK where
your branches live.
+=head1 Usage (without projects)
+
+A very simple sample usage might be to checkout the trunk from a project
+you want to work on but don't have upstream commit rights for. This
+allows you to maintain a local branch and to send in patches.
+
+Assuming you have alread mirrored this repository to //mirror/Project
+
+ svk co //mirror/Project/trunk
+or
+ svk branch --co trunk //mirror/Project/
+
+and then
+
+ svk branch --offline
+
+You're now working in a local branch, make local commits and changes
+as you need to. If you want to bring in changes from your remote
+repository, you can pull them down
+
+ svk branch --pull
+
+To see what changes you've made, you can create a patch between the
+local branch and the remote repository
+
+ svk branch -P - --push
+
+If you have commit rights to the remote repository, you can also
+
+ svk branch --push
+
+to send your changes.
+
+You can use svk branch's branching capability in this mode, but it
+will be much friendlier if you set up a project
+
+=head1 Usage (projects)
+
+To initialize a project in a repository, run the setup command
+
+ svk branch --setup //mirror/Project
+
+If you have the standard trunk branches tags directories svk
+will offer them as the starting point. In fact, if you have
+trunk branches and tags directories, svk will try to use them
+without neeting --setup, but you won't be able to use the
+--project flag and will need to use depotpaths in commands.
+
+The rest of this documentation assumes you've set up a project
+called Example in //mirror/Project
+
+If you're in a working copy of svk where it can work out the
+Project name, you can leave off the --project flag from the
+examples below, but you can branch/tag/merge without having
+working copies
+
+=head2 Branching
+
+To check out the trunk, you can run
+
+ svk branch --co trunk --project Example
+
+To create a branch for release engineering
+
+ svk branch --create Exmaple-1.0-releng --project Example
+
+Since you have a checkout of trunk already, you can convert that
+
+ cd trunk
+ svk branch --switch-to Example-1.0-releng
+
+Or you can get a clean checkout
+
+ svk branch --co Example-1.0-releng --project Example
+
+If changes are made on trunk and you wish to bring them down
+to the release engineering branch, you can do that with the
+branch merge command
+
+ svk branch --merge trunk Example-1.0-releng
+
+If you're cautious, use the check flags first:
+
+ svk branch -C --merge trunk Example-1.0-releng
+ svk branch -P - --merge trunk Example-1.0-releng
+
+These will show you what svk wants to do.
+
+Lets say you want to add a feature to trunk but work
+on a branch so you don't inconvenience others who
+are working on trunk:
+
+ svk branch --create Feature --project Example
+
+work on your feature, svk ci some changes
+
+ svk branch --merge Feature trunk --project Example
+
+continue to bring down changes several ways
+
+ svk branch --pull
+ svk branch --merge trunk Feature
+ svk branch --merge trunk . (if you're in a working copy of the branch)
+
+and then merge back more feature work as you need to
+
+To get rid of a branch when you're done with it
+
+ svk branch --delete Feature --project Example
+
+To see all of your branches, you can do:
+
+ svk branch --list --project Example
+
+=head2 Tagging
+
+If you've been working on your releng branch and are ready to
+cut a release, you can easily create a tag
+
+ svk branch --tag --create 1.0rc1 --from Example-1.0-releng --project Example
+
+If you would like to check out this tag, use
+
+ svk branch --tag --co 1.0rc1 --project Example
+
+=head1 Project Property Details
+
SVK branch also provides another project loading mechanism by setting
properties on root path. Current usable properties for SVK branch are
Modified: trunk/lib/SVK/Help/Intro.pod
==============================================================================
--- trunk/lib/SVK/Help/Intro.pod (original)
+++ trunk/lib/SVK/Help/Intro.pod Mon Aug 18 11:23:19 2008
@@ -94,10 +94,6 @@
copy of that repository for you to branch from, merge to and otherwise
poke at. The local path is sometimes called a "depot path."
- # This command sets up the mirror directory for your local
- # mirrors of remote repositories
- svk mkdir //mirror
-
svk mirror svn://svn.example.com/project_x //mirror/project_x
=item svk sync
@@ -108,25 +104,18 @@
svk sync //mirror/project_x
-=item svk copy
-
-After that, it's easy to I<copy> remote branches to create local
-branches. (svk branches are simply directories, just like Subversion
-branches.)
-
- # This command sets up a directory for your local branches.
- # Local branches can't live inside mirrored paths
- svk mkdir //local
-
- svk copy //mirror/project_x //local/project_x
-
=item svk checkout
When you want to get some work done, you can I<checkout> a working copy
-to make local changes.
+to make changes.
cd ~/svk-checkouts
- svk co //local/project_x
+ svk co //mirror/project_x
+
+If you want to work offline, you can create a local branch
+
+ cd ~/svk-checkouts/project_x
+ svk branch --offline
=item svk add, svk delete and svk move
@@ -154,7 +143,8 @@
Life doesn't stop when you make a local branch. From time to time,
I<pull> down changes from the upstream repository.
- svk pull //local/project_x
+ cd ~/svk-checkouts/project_x
+ svk pull
=item svk push
@@ -162,7 +152,8 @@
When you're ready to share your changes with the world, I<push> them to
the upstream repository.
- svk push //local/project_x
+ cd ~/svk-checkouts/project_x
+ svk push
=back
More information about the svk-commit
mailing list