develop-git.php

   1 <?
   2 $title='Check Out the Source Code';
   3 $breadcrumb=array('Home', '.', 'Develop', 'develop.php');
   4 ?>
   5
   6 <html>
   7   <?php include('head.php') ?>
   8   <link rel="stylesheet" type="text/css" href="css/develop.css" />
   9 </head>
  10
  11 <?php include('top.php') ?>
  12
  13 <?php splash_title('images/splash/git.png', $title); ?>
  14
  15 <?php include('content.php') ?>
  16
  17 <div id="col1" class="widecol">
  18 <ol>
  19   <li><a href="#quick">Quick Instructions</a></li>
  20   <li><a href="#branches">Branches</a></li>
  21   <li><a href="#local">Local changes</a></li>
  22     <ol>
  23       <li><a href="#conflict">Conflicting changes</a></li>
  24     </ol>
  25   </li>
  26   <li><a href="#contrib">Contributing code</a></li>
  27   <li><a href="#lowband">Low bandwidth option</a></li>
  28   <li><a href="#repos">Alternate repos</a></li>
  29   <li><a href="#reading">Further Reading</a></li>
  30 </ol>
  31 </div> <!--col1-->
  32
  33 <div id="col2" class="widecol">
  34 <a name="quick"><h5 class="text">Quick Instructions</h5></a>
  35
  36 <p>
  37 To get up and running, you just need one command. This will create a directory
  38 called openbox and download the git repository into it:
  39 </p>
  40 <blockcode>
  41 git clone git://git.openbox.org/dana/openbox openbox
  42 </blockcode>
  43
  44 <p>To get the latest changes, from inside the downloaded git repository, run</p>
  45 <blockcode>
  46 git pull
  47 </blockcode>
  48
  49 <p>
  50 Note however that this only does what you expect if you haven't made any changes.
  51 If you have, it will attempt to merge your changes which may or may not be what
  52 you want, see <a href="#local">Local Changes</a> below.
  53 </p>
  54
  55 <p>
  56 Read the <code>README.GIT</code> file for instructions on building the
  57 source code from the git repository.
  58 </p>
  59
  60 <a name="branches"><h5 class="text">Branches</h5></a>
  61
  62 <p>
  63 Currently, there are two branches of interest in the Openbox git repos:
  64 master and 3.4-working. Master is the branch that will most likely become
  65 Openbox 3.5 or so, 3.4-working keeps compatibility with the rc.xml file from
  66 the 3.4.x releases. There is also a branch called backport which is where we
  67 put fixes and features that should go in both the other branches.
  68 </p>
  69
  70 <p>
  71 By default you will get the master branch, hence the name. If you want the
  72 3.4-working branch, run
  73 </p>
  74 <blockcode>
  75 git checkout --track -b 3.4-working origin/3.4-working
  76 </blockcode>
  77
  78 <p>
  79 You can now switch between them with git checkout master and git checkout
  80 3.4-working.
  81 </p>
  82
  83 <p>
  84 If you want the very latest changes, first decide if you want 3.4-working or master,
  85 then check if we've recently merged the backport branch, for example by checking
  86 the output of git-log, looking at gitk --all or at the gitweb interface (look
  87 near the bottom under the "heads" header). If there are any interesting changes
  88 in the backport branch you want, just run
  89 </p>
  90 <blockcode>
  91 git merge origin/backport
  92 </blockcode>
  93
  94 <p>
  95 and git will pull in the changes for you. If it did not succeed or if the result
  96 didn't compile, you should wait for us to merge it instead. Note however that a
  97 git pull will not remerge backport for you, it will only get updates from the
  98 branch you're currently on. If there are new commits on backport just rerun the
  99 merge command. If you've merged backport, you might want to reset your master
 100 branch before rerunning git pull. (this will remove local changes, so make
 101 sure they're committed on another branch as detailed below if you have those).
 102 </p>
 103 <blockcode>
 104 git reset --hard origin/3.4-working
 105 </blockcode>
 106
 107 <p>
 108 or if you're using master, type origin/master instead of course. And make sure
 109 you've checked out the correct branch first. If you messed up, read
 110 <code>man git-reflog</code>.
 111 </p>
 112
 113 <a name="local"><h5 class="text">Local changes</h5></a>
 114
 115 <p>
 116 Unlike CVS and Subversion, git lets you have local changes while still tracking
 117 upstream development, in a nut shell, make your changes and run
 118 </p>
 119 <blockcode>
 120 git commit -a -m "informative message"
 121 </blockcode>
 122
 123 <p>
 124 It's usually a good idea to keep your changes in a separate branch. You can do
 125 this in a couple of ways, the easiest way is to run
 126 </p>
 127 <blockcode>
 128 git checkout -b my-branch master
 129 </blockcode>
 130 <p>
 131 then commit all your changes to that branch.
 132 </p>
 133
 134 <a name="conflict"><h6 class="text">Conflicting changes</h6></a>
 135
 136 <p>
 137 If you hang on to your changes for a long time, it's likely that
 138 we will make commits that conflict with yours. There are two ways to
 139 deal with this, you can either <code>git-merge</code> our branch and resolve the
 140 differences, but the better way is to use <code>git-rebase</code>.
 141 This command
 142 will take your commits and apply them to the tip (ie latest version)
 143 of the specified branch, pausing after each commit that conflicts.
 144 This usually makes it easier to resolve the conflicts and also gives
 145 a nicer history. Using git-rebase is a bit complicated so read the
 146 man page.
 147 </p>
 148
 149 <p>
 150 If you just want to test that your changes work with the
 151 latest version of openbox, you can merge master and then
 152 later use <code>git reset --hard HEAD^</code> to revert
 153 the merge. However, I recommend first doing a
 154 <code>git checkout -b my-temp</code>, since running
 155 git-reset twice will continue reverting real commits, so it's
 156 easy to mess up. If you're doing all the temp merging on a
 157 separate branch you don't have to worry about that.
 158 </p>
 159
 160 <a name="contrib"><h5 class="text">Contributing code</h5></a>
 161
 162 <p>
 163 You've coded an exciting feature and now you want to send a
 164 diff, how to do it? git-diff you might guess, and while that
 165 will produce a diff you can send, git-format-patch is a bit
 166 nicer as it will automatically give you a patch file per commit
 167 that you want to send, with the commit message in each file.
 168 </p>
 169
 170 <p>
 171 Another option is to set up your own public repo and simply tell
 172 us where to pull your changes from, look at the git-daemon man
 173 page for details. You can also use the git-bundle command to send
 174 a file that contains all commits, which we can then pull from. For
 175 example if you've made all your commits on the branch my-branch
 176 which you produced at some point from <code>git checkout -b master</code>,
 177 you can produce your bundle with
 178 </p>
 179 <blockcode>
 180 git bundle create my-bundle master..my-branch
 181 </blockcode>
 182 <p>
 183 then send the file my-bundle to us.
 184 </p>
 185
 186 <a name="lowband"><h5 class="text">Low bandwidth option</h5></a>
 187
 188 <p>
 189 If your internet connection is very slow (the full git
 190 repo is currently around 8.5MB) and you just want the very
 191 latest version without any history, you can run
 192 </p>
 193 <blockcode>
 194 git clone --depth 1 git://git.openbox.org/dana/openbox openbox
 195 </blockcode>
 196
 197 <p>
 198 This will give you only the current and preceding commit from
 199 each branch, but you can't do much more with your repo than compile
 200 the code. Merging as described above will only work if you use a
 201 depth high enough to include the point where the backport branch
 202 separated from master. See the git-clone and git-fetch man pages
 203 for further details.
 204 </p>
 205
 206 <p>
 207 You can also download a tarball of any revision via
 208 <a href="http://git.openbox.org/?p=dana/openbox.git;a=summary">gitweb</a>.
 209 Click "tree" next to a branch name at the bottom, then "snapshot" at the
 210 top of the new page.
 211 </p>
 212
 213 <a name="repos"><h5 class="text">Alternate repos</h5></a>
 214
 215 <p>
 216 Due to the distributed nature of git, you can choose to pull
 217 from various upstream locations (see the git-remote man page for
 218 details on how to use several remotes).
 219 </p>
 220 <blockcode>git://git.openbox.org/dana/openbox</blockcode>
 221 <blockcode>git://git.openbox.org/mikachu/openbox</blockcode>
 222 <blockcode>git://git.mika.l3ib.org/openbox.git</blockcode>
 223 <blockcode>git://repo.or.cz/openbox.git</blockcode>
 224
 225 <p>
 226 The astute git user will notice that there are some variations in branches
 227 offered among these, for example dana has a libs branch that separates out
 228 some common wm code in a library, and mikachu has a mikabox branch which
 229 is just some crazy stuff.
 230 </p>
 231
 232 <a name="reading"><h5 class="text">Further reading</h5></a>
 233
 234 <p>
 235 On the <a href="http://git-scm.com/">git homepage</a> there are many great
 236 tutorials and all the man
 237 pages are available for browsing as well.
 238 </p>
 239
 240 </div> <!--col2-->
 241
 242 <?php include('bottom.php') ?>