From: Junio C Hamano Date: Wed, 30 Oct 2013 19:10:34 +0000 (-0700) Subject: Merge branch 'sb/git-svn-docs-indent-with-ht' X-Git-Tag: v1.8.5-rc0~8 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/02882bc8344b851f7f371905678bb5c88b8eaea6?ds=inline;hp=-c Merge branch 'sb/git-svn-docs-indent-with-ht' * sb/git-svn-docs-indent-with-ht: git-svn docs: Use tabs consistently within the ascii doc --- 02882bc8344b851f7f371905678bb5c88b8eaea6 diff --combined Documentation/git-svn.txt index 2a3847649d,e801f2cafb..dcad890616 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@@ -79,21 -79,8 +79,21 @@@ COMMAND 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. ++ +NOTE: In Git v2.0, the default prefix will CHANGE from "" (no prefix) +to "origin/". This is done to put SVN-tracking refs at +"refs/remotes/origin/*" instead of "refs/remotes/*", and make them +more compatible with how Git's own remote-tracking refs are organized +(i.e. refs/remotes/$remote/*). You can enjoy the same benefits today, +by using the --prefix option. + --ignore-paths=;; When passed to 'init' or 'clone' this regular expression will be preserved as a config key. See 'fetch' for a description @@@ -117,11 -104,8 +117,11 @@@ '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 @@@ -175,11 -159,11 +175,11 @@@ Skip "branches" and "tags" of first lev precedence over '--include-paths'. --log-window-size=;; - Fetch 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 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 @@@ -217,9 -201,6 +217,9 @@@ accept. However, '--fetch-all' only fe + 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;; @@@ -275,7 -256,7 +275,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 is "no" or "quit", without + 'git svn dcommit' returns immediately if answer is "no" or "quit", without committing anything to SVN. 'branch':: @@@ -366,12 -347,12 +366,12 @@@ environment). This command has the sam 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 @@@ -454,8 -435,8 +454,8 @@@ specific revision. 'gc':: - Compress $GIT_DIR/svn//unhandled.log files in .git/svn - and remove $GIT_DIR/svn/index files in .git/svn. + Compress $GIT_DIR/svn//unhandled.log files and remove + $GIT_DIR/svn//index files. 'reset':: Undoes the effects of 'fetch' back to the specified revision. @@@ -468,10 -449,9 +468,10 @@@ 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 ;; --revision=;; @@@ -704,7 -684,7 +704,7 @@@ svn-remote..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 @@@ -824,16 -804,16 +824,16 @@@ Tracking and contributing to an entire ------------------------------------------------------------------------ # 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. ------------------------------------------------------------------------ @@@ -847,7 -827,7 +847,7 @@@ have each person clone that repository ------------------------------------------------------------------------ # 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 @@@ -860,9 -840,8 +860,9 @@@ 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 ------------------------------------------------------------------------ @@@ -994,22 -973,12 +994,22 @@@ without giving any repository layout op branches and tags is required, the options '--trunk' / '--branches' / '--tags' must be used. +When using the options for describing the repository layout (--trunk, +--tags, --branches, --stdlayout), please also specify the --prefix +option (e.g. '--prefix=origin/') to cause your SVN-tracking refs to be +placed at refs/remotes/origin/* rather than the default refs/remotes/*. +The former is more compatible with the layout of Git's "regular" +remote-tracking refs (refs/remotes/$remote/*), and may potentially +prevent similarly named SVN branches and Git remotes from clobbering +each other. In Git v2.0 the default prefix used (i.e. when no --prefix +is given) will change from "" (no prefix) to "origin/". + 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/* @@@ -1037,7 -1006,7 +1037,7 @@@ CONFIGURATIO ------------- '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 @@@ -1066,8 -1035,8 +1066,8 @@@ comma-separated list of names within br [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: @@@ -1091,21 -1060,8 +1091,21 @@@ $ git svn branch -d branches/server rel 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 --------