gvn
XXX next three paragraphs copied from pamg's suggested help text
Creating a changebranch publishes its files for review, exactly as they are in your working copy. Use ``gvn mail'' to request review. If you make additional changes to files in the changebranch after creating it, use ``gvn snapshot'' to republish them.
Before a changebranch can be submitted, it must be reviewed and acknowledged by one or more reviewers. The author of a changebranch requests review with ``gvn mail''. Once you, the reviewer, feel that the files in the changebranch are ready to be submitted *exactly* as they are, run ``gvn ack <changebranch>''.
If the author makes more changes to files after you've acknowledged the changebranch, you'll have to acknowledge the new version before it can be submitted.
show help; identical to --help
Add paths to change, creating it if it does not exist. If change is not specified, generate a random name.
Remove paths from change.
Delete change.
[XXX --delete vs --remove is confusing; suggestions welcome]
If --non-interactive is not specified, the first two forms run the user's editor (see --editor-cmd) on a form, allowing the user to add and remove files to and from change and to edit the change description (log message).
If you don't specify paths, gvn will run $EDITOR on a form showing all modified paths in this changebranch or no changebranch at all. You can move paths from one group to another in your editor, as well as update the change description.
force validity of changebranch name
List changebranches.
Without --all or --user, list local changebranches.
You can just run gvn mail without arguments and it will run the change editor (describe above) and create a new changebranch for you. You can give it a -c option and it will use that name for the new branch.
If CHANGE does not exist, it will be created using the files in PATH, and an editor will be launched allowing you to enter a description and move files into and out of the changebranch. If no change name is given, a random one will be generated.
gvn will then launch an editor with the body of the mail to be sent, allowing you to edit it if you wish. A text diff of the files in the changebranch (truncated, if necessary) appears at the bottom of the message.
foo
Print a description of a changebranch or revision, including the current revision number, user, date, change description, the list of modified files, and the diff.
foo
Commit the current contents of each file in change to the
changebranch. If change is omitted, snapshot all local
changebranches. Replace the change description(s) if file or
message is specified.
auth foo
Acknowledge a changebranch.
Print a description of a changebranch or revision, including the current revision number, user, date, change description, and the list of modified files.
Display the changes made to the paths changed in CHANGE or PATHS. Without CHANGE or PATHs, display all changes in the working copy.
Lists all files in your working copy that have never been added to the repository. Note that files that have been added, but not yet submitted, will not be shown, even if they aren't included in any changebranch.
Show the files in your client that have been changed from the versions in the repository, or that have been added (using ``gvn add'').
Output format is the same as svn status, with two differences. ``--- Changebranch'' lines (similar to ``--- Changelist'' lines) are used to group status lines for changebranched paths. Each status line has an additional column, inserted at the front: if this column is blank, this path is up-to-date with the changebranch (or not changebranched at all); if it is a ``*'', this path needs to be snapshotted.
Display the differences between two revisions or repository paths. usage: 1. rdiff [-c M | -r N[:M]] [URL[@REV]...] 2. rdiff [-r N[:M]] --old=OLD-URL[@OLDREV] [--new=NEW-URL[@NEWREV]] [PATH...] 3. rdiff OLD-URL[@OLDREV] NEW-URL[@NEWREV]
1. Display the changes made to URLs as they are seen in REV between two
revisions. N must be specified and M defaults to HEAD. The '-c M' option
is equivalent to '-r N:M' where N = M-1. Using '-c -M' does the reverse:
'-r M:N' where N = M-1.
2. Display the differences between OLD-URL as it was seen in OLDREV and
NEW-URL as it was seen in NEWREV. PATHs, if given, are relative to OLD-URL
and NEW-URL and restrict the output to differences for those paths.
OLD-URL and NEW-URL must be URL[@REV]. NEW-URL defaults to OLD-URL if not
specified. -r N makes OLDREV default to N, -r N:M makes OLDREV default to
N and NEWREV default to M.
3. Shorthand for 'gvn rdiff --old=OLD-URL[@OLDREV] --new=NEW-URL[@NEWREV]'
Revert the changes made to the paths changed in change or paths, restoring them to the pristine versions from the repository. This can also be used to undo ``gvn add''.
This command is irreversible. However, any changes published or checkpointed into a changebranch can still be retrieved from that changebranch's revision.
Options specific to a subcommand are documented exclusively in that subcommand's section, above. Many options are used by many subcommands; they are listed in the subcommand's section, but fully documented here.
All subcommands accept the --help, --gvn-config-dir, --config-dir, and --diag options.
XXX i haven't gone over these to verify that they're all global; some might belong in a subcommand section. Also these need to be grouped, all the log options together, auth options, ... Finally, many of these are only accepted by wrapped svn subcommands, and thus should not be here at all.
read user configuration files from directory config-dir
read user gvn configuration files from directory gvn-config-dir
enable automatic properties
Show diagnostics about what gvn is doing, including full tracebacks for all errors.
use diff-cmd as diff command
use diff3-cmd as merge command
try operation but make no changes
use editor-cmd as external editor
treat value as being in charset encoding encoding
read log message from file file XXX propset, others?
force operation to run
force validity of log message source
ignore ancestry when calculating merges
ignore externals definitions
give output suitable for concatenation
maximum number of log entries
specify log message message
use a different EOL marker than the standard system marker for files with the svn:eol-style property set to 'native'. native-eol may be one of 'LF', 'CR', 'CRLF'
use new as the newer target
do not cache authentication tokens
disable automatic properties
do not print differences for deleted files
disregard default and svn:ignore property ignores
don't unlock the targets
do no interactive prompting
operate on single directory only
notice ancestry when calculating differences
use old as the older target
specify a password password
use project project
print as little as possible
descend recursively
relocate via URL-rewriting
remove from changebranch
comma-separated list of reviewer addresses
revision (some commands also take revision1:revision2 range) A revision argument can be one of: NUMBER revision number '{' DATE '}' revision at start of the date 'HEAD' latest in repository 'BASE' base rev of item's working copy 'COMMITTED' last commit at or before BASE 'PREV' revision just before COMMITTED
operate on a revision property (use with -r)
display update information
do not cross copies while traversing history
use strict semantics
show a summary of the results
pass contents of file targets as additional args
operate on USER (does not affect auth)
specify a username username
print extra information
output in XML
gvn thinks in terms of projects. A project is a directory in a repository that contains at least one code line (typically ``trunk''), or is itself a code line. The project directory itself may have properties which change gvn's behavior.
Today, the only property is gvn:project, and it contains a Python pickle of a dict with the following keys. In the future, we'll use Windows ini (Python ConfigParser) instead of pickle.
List of (regular expression, URL) tuples for bug numbers in the gvn:bug and svn:log revision properties. The actual bug number should be grouped with parentheses, and then referred to in the URL, for example:
'bug-links': [(r'(?i)(bug|issue)\s*#?\s*(\d+)',
r'http://issuetracker/detail?id=\2')],
This matches the ``13'' in ``bug 13'' in the second group, so use ``\2'' to get the number 13.
Directory in which to store change branches, defaults to //changes. If this begins with a / it is relative to the repository root, else it is relative to the project URL.
Number of lines of diff to include in the gvn mail. This should be in the format specifier in the mail template, really, something like %(200)diff for 200 lines or %diff for the whole thing.
Template used for gvn mail. The following format specifiers (e.g. ``%(project)s''):
project url
user/name@rev
user/name
svn:log
First 39 chars of svn:log; like diff-lines, this should just be specified in the mail template directly, but not yet.
diff-lines of diff
Today project files are discovered in this way:
First, if gvn has a working copy, it uses that URL to find a project file, ignoring --project option. If it finds no matching project file, gvn uses the wc top URL as the project URL.
Next, if gvn has a --project option, it uses looks for a project file named project or a project file referencing the URL if project is a URL.
Finally, with neither a working copy nor a --project option, gvn looks for a project file named ``default''.
We're probably going to change the working copy discovery method to instead get the project root from the .gvn file, and that will be filled in a checkout time.
~/.gvn/config and /etc/gvn/config are of the form (with defaults):
[external] diff_command = internal smtp_server = smtp
Specify the command to use for gvn review's diffs; in the future, gvn diff and gvn rdiff will use this as well.
Specify the name of the SMTP server gvn mail uses to send the review request.
Project files don't have derived defaults; see each directive's description for details.
[project] url username email_address email_domain
Specify the url of the project root.
In order to match usernames with repositories gvn matches the repository root url in your working copy with the first matching file in ~/.gvn/projects/<project>.
Defaults to the working copy url.
Specify the username to authenticate, as well as the changebranch path (e.g. //changes/basil).
Defaults to the local system username.
Specify the email address gvn mail uses in the From header.
Defaults to the value of the EMAIL environment variable if set, else to username @ the last two components of the host's fully qualified domain name (e.g. basil@example.com for the user basil on the host torquay.corp.example.com).
Specify the domain name gvn mail appends to reviewers specified with the --reviewers option.
By default, gvn mail uses the reviewers addresses verbatim.
svn mkdir foo
svn ci foo
svn add foo/bar
gvn change -c newchange foo/bar
doesn't work; copies top@rev-with-no-foo then tries to copy into foo/bar, but there's no foo.
Given that:
svn mkdir foo && svn ci foo
svn rm foo && svn ci foo
touch foo && svn add foo
doesn't work without an 'svn up' before the 'svn add foo', this isn't really a big deal.