X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=Documentation%2Fgit-svn.txt;h=488e4b1caf8097de4ab53bf89a03f80173a2cf52;hb=beb474379315654566e78eea8a0e39c66ebcbb8a;hp=87161aedd19bb7bebd0621fda6c381f9a936b7f5;hpb=20f50f1670c18173d74a34527b0c538c3fbbfde3;p=git.git diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 87161aedd..488e4b1ca 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -38,42 +38,45 @@ COMMANDS argument. Normally this command initializes the current directory. --T:: ---trunk=:: --t:: ---tags=:: --b:: ---branches=:: +-T;; +--trunk=;; +-t;; +--tags=;; +-b;; +--branches=;; +-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) - ---no-metadata:: + (--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:: +--use-svm-props;; Set the 'useSvmProps' option in the [svn-remote] config. ---use-svnsync-props:: +--use-svnsync-props;; Set the 'useSvnsyncProps' option in the [svn-remote] config. ---rewrite-root=:: +--rewrite-root=;; Set the 'rewriteRoot' option in the [svn-remote] config. ---username=:: +--username=;; 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. This is useful if - you wish to track multiple projects that share a common - repository. + 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 @@ -94,16 +97,21 @@ COMMANDS 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 dcommit-ing with git-svn. +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' +accepts. However '--fetch-all' only fetches from the current +[svn-remote], and not all [svn-remote] definitions. - This accepts all options that 'git-svn fetch' and 'git-rebase' - accepts. 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. - 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 @@ -117,28 +125,48 @@ COMMANDS 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=[:];; + 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=;; + 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 +-- ++ +Any other arguments are passed directly to `git log' - The following features from `svn log' are supported: - - --revision=[:] - 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= - 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 - - Any other arguments are passed directly to `git log' +-- +'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. @@ -256,16 +284,18 @@ config key: svn.authorsfile Make git-svn less verbose. --repack[=]:: ---repack-flags= - These should help keep disk usage sane for large fetches - with many revisions. +--repack-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 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 gitlink:git-repack[1]. +--repack-flags are passed directly to gitlink:git-repack[1]. +[verse] config key: svn.repack config key: svn.repackflags @@ -323,28 +353,30 @@ CONFIG FILE-ONLY OPTIONS svn.noMetadata:: svn-remote..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 gets rid of the git-svn-id: lines at the end of every commit. - The 'git-svn log' command will not work on repositories using - this, either. Using this conflicts with the 'useSvmProps' - option for (hopefully) obvious reasons. +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..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. +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..useSvnsyncprops:: @@ -369,10 +401,10 @@ section because they affect the 'git-svn-id:' metadata line. -- -Basic Examples -~~~~~~~~~~~~~~ +BASIC EXAMPLES +-------------- -Tracking and contributing to a the trunk of a Subversion-managed project: +Tracking and contributing to the trunk of a Subversion-managed project: ------------------------------------------------------------------------ # Clone a repo (like git clone): @@ -408,6 +440,26 @@ Tracking and contributing to an entire Subversion-managed project # 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 + git clone server:/pub/project +# Tell git-svn which branch contains the Subversion commits + git update-ref refs/remotes/git-svn origin/master +# 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 --------------------- @@ -426,11 +478,44 @@ previous commits in SVN. DESIGN PHILOSOPHY ----------------- Merge tracking in Subversion is lacking and doing branched development -with Subversion is cumbersome as a result. git-svn does not do -automated merge/branch tracking by default and leaves it entirely up to -the user on the git side. git-svn does however follow copy -history of the directory that it is tracking, however (much like -how 'svn log' works). +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 dcommiting 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(1) 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 git-push(1) documentation for details. + +Do not use the --amend option of 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 ---- @@ -465,9 +550,9 @@ listed below are allowed: ------------------------------------------------------------------------ Keep in mind that the '*' (asterisk) wildcard of the local ref -(left of the ':') *must* be the farthest right path component; +(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 componet (surrounded by '/' or EOL). This +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 gitlink:git-config[1]