git-svn: documentation updates
This documents the 'clone' and 'rebase' commands of git-svn. Additionaly, examples are updated to use them instead of the lower-level 'init' and 'fetch' commands. Signed-off-by: Eric Wong <normalperson@yhbt.net>
This commit is contained in:
Eric Wong
parent
e2b36f6018
commit
a81ed0b63e
@ -65,6 +65,32 @@ COMMANDS
|
||||
.git/config file may be specified as an optional command-line
|
||||
argument.
|
||||
|
||||
'clone'::
|
||||
Runs 'init' and 'fetch'. It will automatically create a
|
||||
directory based on the basename of the URL passed to it;
|
||||
or if a second argument is passed; it will create a directory
|
||||
and work within that. It accepts all arguments that the
|
||||
'init' and 'fetch' commands accept; with the exception of
|
||||
'--fetch-all'. After a repository is cloned, the 'fetch'
|
||||
command will be able to update revisions without affecting
|
||||
the working tree; and the 'rebase' command will be able
|
||||
to update the working tree with the latest changes.
|
||||
|
||||
'rebase'::
|
||||
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 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.
|
||||
|
||||
'dcommit'::
|
||||
Commit each diff from a specified head directly to the SVN
|
||||
repository, and then rebase or reset (depending on whether or
|
||||
@ -234,7 +260,7 @@ config key: svn.repackflags
|
||||
-s<strategy>::
|
||||
--strategy=<strategy>::
|
||||
|
||||
These are only used with the 'dcommit' command.
|
||||
These are only used with the 'dcommit' and 'rebase' commands.
|
||||
|
||||
Passed directly to git-rebase when using 'dcommit' if a
|
||||
'git-reset' cannot be used (see dcommit).
|
||||
@ -276,6 +302,11 @@ no longer require this switch as an argument.
|
||||
|
||||
config key: svn.followparent
|
||||
|
||||
--
|
||||
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.
|
||||
@ -301,8 +332,27 @@ svn-remote.<name>.useSvmProps:
|
||||
URL and UUID, and use it when generating metadata in commit
|
||||
messages.
|
||||
|
||||
Using this conflicts with the 'noMetadata' option for
|
||||
(hopefully) obvious reasons.
|
||||
svn.useSvnsyncProps:
|
||||
svn-remote.<name>.useSvnsyncprops:
|
||||
Similar to the useSvmProps option; this is for users
|
||||
of the svnsync(1) command distributed with SVN 1.4.x and
|
||||
later.
|
||||
|
||||
svn-remote.<name>.rewriteRoot
|
||||
This allows users to create repositories from alternate
|
||||
URLs. For example, an administrator could run git-svn on the
|
||||
server locally (accessing via file://) but wish to distribute
|
||||
the repository with a public http:// or svn:// URL in the
|
||||
metadata so users of it will see the public URL.
|
||||
|
||||
|
||||
Since the noMetadata, rewriteRoot, 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
|
||||
and these settings should never be changed once they are set.
|
||||
|
||||
Additionally, only one of these four options can be used per-svn-remote
|
||||
section because they affect the 'git-svn-id:' metadata line.
|
||||
|
||||
--
|
||||
|
||||
@ -312,17 +362,20 @@ Basic Examples
|
||||
Tracking and contributing to a the trunk of a Subversion-managed project:
|
||||
|
||||
------------------------------------------------------------------------
|
||||
# Initialize a repo (like git init):
|
||||
git-svn init http://svn.foo.org/project/trunk
|
||||
# Fetch remote revisions:
|
||||
git-svn fetch
|
||||
# Create your own branch to hack on:
|
||||
git checkout -b my-branch remotes/git-svn
|
||||
# Do some work, and then commit your new changes to SVN, as well as
|
||||
# automatically updating your working HEAD:
|
||||
# Clone a repo (like git clone):
|
||||
git-svn clone http://svn.foo.org/project/trunk
|
||||
# Enter the newly cloned directory:
|
||||
cd trunk
|
||||
# You should be on master branch, double-check with git-branch
|
||||
git branch
|
||||
# Do some work and commit locally to git:
|
||||
git commit ...
|
||||
# Something is committed to SVN, rebase your local changes against the
|
||||
# latest changes in SVN:
|
||||
git-svn rebase
|
||||
# Now commit your changes (that were committed previously using git) to SVN,
|
||||
# as well as automatically updating your working HEAD:
|
||||
git-svn dcommit
|
||||
# Something is committed to SVN, rebase the latest into your branch:
|
||||
git-svn fetch && git rebase remotes/git-svn
|
||||
# Append svn:ignore settings to the default git exclude file:
|
||||
git-svn show-ignore >> .git/info/exclude
|
||||
------------------------------------------------------------------------
|
||||
@ -331,19 +384,15 @@ Tracking and contributing to an entire Subversion-managed project
|
||||
(complete with a trunk, tags and branches):
|
||||
|
||||
------------------------------------------------------------------------
|
||||
# Initialize a repo (like git init):
|
||||
git-svn init http://svn.foo.org/project -T trunk -b branches -t tags
|
||||
# Fetch remote revisions:
|
||||
git-svn fetch
|
||||
# Create your own branch of trunk to hack on:
|
||||
git checkout -b my-trunk remotes/trunk
|
||||
# Do some work, and then commit your new changes to SVN, as well as
|
||||
# automatically updating your working HEAD:
|
||||
git-svn dcommit
|
||||
# Something has been committed to trunk, rebase the latest into your branch:
|
||||
git-svn fetch && git rebase remotes/trunk
|
||||
# Append svn:ignore settings of trunk to the default git exclude file:
|
||||
git-svn show-ignore -i trunk >> .git/info/exclude
|
||||
# Clone a repo (like git clone):
|
||||
git-svn clone http://svn.foo.org/project -T trunk -b branches -t tags
|
||||
# View all branches and tags you have cloned:
|
||||
git branch -r
|
||||
# Reset your master to trunk (or any other branch, replacing 'trunk'
|
||||
# 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.
|
||||
------------------------------------------------------------------------
|
||||
|
||||
REBASE VS. PULL/MERGE
|
||||
@ -356,7 +405,7 @@ pulled or merged from. This is because the author favored
|
||||
|
||||
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 rebase' to update your work branch instead of 'git pull' or
|
||||
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.
|
||||
@ -373,17 +422,15 @@ how 'svn log' works).
|
||||
BUGS
|
||||
----
|
||||
|
||||
We ignore all SVN properties except svn:executable. Too difficult to
|
||||
map them since we rely heavily on git write-tree being _exactly_ the
|
||||
same on both the SVN and git working trees and I prefer not to clutter
|
||||
working trees with metadata files.
|
||||
We ignore all SVN properties except svn:executable. Any unhandled
|
||||
properties are logged to $GIT_DIR/svn/<refname>/unhandled.log
|
||||
|
||||
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). Renamed and
|
||||
copied files are fully supported if they're similar enough for git to
|
||||
detect them.
|
||||
the possible corner cases (git doesn't do it, either). Committing
|
||||
renamed and copied files are fully supported if they're similar enough
|
||||
for git to detect them.
|
||||
|
||||
CONFIGURATION
|
||||
-------------
|
||||
|
||||
Loading…
Reference in New Issue
Block a user