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