README.markdown in nirvdrum-svn2git-1.2.4 vs README.markdown in nirvdrum-svn2git-1.3.0

@@ -11,54 +11,54 @@
 Examples
 --------
 
 Say I have this code in svn:
 
-  trunk
-    ...
-  branches
-    1.x
-    2.x
-  tags
-    1.0.0
-    1.0.1
-    1.0.2
-    1.1.0
-    2.0.0
+    trunk
+      ...
+    branches
+      1.x
+      2.x
+    tags
+      1.0.0
+      1.0.1
+      1.0.2
+      1.1.0
+      2.0.0
 
 git-svn will go through the commit history to build a new git repo. It will
 import all branches and tags as remote svn branches, whereas what you really
 want is git-native local branches and git tag objects. So after importing this
 project I'll get:
 
-  $ git branch
-  * master
-  $ git branch -a
-  * master
-    1.x
-    2.x
-    tags/1.0.0
-    tags/1.0.1
-    tags/1.0.2
-    tags/1.1.0
-    tags/2.0.0
-    trunk
-  $ git tag -l
-  [ empty ]
+    $ git branch
+    * master
+    $ git branch -a
+    * master
+      1.x
+      2.x
+      tags/1.0.0
+      tags/1.0.1
+      tags/1.0.2
+      tags/1.1.0
+      tags/2.0.0
+      trunk
+    $ git tag -l
+    [ empty ]
 
 After svn2git is done with your project, you'll get this instead:
 
-  $ git branch
-  * master
-    1.x
-    2.x
-  $ git tag -l
-    1.0.0
-    1.0.1
-    1.0.2
-    1.1.0
-    2.0.0
+    $ git branch
+    * master
+      1.x
+      2.x
+    $ git tag -l
+      1.0.0
+      1.0.1
+      1.0.2
+      1.1.0
+      2.0.0
 
 Finally, it makes sure the HEAD of master is the same as the current trunk of
 the svn repo.
 
 Installation
@@ -78,54 +78,54 @@
 create a git repo from a svn repo in the specified layout.
 
 1. The svn repo is in the standard layout of (trunk, branches, tags) at the
 root level of the repo.
 
-    $ svn2git http://svn.yoursite.com/path/to/repo --trunk trunk --branches branches --tags tags
+        $ svn2git http://svn.example.com/path/to/repo
 
 2. The svn repo is NOT in standard layout and has only a trunk and tags at the
 root level of the repo.
 
-    $ svn2git http://svn.yoursite.com/path/to/repo --trunk trunk --tags tags
+        $ svn2git http://svn.example.com/path/to/repo --trunk dev --tags rel --nobranches
 
-3. The svn repo is NOT in standard layout and has only a trunk and branches at
-the root level of the repo.
-
-    $ svn2git http://svn.yoursite.com/path/to/repo --trunk trunk --branches branches
-
-4. The svn repo is NOT in standard layout and has only a trunk at the root
+3. The svn repo is NOT in standard layout and has only a trunk at the root
 level of the repo.
 
-    $ svn2git http://svn.yoursite.com/path/to/repo --trunk trunk
+        $ svn2git http://svn.example.com/path/to/repo --trunk trunk --nobranches --notags
 
-5. The svn repo is NOT in standard layout and has no trunk, branches, or tags
+4. The svn repo is NOT in standard layout and has no trunk, branches, or tags
 at the root level of the repo. Instead the root level of the repo is
 equivalent to the trunk and there are no tags or branches.
 
-    $ svn2git http://svn.yoursite.com/path/to/repo --rootistrunk
+        $ svn2git http://svn.example.com/path/to/repo --rootistrunk
 
+5. The svn repo is in the standard layout but you want to exclude the massive
+doc directory and the backup files you once accidently added.
+
+        $ svn2git http://svn.example.com/path/to/repo --exclude doc --exclude '.*~$'
+
 The above will create a git repository in the current directory with the git
 version of the svn repository. Hence, you need to make a directory that you
 want your new git repo to exist in, change into it and then run one of the
 above commands. Note that in the above cases the trunk, branches, tags options
 are simply folder names relative to the provided repo path. For example if you
 specified trunk=foo branches=bar and tags=foobar it would be referencing
-http://svn.yoursite.com/path/to/repo/foo as your trunk, and so on. However, in
-case 5 it references the root of the repo as trunk.
+http://svn.example.com/path/to/repo/foo as your trunk, and so on. However, in
+case 4 it references the root of the repo as trunk.
 
 Authors
 -------
 
 To convert all your svn authors to git format, create a file somewhere on your
 system with the list of conversions to make, one per line, for example:
 
-  jcoglan = James Coglan <[e-mail]>
-  stnick = Santa Claus <[e-mail]>
+    jcoglan = James Coglan <[e-mail]>
+    stnick = Santa Claus <[e-mail]>
 
 Then pass an +authors+ option to +svn2git+ pointing to your file:
 
-  svn2git http://repos.com/myproject --authors ~/authors.txt
+    $ svn2git http://svn.example.com/path/to/repo --authors ~/authors.txt
 
 Alternatively, you can place the authors file into ~/.svn2git/authors and
 svn2git will load it out of there. This allows you to build up one authors
 file for all your projects and have it loaded for each repository that you
 migrate.
@@ -137,6 +137,36 @@
 try turning on verbose logging.  This will print out more information from the
 underlying git-svn process.
 
 You can turn on verbose logging with the '-v' or '--verbose' flags, like so:
 
-  $ svn2git http://svn.yoursite.com/path/to/repo --verbose
+    $ svn2git http://svn.yoursite.com/path/to/repo --verbose
+
+FAQ
+---
+
+1. Why don't the tags show up in the master branch?
+
+    The tags won't show up in the master branch because the tags are actually
+    tied to the commits that were created in svn when the user made the tag.
+    Those commits are the first (head) commit of branch in svn that is
+    associated with that tag. If you want to see all the branches and tags
+    and their relationships in gitk you can run the following: gitk --all
+    
+    For further details please refer to FAQ #2.
+    
+2. Why don't you reference the parent of the tag commits instead?
+
+    In svn you are forced to create what are known in git as annotated tags.
+    It just so happens that svn annotated tags allow you to commit change
+    sets along with the tagging action. This means that the svn annotated tag
+    is a bit more complex then just an annotated tag it is a commit which is
+    treated as an annotated tag. Hence, for there to be a true 1-to-1 mapping
+    between git and svn we have to transfer over the svn commit which acts as
+    an annotated tag and then tag that commit in git using an annotated tag.
+    
+    If we were to reference the parent of this svn tagged commit there could
+    potentially be situations where a developer would checkout a tag in git
+    and the resulting code base would be different then if they checked out
+    that very same tag in the original svn repo. This is only due to the fact
+    that the svn tags allow changesets in them, making them not just annotated
+    tags.
\ No newline at end of file