Projects/MoveToGit/UsingSvn2Git: Difference between revisions

    From KDE TechBase
    (→‎How rulesets work: add some explanations on the format of rules.)
    Line 17: Line 17:


    === How rulesets work ===
    === How rulesets work ===
    The format for the svn2git rules is pretty simple. First and foremost you
    have to declare some repositories:
    <pre>
    create repository kdelibs
    end repository
    </pre>
    This tells svn2git that it should create a git repository called "kdelibs" that we can later on use to put commits into it.
    The rest of the file are rules matching specific paths in Subversion, each rule
    specifies what to do with the commits that appeared at the given path. The
    possible actions are ignoring them or adding them to a particular branch in a particular repository. '''Note:''' Ignoring is done by simply leaving out the information about the repository and the branch.
    As examples are more explanatory, the following rule would put all commits from 123453 to 456789 from the path /trunk/KDE/kdelibs into the master branch of
    the kdelibs repository:
    <pre>
    match /trunk/KDE/kdelibs/
      min revision 123453
      max revision 456789
      repository kdelibs
      branch master
    end match
    </pre>
    The min and max revision are useful in cases where the same path in SVN contains
    code for different branches. An example would be KDevelop3, where KDevelop 3.3 was shipped with KDE 3.5 until 3.5.7, 3.5.8 contained KDevelop 3.4 and 3.5.9 contained KDevelop 3.5 and all of those kdevelop versions are now under /branches/KDE/3.5/kdevelop.
    The two revision parameters are however not mandatory, if they're left out, then all commits that went to the given matching path in SVN are taken over into the specified branch.
    To generate tags with git you use a special format for the branch parameter: refs/tag/<tagname>. So to put all commits from /tags/KDE/4.4.0/kdelibs into the v4.4.0 tag in the kdelibs git repository the rule would be like this:
    <pre>
    match /tags/KDE/4.4.0/kdelibs/
      repository kdelibs
      branch refs/tags/v4.4.0
    end match
    </pre>
    For more examples see the svn2git/samples/ directory and the rules in the kde-ruleset repository.
    '''TODO''': Add some information how the recurse-stuff works.
    ==== Important Details ====
    * All matching rules need to end with a '/', else the tool will crash at some point. This is a known bug. The only exception are the rules using the recurse-action.
    * The rules form an ordered list that the tool goes through while matching the changed paths for each commit. So if two rules match the same path and neither of the two has more matching criteria, then the rule that is written further up in the file wins. This is useful to exclude certain commits from the extraction process, if you look at the existing kde ruleset  you'll notice that at the top some revisions are ignored.


    === Setting up your system ===
    === Setting up your system ===

    Revision as of 21:00, 2 March 2010

    This page documents how to go about getting a KDE module ready for the Great Git Migration of 2010.

    Getting the tools

    The necessary tools are hosted at http://www.gitorious.org/svn2git. To get started do:

    git clone git://gitorious.org/svn2git/svn2git.git git clone git://gitorious.org/svn2git/kde-ruleset.git

    This will get you the source code to build svn2git and the KDE ruleset files as they currently exist. Build the svn2git tool before moving on to the next step.

    Building svn2git

    Make sure you have Qt4 installed, then simply issue qmake && make to build the executable called "svn-all-fast-export"

    How rulesets work

    The format for the svn2git rules is pretty simple. First and foremost you have to declare some repositories:

    create repository kdelibs
    end repository
    

    This tells svn2git that it should create a git repository called "kdelibs" that we can later on use to put commits into it.

    The rest of the file are rules matching specific paths in Subversion, each rule specifies what to do with the commits that appeared at the given path. The possible actions are ignoring them or adding them to a particular branch in a particular repository. Note: Ignoring is done by simply leaving out the information about the repository and the branch.

    As examples are more explanatory, the following rule would put all commits from 123453 to 456789 from the path /trunk/KDE/kdelibs into the master branch of the kdelibs repository:

    match /trunk/KDE/kdelibs/
      min revision 123453
      max revision 456789
      repository kdelibs
      branch master
    end match
    

    The min and max revision are useful in cases where the same path in SVN contains code for different branches. An example would be KDevelop3, where KDevelop 3.3 was shipped with KDE 3.5 until 3.5.7, 3.5.8 contained KDevelop 3.4 and 3.5.9 contained KDevelop 3.5 and all of those kdevelop versions are now under /branches/KDE/3.5/kdevelop.

    The two revision parameters are however not mandatory, if they're left out, then all commits that went to the given matching path in SVN are taken over into the specified branch.

    To generate tags with git you use a special format for the branch parameter: refs/tag/<tagname>. So to put all commits from /tags/KDE/4.4.0/kdelibs into the v4.4.0 tag in the kdelibs git repository the rule would be like this:

    match /tags/KDE/4.4.0/kdelibs/
      repository kdelibs
      branch refs/tags/v4.4.0
    end match
    

    For more examples see the svn2git/samples/ directory and the rules in the kde-ruleset repository.

    TODO: Add some information how the recurse-stuff works.

    Important Details

    • All matching rules need to end with a '/', else the tool will crash at some point. This is a known bug. The only exception are the rules using the recurse-action.
    • The rules form an ordered list that the tool goes through while matching the changed paths for each commit. So if two rules match the same path and neither of the two has more matching criteria, then the rule that is written further up in the file wins. This is useful to exclude certain commits from the extraction process, if you look at the existing kde ruleset you'll notice that at the top some revisions are ignored.

    Setting up your system

    You will need ~60GB (is that correct?) of disk space to get started, as the process requires a copy of the KDE svn database. There is a script that will download this for you (and which can be used to update it periodically using rsync) in kde-ruleset/bin/startSync. By default the startSync script runs rsync in "dry run" mode, so before using it to actually get the svn database edit the startSync script and remove the -n from both rsync lines.

    more stuff goes here ...

    Testing a module

    • Step 1
    • ..
    • Profit! aka "How do I know I've succeeded or failed"
    • How to report findings
    • How to fix issues one comes across while testing