Difference between revisions of "Development/Tutorials/Git/git-svn"

Jump to: navigation, search
(git-stash instructions moved)
(massive rewrite based on my own experiences)
Line 1: Line 1:
More and more kde developers are using git-svn to contribute to KDE's SVN repository. Git-svn allows you to create a local git repository based on an existing svn repository. This allows you to use some (but not all) of git's useful features. It's very useful if you want to commit code on an airplane. ;)
+
More and more KDE developers are using git-svn to contribute to KDE's SVN repository. Git-svn allows you to create a local git repository based on an existing svn repository. This allows you to use some (but not all) of git's useful features. It's very useful if you want to commit code on an airplane. ;)
  
<strong>Note:</strong> Please make sure to use Git 1.5.4 or better when you are interfacing with SVN. older versions of git-svn have many issues you might run into otherwise.
+
<strong>Important notes:</strong>
 +
* Please make sure to use Git 1.5.4 or better when you are interfacing with SVN. Older versions of git-svn have many issues you might run into otherwise.
 +
* git-svn is not able to track most of the svn:properties yet. So, svn:externals are not fetched.
  
<strong>Note:</strong> git-svn is not able to track most of the svn:properties yet. So, svn:externals are not fetched.
+
This page explains how to fetch [http://edu.kde.org kdeedu] trunk from and import it into Git. It will then demonstrate how to make use of Git's features and sync with SVN again.
  
Here I'm going to explain to you how to fetch [http://edu.kde.org KDE-EDU]-trunk and import it into Git. I will then demonstrate how to make use of Git's features and sync with SVN again.
+
{{Box|Further reading|If terms like "rebase" and "branch" do not mean anything to you, you should read a tutorial on general Git usage and workflows first, e.g. the [[Development/Tutorials/Git/Basics|Git Basics]] page on this wiki.}}
  
 +
== Checking out ==
 +
 +
The "svn checkout" command becomes:
 
<pre>
 
<pre>
 +
# Anonymous access (if you do not have a KDE SVN account)
 +
git svn init svn://anonsvn.kde.org/home/kde/trunk/KDE/kdeedu
 +
# For those using HTTPS authentication:
 
git svn init https://svn.kde.org/home/kde/trunk/KDE/kdeedu
 
git svn init https://svn.kde.org/home/kde/trunk/KDE/kdeedu
git svn fetch -r798745
+
# For those using SSH authentication:
 +
git svn init svn+ssh://USERNAME@svn.kde.org/home/kde/trunk/KDE/kdeedu
 +
# Further steps which are common to all methods
 +
git svn fetch -r 1000000
 +
git svn fetch
 
</pre>
 
</pre>
 +
Note that, unlike "svn checkout", "git svn init" does not create the directory that contains the checkout. Instead, it behaves similar to "git init": It expects you to create this base directory yourself and call "git svn init" inside this directory.
  
For those who don't have a password set up for https access, or who would rather use the more traditional SSH+SVN approach an alternate initialization line for the git repository (replace USERNAME with your username).
+
The number given to "git svn fetch" on the second-to-last line is the first revision that will be fetched. At this point, the differences between SVN and Git become apparent. While "svn checkout" only reads the current state of the repository, Git wants to read the whole history. But KDE's repository is big. Very big. In fact, it's exorbitantly huge.
  
<pre>
+
To reduce unnecessary load on KDE's server infrastructure, we instruct git-svn to fetch only those revisions that are older than revision no. 1000000, which is a sensible default at the time of this writing (December 2009, current revision ~1060000). The current SVN revision can be found at http://websvn.kde.org (take a look at the line "Directory revision" just below the header). You can also choose exactly the current SVN revision if you're absolutely sure that you will not be needing any history ("git log", "git blame" and Co. might then not behave as expected).
git svn init svn+ssh://USERNAME@svn.kde.org/home/kde/trunk/KDE/kdeedu
+
</pre>
+
 
+
The revision has to be an existing revision of the module (to be found [http://websvn.kde.org/trunk/KDE/ here]).
+
  
To later update (sync with SVN) do:
+
== Updating ==
  
 +
The equivalent to "svn update" becomes:
 
<pre>
 
<pre>
 
git svn rebase
 
git svn rebase
 
</pre>
 
</pre>
 +
You'll usually do this on the master branch. If you're using multiple branches, you might want to rebase them on the master after the update.
  
Now you can start hacking. :)
+
== Commiting ==
Whenever you want you can use this command to push your changes back into KDE's SVN repository:
+
 
 +
{{Box|Work notice|The following two paragraphs are IMHO. Please correct me if my assumptions are wrong. -- [[User:Majewsky|Majewsky]] 22:35, 15 December 2009 (UTC)}}
 +
 
 +
You can only push your changes back into KDE's SVN repository when your checkout is current (run "git svn rebase" if you're not sure) or when you have local, uncommitted changes. If the latter becomes inconvenient, you should use [[Development/Tutorials/Git/Intermediate|git stash]].
 +
 
 +
Usually, you will be working in feature branches. When you want to commit them to SVN, you will rebase them onto master or merge them into master, and then do the following from the master branch:
  
 
<pre>
 
<pre>
Line 33: Line 49:
 
</pre>
 
</pre>
  
Be warned, Git will create one SVN commit for each commit in your Git repository. To create just <b>one</b> commit for the whole merge of a branch into the master branch use the "--squash" feature like this:
+
Git will create one SVN commit for each commit in your Git repository. To create just <b>one</b> commit for the whole merge of a branch into the master branch use the "--squash" feature like this:
  
 
<pre>
 
<pre>
Line 39: Line 55:
 
</pre>
 
</pre>
  
see [[Development/Tutorials/Git/BestPractices]] for guidelines on when to squash.
+
See [[Development/Tutorials/Git/BestPractices]] for guidelines on when to squash.
 
+
Note: git-svn cannot sync with SVN when you have local, uncommited changes. If this becomes inconvenient you should use [[Development/Tutorials/Git/Intermediate|git stash]].
+
 
+
Now that you've got a git-svn repository set up, you can read about [[Development/Tutorials/Git/Basics|Git Basics]].
+

Revision as of 22:35, 15 December 2009

More and more KDE developers are using git-svn to contribute to KDE's SVN repository. Git-svn allows you to create a local git repository based on an existing svn repository. This allows you to use some (but not all) of git's useful features. It's very useful if you want to commit code on an airplane. ;)

Important notes:

  • Please make sure to use Git 1.5.4 or better when you are interfacing with SVN. Older versions of git-svn have many issues you might run into otherwise.
  • git-svn is not able to track most of the svn:properties yet. So, svn:externals are not fetched.

This page explains how to fetch kdeedu trunk from and import it into Git. It will then demonstrate how to make use of Git's features and sync with SVN again.

{{{3}}}
 
If terms like "rebase" and "branch" do not mean anything to you, you should read a tutorial on general Git usage and workflows first, e.g. the Git Basics page on this wiki.
Further reading


Checking out

The "svn checkout" command becomes:

# Anonymous access (if you do not have a KDE SVN account)
git svn init svn://anonsvn.kde.org/home/kde/trunk/KDE/kdeedu
# For those using HTTPS authentication:
git svn init https://svn.kde.org/home/kde/trunk/KDE/kdeedu
# For those using SSH authentication:
git svn init svn+ssh://USERNAME@svn.kde.org/home/kde/trunk/KDE/kdeedu
# Further steps which are common to all methods
git svn fetch -r 1000000
git svn fetch

Note that, unlike "svn checkout", "git svn init" does not create the directory that contains the checkout. Instead, it behaves similar to "git init": It expects you to create this base directory yourself and call "git svn init" inside this directory.

The number given to "git svn fetch" on the second-to-last line is the first revision that will be fetched. At this point, the differences between SVN and Git become apparent. While "svn checkout" only reads the current state of the repository, Git wants to read the whole history. But KDE's repository is big. Very big. In fact, it's exorbitantly huge.

To reduce unnecessary load on KDE's server infrastructure, we instruct git-svn to fetch only those revisions that are older than revision no. 1000000, which is a sensible default at the time of this writing (December 2009, current revision ~1060000). The current SVN revision can be found at http://websvn.kde.org (take a look at the line "Directory revision" just below the header). You can also choose exactly the current SVN revision if you're absolutely sure that you will not be needing any history ("git log", "git blame" and Co. might then not behave as expected).

Updating

The equivalent to "svn update" becomes:

git svn rebase

You'll usually do this on the master branch. If you're using multiple branches, you might want to rebase them on the master after the update.

Commiting

{{{3}}}
 
The following two paragraphs are IMHO. Please correct me if my assumptions are wrong. -- Majewsky 22:35, 15 December 2009 (UTC)
Work notice


You can only push your changes back into KDE's SVN repository when your checkout is current (run "git svn rebase" if you're not sure) or when you have local, uncommitted changes. If the latter becomes inconvenient, you should use git stash.

Usually, you will be working in feature branches. When you want to commit them to SVN, you will rebase them onto master or merge them into master, and then do the following from the master branch:

git svn dcommit

Git will create one SVN commit for each commit in your Git repository. To create just one commit for the whole merge of a branch into the master branch use the "--squash" feature like this:

git merge --squash mybranch

See Development/Tutorials/Git/BestPractices for guidelines on when to squash.


KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal