user-manual: use pithier example commit
[gitweb.git] / Documentation / git-svn.txt
index cf094ca357758d147c9ab7684ef5abc7d15a50ef..c0d7d9597b8f569a1e996072bef667f517e74bd2 100644 (file)
@@ -38,32 +38,30 @@ COMMANDS
        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>::
+-T<trunk_subdir>;;
+--trunk=<trunk_subdir>;;
+-t<tags_subdir>;;
+--tags=<tags_subdir>;;
+-b<branches_subdir>;;
+--branches=<branches_subdir>;;
        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::
+--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=<URL>::
+--rewrite-root=<URL>;;
        Set the 'rewriteRoot' 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
        the URL, eg svn+ssh://foo@svn.bar.com/project
-
---prefix=<prefix>
+--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
@@ -73,7 +71,6 @@ COMMANDS
        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 +91,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 dcommit-ing 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 +119,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=<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
+--
++
+Any other arguments are passed directly to `git log'
 
-       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
-
-       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 +278,18 @@ config key: svn.authorsfile
        Make git-svn less verbose.
 
 --repack[=<n>]::
---repack-flags=<flags>
-       These should help keep disk usage sane for large fetches
-       with many revisions.
+--repack-flags=<flags>::
 
-       --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.
+These should help keep disk usage sane for large fetches
+with many revisions.
 
-       --repack-flags are passed directly to gitlink:git-repack[1].
+--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].
+
+[verse]
 config key: svn.repack
 config key: svn.repackflags
 
@@ -323,28 +347,30 @@ 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.
+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.<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.
+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::
@@ -369,8 +395,8 @@ 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:
 
@@ -405,7 +431,7 @@ Tracking and contributing to an entire Subversion-managed project
 # 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 teh same as above.
+# of dcommit/rebase/show-ignore should be the same as above.
 ------------------------------------------------------------------------
 
 REBASE VS. PULL/MERGE