You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@poi.apache.org by ce...@apache.org on 2016/06/30 21:19:52 UTC
svn commit: r1750865 - in /poi/site: publish/subversion.html
src/documentation/content/xdocs/subversion.xml
Author: centic
Date: Thu Jun 30 21:19:52 2016
New Revision: 1750865
URL: http://svn.apache.org/viewvc?rev=1750865&view=rev
Log:
Add a section about how to use Git-svn to develop in Git locally while still sending changes to SVN as multiple people were interested in this. This way we have a ready-made description of this to hand out. This can be moved elsewhere in Apache land later on if it proves to be useful to others as well.
Modified:
poi/site/publish/subversion.html
poi/site/src/documentation/content/xdocs/subversion.xml
Modified: poi/site/publish/subversion.html
URL: http://svn.apache.org/viewvc/poi/site/publish/subversion.html?rev=1750865&r1=1750864&r2=1750865&view=diff
==============================================================================
--- poi/site/publish/subversion.html (original)
+++ poi/site/publish/subversion.html Thu Jun 30 21:19:52 2016
@@ -367,6 +367,177 @@ if (VERSION > 3) {
information on getting involved in the project.</p>
+<a name="Using+Git+via+the+SVN-Git+bridge"></a>
+<div class="h3">
+<h3>Using Git via the SVN-Git bridge</h3>
+</div>
+
+<a name="General+information"></a>
+<div class="h4">
+<h4>General information</h4>
+</div>
+
+<p>
+ Git provides a nice functionality "git-svn" which allows to read the history
+ of a Subversion repository and convert it into a full Git repository. This
+ will keep information from the SVN revisions so that the Git repository can
+ be updated with newer revisions from Subversion as well as allowing to push
+ commits from Git "upstream" into the Subversion repository. See the
+ <a href="https://www.kernel.org/pub/software/scm/git/docs/git-svn.html">
+ official documentation</a> for more details.
+ </p>
+
+
+<a name="Set+up+the+repository"></a>
+<div class="h4">
+<h4>Set up the repository</h4>
+</div>
+
+<p>
+ The git-svn functionality is provided as a set of sub-commands to
+ "git svn". To start retrieving information from SVN and create the
+ initial Git repository run the following command:
+
+ </p>
+
+<pre class="code">
+ git svn clone https://svn.apache.org/repos/asf/poi/trunk poisvngit
+ </pre>
+
+<p>
+ This will run for a long time and will retrieve the full version history of
+ the Subversion repository.
+
+ If you would like to speed this up you can restrict the Git repository to a
+ certain range of SVN revisions via
+ <span class="codefrag">--revision from:HEAD</span>.
+ </p>
+
+<p>
+ When this finishes you have a Git repository whose "master" branch
+ mirrors the SVN "trunk".
+ <br>
+ From here you can use the full power of Git, i.e. quick branching,
+ rebasing, merging, ...
+ <br>
+ See below for some common usage hints.
+ </p>
+
+
+<a name="Fetching+newer+SVN+revisions"></a>
+<div class="h4">
+<h4>Fetching newer SVN revisions</h4>
+</div>
+
+<p>
+ In order to fetch the latest SVN revisions, you need to "rebase" onto
+ the SVN trunk:
+ </p>
+
+<pre class="code">
+ git checkout master
+ git svn rebase
+ </pre>
+
+<p>
+ This will fetch the latest changes from Subversion and will rebase
+ the master-branch onto them.
+ </p>
+
+
+<a name="Pushing+Git+commits+to+Subversion"></a>
+<div class="h4">
+<h4>Pushing Git commits to Subversion</h4>
+</div>
+
+<p>
+ The following command will push all changes on <span class="codefrag">master</span> back to
+ Subversion:
+ </p>
+
+<pre class="code">
+ git svn dcommit
+ </pre>
+
+<p>
+ Note that usually all commits on master will be sent to Subversion
+ in one go, so it's similar to a "push" to another Git repository.
+
+ The dcommit may fail if there are newer revisions in Subversion, you
+ will need to run a <span class="codefrag">git svn rebase</span> first in this case.
+ </p>
+
+
+<a name="General+usage+guidelines"></a>
+<div class="h4">
+<h4>General usage guidelines</h4>
+</div>
+
+<p>
+ Although you can use the full power of Git, there are a few
+ things that work well and some things that will get you into
+ trouble:
+ </p>
+
+<p>
+ You should not develop on master, rather use some branching
+ concept where you do work on sub-branches and only merge/cherry-pick the
+ changes that are ready for being sent upstream.
+ It seems to work better to constantly rebase changes onto the
+ master branch as this will keep the history clean compared to
+ the SVN repository and will avoid sending useless "Merge" commits to
+ Subversion.
+ </p>
+
+<p>
+ You can keep some changes that are only useful locally by using
+ two branches that are rebased onto each other. E.g.
+ something like the following has proven to work well:
+ </p>
+
+<pre class="code">
+ master
+ -> localchanges - commits that should not be sent upstream ->
+ -> workbranch - place for doing development work
+ </pre>
+
+<p>
+ When things are ready in the workbranch do a
+ </p>
+
+<pre class="code">
+ git co master
+ git cherry-pick commitid ...
+ </pre>
+
+<p>
+ to get all the finished commits onto master as preparation for pushing them upstream.
+
+ Then you can <span class="codefrag">git svn dcommit</span> to send the changes upstream
+ and a <span class="codefrag">git svn rebase</span> to get master updated with the newly
+ created SVN revisions.
+
+ Finally do the following to update both branches onto the new SVN head
+ </p>
+
+<pre class="code">
+ # rebase you local changes onto the latest SVN state
+ git checkout localchanges
+ git rebase master
+
+ # also set the working branch to the latest state from SVN.
+ git checkout workbranch
+ git rebase workbranch
+ </pre>
+
+<p>
+ Sounds like too much work? Put these steps into a small script and all
+ this will become a simple <span class="codefrag">poiupdate</span> to get all branches
+ rebased onto HEAD from Subversion.
+ </p>
+
+
+
<a name="Code+metrics+"></a>
<div class="h3">
<h3>Code metrics </h3>
Modified: poi/site/src/documentation/content/xdocs/subversion.xml
URL: http://svn.apache.org/viewvc/poi/site/src/documentation/content/xdocs/subversion.xml?rev=1750865&r1=1750864&r2=1750865&view=diff
==============================================================================
--- poi/site/src/documentation/content/xdocs/subversion.xml (original)
+++ poi/site/src/documentation/content/xdocs/subversion.xml Thu Jun 30 21:19:52 2016
@@ -107,6 +107,133 @@
<link href="guidelines.html">contribution guidelines</link> for more
information on getting involved in the project.</p>
</section>
+ <section><title>Using Git via the SVN-Git bridge</title>
+ <section><title>General information</title>
+ <p>
+ Git provides a nice functionality "git-svn" which allows to read the history
+ of a Subversion repository and convert it into a full Git repository. This
+ will keep information from the SVN revisions so that the Git repository can
+ be updated with newer revisions from Subversion as well as allowing to push
+ commits from Git "upstream" into the Subversion repository. See the
+ <link href="https://www.kernel.org/pub/software/scm/git/docs/git-svn.html">
+ official documentation</link> for more details.
+ </p>
+ </section>
+ <section><title>Set up the repository</title>
+ <p>
+ The git-svn functionality is provided as a set of sub-commands to
+ "git svn". To start retrieving information from SVN and create the
+ initial Git repository run the following command:
+
+ </p>
+ <source>
+ git svn clone https://svn.apache.org/repos/asf/poi/trunk poisvngit
+ </source>
+ <p>
+ This will run for a long time and will retrieve the full version history of
+ the Subversion repository.
+
+ If you would like to speed this up you can restrict the Git repository to a
+ certain range of SVN revisions via
+ <code>--revision from:HEAD</code>.
+ </p>
+ <p>
+ When this finishes you have a Git repository whose "master" branch
+ mirrors the SVN "trunk".
+ <br/>
+ From here you can use the full power of Git, i.e. quick branching,
+ rebasing, merging, ...
+ <br/>
+ See below for some common usage hints.
+ </p>
+ </section>
+ <section><title>Fetching newer SVN revisions</title>
+ <p>
+ In order to fetch the latest SVN revisions, you need to "rebase" onto
+ the SVN trunk:
+ </p>
+ <source>
+ git checkout master
+ git svn rebase
+ </source>
+ <p>
+ This will fetch the latest changes from Subversion and will rebase
+ the master-branch onto them.
+ </p>
+ </section>
+ <section><title>Pushing Git commits to Subversion</title>
+ <p>
+ The following command will push all changes on <code>master</code> back to
+ Subversion:
+ </p>
+ <source>
+ git svn dcommit
+ </source>
+ <p>
+ Note that usually all commits on master will be sent to Subversion
+ in one go, so it's similar to a "push" to another Git repository.
+
+ The dcommit may fail if there are newer revisions in Subversion, you
+ will need to run a <code>git svn rebase</code> first in this case.
+ </p>
+ </section>
+ <section><title>General usage guidelines</title>
+ <p>
+ Although you can use the full power of Git, there are a few
+ things that work well and some things that will get you into
+ trouble:
+ </p>
+ <p>
+ You should not develop on master, rather use some branching
+ concept where you do work on sub-branches and only merge/cherry-pick the
+ changes that are ready for being sent upstream.
+ It seems to work better to constantly rebase changes onto the
+ master branch as this will keep the history clean compared to
+ the SVN repository and will avoid sending useless "Merge" commits to
+ Subversion.
+ </p>
+ <p>
+ You can keep some changes that are only useful locally by using
+ two branches that are rebased onto each other. E.g.
+ something like the following has proven to work well:
+ </p>
+ <source>
+ master
+ -> localchanges - commits that should not be sent upstream ->
+ -> workbranch - place for doing development work
+ </source>
+ <p>
+ When things are ready in the workbranch do a
+ </p>
+ <source>
+ git co master
+ git cherry-pick commitid ...
+ </source>
+ <p>
+ to get all the finished commits onto master as preparation for pushing them upstream.
+
+ Then you can <code>git svn dcommit</code> to send the changes upstream
+ and a <code>git svn rebase</code> to get master updated with the newly
+ created SVN revisions.
+
+ Finally do the following to update both branches onto the new SVN head
+ </p>
+ <source>
+ # rebase you local changes onto the latest SVN state
+ git checkout localchanges
+ git rebase master
+
+ # also set the working branch to the latest state from SVN.
+ git checkout workbranch
+ git rebase workbranch
+ </source>
+ <p>
+ Sounds like too much work? Put these steps into a small script and all
+ this will become a simple <code>poiupdate</code> to get all branches
+ rebased onto HEAD from Subversion.
+ </p>
+ </section>
+ </section>
<section><title>Code metrics </title>
<p>
Code quality reports for Apache POI are available on the
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@poi.apache.org
For additional commands, e-mail: commits-help@poi.apache.org