diff options
Diffstat (limited to 'Documentation/git-svn.txt')
| -rw-r--r-- | Documentation/git-svn.txt | 187 |
1 files changed, 129 insertions, 58 deletions
diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 99f3c1ea6c..cfe8d2b5df 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -7,6 +7,7 @@ git-svn - Bidirectional operation between a Subversion repository and git SYNOPSIS -------- +[verse] 'git svn' <command> [options] [arguments] DESCRIPTION @@ -56,6 +57,8 @@ COMMANDS as well, they take precedence. --no-metadata;; Set the 'noMetadata' option in the [svn-remote] config. + This option is not recommended, please read the 'svn.noMetadata' + section of this manpage before using this option. --use-svm-props;; Set the 'useSvmProps' option in the [svn-remote] config. --use-svnsync-props;; @@ -64,7 +67,7 @@ COMMANDS Set the 'rewriteRoot' option in the [svn-remote] config. --rewrite-uuid=<UUID>;; Set the 'rewriteUUID' option in the [svn-remote] config. ---username=<USER>;; +--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 @@ -143,17 +146,6 @@ Skip "branches" and "tags" of first level directories;; ------------------------------------------------------------------------ -- ---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. - 'clone':: Runs 'init' and 'fetch'. It will automatically create a directory based on the basename of the URL passed to it; @@ -165,6 +157,17 @@ Skip "branches" and "tags" of first level directories;; affecting the working tree; and the 'rebase' command will be able to update the working tree with the latest changes. +--preserve-empty-dirs;; + Create a placeholder file in the local Git repository for each + empty directory fetched from Subversion. This includes directories + that become empty by removing all entries in the Subversion + repository (but not the directory itself). The placeholder files + are also tracked and removed when no longer necessary. + +--placeholder-filename=<filename>;; + Set the name of placeholder files created by --preserve-empty-dirs. + Default: ".gitignore" + 'rebase':: This fetches revisions from the SVN parent of the current HEAD and rebases the current (uncommitted to SVN) work against it. @@ -186,18 +189,16 @@ and have no uncommitted changes. last fetched commit from the upstream SVN. 'dcommit':: - Commit each diff from a specified head directly to the SVN + Commit each diff from the current branch 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 revision or branch argument may be specified, and - causes 'git svn' to do all work on that revision/branch - instead of HEAD. - This is advantageous over 'set-tree' (below) because it produces - cleaner, more linear history. ++ +When an optional git branch name (or a git commit object name) +is specified as an argument, the subcommand works on the specified +branch, not on the current branch. ++ +Use of 'dcommit' is preferred to 'set-tree' (below). + --no-rebase;; After committing, do not rebase or reset. @@ -215,6 +216,30 @@ config key: svn.commiturl (overwrites all svn-remote.<name>.commiturl options) Using this option for any other purpose (don't ask) is very strongly discouraged. +--mergeinfo=<mergeinfo>;; + Add the given merge information during the dcommit + (e.g. `--mergeinfo="/branches/foo:1-10"`). All svn server versions can + store this information (as a property), and svn clients starting from + version 1.5 can make use of it. To specify merge information from multiple + branches, use a single space character between the branches + (`--mergeinfo="/branches/foo:1-10 /branches/bar:3,5-6,8"`) ++ +[verse] +config key: svn.pushmergeinfo ++ +This option will cause git-svn to attempt to automatically populate the +svn:mergeinfo property in the SVN repository when possible. Currently, this can +only be done when dcommitting non-fast-forward merges where all parents but the +first have already been pushed into SVN. + +--interactive;; + Ask the user to confirm that a patch set should actually be sent to SVN. + For each patch, one may answer "yes" (accept this patch), "no" (discard this + patch), "all" (accept all patches), or "quit". + + + 'git svn dcommit' returns immediately if answer if "no" or "quit", without + commiting anything to SVN. + 'branch':: Create a branch in the SVN repository. @@ -243,7 +268,7 @@ where <name> is the name of the SVN repository as specified by the -R option to --username;; Specify the SVN username to perform the commit as. This option overrides - configuration property 'username'. + the 'username' configuration property. --commit-url;; Use the specified URL to connect to the destination Subversion @@ -299,7 +324,7 @@ Any other arguments are passed directly to 'git log' 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; + local uncommitted changes in the working tree are ignored; the version of the file in the HEAD revision is annotated. Unknown arguments are passed directly to 'git blame'. + @@ -341,6 +366,8 @@ Any other arguments are passed directly to 'git log' Empty directories are automatically recreated when using "git svn clone" and "git svn rebase", so "mkdirs" is intended for use after commands like "git checkout" or "git reset". + (See the svn-remote.<name>.automkdirs config file option for + more information.) 'commit-diff':: Commits the diff of two tree-ish arguments from the @@ -436,13 +463,13 @@ git rebase --onto remotes/git-svn A^ master OPTIONS ------- ---shared[={false|true|umask|group|all|world|everybody}]:: +--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>:: +-r <arg>:: +--revision <arg>:: Used with the 'fetch' command. + This allows revision ranges for partial/cauterized history @@ -543,6 +570,8 @@ config key: svn.repackflags --merge:: -s<strategy>:: --strategy=<strategy>:: +-p:: +--preserve-merges:: These are only used with the 'dcommit' and 'rebase' commands. + Passed directly to 'git rebase' when using 'dcommit' if a @@ -563,6 +592,17 @@ repository that will be fetched from. For 'branch' and 'tag', display the urls that will be used for copying when creating the branch or tag. +--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-diff', 'set-tree' 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. + ADVANCED OPTIONS ---------------- @@ -597,13 +637,22 @@ 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. +This option can only be used for one-shot imports as 'git svn' +will not be able to fetch again without metadata. Additionally, +if you lose your .git/svn/**/.rev_map.* files, 'git svn' will not +be able to rebuild them. + The 'git svn log' command will not work on repositories using this, either. Using this conflicts with the 'useSvmProps' option for (hopefully) obvious reasons. ++ +This option is NOT recommended as it makes it difficult to track down +old references to SVN revision numbers in existing documentation, bug +reports and archives. If you plan to eventually migrate from SVN to git +and are certain about dropping SVN history, consider +linkgit:git-filter-branch[1] instead. filter-branch also allows +reformatting of metadata for ease-of-reading and rewriting authorship +info for non-"svn.authorsFile" users. svn.useSvmProps:: svn-remote.<name>.useSvmProps:: @@ -637,6 +686,16 @@ svn-remote.<name>.rewriteUUID:: where the original UUID is not available via either useSvmProps or useSvnsyncProps. +svn-remote.<name>.pushurl:: + + Similar to git's 'remote.<name>.pushurl', this key is designed + to be used in cases where 'url' points to an SVN repository + via a read-only transport, to provide an alternate read/write + transport. It is assumed that both keys point to the same + repository. Unlike 'commiturl', 'pushurl' is a base path. If + either 'commiturl' or 'pushurl' could be used, 'commiturl' + takes precedence. + svn.brokenSymlinkWorkaround:: This disables potentially expensive checks to workaround broken symlinks checked into SVN by broken clients. Set this @@ -646,6 +705,20 @@ svn.brokenSymlinkWorkaround:: revision fetched. If unset, 'git svn' assumes this option to be "true". +svn.pathnameencoding:: + This instructs git svn to recode pathnames to a given encoding. + It can be used by windows users and by those who work in non-utf8 + locales to avoid corrupted file names with non-ASCII characters. + Valid encodings are the ones supported by Perl's Encode module. + +svn-remote.<name>.automkdirs:: + Normally, the "git svn clone" and "git svn rebase" commands + attempt to recreate empty directories that are in the + Subversion repository. If this option is set to "false", then + empty directories will only be created if the "git svn mkdirs" + command is run explicitly. If unset, 'git svn' assumes this + option to be "true". + Since the noMetadata, rewriteRoot, rewriteUUID, 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 @@ -712,8 +785,11 @@ have each person clone that repository with 'git clone': cd project git init git remote add origin server:/pub/project - git config --add remote.origin.fetch '+refs/remotes/*:refs/remotes/*' + git config --replace-all remote.origin.fetch '+refs/remotes/*:refs/remotes/*' git fetch +# Prevent fetch/pull from remote git server in the future, +# we only want to use git svn for future updates + git config --remove-section remote.origin # Create a local branch from one of the branches just fetched git checkout -b master FETCH_HEAD # Initialize 'git svn' locally (be sure to use the same URL and -T/-b/-t options as were used on server) @@ -724,23 +800,23 @@ have each person clone that repository with 'git clone': 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 +Prefer to use 'git svn rebase' or 'git rebase', rather than +'git pull' or 'git merge' to synchronize unintegrated commits with a 'git svn' +branch. Doing so will keep the history of unintegrated commits linear with +respect to the upstream SVN repository and allow the use of the preferred +'git svn dcommit' subcommand to push unintegrated commits back into SVN. + +Originally, 'git svn' recommended that developers pulled or merged from +the 'git svn' branch. This was 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 +`git svn set-tree A..B` notation to commit multiple commits. Use of +'git pull' or 'git merge' with `git svn set-tree A..B` will cause non-linear +history to be flattened when committing into SVN and this can lead to merge +commits unexpectedly reversing previous commits in SVN. + +MERGE TRACKING +-------------- +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 @@ -750,16 +826,15 @@ 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 +For the sake of simplicity and interoperating with Subversion, +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 +plan to 'dcommit' from because Subversion users 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. @@ -809,7 +884,7 @@ 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 +renamed and copied files is fully supported if they're similar enough for git to detect them. CONFIGURATION @@ -858,10 +933,6 @@ SEE ALSO -------- linkgit:git-rebase[1] -Author ------- -Written by Eric Wong <normalperson@yhbt.net>. - -Documentation -------------- -Written by Eric Wong <normalperson@yhbt.net>. +GIT +--- +Part of the linkgit:git[1] suite |