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 Subversion and git. 15It is not to be confused with gitlink:git-svnimport[1], which is 16read-only. 17 18git-svn was originally designed for an individual developer who wants a 19bidirectional flow of changesets between a single branch in Subversion 20and an arbitrary number of branches in git. Since its inception, 21git-svn has gained the ability to track multiple branches in a manner 22similar to git-svnimport. 23 24git-svn is especially useful when it comes to tracking repositories 25not organized in the way Subversion developers recommend (trunk, 26branches, tags directories). 27 28COMMANDS 29-------- 30-- 31 32'init':: 33 Initializes an empty git repository with additional 34 metadata directories for git-svn. The Subversion URL 35 may be specified as a command-line argument, or as full 36 URL arguments to -T/-t/-b. Optionally, the target 37 directory to operate on can be specified as a second 38 argument. Normally this command initializes the current 39 directory. 40 41-T<trunk_subdir>:: 42--trunk=<trunk_subdir>:: 43-t<tags_subdir>:: 44--tags=<tags_subdir>:: 45-b<branches_subdir>:: 46--branches=<branches_subdir>:: 47 These are optional command-line options for init. Each of 48 these flags can point to a relative repository path 49 (--tags=project/tags') or a full url 50 (--tags=https://foo.org/project/tags) 51 52--no-metadata:: 53 Set the 'noMetadata' option in the [svn-remote] config. 54--use-svm-props:: 55 Set the 'useSvmProps' option in the [svn-remote] config. 56--use-svnsync-props:: 57 Set the 'useSvnsyncProps' option in the [svn-remote] config. 58--rewrite-root=<URL>:: 59 Set the 'rewriteRoot' option in the [svn-remote] config. 60 61--prefix=<prefix> 62 This allows one to specify a prefix which is prepended 63 to the names of remotes if trunk/branches/tags are 64 specified. The prefix does not automatically include a 65 trailing slash, so be sure you include one in the 66 argument if that is what you want. This is useful if 67 you wish to track multiple projects that share a common 68 repository. 69 70'fetch':: 71 72 Fetch unfetched revisions from the Subversion remote we are 73 tracking. The name of the [svn-remote "..."] section in the 74 .git/config file may be specified as an optional command-line 75 argument. 76 77'clone':: 78 Runs 'init' and 'fetch'. It will automatically create a 79 directory based on the basename of the URL passed to it; 80 or if a second argument is passed; it will create a directory 81 and work within that. It accepts all arguments that the 82 'init' and 'fetch' commands accept; with the exception of 83 '--fetch-all'. After a repository is cloned, the 'fetch' 84 command will be able to update revisions without affecting 85 the working tree; and the 'rebase' command will be able 86 to update the working tree with the latest changes. 87 88'rebase':: 89 This fetches revisions from the SVN parent of the current HEAD 90 and rebases the current (uncommitted to SVN) work against it. 91 92 This works similarly to 'svn update' or 'git-pull' except that 93 it preserves linear history with 'git-rebase' instead of 94 'git-merge' for ease of dcommit-ing with git-svn. 95 96 This accepts all options that 'git-svn fetch' and 'git-rebase' 97 accepts. However '--fetch-all' only fetches from the current 98 [svn-remote], and not all [svn-remote] definitions. 99 100 Like 'git-rebase'; this requires that the working tree be clean 101 and have no uncommitted changes. 102 103'dcommit':: 104 Commit each diff from a specified head directly to the SVN 105 repository, and then rebase or reset (depending on whether or 106 not there is a diff between SVN and head). This will create 107 a revision in SVN for each commit in git. 108 It is recommended that you run git-svn fetch and rebase (not 109 pull or merge) your commits against the latest changes in the 110 SVN repository. 111 An optional command-line argument may be specified as an 112 alternative to HEAD. 113 This is advantageous over 'set-tree' (below) because it produces 114 cleaner, more linear history. 115 116'log':: 117 This should make it easy to look up svn log messages when svn 118 users refer to -r/--revision numbers. 119 120 The following features from `svn log' are supported: 121 122 --revision=<n>[:<n>] - is supported, non-numeric args are not: 123 HEAD, NEXT, BASE, PREV, etc ... 124 -v/--verbose - it's not completely compatible with 125 the --verbose output in svn log, but 126 reasonably close. 127 --limit=<n> - is NOT the same as --max-count, 128 doesn't count merged/excluded commits 129 --incremental - supported 130 131 New features: 132 133 --show-commit - shows the git commit sha1, as well 134 --oneline - our version of --pretty=oneline 135 136 Any other arguments are passed directly to `git log' 137 138'set-tree':: 139 You should consider using 'dcommit' instead of this command. 140 Commit specified commit or tree objects to SVN. This relies on 141 your imported fetch data being up-to-date. This makes 142 absolutely no attempts to do patching when committing to SVN, it 143 simply overwrites files with those specified in the tree or 144 commit. All merging is assumed to have taken place 145 independently of git-svn functions. 146 147'show-ignore':: 148 Recursively finds and lists the svn:ignore property on 149 directories. The output is suitable for appending to 150 the $GIT_DIR/info/exclude file. 151 152'commit-diff':: 153 Commits the diff of two tree-ish arguments from the 154 command-line. This command is intended for interoperability with 155 git-svnimport and does not rely on being inside an git-svn 156 init-ed repository. This command takes three arguments, (a) the 157 original tree to diff against, (b) the new tree result, (c) the 158 URL of the target Subversion repository. The final argument 159 (URL) may be omitted if you are working from a git-svn-aware 160 repository (that has been init-ed with git-svn). 161 The -r<revision> option is required for this. 162 163-- 164 165OPTIONS 166------- 167-- 168 169--shared[={false|true|umask|group|all|world|everybody}]:: 170--template=<template_directory>:: 171 Only used with the 'init' command. 172 These are passed directly to gitlink:git-init[1]. 173 174-r <ARG>:: 175--revision <ARG>:: 176 177Used with the 'fetch' command. 178 179This allows revision ranges for partial/cauterized history 180to be supported. $NUMBER, $NUMBER1:$NUMBER2 (numeric ranges), 181$NUMBER:HEAD, and BASE:$NUMBER are all supported. 182 183This can allow you to make partial mirrors when running fetch; 184but is generally not recommended because history will be skipped 185and lost. 186 187-:: 188--stdin:: 189 190Only used with the 'set-tree' command. 191 192Read a list of commits from stdin and commit them in reverse 193order. Only the leading sha1 is read from each line, so 194git-rev-list --pretty=oneline output can be used. 195 196--rmdir:: 197 198Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. 199 200Remove directories from the SVN tree if there are no files left 201behind. SVN can version empty directories, and they are not 202removed by default if there are no files left in them. git 203cannot version empty directories. Enabling this flag will make 204the commit to SVN act like git. 205 206config key: svn.rmdir 207 208-e:: 209--edit:: 210 211Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. 212 213Edit the commit message before committing to SVN. This is off by 214default for objects that are commits, and forced on when committing 215tree objects. 216 217config key: svn.edit 218 219-l<num>:: 220--find-copies-harder:: 221 222Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. 223 224They are both passed directly to git-diff-tree see 225gitlink:git-diff-tree[1] for more information. 226 227[verse] 228config key: svn.l 229config key: svn.findcopiesharder 230 231-A<filename>:: 232--authors-file=<filename>:: 233 234Syntax is compatible with the files used by git-svnimport and 235git-cvsimport: 236 237------------------------------------------------------------------------ 238 loginname = Joe User <user@example.com> 239------------------------------------------------------------------------ 240 241If this option is specified and git-svn encounters an SVN 242committer name that does not exist in the authors-file, git-svn 243will abort operation. The user will then have to add the 244appropriate entry. Re-running the previous git-svn command 245after the authors-file is modified should continue operation. 246 247config key: svn.authorsfile 248 249-q:: 250--quiet:: 251 Make git-svn less verbose. 252 253--repack[=<n>]:: 254--repack-flags=<flags> 255 These should help keep disk usage sane for large fetches 256 with many revisions. 257 258 --repack takes an optional argument for the number of revisions 259 to fetch before repacking. This defaults to repacking every 260 1000 commits fetched if no argument is specified. 261 262 --repack-flags are passed directly to gitlink:git-repack[1]. 263 264config key: svn.repack 265config key: svn.repackflags 266 267-m:: 268--merge:: 269-s<strategy>:: 270--strategy=<strategy>:: 271 272These are only used with the 'dcommit' and 'rebase' commands. 273 274Passed directly to git-rebase when using 'dcommit' if a 275'git-reset' cannot be used (see dcommit). 276 277-n:: 278--dry-run:: 279 280This is only used with the 'dcommit' command. 281 282Print out the series of git arguments that would show 283which diffs would be committed to SVN. 284 285-- 286 287ADVANCED OPTIONS 288---------------- 289-- 290 291-i<GIT_SVN_ID>:: 292--id <GIT_SVN_ID>:: 293 294This sets GIT_SVN_ID (instead of using the environment). This 295allows the user to override the default refname to fetch from 296when tracking a single URL. The 'log' and 'dcommit' commands 297no longer require this switch as an argument. 298 299-R<remote name>:: 300--svn-remote <remote name>:: 301 Specify the [svn-remote "<remote name>"] section to use, 302 this allows SVN multiple repositories to be tracked. 303 Default: "svn" 304 305--follow-parent:: 306 This is especially helpful when we're tracking a directory 307 that has been moved around within the repository, or if we 308 started tracking a branch and never tracked the trunk it was 309 descended from. This feature is enabled by default, use 310 --no-follow-parent to disable it. 311 312config key: svn.followparent 313 314-- 315CONFIG FILE-ONLY OPTIONS 316------------------------ 317-- 318 319svn.noMetadata:: 320svn-remote.<name>.noMetadata:: 321 This gets rid of the git-svn-id: lines at the end of every commit. 322 323 If you lose your .git/svn/git-svn/.rev_db file, git-svn will not 324 be able to rebuild it and you won't be able to fetch again, 325 either. This is fine for one-shot imports. 326 327 The 'git-svn log' command will not work on repositories using 328 this, either. Using this conflicts with the 'useSvmProps' 329 option for (hopefully) obvious reasons. 330 331svn.useSvmProps:: 332svn-remote.<name>.useSvmProps:: 333 This allows git-svn to re-map repository URLs and UUIDs from 334 mirrors created using SVN::Mirror (or svk) for metadata. 335 336 If an SVN revision has a property, "svm:headrev", it is likely 337 that the revision was created by SVN::Mirror (also used by SVK). 338 The property contains a repository UUID and a revision. We want 339 to make it look like we are mirroring the original URL, so 340 introduce a helper function that returns the original identity 341 URL and UUID, and use it when generating metadata in commit 342 messages. 343 344svn.useSvnsyncProps:: 345svn-remote.<name>.useSvnsyncprops:: 346 Similar to the useSvmProps option; this is for users 347 of the svnsync(1) command distributed with SVN 1.4.x and 348 later. 349 350svn-remote.<name>.rewriteRoot:: 351 This allows users to create repositories from alternate 352 URLs. For example, an administrator could run git-svn on the 353 server locally (accessing via file://) but wish to distribute 354 the repository with a public http:// or svn:// URL in the 355 metadata so users of it will see the public URL. 356 357Since the noMetadata, rewriteRoot, useSvnsyncProps and useSvmProps 358options all affect the metadata generated and used by git-svn; they 359*must* be set in the configuration file before any history is imported 360and these settings should never be changed once they are set. 361 362Additionally, only one of these four options can be used per-svn-remote 363section because they affect the 'git-svn-id:' metadata line. 364 365-- 366 367Basic Examples 368~~~~~~~~~~~~~~ 369 370Tracking and contributing to a the trunk of a Subversion-managed project: 371 372------------------------------------------------------------------------ 373# Clone a repo (like git clone): 374 git-svn clone http://svn.foo.org/project/trunk 375# Enter the newly cloned directory: 376 cd trunk 377# You should be on master branch, double-check with git-branch 378 git branch 379# Do some work and commit locally to git: 380 git commit ... 381# Something is committed to SVN, rebase your local changes against the 382# latest changes in SVN: 383 git-svn rebase 384# Now commit your changes (that were committed previously using git) to SVN, 385# as well as automatically updating your working HEAD: 386 git-svn dcommit 387# Append svn:ignore settings to the default git exclude file: 388 git-svn show-ignore >> .git/info/exclude 389------------------------------------------------------------------------ 390 391Tracking and contributing to an entire Subversion-managed project 392(complete with a trunk, tags and branches): 393 394------------------------------------------------------------------------ 395# Clone a repo (like git clone): 396 git-svn clone http://svn.foo.org/project -T trunk -b branches -t tags 397# View all branches and tags you have cloned: 398 git branch -r 399# Reset your master to trunk (or any other branch, replacing 'trunk' 400# with the appropriate name): 401 git reset --hard remotes/trunk 402# You may only dcommit to one branch/tag/trunk at a time. The usage 403# of dcommit/rebase/show-ignore should be teh same as above. 404------------------------------------------------------------------------ 405 406REBASE VS. PULL/MERGE 407--------------------- 408 409Originally, git-svn recommended that the remotes/git-svn branch be 410pulled or merged from. This is because the author favored 411'git-svn set-tree B' to commit a single head rather than the 412'git-svn set-tree A..B' notation to commit multiple commits. 413 414If you use 'git-svn set-tree A..B' to commit several diffs and you do 415not have the latest remotes/git-svn merged into my-branch, you should 416use 'git-svn rebase' to update your work branch instead of 'git pull' or 417'git merge'. 'pull/merge' can cause non-linear history to be flattened 418when committing into SVN, which can lead to merge commits reversing 419previous commits in SVN. 420 421DESIGN PHILOSOPHY 422----------------- 423Merge tracking in Subversion is lacking and doing branched development 424with Subversion is cumbersome as a result. git-svn does not do 425automated merge/branch tracking by default and leaves it entirely up to 426the user on the git side. git-svn does however follow copy 427history of the directory that it is tracking, however (much like 428how 'svn log' works). 429 430BUGS 431---- 432 433We ignore all SVN properties except svn:executable. Any unhandled 434properties are logged to $GIT_DIR/svn/<refname>/unhandled.log 435 436Renamed and copied directories are not detected by git and hence not 437tracked when committing to SVN. I do not plan on adding support for 438this as it's quite difficult and time-consuming to get working for all 439the possible corner cases (git doesn't do it, either). Committing 440renamed and copied files are fully supported if they're similar enough 441for git to detect them. 442 443CONFIGURATION 444------------- 445 446git-svn stores [svn-remote] configuration information in the 447repository .git/config file. It is similar the core git 448[remote] sections except 'fetch' keys do not accept glob 449arguments; but they are instead handled by the 'branches' 450and 'tags' keys. Since some SVN repositories are oddly 451configured with multiple projects glob expansions such those 452listed below are allowed: 453 454------------------------------------------------------------------------ 455[svn-remote "project-a"] 456 url = http://server.org/svn 457 branches = branches/*/project-a:refs/remotes/project-a/branches/* 458 tags = tags/*/project-a:refs/remotes/project-a/tags/* 459 trunk = trunk/project-a:refs/remotes/project-a/trunk 460------------------------------------------------------------------------ 461 462Keep in mind that the '*' (asterisk) wildcard of the local ref 463(left of the ':') *must* be the farthest right path component; 464however the remote wildcard may be anywhere as long as it's own 465independent path componet (surrounded by '/' or EOL). This 466type of configuration is not automatically created by 'init' and 467should be manually entered with a text-editor or using 468gitlink:git-config[1] 469 470SEE ALSO 471-------- 472gitlink:git-rebase[1] 473 474Author 475------ 476Written by Eric Wong <normalperson@yhbt.net>. 477 478Documentation 479------------- 480Written by Eric Wong <normalperson@yhbt.net>.