diff options
Diffstat (limited to 'Documentation/git-svn.txt')
| -rw-r--r-- | Documentation/git-svn.txt | 628 |
1 files changed, 628 insertions, 0 deletions
diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt new file mode 100644 index 0000000000..773ae9654b --- /dev/null +++ b/Documentation/git-svn.txt @@ -0,0 +1,628 @@ +git-svn(1) +========== + +NAME +---- +git-svn - Bidirectional operation between a single Subversion branch and git + +SYNOPSIS +-------- +'git svn' <command> [options] [arguments] + +DESCRIPTION +----------- +'git-svn' is a simple conduit for changesets between Subversion and git. +It provides a bidirectional flow of changes between a Subversion and a git +repository. + +'git-svn' can track a single Subversion branch simply by using a +URL to the branch, follow branches laid out in the Subversion recommended +method (trunk, branches, tags directories) with the --stdlayout option, or +follow branches in any layout with the -T/-t/-b options (see options to +'init' below, and also the 'clone' command). + +Once tracking a Subversion branch (with any of the above methods), the git +repository can be updated from Subversion by the 'fetch' command and +Subversion updated from git by the 'dcommit' command. + +COMMANDS +-------- +-- + +'init':: + Initializes an empty git repository with additional + metadata directories for 'git-svn'. The Subversion URL + may be specified as a command-line argument, or as full + URL arguments to -T/-t/-b. Optionally, the target + directory to operate on can be specified as a second + argument. Normally this command initializes the current + directory. + +-T<trunk_subdir>;; +--trunk=<trunk_subdir>;; +-t<tags_subdir>;; +--tags=<tags_subdir>;; +-b<branches_subdir>;; +--branches=<branches_subdir>;; +-s;; +--stdlayout;; + These are optional command-line options for init. Each of + these flags can point to a relative repository path + (--tags=project/tags') or a full url + (--tags=https://foo.org/project/tags). The option --stdlayout is + a shorthand way of setting trunk,tags,branches as the relative paths, + which is the Subversion default. If any of the other options are given + as well, they take precedence. +--no-metadata;; + Set the 'noMetadata' option in the [svn-remote] config. +--use-svm-props;; + Set the 'useSvmProps' option in the [svn-remote] config. +--use-svnsync-props;; + Set the 'useSvnsyncProps' option in the [svn-remote] config. +--rewrite-root=<URL>;; + Set the 'rewriteRoot' option in the [svn-remote] config. +--use-log-author;; + When retrieving svn commits into git (as part of fetch, rebase, or + dcommit operations), look for the first From: or Signed-off-by: line + in the log message and use that as the author string. +--add-author-from;; + When committing to svn from git (as part of commit or dcommit + operations), if the existing log message doesn't already have a + From: or Signed-off-by: line, append a From: line based on the + git commit's author string. If you use this, then --use-log-author + will retrieve a valid author string for all commits. +--username=<USER>;; + For transports that SVN handles authentication for (http, + https, and plain svn), specify the username. For other + transports (eg svn+ssh://), you must include the username in + the URL, eg svn+ssh://foo@svn.bar.com/project +--prefix=<prefix>;; + This allows one to specify a prefix which is prepended + to the names of remotes if trunk/branches/tags are + specified. The prefix does not automatically include a + trailing slash, so be sure you include one in the + argument if that is what you want. If --branches/-b is + specified, the prefix must include a trailing slash. + Setting a prefix is useful if you wish to track multiple + projects that share a common repository. + +'fetch':: + Fetch unfetched revisions from the Subversion remote we are + tracking. The name of the [svn-remote "..."] section in the + .git/config file may be specified as an optional command-line + argument. + +'clone':: + Runs 'init' and 'fetch'. It will automatically create a + directory based on the basename of the URL passed to it; + or if a second argument is passed; it will create a directory + and work within that. It accepts all arguments that the + 'init' and 'fetch' commands accept; with the exception of + '--fetch-all'. After a repository is cloned, the 'fetch' + command will be able to update revisions without affecting + the working tree; and the 'rebase' command will be able + to update the working tree with the latest changes. + +'rebase':: + This fetches revisions from the SVN parent of the current HEAD + and rebases the current (uncommitted to SVN) work against it. + +This works similarly to `svn update` or 'git-pull' except that +it preserves linear history with 'git-rebase' instead of +'git-merge' for ease of dcommiting with 'git-svn'. + +This accepts all options that 'git-svn fetch' and 'git-rebase' +accept. However, '--fetch-all' only fetches from the current +[svn-remote], and not all [svn-remote] definitions. + +Like 'git-rebase'; this requires that the working tree be clean +and have no uncommitted changes. + +-l;; +--local;; + Do not fetch remotely; only run 'git-rebase' against the + last fetched commit from the upstream SVN. + +'dcommit':: + Commit each diff from a specified head directly to the SVN + repository, and then rebase or reset (depending on whether or + not there is a diff between SVN and head). This will create + a revision in SVN for each commit in git. + It is recommended that you run 'git-svn' fetch and rebase (not + pull or merge) your commits against the latest changes in the + SVN repository. + An optional command-line argument may be specified as an + alternative to HEAD. + This is advantageous over 'set-tree' (below) because it produces + cleaner, more linear history. ++ +--no-rebase;; + After committing, do not rebase or reset. +-- + +'log':: + This should make it easy to look up svn log messages when svn + users refer to -r/--revision numbers. ++ +The following features from `svn log' are supported: ++ +-- +--revision=<n>[:<n>];; + is supported, non-numeric args are not: + HEAD, NEXT, BASE, PREV, etc ... +-v/--verbose;; + it's not completely compatible with the --verbose + output in svn log, but reasonably close. +--limit=<n>;; + is NOT the same as --max-count, doesn't count + merged/excluded commits +--incremental;; + supported +-- ++ +New features: ++ +-- +--show-commit;; + shows the git commit sha1, as well +--oneline;; + our version of --pretty=oneline +-- ++ +NOTE: SVN itself only stores times in UTC and nothing else. The regular svn +client converts the UTC time to the local time (or based on the TZ= +environment). This command has the same behaviour. ++ +Any other arguments are passed directly to 'git-log' + +'blame':: + Show what revision and author last modified each line of a file. The + output of this mode is format-compatible with the output of + `svn blame' by default. Like the SVN blame command, + local uncommitted changes in the working copy are ignored; + the version of the file in the HEAD revision is annotated. Unknown + arguments are passed directly to 'git-blame'. ++ +--git-format;; + Produce output in the same format as 'git-blame', but with + SVN revision numbers instead of git commit hashes. In this mode, + changes that haven't been committed to SVN (including local + working-copy edits) are shown as revision 0. + +-- +'find-rev':: + When given an SVN revision number of the form 'rN', returns the + corresponding git commit hash (this can optionally be followed by a + tree-ish to specify which branch should be searched). When given a + tree-ish, returns the corresponding SVN revision number. + +'set-tree':: + You should consider using 'dcommit' instead of this command. + Commit specified commit or tree objects to SVN. This relies on + your imported fetch data being up-to-date. This makes + absolutely no attempts to do patching when committing to SVN, it + simply overwrites files with those specified in the tree or + commit. All merging is assumed to have taken place + independently of 'git-svn' functions. + +'create-ignore':: + Recursively finds the svn:ignore property on directories and + creates matching .gitignore files. The resulting files are staged to + be committed, but are not committed. Use -r/--revision to refer to a + specific revision. + +'show-ignore':: + Recursively finds and lists the svn:ignore property on + directories. The output is suitable for appending to + the $GIT_DIR/info/exclude file. + +'commit-diff':: + Commits the diff of two tree-ish arguments from the + command-line. This command does not rely on being inside an `git-svn + init`-ed repository. This command takes three arguments, (a) the + original tree to diff against, (b) the new tree result, (c) the + URL of the target Subversion repository. The final argument + (URL) may be omitted if you are working from a 'git-svn'-aware + repository (that has been `init`-ed with 'git-svn'). + The -r<revision> option is required for this. + +'info':: + Shows information about a file or directory similar to what + `svn info' provides. Does not currently support a -r/--revision + argument. Use the --url option to output only the value of the + 'URL:' field. + +'proplist':: + Lists the properties stored in the Subversion repository about a + given file or directory. Use -r/--revision to refer to a specific + Subversion revision. + +'propget':: + Gets the Subversion property given as the first argument, for a + file. A specific revision can be specified with -r/--revision. + +'show-externals':: + Shows the Subversion externals. Use -r/--revision to specify a + specific revision. + +-- + +OPTIONS +------- +-- + +--shared[={false|true|umask|group|all|world|everybody}]:: +--template=<template_directory>:: + Only used with the 'init' command. + These are passed directly to 'git-init'. + +-r <ARG>:: +--revision <ARG>:: + +Used with the 'fetch' command. + +This allows revision ranges for partial/cauterized history +to be supported. $NUMBER, $NUMBER1:$NUMBER2 (numeric ranges), +$NUMBER:HEAD, and BASE:$NUMBER are all supported. + +This can allow you to make partial mirrors when running fetch; +but is generally not recommended because history will be skipped +and lost. + +-:: +--stdin:: + +Only used with the 'set-tree' command. + +Read a list of commits from stdin and commit them in reverse +order. Only the leading sha1 is read from each line, so +'git-rev-list --pretty=oneline' output can be used. + +--rmdir:: + +Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. + +Remove directories from the SVN tree if there are no files left +behind. SVN can version empty directories, and they are not +removed by default if there are no files left in them. git +cannot version empty directories. Enabling this flag will make +the commit to SVN act like git. + +config key: svn.rmdir + +-e:: +--edit:: + +Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. + +Edit the commit message before committing to SVN. This is off by +default for objects that are commits, and forced on when committing +tree objects. + +config key: svn.edit + +-l<num>:: +--find-copies-harder:: + +Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. + +They are both passed directly to 'git-diff-tree'; see +linkgit:git-diff-tree[1] for more information. + +[verse] +config key: svn.l +config key: svn.findcopiesharder + +-A<filename>:: +--authors-file=<filename>:: + +Syntax is compatible with the file used by 'git-cvsimport': + +------------------------------------------------------------------------ + loginname = Joe User <user@example.com> +------------------------------------------------------------------------ + +If this option is specified and 'git-svn' encounters an SVN +committer name that does not exist in the authors-file, 'git-svn' +will abort operation. The user will then have to add the +appropriate entry. Re-running the previous 'git-svn' command +after the authors-file is modified should continue operation. + +config key: svn.authorsfile + +-q:: +--quiet:: + Make 'git-svn' less verbose. + +--repack[=<n>]:: +--repack-flags=<flags>:: + +These should help keep disk usage sane for large fetches +with many revisions. + +--repack takes an optional argument for the number of revisions +to fetch before repacking. This defaults to repacking every +1000 commits fetched if no argument is specified. + +--repack-flags are passed directly to 'git-repack'. + +[verse] +config key: svn.repack +config key: svn.repackflags + +-m:: +--merge:: +-s<strategy>:: +--strategy=<strategy>:: + +These are only used with the 'dcommit' and 'rebase' commands. + +Passed directly to 'git-rebase' when using 'dcommit' if a +'git-reset' cannot be used (see 'dcommit'). + +-n:: +--dry-run:: + +This can be used with the 'dcommit' and 'rebase' commands. + +For 'dcommit', print out the series of git arguments that would show +which diffs would be committed to SVN. + +For 'rebase', display the local branch associated with the upstream svn +repository associated with the current branch and the URL of svn +repository that will be fetched from. + +-- + +ADVANCED OPTIONS +---------------- +-- + +-i<GIT_SVN_ID>:: +--id <GIT_SVN_ID>:: + +This sets GIT_SVN_ID (instead of using the environment). This +allows the user to override the default refname to fetch from +when tracking a single URL. The 'log' and 'dcommit' commands +no longer require this switch as an argument. + +-R<remote name>:: +--svn-remote <remote name>:: + Specify the [svn-remote "<remote name>"] section to use, + this allows SVN multiple repositories to be tracked. + Default: "svn" + +--follow-parent:: + This is especially helpful when we're tracking a directory + that has been moved around within the repository, or if we + started tracking a branch and never tracked the trunk it was + descended from. This feature is enabled by default, use + --no-follow-parent to disable it. + +config key: svn.followparent + +-- +CONFIG FILE-ONLY OPTIONS +------------------------ +-- + +svn.noMetadata:: +svn-remote.<name>.noMetadata:: + +This gets rid of the 'git-svn-id:' lines at the end of every commit. + +If you lose your .git/svn/git-svn/.rev_db file, 'git-svn' will not +be able to rebuild it and you won't be able to fetch again, +either. This is fine for one-shot imports. + +The 'git-svn log' command will not work on repositories using +this, either. Using this conflicts with the 'useSvmProps' +option for (hopefully) obvious reasons. + +svn.useSvmProps:: +svn-remote.<name>.useSvmProps:: + +This allows 'git-svn' to re-map repository URLs and UUIDs from +mirrors created using SVN::Mirror (or svk) for metadata. + +If an SVN revision has a property, "svm:headrev", it is likely +that the revision was created by SVN::Mirror (also used by SVK). +The property contains a repository UUID and a revision. We want +to make it look like we are mirroring the original URL, so +introduce a helper function that returns the original identity +URL and UUID, and use it when generating metadata in commit +messages. + +svn.useSvnsyncProps:: +svn-remote.<name>.useSvnsyncprops:: + Similar to the useSvmProps option; this is for users + of the svnsync(1) command distributed with SVN 1.4.x and + later. + +svn-remote.<name>.rewriteRoot:: + This allows users to create repositories from alternate + URLs. For example, an administrator could run 'git-svn' on the + server locally (accessing via file://) but wish to distribute + the repository with a public http:// or svn:// URL in the + metadata so users of it will see the public URL. + +-- + +Since the noMetadata, rewriteRoot, useSvnsyncProps and useSvmProps +options all affect the metadata generated and used by 'git-svn'; they +*must* be set in the configuration file before any history is imported +and these settings should never be changed once they are set. + +Additionally, only one of these four options can be used per-svn-remote +section because they affect the 'git-svn-id:' metadata line. + + +BASIC EXAMPLES +-------------- + +Tracking and contributing to the trunk of a Subversion-managed project: + +------------------------------------------------------------------------ +# Clone a repo (like git clone): + git svn clone http://svn.foo.org/project/trunk +# Enter the newly cloned directory: + cd trunk +# You should be on master branch, double-check with git-branch + git branch +# Do some work and commit locally to git: + git commit ... +# Something is committed to SVN, rebase your local changes against the +# latest changes in SVN: + git svn rebase +# Now commit your changes (that were committed previously using git) to SVN, +# as well as automatically updating your working HEAD: + git svn dcommit +# Append svn:ignore settings to the default git exclude file: + git svn show-ignore >> .git/info/exclude +------------------------------------------------------------------------ + +Tracking and contributing to an entire Subversion-managed project +(complete with a trunk, tags and branches): + +------------------------------------------------------------------------ +# Clone a repo (like git clone): + git svn clone http://svn.foo.org/project -T trunk -b branches -t tags +# View all branches and tags you have cloned: + git branch -r +# Reset your master to trunk (or any other branch, replacing 'trunk' +# with the appropriate name): + git reset --hard remotes/trunk +# You may only dcommit to one branch/tag/trunk at a time. The usage +# of dcommit/rebase/show-ignore should be the same as above. +------------------------------------------------------------------------ + +The initial 'git-svn clone' can be quite time-consuming +(especially for large Subversion repositories). If multiple +people (or one person with multiple machines) want to use +'git-svn' to interact with the same Subversion repository, you can +do the initial 'git-svn clone' to a repository on a server and +have each person clone that repository with 'git-clone': + +------------------------------------------------------------------------ +# Do the initial import on a server + ssh server "cd /pub && git svn clone http://svn.foo.org/project +# Clone locally - make sure the refs/remotes/ space matches the server + mkdir project + cd project + git init + git remote add origin server:/pub/project + git config --add remote.origin.fetch '+refs/remotes/*:refs/remotes/*' + git fetch +# Initialize git-svn locally (be sure to use the same URL and -T/-b/-t options as were used on server) + git svn init http://svn.foo.org/project +# Pull the latest changes from Subversion + git svn rebase +------------------------------------------------------------------------ + +REBASE VS. PULL/MERGE +--------------------- + +Originally, 'git-svn' recommended that the 'remotes/git-svn' branch be +pulled or merged from. This is because the author favored +`git svn set-tree B` to commit a single head rather than the +`git svn set-tree A..B` notation to commit multiple commits. + +If you use `git svn set-tree A..B` to commit several diffs and you do +not have the latest remotes/git-svn merged into my-branch, you should +use `git svn rebase` to update your work branch instead of `git pull` or +`git merge`. `pull`/`merge' can cause non-linear history to be flattened +when committing into SVN, which can lead to merge commits reversing +previous commits in SVN. + +DESIGN PHILOSOPHY +----------------- +Merge tracking in Subversion is lacking and doing branched development +with Subversion can be cumbersome as a result. While 'git-svn' can track +copy history (including branches and tags) for repositories adopting a +standard layout, it cannot yet represent merge history that happened +inside git back upstream to SVN users. Therefore it is advised that +users keep history as linear as possible inside git to ease +compatibility with SVN (see the CAVEATS section below). + +CAVEATS +------- + +For the sake of simplicity and interoperating with a less-capable system +(SVN), it is recommended that all 'git-svn' users clone, fetch and dcommit +directly from the SVN server, and avoid all 'git-clone'/'pull'/'merge'/'push' +operations between git repositories and branches. The recommended +method of exchanging code between git branches and users is +'git-format-patch' and 'git-am', or just 'dcommit'ing to the SVN repository. + +Running 'git-merge' or 'git-pull' is NOT recommended on a branch you +plan to 'dcommit' from. Subversion does not represent merges in any +reasonable or useful fashion; so users using Subversion cannot see any +merges you've made. Furthermore, if you merge or pull from a git branch +that is a mirror of an SVN branch, 'dcommit' may commit to the wrong +branch. + +'git-clone' does not clone branches under the refs/remotes/ hierarchy or +any 'git-svn' metadata, or config. So repositories created and managed with +using 'git-svn' should use 'rsync' for cloning, if cloning is to be done +at all. + +Since 'dcommit' uses rebase internally, any git branches you 'git-push' to +before 'dcommit' on will require forcing an overwrite of the existing ref +on the remote repository. This is generally considered bad practice, +see the linkgit:git-push[1] documentation for details. + +Do not use the --amend option of linkgit:git-commit[1] on a change you've +already dcommitted. It is considered bad practice to --amend commits +you've already pushed to a remote repository for other users, and +dcommit with SVN is analogous to that. + +BUGS +---- + +We ignore all SVN properties except svn:executable. Any unhandled +properties are logged to $GIT_DIR/svn/<refname>/unhandled.log + +Renamed and copied directories are not detected by git and hence not +tracked when committing to SVN. I do not plan on adding support for +this as it's quite difficult and time-consuming to get working for all +the possible corner cases (git doesn't do it, either). Committing +renamed and copied files are fully supported if they're similar enough +for git to detect them. + +CONFIGURATION +------------- + +'git-svn' stores [svn-remote] configuration information in the +repository .git/config file. It is similar the core git +[remote] sections except 'fetch' keys do not accept glob +arguments; but they are instead handled by the 'branches' +and 'tags' keys. Since some SVN repositories are oddly +configured with multiple projects glob expansions such those +listed below are allowed: + +------------------------------------------------------------------------ +[svn-remote "project-a"] + url = http://server.org/svn + branches = branches/*/project-a:refs/remotes/project-a/branches/* + tags = tags/*/project-a:refs/remotes/project-a/tags/* + trunk = trunk/project-a:refs/remotes/project-a/trunk +------------------------------------------------------------------------ + +Keep in mind that the '*' (asterisk) wildcard of the local ref +(right of the ':') *must* be the farthest right path component; +however the remote wildcard may be anywhere as long as it's own +independent path component (surrounded by '/' or EOL). This +type of configuration is not automatically created by 'init' and +should be manually entered with a text-editor or using 'git-config'. + +SEE ALSO +-------- +linkgit:git-rebase[1] + +Author +------ +Written by Eric Wong <normalperson@yhbt.net>. + +Documentation +------------- +Written by Eric Wong <normalperson@yhbt.net>. |