diff options
Diffstat (limited to 'Documentation/git-svn.txt')
| -rw-r--r-- | Documentation/git-svn.txt | 202 |
1 files changed, 184 insertions, 18 deletions
diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 5d6d30f764..7e9b9a0423 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -3,7 +3,7 @@ git-svn(1) NAME ---- -git-svn - Bidirectional operation between a single Subversion branch and git +git-svn - Bidirectional operation between a Subversion repository and git SYNOPSIS -------- @@ -15,13 +15,12 @@ DESCRIPTION It provides a bidirectional flow of changes between a Subversion and a git repository. -'git-svn' can track a single Subversion branch simply by using a -URL to the branch, follow branches laid out in the Subversion recommended -method (trunk, branches, tags directories) with the --stdlayout option, or -follow branches in any layout with the -T/-t/-b options (see options to -'init' below, and also the 'clone' command). +'git-svn' can track a standard Subversion repository, +following the common "trunk/branches/tags" layout, with the --stdlayout option. +It can also follow branches and tags in any layout with the -T/-t/-b options +(see options to 'init' below, and also the 'clone' command). -Once tracking a Subversion branch (with any of the above methods), the git +Once tracking a Subversion repository (with any of the above methods), the git repository can be updated from Subversion by the 'fetch' command and Subversion updated from git by the 'dcommit' command. @@ -48,8 +47,11 @@ COMMANDS --stdlayout;; These are optional command-line options for init. Each of these flags can point to a relative repository path - (--tags=project/tags') or a full url - (--tags=https://foo.org/project/tags). The option --stdlayout is + (--tags=project/tags) or a full url + (--tags=https://foo.org/project/tags). + You can specify more than one --tags and/or --branches options, in case + your Subversion repository places tags or branches under multiple paths. + The option --stdlayout is a shorthand way of setting trunk,tags,branches as the relative paths, which is the Subversion default. If any of the other options are given as well, they take precedence. @@ -85,6 +87,10 @@ COMMANDS specified, the prefix must include a trailing slash. Setting a prefix is useful if you wish to track multiple projects that share a common repository. +--ignore-paths=<regex>;; + When passed to 'init' or 'clone' this regular expression will + be preserved as a config key. See 'fetch' for a description + of '--ignore-paths'. 'fetch':: Fetch unfetched revisions from the Subversion remote we are @@ -92,6 +98,41 @@ COMMANDS .git/config file may be specified as an optional command-line argument. +--localtime;; + Store Git commit times in the local timezone instead of UTC. This + makes 'git-log' (even without --date=local) show the same times + that `svn log` would in the local timezone. + +--parent;; + Fetch only from the SVN parent of the current HEAD. + +This doesn't interfere with interoperating with the Subversion +repository you cloned from, but if you wish for your local Git +repository to be able to interoperate with someone else's local Git +repository, either don't use this option or you should both use it in +the same local timezone. + +--ignore-paths=<regex>;; + This allows one to specify a Perl regular expression that will + cause skipping of all matching paths from checkout from SVN. + The '--ignore-paths' option should match for every 'fetch' + (including automatic fetches due to 'clone', 'dcommit', + 'rebase', etc) on a given repository. + +config key: svn-remote.<name>.ignore-paths + + If the ignore-paths config key is set and the command + line option is also given, both regular expressions + will be used. + +Examples: + + --ignore-paths="^doc" - skip "doc*" directory for every + fetch. + + --ignore-paths="^[^/]+/(?:branches|tags)" - skip + "branches" and "tags" of first level directories. + 'clone':: Runs 'init' and 'fetch'. It will automatically create a directory based on the basename of the URL passed to it; @@ -131,8 +172,9 @@ and have no uncommitted changes. It is recommended that you run 'git-svn' fetch and rebase (not pull or merge) your commits against the latest changes in the SVN repository. - An optional command-line argument may be specified as an - alternative to HEAD. + An optional revision or branch argument may be specified, and + causes 'git-svn' to do all work on that revision/branch + instead of HEAD. This is advantageous over 'set-tree' (below) because it produces cleaner, more linear history. + @@ -145,10 +187,44 @@ and have no uncommitted changes. reused if a user is later given access to an alternate transport method (e.g. `svn+ssh://` or `https://`) for commit. +config key: svn-remote.<name>.commiturl + +config key: svn.commiturl (overwrites all svn-remote.<name>.commiturl options) + Using this option for any other purpose (don't ask) is very strongly discouraged. -- +'branch':: + Create a branch in the SVN repository. + +-m;; +--message;; + Allows to specify the commit message. + +-t;; +--tag;; + Create a tag by using the tags_subdir instead of the branches_subdir + specified during git svn init. + +-d;; +--destination;; + If more than one --branches (or --tags) option was given to the 'init' + or 'clone' command, you must provide the location of the branch (or + tag) you wish to create in the SVN repository. The value of this + option must match one of the paths specified by a --branches (or + --tags) option. You can see these paths with the commands ++ + git config --get-all svn-remote.<name>.branches + git config --get-all svn-remote.<name>.tags ++ +where <name> is the name of the SVN repository as specified by the -R option to +'init' (or "svn" by default). + +'tag':: + Create a tag in the SVN repository. This is a shorthand for + 'branch -t'. + 'log':: This should make it easy to look up svn log messages when svn users refer to -r/--revision numbers. @@ -156,7 +232,7 @@ and have no uncommitted changes. The following features from `svn log' are supported: + -- ---revision=<n>[:<n>];; +-r/--revision=<n>[:<n>];; is supported, non-numeric args are not: HEAD, NEXT, BASE, PREV, etc ... -v/--verbose;; @@ -254,6 +330,63 @@ Any other arguments are passed directly to 'git-log' Shows the Subversion externals. Use -r/--revision to specify a specific revision. +'reset':: + Undoes the effects of 'fetch' back to the specified revision. + This allows you to re-'fetch' an SVN revision. Normally the + contents of an SVN revision should never change and 'reset' + should not be necessary. However, if SVN permissions change, + or if you alter your --ignore-paths option, a 'fetch' may fail + with "not found in commit" (file not previously visible) or + "checksum mismatch" (missed a modification). If the problem + file cannot be ignored forever (with --ignore-paths) the only + way to repair the repo is to use 'reset'. + +Only the rev_map and refs/remotes/git-svn are changed. Follow 'reset' +with a 'fetch' and then 'git-reset' or 'git-rebase' to move local +branches onto the new tree. + +-r/--revision=<n>;; + Specify the most recent revision to keep. All later revisions + are discarded. +-p/--parent;; + Discard the specified revision as well, keeping the nearest + parent instead. +Example:;; +Assume you have local changes in "master", but you need to refetch "r2". + +------------ + r1---r2---r3 remotes/git-svn + \ + A---B master +------------ + +Fix the ignore-paths or SVN permissions problem that caused "r2" to +be incomplete in the first place. Then: + +[verse] +git svn reset -r2 -p +git svn fetch + +------------ + r1---r2'--r3' remotes/git-svn + \ + r2---r3---A---B master +------------ + +Then fixup "master" with 'git-rebase'. +Do NOT use 'git-merge' or your history will not be compatible with a +future 'dcommit'! + +[verse] +git rebase --onto remotes/git-svn A^ master + +------------ + r1---r2'--r3' remotes/git-svn + \ + A'--B' master +------------ + + -- OPTIONS @@ -339,9 +472,18 @@ after the authors-file is modified should continue operation. config key: svn.authorsfile +--authors-prog=<filename>:: + +If this option is specified, for each SVN committer name that does not +exist in the authors file, the given file is executed with the committer +name as the first argument. The program is expected to return a single +line of the form "Name <email>", which will be treated as if included in +the authors file. + -q:: --quiet:: - Make 'git-svn' less verbose. + Make 'git-svn' less verbose. Specify a second time to make it + even less verbose. --repack[=<n>]:: --repack-flags=<flags>:: @@ -372,7 +514,8 @@ Passed directly to 'git-rebase' when using 'dcommit' if a -n:: --dry-run:: -This can be used with the 'dcommit' and 'rebase' commands. +This can be used with the 'dcommit', 'rebase', 'branch' and 'tag' +commands. For 'dcommit', print out the series of git arguments that would show which diffs would be committed to SVN. @@ -381,6 +524,9 @@ For 'rebase', display the local branch associated with the upstream svn repository associated with the current branch and the URL of svn repository that will be fetched from. +For 'branch' and 'tag', display the urls that will be used for copying when +creating the branch or tag. + -- ADVANCED OPTIONS @@ -455,6 +601,14 @@ svn-remote.<name>.rewriteRoot:: the repository with a public http:// or svn:// URL in the metadata so users of it will see the public URL. +svn.brokenSymlinkWorkaround:: +This disables potentially expensive checks to workaround broken symlinks +checked into SVN by broken clients. Set this option to "false" if you +track a SVN repository with many empty blobs that are not symlinks. +This option may be changed while "git-svn" is running and take effect on +the next revision fetched. If unset, git-svn assumes this option to be +"true". + -- Since the noMetadata, rewriteRoot, useSvnsyncProps and useSvmProps @@ -498,6 +652,8 @@ Tracking and contributing to an entire Subversion-managed project git svn clone http://svn.example.com/project -T trunk -b branches -t tags # View all branches and tags you have cloned: git branch -r +# Create a new branch in SVN + git svn branch waldo # Reset your master to trunk (or any other branch, replacing 'trunk' # with the appropriate name): git reset --hard remotes/trunk @@ -541,7 +697,7 @@ pulled or merged from. This is because the author favored If you use `git svn set-tree A..B` to commit several diffs and you do not have the latest remotes/git-svn merged into my-branch, you should use `git svn rebase` to update your work branch instead of `git pull` or -`git merge`. `pull`/`merge' can cause non-linear history to be flattened +`git merge`. `pull`/`merge` can cause non-linear history to be flattened when committing into SVN, which can lead to merge commits reversing previous commits in SVN. @@ -587,6 +743,16 @@ already dcommitted. It is considered bad practice to --amend commits you've already pushed to a remote repository for other users, and dcommit with SVN is analogous to that. +When using multiple --branches or --tags, 'git-svn' does not automatically +handle name collisions (for example, if two branches from different paths have +the same name, or if a branch and a tag have the same name). In these cases, +use 'init' to set up your git repository then, before your first 'fetch', edit +the .git/config file so that the branches and tags are associated with +different name spaces. For example: + + branches = stable/*:refs/remotes/svn/stable/* + branches = debug/*:refs/remotes/svn/debug/* + BUGS ---- @@ -614,14 +780,14 @@ listed below are allowed: ------------------------------------------------------------------------ [svn-remote "project-a"] url = http://server.org/svn + fetch = trunk/project-a:refs/remotes/project-a/trunk branches = branches/*/project-a:refs/remotes/project-a/branches/* tags = tags/*/project-a:refs/remotes/project-a/tags/* - trunk = trunk/project-a:refs/remotes/project-a/trunk ------------------------------------------------------------------------ -Keep in mind that the '*' (asterisk) wildcard of the local ref +Keep in mind that the '\*' (asterisk) wildcard of the local ref (right of the ':') *must* be the farthest right path component; -however the remote wildcard may be anywhere as long as it's own +however the remote wildcard may be anywhere as long as it's an independent path component (surrounded by '/' or EOL). This type of configuration is not automatically created by 'init' and should be manually entered with a text-editor or using 'git-config'. |