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----------- 14'git-svn' is a simple conduit for changesets between Subversion and git. 15It provides a bidirectional flow of changes between a Subversion and a git 16repository. 17 18'git-svn' can track a single Subversion branch simply by using a 19URL to the branch, follow branches laid out in the Subversion recommended 20method (trunk, branches, tags directories) with the --stdlayout option, or 21follow branches in any layout with the -T/-t/-b options (see options to 22'init' below, and also the 'clone' command). 23 24Once tracking a Subversion branch (with any of the above methods), the git 25repository can be updated from Subversion by the 'fetch' command and 26Subversion updated from git by the 'dcommit' command. 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-s;; 48--stdlayout;; 49 These are optional command-line options for init. Each of 50 these flags can point to a relative repository path 51 (--tags=project/tags') or a full url 52 (--tags=https://foo.org/project/tags). The option --stdlayout is 53 a shorthand way of setting trunk,tags,branches as the relative paths, 54 which is the Subversion default. If any of the other options are given 55 as well, they take precedence. 56--no-metadata;; 57 Set the 'noMetadata' option in the [svn-remote] config. 58--use-svm-props;; 59 Set the 'useSvmProps' option in the [svn-remote] config. 60--use-svnsync-props;; 61 Set the 'useSvnsyncProps' option in the [svn-remote] config. 62--rewrite-root=<URL>;; 63 Set the 'rewriteRoot' option in the [svn-remote] config. 64--use-log-author;; 65 When retrieving svn commits into git (as part of fetch, rebase, or 66 dcommit operations), look for the first From: or Signed-off-by: line 67 in the log message and use that as the author string. 68--add-author-from;; 69 When committing to svn from git (as part of commit or dcommit 70 operations), if the existing log message doesn't already have a 71 From: or Signed-off-by: line, append a From: line based on the 72 git commit's author string. If you use this, then --use-log-author 73 will retrieve a valid author string for all commits. 74--username=<USER>;; 75 For transports that SVN handles authentication for (http, 76 https, and plain svn), specify the username. For other 77 transports (eg svn+ssh://), you must include the username in 78 the URL, eg svn+ssh://foo@svn.bar.com/project 79--prefix=<prefix>;; 80 This allows one to specify a prefix which is prepended 81 to the names of remotes if trunk/branches/tags are 82 specified. The prefix does not automatically include a 83 trailing slash, so be sure you include one in the 84 argument if that is what you want. If --branches/-b is 85 specified, the prefix must include a trailing slash. 86 Setting a prefix is useful if you wish to track multiple 87 projects that share a common repository. 88 89'fetch':: 90 Fetch unfetched revisions from the Subversion remote we are 91 tracking. The name of the [svn-remote "..."] section in the 92 .git/config file may be specified as an optional command-line 93 argument. 94 95--localtime;; 96 Store Git commit times in the local timezone instead of UTC. This 97 makes 'git-log' (even without --date=local) show the same times 98 that `svn log` would in the local timezone. 99 100This doesn't interfere with interoperating with the Subversion 101repository you cloned from, but if you wish for your local Git 102repository to be able to interoperate with someone else's local Git 103repository, either don't use this option or you should both use it in 104the same local timezone. 105 106--ignore-paths=<regex>;; 107 This allows one to specify Perl regular expression that will 108 cause skipping of all matching paths from checkout from SVN. 109 Examples: 110 111 --ignore-paths="^doc" - skip "doc*" directory for every fetch. 112 113 --ignore-paths="^[^/]+/(?:branches|tags)" - skip "branches" 114 and "tags" of first level directories. 115 116 Regular expression is not persistent, you should specify 117 it every time when fetching. 118 119'clone':: 120 Runs 'init' and 'fetch'. It will automatically create a 121 directory based on the basename of the URL passed to it; 122 or if a second argument is passed; it will create a directory 123 and work within that. It accepts all arguments that the 124 'init' and 'fetch' commands accept; with the exception of 125 '--fetch-all'. After a repository is cloned, the 'fetch' 126 command will be able to update revisions without affecting 127 the working tree; and the 'rebase' command will be able 128 to update the working tree with the latest changes. 129 130'rebase':: 131 This fetches revisions from the SVN parent of the current HEAD 132 and rebases the current (uncommitted to SVN) work against it. 133 134This works similarly to `svn update` or 'git-pull' except that 135it preserves linear history with 'git-rebase' instead of 136'git-merge' for ease of dcommitting with 'git-svn'. 137 138This accepts all options that 'git-svn fetch' and 'git-rebase' 139accept. However, '--fetch-all' only fetches from the current 140[svn-remote], and not all [svn-remote] definitions. 141 142Like 'git-rebase'; this requires that the working tree be clean 143and have no uncommitted changes. 144 145-l;; 146--local;; 147 Do not fetch remotely; only run 'git-rebase' against the 148 last fetched commit from the upstream SVN. 149 150'dcommit':: 151 Commit each diff from a specified head directly to the SVN 152 repository, and then rebase or reset (depending on whether or 153 not there is a diff between SVN and head). This will create 154 a revision in SVN for each commit in git. 155 It is recommended that you run 'git-svn' fetch and rebase (not 156 pull or merge) your commits against the latest changes in the 157 SVN repository. 158 An optional command-line argument may be specified as an 159 alternative to HEAD. 160 This is advantageous over 'set-tree' (below) because it produces 161 cleaner, more linear history. 162+ 163--no-rebase;; 164 After committing, do not rebase or reset. 165--commit-url <URL>;; 166 Commit to this SVN URL (the full path). This is intended to 167 allow existing git-svn repositories created with one transport 168 method (e.g. `svn://` or `http://` for anonymous read) to be 169 reused if a user is later given access to an alternate transport 170 method (e.g. `svn+ssh://` or `https://`) for commit. 171 172 Using this option for any other purpose (don't ask) 173 is very strongly discouraged. 174-- 175 176'branch':: 177 Create a branch in the SVN repository. 178 179-m;; 180--message;; 181 Allows to specify the commit message. 182 183-t;; 184--tag;; 185 Create a tag by using the tags_subdir instead of the branches_subdir 186 specified during git svn init. 187 188'tag':: 189 Create a tag in the SVN repository. This is a shorthand for 190 'branch -t'. 191 192'log':: 193 This should make it easy to look up svn log messages when svn 194 users refer to -r/--revision numbers. 195+ 196The following features from `svn log' are supported: 197+ 198-- 199--revision=<n>[:<n>];; 200 is supported, non-numeric args are not: 201 HEAD, NEXT, BASE, PREV, etc ... 202-v/--verbose;; 203 it's not completely compatible with the --verbose 204 output in svn log, but reasonably close. 205--limit=<n>;; 206 is NOT the same as --max-count, doesn't count 207 merged/excluded commits 208--incremental;; 209 supported 210-- 211+ 212New features: 213+ 214-- 215--show-commit;; 216 shows the git commit sha1, as well 217--oneline;; 218 our version of --pretty=oneline 219-- 220+ 221NOTE: SVN itself only stores times in UTC and nothing else. The regular svn 222client converts the UTC time to the local time (or based on the TZ= 223environment). This command has the same behaviour. 224+ 225Any other arguments are passed directly to 'git-log' 226 227'blame':: 228 Show what revision and author last modified each line of a file. The 229 output of this mode is format-compatible with the output of 230 `svn blame' by default. Like the SVN blame command, 231 local uncommitted changes in the working copy are ignored; 232 the version of the file in the HEAD revision is annotated. Unknown 233 arguments are passed directly to 'git-blame'. 234+ 235--git-format;; 236 Produce output in the same format as 'git-blame', but with 237 SVN revision numbers instead of git commit hashes. In this mode, 238 changes that haven't been committed to SVN (including local 239 working-copy edits) are shown as revision 0. 240 241-- 242'find-rev':: 243 When given an SVN revision number of the form 'rN', returns the 244 corresponding git commit hash (this can optionally be followed by a 245 tree-ish to specify which branch should be searched). When given a 246 tree-ish, returns the corresponding SVN revision number. 247 248'set-tree':: 249 You should consider using 'dcommit' instead of this command. 250 Commit specified commit or tree objects to SVN. This relies on 251 your imported fetch data being up-to-date. This makes 252 absolutely no attempts to do patching when committing to SVN, it 253 simply overwrites files with those specified in the tree or 254 commit. All merging is assumed to have taken place 255 independently of 'git-svn' functions. 256 257'create-ignore':: 258 Recursively finds the svn:ignore property on directories and 259 creates matching .gitignore files. The resulting files are staged to 260 be committed, but are not committed. Use -r/--revision to refer to a 261 specific revision. 262 263'show-ignore':: 264 Recursively finds and lists the svn:ignore property on 265 directories. The output is suitable for appending to 266 the $GIT_DIR/info/exclude file. 267 268'commit-diff':: 269 Commits the diff of two tree-ish arguments from the 270 command-line. This command does not rely on being inside an `git-svn 271 init`-ed repository. This command takes three arguments, (a) the 272 original tree to diff against, (b) the new tree result, (c) the 273 URL of the target Subversion repository. The final argument 274 (URL) may be omitted if you are working from a 'git-svn'-aware 275 repository (that has been `init`-ed with 'git-svn'). 276 The -r<revision> option is required for this. 277 278'info':: 279 Shows information about a file or directory similar to what 280 `svn info' provides. Does not currently support a -r/--revision 281 argument. Use the --url option to output only the value of the 282 'URL:' field. 283 284'proplist':: 285 Lists the properties stored in the Subversion repository about a 286 given file or directory. Use -r/--revision to refer to a specific 287 Subversion revision. 288 289'propget':: 290 Gets the Subversion property given as the first argument, for a 291 file. A specific revision can be specified with -r/--revision. 292 293'show-externals':: 294 Shows the Subversion externals. Use -r/--revision to specify a 295 specific revision. 296 297-- 298 299OPTIONS 300------- 301-- 302 303--shared[={false|true|umask|group|all|world|everybody}]:: 304--template=<template_directory>:: 305 Only used with the 'init' command. 306 These are passed directly to 'git-init'. 307 308-r <ARG>:: 309--revision <ARG>:: 310 311Used with the 'fetch' command. 312 313This allows revision ranges for partial/cauterized history 314to be supported. $NUMBER, $NUMBER1:$NUMBER2 (numeric ranges), 315$NUMBER:HEAD, and BASE:$NUMBER are all supported. 316 317This can allow you to make partial mirrors when running fetch; 318but is generally not recommended because history will be skipped 319and lost. 320 321-:: 322--stdin:: 323 324Only used with the 'set-tree' command. 325 326Read a list of commits from stdin and commit them in reverse 327order. Only the leading sha1 is read from each line, so 328'git-rev-list --pretty=oneline' output can be used. 329 330--rmdir:: 331 332Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. 333 334Remove directories from the SVN tree if there are no files left 335behind. SVN can version empty directories, and they are not 336removed by default if there are no files left in them. git 337cannot version empty directories. Enabling this flag will make 338the commit to SVN act like git. 339 340config key: svn.rmdir 341 342-e:: 343--edit:: 344 345Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. 346 347Edit the commit message before committing to SVN. This is off by 348default for objects that are commits, and forced on when committing 349tree objects. 350 351config key: svn.edit 352 353-l<num>:: 354--find-copies-harder:: 355 356Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. 357 358They are both passed directly to 'git-diff-tree'; see 359linkgit:git-diff-tree[1] for more information. 360 361[verse] 362config key: svn.l 363config key: svn.findcopiesharder 364 365-A<filename>:: 366--authors-file=<filename>:: 367 368Syntax is compatible with the file used by 'git-cvsimport': 369 370------------------------------------------------------------------------ 371 loginname = Joe User <user@example.com> 372------------------------------------------------------------------------ 373 374If this option is specified and 'git-svn' encounters an SVN 375committer name that does not exist in the authors-file, 'git-svn' 376will abort operation. The user will then have to add the 377appropriate entry. Re-running the previous 'git-svn' command 378after the authors-file is modified should continue operation. 379 380config key: svn.authorsfile 381 382-q:: 383--quiet:: 384 Make 'git-svn' less verbose. 385 386--repack[=<n>]:: 387--repack-flags=<flags>:: 388 389These should help keep disk usage sane for large fetches 390with many revisions. 391 392--repack takes an optional argument for the number of revisions 393to fetch before repacking. This defaults to repacking every 3941000 commits fetched if no argument is specified. 395 396--repack-flags are passed directly to 'git-repack'. 397 398[verse] 399config key: svn.repack 400config key: svn.repackflags 401 402-m:: 403--merge:: 404-s<strategy>:: 405--strategy=<strategy>:: 406 407These are only used with the 'dcommit' and 'rebase' commands. 408 409Passed directly to 'git-rebase' when using 'dcommit' if a 410'git-reset' cannot be used (see 'dcommit'). 411 412-n:: 413--dry-run:: 414 415This can be used with the 'dcommit', 'rebase', 'branch' and 'tag' 416commands. 417 418For 'dcommit', print out the series of git arguments that would show 419which diffs would be committed to SVN. 420 421For 'rebase', display the local branch associated with the upstream svn 422repository associated with the current branch and the URL of svn 423repository that will be fetched from. 424 425For 'branch' and 'tag', display the urls that will be used for copying when 426creating the branch or tag. 427 428-- 429 430ADVANCED OPTIONS 431---------------- 432-- 433 434-i<GIT_SVN_ID>:: 435--id <GIT_SVN_ID>:: 436 437This sets GIT_SVN_ID (instead of using the environment). This 438allows the user to override the default refname to fetch from 439when tracking a single URL. The 'log' and 'dcommit' commands 440no longer require this switch as an argument. 441 442-R<remote name>:: 443--svn-remote <remote name>:: 444 Specify the [svn-remote "<remote name>"] section to use, 445 this allows SVN multiple repositories to be tracked. 446 Default: "svn" 447 448--follow-parent:: 449 This is especially helpful when we're tracking a directory 450 that has been moved around within the repository, or if we 451 started tracking a branch and never tracked the trunk it was 452 descended from. This feature is enabled by default, use 453 --no-follow-parent to disable it. 454 455config key: svn.followparent 456 457-- 458CONFIG FILE-ONLY OPTIONS 459------------------------ 460-- 461 462svn.noMetadata:: 463svn-remote.<name>.noMetadata:: 464 465This gets rid of the 'git-svn-id:' lines at the end of every commit. 466 467If you lose your .git/svn/git-svn/.rev_db file, 'git-svn' will not 468be able to rebuild it and you won't be able to fetch again, 469either. This is fine for one-shot imports. 470 471The 'git-svn log' command will not work on repositories using 472this, either. Using this conflicts with the 'useSvmProps' 473option for (hopefully) obvious reasons. 474 475svn.useSvmProps:: 476svn-remote.<name>.useSvmProps:: 477 478This allows 'git-svn' to re-map repository URLs and UUIDs from 479mirrors created using SVN::Mirror (or svk) for metadata. 480 481If an SVN revision has a property, "svm:headrev", it is likely 482that the revision was created by SVN::Mirror (also used by SVK). 483The property contains a repository UUID and a revision. We want 484to make it look like we are mirroring the original URL, so 485introduce a helper function that returns the original identity 486URL and UUID, and use it when generating metadata in commit 487messages. 488 489svn.useSvnsyncProps:: 490svn-remote.<name>.useSvnsyncprops:: 491 Similar to the useSvmProps option; this is for users 492 of the svnsync(1) command distributed with SVN 1.4.x and 493 later. 494 495svn-remote.<name>.rewriteRoot:: 496 This allows users to create repositories from alternate 497 URLs. For example, an administrator could run 'git-svn' on the 498 server locally (accessing via file://) but wish to distribute 499 the repository with a public http:// or svn:// URL in the 500 metadata so users of it will see the public URL. 501 502svn.brokenSymlinkWorkaround:: 503This disables potentially expensive checks to workaround broken symlinks 504checked into SVN by broken clients. Set this option to "false" if you 505track a SVN repository with many empty blobs that are not symlinks. 506This option may be changed while "git-svn" is running and take effect on 507the next revision fetched. If unset, git-svn assumes this option to be 508"true". 509 510-- 511 512Since the noMetadata, rewriteRoot, useSvnsyncProps and useSvmProps 513options all affect the metadata generated and used by 'git-svn'; they 514*must* be set in the configuration file before any history is imported 515and these settings should never be changed once they are set. 516 517Additionally, only one of these four options can be used per-svn-remote 518section because they affect the 'git-svn-id:' metadata line. 519 520 521BASIC EXAMPLES 522-------------- 523 524Tracking and contributing to the trunk of a Subversion-managed project: 525 526------------------------------------------------------------------------ 527# Clone a repo (like git clone): 528 git svn clone http://svn.example.com/project/trunk 529# Enter the newly cloned directory: 530 cd trunk 531# You should be on master branch, double-check with git-branch 532 git branch 533# Do some work and commit locally to git: 534 git commit ... 535# Something is committed to SVN, rebase your local changes against the 536# latest changes in SVN: 537 git svn rebase 538# Now commit your changes (that were committed previously using git) to SVN, 539# as well as automatically updating your working HEAD: 540 git svn dcommit 541# Append svn:ignore settings to the default git exclude file: 542 git svn show-ignore >> .git/info/exclude 543------------------------------------------------------------------------ 544 545Tracking and contributing to an entire Subversion-managed project 546(complete with a trunk, tags and branches): 547 548------------------------------------------------------------------------ 549# Clone a repo (like git clone): 550 git svn clone http://svn.example.com/project -T trunk -b branches -t tags 551# View all branches and tags you have cloned: 552 git branch -r 553# Create a new branch in SVN 554 git svn branch waldo 555# Reset your master to trunk (or any other branch, replacing 'trunk' 556# with the appropriate name): 557 git reset --hard remotes/trunk 558# You may only dcommit to one branch/tag/trunk at a time. The usage 559# of dcommit/rebase/show-ignore should be the same as above. 560------------------------------------------------------------------------ 561 562The initial 'git-svn clone' can be quite time-consuming 563(especially for large Subversion repositories). If multiple 564people (or one person with multiple machines) want to use 565'git-svn' to interact with the same Subversion repository, you can 566do the initial 'git-svn clone' to a repository on a server and 567have each person clone that repository with 'git-clone': 568 569------------------------------------------------------------------------ 570# Do the initial import on a server 571 ssh server "cd /pub && git svn clone http://svn.example.com/project 572# Clone locally - make sure the refs/remotes/ space matches the server 573 mkdir project 574 cd project 575 git init 576 git remote add origin server:/pub/project 577 git config --add remote.origin.fetch '+refs/remotes/*:refs/remotes/*' 578 git fetch 579# Create a local branch from one of the branches just fetched 580 git checkout -b master FETCH_HEAD 581# Initialize git-svn locally (be sure to use the same URL and -T/-b/-t options as were used on server) 582 git svn init http://svn.example.com/project 583# Pull the latest changes from Subversion 584 git svn rebase 585------------------------------------------------------------------------ 586 587REBASE VS. PULL/MERGE 588--------------------- 589 590Originally, 'git-svn' recommended that the 'remotes/git-svn' branch be 591pulled or merged from. This is because the author favored 592`git svn set-tree B` to commit a single head rather than the 593`git svn set-tree A..B` notation to commit multiple commits. 594 595If you use `git svn set-tree A..B` to commit several diffs and you do 596not have the latest remotes/git-svn merged into my-branch, you should 597use `git svn rebase` to update your work branch instead of `git pull` or 598`git merge`. `pull`/`merge' can cause non-linear history to be flattened 599when committing into SVN, which can lead to merge commits reversing 600previous commits in SVN. 601 602DESIGN PHILOSOPHY 603----------------- 604Merge tracking in Subversion is lacking and doing branched development 605with Subversion can be cumbersome as a result. While 'git-svn' can track 606copy history (including branches and tags) for repositories adopting a 607standard layout, it cannot yet represent merge history that happened 608inside git back upstream to SVN users. Therefore it is advised that 609users keep history as linear as possible inside git to ease 610compatibility with SVN (see the CAVEATS section below). 611 612CAVEATS 613------- 614 615For the sake of simplicity and interoperating with a less-capable system 616(SVN), it is recommended that all 'git-svn' users clone, fetch and dcommit 617directly from the SVN server, and avoid all 'git-clone'/'pull'/'merge'/'push' 618operations between git repositories and branches. The recommended 619method of exchanging code between git branches and users is 620'git-format-patch' and 'git-am', or just 'dcommit'ing to the SVN repository. 621 622Running 'git-merge' or 'git-pull' is NOT recommended on a branch you 623plan to 'dcommit' from. Subversion does not represent merges in any 624reasonable or useful fashion; so users using Subversion cannot see any 625merges you've made. Furthermore, if you merge or pull from a git branch 626that is a mirror of an SVN branch, 'dcommit' may commit to the wrong 627branch. 628 629'git-clone' does not clone branches under the refs/remotes/ hierarchy or 630any 'git-svn' metadata, or config. So repositories created and managed with 631using 'git-svn' should use 'rsync' for cloning, if cloning is to be done 632at all. 633 634Since 'dcommit' uses rebase internally, any git branches you 'git-push' to 635before 'dcommit' on will require forcing an overwrite of the existing ref 636on the remote repository. This is generally considered bad practice, 637see the linkgit:git-push[1] documentation for details. 638 639Do not use the --amend option of linkgit:git-commit[1] on a change you've 640already dcommitted. It is considered bad practice to --amend commits 641you've already pushed to a remote repository for other users, and 642dcommit with SVN is analogous to that. 643 644BUGS 645---- 646 647We ignore all SVN properties except svn:executable. Any unhandled 648properties are logged to $GIT_DIR/svn/<refname>/unhandled.log 649 650Renamed and copied directories are not detected by git and hence not 651tracked when committing to SVN. I do not plan on adding support for 652this as it's quite difficult and time-consuming to get working for all 653the possible corner cases (git doesn't do it, either). Committing 654renamed and copied files are fully supported if they're similar enough 655for git to detect them. 656 657CONFIGURATION 658------------- 659 660'git-svn' stores [svn-remote] configuration information in the 661repository .git/config file. It is similar the core git 662[remote] sections except 'fetch' keys do not accept glob 663arguments; but they are instead handled by the 'branches' 664and 'tags' keys. Since some SVN repositories are oddly 665configured with multiple projects glob expansions such those 666listed below are allowed: 667 668------------------------------------------------------------------------ 669[svn-remote "project-a"] 670 url = http://server.org/svn 671 branches = branches/*/project-a:refs/remotes/project-a/branches/* 672 tags = tags/*/project-a:refs/remotes/project-a/tags/* 673 trunk = trunk/project-a:refs/remotes/project-a/trunk 674------------------------------------------------------------------------ 675 676Keep in mind that the '*' (asterisk) wildcard of the local ref 677(right of the ':') *must* be the farthest right path component; 678however the remote wildcard may be anywhere as long as it's own 679independent path component (surrounded by '/' or EOL). This 680type of configuration is not automatically created by 'init' and 681should be manually entered with a text-editor or using 'git-config'. 682 683SEE ALSO 684-------- 685linkgit:git-rebase[1] 686 687Author 688------ 689Written by Eric Wong <normalperson@yhbt.net>. 690 691Documentation 692------------- 693Written by Eric Wong <normalperson@yhbt.net>.