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