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