diff options
Diffstat (limited to 'Documentation/git-svn.txt')
| -rw-r--r-- | Documentation/git-svn.txt | 142 |
1 files changed, 84 insertions, 58 deletions
diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index aad452f169..39e9a181cc 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -70,8 +70,8 @@ COMMANDS --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 + transports (e.g. svn+ssh://), you must include the username in + the URL, e.g. 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 @@ -79,8 +79,22 @@ COMMANDS 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. + Setting a prefix (with a trailing slash) is strongly + encouraged in any case, as your SVN-tracking refs will + then be located at "refs/remotes/$prefix/*", which is + compatible with Git's own remote-tracking ref layout + (refs/remotes/$remote/*). Setting a prefix is also useful + if you wish to track multiple projects that share a common + repository. + By default, the prefix is set to 'origin/'. ++ +NOTE: Before Git v2.0, the default prefix was "" (no prefix). This +meant that SVN-tracking refs were put at "refs/remotes/*", which is +incompatible with how Git's own remote-tracking refs are organized. +If you still want the old default, you can get it by passing +`--prefix ""` on the command line (`--prefix=""` may not work if +your Perl's Getopt::Long is < v2.37). + --ignore-paths=<regex>;; When passed to 'init' or 'clone' this regular expression will be preserved as a config key. See 'fetch' for a description @@ -104,19 +118,22 @@ COMMANDS '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. + $GIT_DIR/config file may be specified as an optional + command-line argument. ++ +This automatically updates the rev_map if needed (see +'$GIT_DIR/svn/\*\*/.rev_map.*' in the FILES section below for details). --localtime;; - Store Git commit times in the local timezone instead of UTC. This + Store Git commit times in the local time zone instead of UTC. This makes 'git log' (even without --date=local) show the same times - that `svn log` would in the local timezone. + that `svn log` would in the local time zone. + This doesn't interfere with interoperating with the Subversion repository you cloned from, but if you wish for your local Git repository to be able to interoperate with someone else's local Git repository, either don't use this option or you should both use it in -the same local timezone. +the same local time zone. --parent;; Fetch only from the SVN parent of the current HEAD. @@ -131,8 +148,8 @@ the same local timezone. [verse] config key: svn-remote.<name>.ignore-paths + -If the ignore-paths config key is set and the command line option is -also given, both regular expressions will be used. +If the ignore-paths configuration key is set, and the command-line +option is also given, both regular expressions will be used. + Examples: + @@ -159,11 +176,11 @@ Skip "branches" and "tags" of first level directories;; precedence over '--include-paths'. --log-window-size=<n>;; - Fetch <n> log entries per request when scanning Subversion history. - The default is 100. For very large Subversion repositories, larger - values may be needed for 'clone'/'fetch' to complete in reasonable - time. But overly large values may lead to higher memory usage and - request timeouts. + Fetch <n> log entries per request when scanning Subversion history. + The default is 100. For very large Subversion repositories, larger + values may be needed for 'clone'/'fetch' to complete in reasonable + time. But overly large values may lead to higher memory usage and + request timeouts. 'clone':: Runs 'init' and 'fetch'. It will automatically create a @@ -201,6 +218,9 @@ accept. However, '--fetch-all' only fetches from the current + Like 'git rebase'; this requires that the working tree be clean and have no uncommitted changes. ++ +This automatically updates the rev_map if needed (see +'$GIT_DIR/svn/\*\*/.rev_map.*' in the FILES section below for details). -l;; --local;; @@ -232,6 +252,10 @@ Use of 'dcommit' is preferred to 'set-tree' (below). config key: svn-remote.<name>.commiturl config key: svn.commiturl (overwrites all svn-remote.<name>.commiturl options) + +Note that the SVN URL of the commiturl config key includes the SVN branch. +If you rather want to set the commit URL for an entire SVN repository use +svn-remote.<name>.pushurl instead. ++ Using this option for any other purpose (don't ask) is very strongly discouraged. @@ -256,7 +280,7 @@ first have already been pushed into 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 + 'git svn dcommit' returns immediately if answer is "no" or "quit", without committing anything to SVN. 'branch':: @@ -347,12 +371,12 @@ 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 tree are ignored; - the version of the file in the HEAD revision is annotated. Unknown - arguments are passed directly to 'git 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 tree 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 @@ -366,11 +390,13 @@ Any other arguments are passed directly to 'git log' tree-ish to specify which branch should be searched). When given a tree-ish, returns the corresponding SVN revision number. + +-B;; --before;; Don't require an exact match if given an SVN revision, instead find the commit corresponding to the state of the SVN repository (on the current branch) at the specified revision. + +-A;; --after;; Don't require an exact match if given an SVN revision; if there is not an exact match return the closest match searching forward in the @@ -435,8 +461,8 @@ Any other arguments are passed directly to 'git log' specific revision. 'gc':: - Compress $GIT_DIR/svn/<refname>/unhandled.log files in .git/svn - and remove $GIT_DIR/svn/<refname>index files in .git/svn. + Compress $GIT_DIR/svn/<refname>/unhandled.log files and remove + $GIT_DIR/svn/<refname>/index files. 'reset':: Undoes the effects of 'fetch' back to the specified revision. @@ -449,9 +475,10 @@ Any other arguments are passed directly to 'git log' file cannot be ignored forever (with --ignore-paths) the only way to repair the repo is to use 'reset'. + -Only the rev_map and refs/remotes/git-svn are changed. Follow 'reset' -with a 'fetch' and then 'git reset' or 'git rebase' to move local -branches onto the new tree. +Only the rev_map and refs/remotes/git-svn are changed (see +'$GIT_DIR/svn/\*\*/.rev_map.*' in the FILES section below for details). +Follow 'reset' with a 'fetch' and then 'git reset' or 'git rebase' to +move local branches onto the new tree. -r <n>;; --revision=<n>;; @@ -587,21 +614,6 @@ config key: svn.authorsfile Make 'git svn' less verbose. Specify a second time to make it even 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>:: @@ -684,7 +696,7 @@ svn-remote.<name>.noMetadata:: + 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 +if you lose your '$GIT_DIR/svn/\*\*/.rev_map.*' files, 'git svn' will not be able to rebuild them. + The 'git svn log' command will not work on repositories using @@ -804,16 +816,16 @@ Tracking and contributing to an entire Subversion-managed project ------------------------------------------------------------------------ # Clone a repo with standard SVN directory layout (like git clone): - git svn clone http://svn.example.com/project --stdlayout + git svn clone http://svn.example.com/project --stdlayout --prefix svn/ # Or, if the repo uses a non-standard directory layout: - git svn clone http://svn.example.com/project -T tr -b branch -t tag + git svn clone http://svn.example.com/project -T tr -b branch -t tag --prefix svn/ # View all branches and tags you have cloned: git branch -r # Create a new branch in SVN - git svn branch waldo + git svn branch waldo # Reset your master to trunk (or any other branch, replacing 'trunk' # with the appropriate name): - git reset --hard remotes/trunk + git reset --hard svn/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. ------------------------------------------------------------------------ @@ -827,7 +839,7 @@ 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.example.com/project + ssh server "cd /pub && git svn clone http://svn.example.com/project [options...]" # Clone locally - make sure the refs/remotes/ space matches the server mkdir project cd project @@ -840,8 +852,9 @@ have each person clone that repository with 'git clone': 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) - git svn init http://svn.example.com/project +# Initialize 'git svn' locally (be sure to use the same URL and +# --stdlayout/-T/-b/-t/--prefix options as were used on server) + git svn init http://svn.example.com/project [options...] # Pull the latest changes from Subversion git svn rebase ------------------------------------------------------------------------ @@ -977,8 +990,8 @@ When using multiple --branches or --tags, 'git svn' does not automatically handle name collisions (for example, if two branches from different paths have the same name, or if a branch and a tag have the same name). In these cases, use 'init' to set up your Git repository then, before your first 'fetch', edit -the .git/config file so that the branches and tags are associated with -different name spaces. For example: +the $GIT_DIR/config file so that the branches and tags are associated +with different name spaces. For example: branches = stable/*:refs/remotes/svn/stable/* branches = debug/*:refs/remotes/svn/debug/* @@ -1006,7 +1019,7 @@ CONFIGURATION ------------- 'git svn' stores [svn-remote] configuration information in the -repository .git/config file. It is similar the core Git +repository $GIT_DIR/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 @@ -1035,8 +1048,8 @@ comma-separated list of names within braces. For example: [svn-remote "huge-project"] url = http://server.org/svn fetch = trunk/src:refs/remotes/trunk - branches = branches/{red,green}/src:refs/remotes/branches/* - tags = tags/{1.0,2.0}/src:refs/remotes/tags/* + branches = branches/{red,green}/src:refs/remotes/project-a/branches/* + tags = tags/{1.0,2.0}/src:refs/remotes/project-a/tags/* ------------------------------------------------------------------------ Multiple fetch, branches, and tags keys are supported: @@ -1060,8 +1073,21 @@ $ git svn branch -d branches/server release-2-3-0 Note that git-svn keeps track of the highest revision in which a branch or tag has appeared. If the subset of branches or tags is changed after -fetching, then .git/svn/.metadata must be manually edited to remove (or -reset) branches-maxRev and/or tags-maxRev as appropriate. +fetching, then $GIT_DIR/svn/.metadata must be manually edited to remove +(or reset) branches-maxRev and/or tags-maxRev as appropriate. + +FILES +----- +$GIT_DIR/svn/\*\*/.rev_map.*:: + Mapping between Subversion revision numbers and Git commit + names. In a repository where the noMetadata option is not set, + this can be rebuilt from the git-svn-id: lines that are at the + end of every commit (see the 'svn.noMetadata' section above for + details). ++ +'git svn fetch' and 'git svn rebase' automatically update the rev_map +if it is missing or not up to date. 'git svn reset' automatically +rewinds it. SEE ALSO -------- |