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