1git-svn(1) 2========== 3 4NAME 5---- 6git-svn - bidirectional operation between a single Subversion branch and git 7 8SYNOPSIS 9-------- 10'git-svn' <command> [options] [arguments] 11 12DESCRIPTION 13----------- 14git-svn is a simple conduit for changesets between a single Subversion 15branch and git. 16 17git-svn is not to be confused with git-svnimport. The were designed 18with very different goals in mind. 19 20git-svn is designed for an individual developer who wants a 21bidirectional flow of changesets between a single branch in Subversion 22and an arbitrary number of branches in git. git-svnimport is designed 23for read-only operation on repositories that match a particular layout 24(albeit the recommended one by SVN developers). 25 26For importing svn, git-svnimport is potentially more powerful when 27operating on repositories organized under the recommended 28trunk/branch/tags structure, and should be faster, too. 29 30git-svn mostly ignores the very limited view of branching that 31Subversion has. This allows git-svn to be much easier to use, 32especially on repositories that are not organized in a manner that 33git-svnimport is designed for. 34 35COMMANDS 36-------- 37init:: 38 Creates an empty git repository with additional metadata 39 directories for git-svn. The Subversion URL must be specified 40 as a command-line argument. 41 42fetch:: 43 Fetch unfetched revisions from the Subversion URL we are 44 tracking. refs/remotes/git-svn will be updated to the 45 latest revision. 46 47 Note: You should never attempt to modify the remotes/git-svn 48 branch outside of git-svn. Instead, create a branch from 49 remotes/git-svn and work on that branch. Use the 'commit' 50 command (see below) to write git commits back to 51 remotes/git-svn. 52 53 See 'Additional Fetch Arguments' if you are interested in 54 manually joining branches on commit. 55 56commit:: 57 Commit specified commit or tree objects to SVN. This relies on 58 your imported fetch data being up-to-date. This makes 59 absolutely no attempts to do patching when committing to SVN, it 60 simply overwrites files with those specified in the tree or 61 commit. All merging is assumed to have taken place 62 independently of git-svn functions. 63 64rebuild:: 65 Not a part of daily usage, but this is a useful command if 66 you've just cloned a repository (using git-clone) that was 67 tracked with git-svn. Unfortunately, git-clone does not clone 68 git-svn metadata and the svn working tree that git-svn uses for 69 its operations. This rebuilds the metadata so git-svn can 70 resume fetch operations. A Subversion URL may be optionally 71 specified at the command-line if the directory/repository you're 72 tracking has moved or changed protocols. 73 74show-ignore:: 75 Recursively finds and lists the svn:ignore property on 76 directories. The output is suitable for appending to 77 the $GIT_DIR/info/exclude file. 78 79OPTIONS 80------- 81-r <ARG>:: 82--revision <ARG>:: 83 Only used with the 'fetch' command. 84 85 Takes any valid -r<argument> svn would accept and passes it 86 directly to svn. -r<ARG1>:<ARG2> ranges and "{" DATE "}" syntax 87 is also supported. This is passed directly to svn, see svn 88 documentation for more details. 89 90 This can allow you to make partial mirrors when running fetch. 91 92-:: 93--stdin:: 94 Only used with the 'commit' command. 95 96 Read a list of commits from stdin and commit them in reverse 97 order. Only the leading sha1 is read from each line, so 98 git-rev-list --pretty=oneline output can be used. 99 100--rmdir:: 101 Only used with the 'commit' command. 102 103 Remove directories from the SVN tree if there are no files left 104 behind. SVN can version empty directories, and they are not 105 removed by default if there are no files left in them. git 106 cannot version empty directories. Enabling this flag will make 107 the commit to SVN act like git. 108 109 repo-config key: svn.rmdir 110 111-e:: 112--edit:: 113 Only used with the 'commit' command. 114 115 Edit the commit message before committing to SVN. This is off by 116 default for objects that are commits, and forced on when committing 117 tree objects. 118 119 repo-config key: svn.edit 120 121-l<num>:: 122--find-copies-harder:: 123 Both of these are only used with the 'commit' command. 124 125 They are both passed directly to git-diff-tree see 126 git-diff-tree(1) for more information. 127 128 repo-config key: svn.l 129 repo-config key: svn.findcopiesharder 130 131-A<filename>:: 132--authors-file=<filename>:: 133 134 Syntax is compatible with the files used by git-svnimport and 135 git-cvsimport: 136 137------------------------------------------------------------------------ 138loginname = Joe User <user@example.com> 139------------------------------------------------------------------------ 140 141 If this option is specified and git-svn encounters an SVN 142 committer name that does not exist in the authors-file, git-svn 143 will abort operation. The user will then have to add the 144 appropriate entry. Re-running the previous git-svn command 145 after the authors-file is modified should continue operation. 146 147 repo-config key: svn.authors-file 148 149ADVANCED OPTIONS 150---------------- 151-b<refname>:: 152--branch <refname>:: 153 Used with 'fetch' or 'commit'. 154 155 This can be used to join arbitrary git branches to remotes/git-svn 156 on new commits where the tree object is equivalent. 157 158 When used with different GIT_SVN_ID values, tags and branches in 159 SVN can be tracked this way, as can some merges where the heads 160 end up having completely equivalent content. This can even be 161 used to track branches across multiple SVN _repositories_. 162 163 This option may be specified multiple times, once for each 164 branch. 165 166 repo-config key: svn.branch 167 168-i<GIT_SVN_ID>:: 169--id <GIT_SVN_ID>:: 170 This sets GIT_SVN_ID (instead of using the environment). See 171 the section on "Tracking Multiple Repositories or Branches" for 172 more information on using GIT_SVN_ID. 173 174COMPATIBILITY OPTIONS 175--------------------- 176--upgrade:: 177 Only used with the 'rebuild' command. 178 179 Run this if you used an old version of git-svn that used 180 "git-svn-HEAD" instead of "remotes/git-svn" as the branch 181 for tracking the remote. 182 183--no-ignore-externals:: 184 Only used with the 'fetch' and 'rebuild' command. 185 186 By default, git-svn passes --ignore-externals to svn to avoid 187 fetching svn:external trees into git. Pass this flag to enable 188 externals tracking directly via git. 189 190 Versions of svn that do not support --ignore-externals are 191 automatically detected and this flag will be automatically 192 enabled for them. 193 194 Otherwise, do not enable this flag unless you know what you're 195 doing. 196 197 repo-config key: svn.noignoreexternals 198 199Basic Examples 200~~~~~~~~~~~~~~ 201 202Tracking and contributing to an Subversion managed-project: 203 204------------------------------------------------------------------------ 205# Initialize a tree (like git init-db): 206 git-svn init http://svn.foo.org/project/trunk 207# Fetch remote revisions: 208 git-svn fetch 209# Create your own branch to hack on: 210 git checkout -b my-branch remotes/git-svn 211# Commit only the git commits you want to SVN: 212 git-svn commit <tree-ish> [<tree-ish_2> ...] 213# Commit all the git commits from my-branch that don't exist in SVN: 214 git-svn commit remotes/git-svn..my-branch 215# Something is committed to SVN, pull the latest into your branch: 216 git-svn fetch && git pull . remotes/git-svn 217# Append svn:ignore settings to the default git exclude file: 218 git-svn show-ignore >> .git/info/exclude 219------------------------------------------------------------------------ 220 221DESIGN PHILOSOPHY 222----------------- 223Merge tracking in Subversion is lacking and doing branched development 224with Subversion is cumbersome as a result. git-svn completely forgoes 225any automated merge/branch tracking on the Subversion side and leaves it 226entirely up to the user on the git side. It's simply not worth it to do 227a useful translation when the the original signal is weak. 228 229TRACKING MULTIPLE REPOSITORIES OR BRANCHES 230------------------------------------------ 231This is for advanced users, most users should ignore this section. 232 233Because git-svn does not care about relationships between different 234branches or directories in a Subversion repository, git-svn has a simple 235hack to allow it to track an arbitrary number of related _or_ unrelated 236SVN repositories via one git repository. Simply set the GIT_SVN_ID 237environment variable to a name other other than "git-svn" (the default) 238and git-svn will ignore the contents of the $GIT_DIR/git-svn directory 239and instead do all of its work in $GIT_DIR/$GIT_SVN_ID for that 240invocation. The interface branch will be remotes/$GIT_SVN_ID, instead of 241remotes/git-svn. Any remotes/$GIT_SVN_ID branch should never be modified 242by the user outside of git-svn commands. 243 244ADDITIONAL FETCH ARGUMENTS 245-------------------------- 246This is for advanced users, most users should ignore this section. 247 248Unfetched SVN revisions may be imported as children of existing commits 249by specifying additional arguments to 'fetch'. Additional parents may 250optionally be specified in the form of sha1 hex sums at the 251command-line. Unfetched SVN revisions may also be tied to particular 252git commits with the following syntax: 253 254 svn_revision_number=git_commit_sha1 255 256This allows you to tie unfetched SVN revision 375 to your current HEAD:: 257 258 `git-svn fetch 375=$(git-rev-parse HEAD)` 259 260Advanced Example: Tracking a Reorganized Repository 261~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 262If you're tracking a directory that has moved, or otherwise been 263branched or tagged off of another directory in the repository and you 264care about the full history of the project, then you can read this 265section. 266 267This is how Yann Dirson tracked the trunk of the ufoai directory when 268the /trunk directory of his repository was moved to /ufoai/trunk and 269he needed to continue tracking /ufoai/trunk where /trunk left off. 270 271------------------------------------------------------------------------ 272 # This log message shows when the repository was reorganized: 273 r166 | ydirson | 2006-03-02 01:36:55 +0100 (Thu, 02 Mar 2006) | 1 line 274 Changed paths: 275 D /trunk 276 A /ufoai/trunk (from /trunk:165) 277 278 # First we start tracking the old revisions: 279 GIT_SVN_ID=git-oldsvn git-svn init \ 280 https://svn.sourceforge.net/svnroot/ufoai/trunk 281 GIT_SVN_ID=git-oldsvn git-svn fetch -r1:165 282 283 # And now, we continue tracking the new revisions: 284 GIT_SVN_ID=git-newsvn git-svn init \ 285 https://svn.sourceforge.net/svnroot/ufoai/ufoai/trunk 286 GIT_SVN_ID=git-newsvn git-svn fetch \ 287 166=`git-rev-parse refs/remotes/git-oldsvn` 288------------------------------------------------------------------------ 289 290BUGS 291---- 292If somebody commits a conflicting changeset to SVN at a bad moment 293(right before you commit) causing a conflict and your commit to fail, 294your svn working tree ($GIT_DIR/git-svn/tree) may be dirtied. The 295easiest thing to do is probably just to rm -rf $GIT_DIR/git-svn/tree and 296run 'rebuild'. 297 298We ignore all SVN properties except svn:executable. Too difficult to 299map them since we rely heavily on git write-tree being _exactly_ the 300same on both the SVN and git working trees and I prefer not to clutter 301working trees with metadata files. 302 303svn:keywords can't be ignored in Subversion (at least I don't know of 304a way to ignore them). 305 306Renamed and copied directories are not detected by git and hence not 307tracked when committing to SVN. I do not plan on adding support for 308this as it's quite difficult and time-consuming to get working for all 309the possible corner cases (git doesn't do it, either). Renamed and 310copied files are fully supported if they're similar enough for git to 311detect them. 312 313Author 314------ 315Written by Eric Wong <normalperson@yhbt.net>. 316 317Documentation 318------------- 319Written by Eric Wong <normalperson@yhbt.net>.