You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by bu...@apache.org on 2012/11/29 14:00:13 UTC
svn commit: r839997 - in /websites/staging/isis/trunk: cgi-bin/ content/
content/contributors/about.html content/contributors/using-git.html
content/documentation.html
Author: buildbot
Date: Thu Nov 29 13:00:12 2012
New Revision: 839997
Log:
Staging update by buildbot for isis
Added:
websites/staging/isis/trunk/content/contributors/using-git.html
Modified:
websites/staging/isis/trunk/cgi-bin/ (props changed)
websites/staging/isis/trunk/content/ (props changed)
websites/staging/isis/trunk/content/contributors/about.html
websites/staging/isis/trunk/content/documentation.html
Propchange: websites/staging/isis/trunk/cgi-bin/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Thu Nov 29 13:00:12 2012
@@ -1 +1 @@
-1415065
+1415147
Propchange: websites/staging/isis/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Thu Nov 29 13:00:12 2012
@@ -1 +1 @@
-1415065
+1415147
Modified: websites/staging/isis/trunk/content/contributors/about.html
==============================================================================
--- websites/staging/isis/trunk/content/contributors/about.html (original)
+++ websites/staging/isis/trunk/content/contributors/about.html Thu Nov 29 13:00:12 2012
@@ -193,6 +193,7 @@
</div>
<ul>
+<li>[Using Git][using-git.html)</li>
<li><a href="coding-conventions.html">Coding conventions</a></li>
<li><a href="updating-the-cms-site.html">Updating the CMS site</a></li>
<li><a href="release-process.html">Release process</a></li>
Added: websites/staging/isis/trunk/content/contributors/using-git.html
==============================================================================
--- websites/staging/isis/trunk/content/contributors/using-git.html (added)
+++ websites/staging/isis/trunk/content/contributors/using-git.html Thu Nov 29 13:00:12 2012
@@ -0,0 +1,488 @@
+<!DOCTYPE html>
+<html lang="en">
+ <head>
+
+ <meta charset="utf-8">
+ <title>Using Git
</title>
+ <meta name="description" content="">
+ <meta name="author" content="">
+
+ <!-- Le HTML5 shim, for IE6-8 support of HTML elements -->
+ <!--[if lt IE 9]>
+ <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
+ <![endif]-->
+
+ <!-- Le styles -->
+ <link href="./../bootstrap.css" rel="stylesheet">
+ <link href="./../prettify.css" rel="stylesheet">
+ <link href="./../bootstrap-mods.css" rel="stylesheet">
+
+ <style type="text/css">
+ body {
+ padding-top: 60px;
+ }
+ .sprite {
+ display: inline-block;
+ height: 20px;
+ margin: 0 auto 4px;
+ outline: medium none;
+ text-indent: -999em;
+ width: 24px;
+ background-image: url('./../images/sprites.png');
+ background-repeat: no-repeat;
+ overflow: hidden;
+ cursor: pointer;
+ }
+ .edit-page {
+ display: inline-block;
+ height: 20px;
+ margin: 0 auto 4px;
+ outline: medium none;
+ text-indent: -999em;
+ width: 24px;
+ background-image: url('./../images/edit.png');
+ background-repeat: no-repeat;
+ overflow: hidden;
+ cursor: pointer;
+ }
+ .fb-share {
+ background-position: 0px -40px;
+ }
+ .gp-share {
+ background-position: 0px 0px;
+ }
+ .tw-share {
+ background-position: 0px -80px;
+ }
+ .markdown-content {
+ min-height: 500px;
+ }
+ .book-image img {
+ border: 1px;
+ border-style: solid;
+ }
+ .stub {
+ position: relative;
+ padding: 7px 15px;
+ margin-bottom: 18px;
+ color: #404040;
+ background-color: #eedc94;
+ background-repeat: repeat-x;
+ background-image: -khtml-gradient(linear, left top, left bottom, from(#fceec1), to(#eedc94));
+ background-image: -moz-linear-gradient(top, #fceec1, #eedc94);
+ background-image: -ms-linear-gradient(top, #fceec1, #eedc94);
+ background-image: -webkit-gradient(linear, left top, left bottom, color-stop(0%, #fceec1), color-stop(100%, #eedc94));
+ background-image: -webkit-linear-gradient(top, #fceec1, #eedc94);
+ background-image: -o-linear-gradient(top, #fceec1, #eedc94);
+ background-image: linear-gradient(top, #fceec1, #eedc94);
+ filter: progid:DXImageTransform.Microsoft.gradient(startColorstr='#fceec1', endColorstr='#eedc94', GradientType=0);
+ text-shadow: 0 -1px 0 rgba(0, 0, 0, 0.25);
+ border-color: #eedc94 #eedc94 #e4c652;
+ border-color: rgba(0, 0, 0, 0.1) rgba(0, 0, 0, 0.1) rgba(0, 0, 0, 0.25);
+ text-shadow: 0 1px 0 rgba(255, 255, 255, 0.5);
+ border-width: 1px;
+ border-style: solid;
+ -webkit-border-radius: 4px;
+ -moz-border-radius: 4px;
+ border-radius: 4px;
+ -webkit-box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.25);
+ -moz-box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.25);
+ box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.25);
+ }
+ </style>
+ <script type="text/javascript">
+ function fbshare () {
+ window.open(
+ "http://www.facebook.com/sharer/sharer.php?u="+document.URL,
+ 'Share on Facebook',
+ 'width=640,height=426');
+ };
+ function gpshare () {
+ window.open(
+ "https://plus.google.com/share?url="+document.URL,
+ 'Share on Google+',
+ 'width=584,height=385');
+ };
+ function twshare () {
+ window.open(
+ "https://twitter.com/intent/tweet?url="+document.URL+"&text=Using Git
",
+ 'Share on Twitter',
+ 'width=800,height=526');
+ };
+ </script>
+
+ <!-- Le fav and touch icons -->
+ <link rel="shortcut icon" href="./../images/favicon.ico">
+ <link rel="apple-touch-icon" href="./../images/apple-touch-icon.png">
+ <link rel="apple-touch-icon" sizes="72x72" href="./../images/apple-touch-icon-72x72.png">
+ <link rel="apple-touch-icon" sizes="114x114" href="./../images/apple-touch-icon-114x114.png">
+
+ <script src="./../javascript/prettify.js" type="text/javascript"></script>
+ <script src="./../javascript/jquery-latest.js"></script>
+ <script src="http://platform.twitter.com/widgets.js" type="text/javascript"></script>
+ <script src="./../javascript/common.js"></script>
+ <script src="./../javascript/prettyprint.js"></script>
+
+ <script type="text/javascript">
+
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', 'UA-2717626-1']);
+ _gaq.push(['_setDomainName', 'apache.org']);
+ _gaq.push(['_trackPageview']);
+
+ (function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+ })();
+
+ </script>
+
+
+ </head>
+
+ <body>
+
+ <div class="topbar">
+ <div class="fill">
+ <div class="container">
+ <a class="brand" href="./../index.html">Apache Isis</a>
+ <ul class="nav">
+ <li><a href="./../index.html">Home</a></li>
+ <li><a href="./../download.html">Download</a></li>
+ <li><a href="./../documentation.html">Documentation</a></li>
+ <li><a href="./../support.html">Support</a></li>
+ </ul>
+
+ <!-- Google CSE Search Box Begins -->
+ <div style="float: right; position: relative; ">
+ <form action="http://www.google.com/cse" id="cse-search-box" _lpchecked="1">
+ <div>
+ <input type="hidden" name="cx" value="001500763902520246267:purt3m54z98">
+ <input type="hidden" name="ie" value="UTF-8">
+ <input type="text" name="q" size="31" style="border: 1px solid rgb(126, 157, 185); padding: 2px; background-color: rgb(255, 255, 255); background-position: 0% 50%; background-repeat: no-repeat no-repeat;">
+ <input type="submit" name="sa" value="Search">
+ </div>
+ <input name="siteurl" type="hidden" value="incubator.apache.org/isis/">
+ <input name="ref" type="hidden" value="">
+ <input name="ss" type="hidden" value="677j458329j2">
+ </form>
+ </div>
+ <!-- Google CSE Search Box Ends -->
+ </div>
+ </div>
+ </div>
+
+ <div class="container">
+ <div class="markdown-content">
+
+
+<div class="page-header">
+<p><a href="./../documentation.html">Docs</a> » <a href="./../contributors/about.html">Contributors</a></p>
+<h1>Using Git
+
+<!--
+ <div style="float: right; position: relative; bottom: -10px; ">
+ <a onclick="javascript:gpshare()" class="gp-share sprite" title="share on Google+">share [gp]</a>
+ <a onclick="javascript:fbshare()" class="fb-share sprite" title="share on Facebook">share [fb]</a>
+ <a onclick="javascript:twshare()" class="tw-share sprite" title="share on Twitter">share [tw]</a>
+ <a data-toggle="modal" href="#edit" class="edit-page" title="Contribute to this Page">contribute</a>
+ </div>
+-->
+</h1>
+</div>
+
+<p><em>See <a href="https://issues.apache.org/jira/browse/INFRA-5502">INFRA-5502</a> for current status on our move from svn to git</em></p>
+
+<h2>Introduction</h2>
+
+<p>These notes recommend how contributors should work with git. To understand these notes, the only real concepts that you need to grok are:</p>
+
+<ul>
+<li>git commits form an acyclic graph, with each commit pointing to its parent commit (or commit*<em>s</em>*, if a merge)</li>
+<li>a branch is merely a pointer to one of these commits; git calls the main branch <code>master</code></li>
+<li>git commits happen in two steps: first they are added to the index (also called the staging area), then they are committed.</li>
+</ul>
+
+<p>For more background reading, see:</p>
+
+<ul>
+<li><a href="http://git-scm.com/book">Pro Git</a> book (free in electronic form)</li>
+<li><a href="https://github.s3.amazonaws.com/media/book.pdf">Git community book</a></li>
+<li><a href="http://git-scm.com/2011/07/11/reset.html">git reset demystified</a> - differentiating the working directory vs staging area (index)</li>
+</ul>
+
+<p>And, of course, there is loads of good advice on <a href="http://stackoverflow.com/questions/tagged/git">stackoverflow.com</a></p>
+
+<h2>General principle</h2>
+
+<p>There are many ways of using Git, but the only real prescriptive advice here is that commits should only have one parent. Doing this keeps the commit history clean; even though work actually happens in parallel, in the commit history it will look like all work was done serially.</p>
+
+<p>This is accomplished using <code>git rebase</code>; the idea being that any changes that you make locally are re-applied on top of the latest fetch from the <code>master</code> branch. Many other projects also work this way; a good write-up of how SpringSocial use git can be found <a href="https://github.com/SpringSource/spring-social/wiki/Contributing">here</a>.</p>
+
+<h2>Basics</h2>
+
+<h4>Installing Git</h4>
+
+<p>The easiest place to get hold of command-line git is probably the <a href="http://git-scm.com/downloads">github download page</a>. On Windows, this also installs the rather good mSysGit Unix shell.</p>
+
+<p>Once git is installed, the two main command line tools to note are:</p>
+
+<ul>
+<li><code>git</code> command line tool</li>
+<li><code>gitk</code> for viewing the commit history</li>
+</ul>
+
+<p>Three commands in particular worth knowing:</p>
+
+<ul>
+<li><code>git help *command*</code></p>
+
+<p>will open the man page in your web browser</li>
+<li><code>git gui</code></p>
+
+<p>will open up a basic GUI client to staging changes and making commits</li>
+<li><code>gitk --all</code></p>
+
+<p>will open the commit history for all branches. In particular, you should be able to see the local <code>master</code>, which branch you are working on (the <code>HEAD</code>), and also the last known position of the <code>master</code> branch from the central repo, called <code>origin/master</code>.</li>
+</ul>
+
+<p>If using Windows, note that github also have a dedicated <a href="https://help.github.com/articles/set-up-git">Windows client</a>. With a little <a href="http://haacked.com/archive/2012/05/30/using-github-for-windows-with-non-github-repositories.aspx">hacking around</a>, it can also be made to work with non-github repositories.</p>
+
+<p>If using Mac, you might also want to check out Atlassian's <a href="http://www.atlassian.com/software/sourcetree/overview">Sourcetree</a>.</p>
+
+<h4>Git clone</h4>
+
+<pre>
+git clone url # awaiting url, pending completion of INFRA-5502
+</pre>
+
+<h4>Commit message format</h4>
+
+<p>Commit messages should follow the format:</p>
+
+<pre>
+ISIS-nnn: brief summary here
+
+- optionally, longer details
+- should be written here
+- in bullet points
+</pre>
+
+<p>where <code>ISIS-nnn</code> is a ticket raised in our <a href="https://issues.apache.org/jira/browse/ISIS">JIRA issue tracker</a>.</p>
+
+<h4>Modifying existing files</h4>
+
+<p>To modify existing files:</p>
+
+<pre>
+git add <i>filename</i>
+git commit -m "ISIS-nnn: yada yada"
+</pre>
+
+<p>The <code>git add</code> command adds the changes to the file(s) to the git index (aka staging area). If you were to make subsequent changes to the file these would not be committed.</p>
+
+<p>The <code>git commit</code> takes all the staged changes and commits them locally. Note that these changes are not shared public with Isis' central git repo.</p>
+
+<p>You can combine these two commands using <code>-am</code> flag to git commit:</p>
+
+<pre>
+git commit -am "ISIS-nnn: yada yada"
+</pre>
+
+<h4>Adding new files</h4>
+
+<p>To add a new file:</p>
+
+<pre>
+git add .
+git commit -m "ISIS-nnn: yada yada"
+</pre>
+
+<p>Note that this sequence of commands is identical to modifying an existing file. However, it isn't possible to combine the two steps using <code>git commit -am</code>; the <code>git add</code> is always needed when adding new files to the repo.</p>
+
+<h4>Deleting files</h4>
+
+<p>To delete a file:</p>
+
+<pre>
+git rm filename
+git commit -m "ISIS-nnn: yada yada"
+</pre>
+
+<h4>Renaming or moving files</h4>
+
+<p>To rename or move a file:</p>
+
+<pre>
+git mv <i>filename</i> <i>newfilename</i>
+git commit -m "ISIS-nnn: yada yada"
+</pre>
+
+<h2>Common Workflows</h2>
+
+<h3>Working on master</h3>
+
+<p>With this option, you do nothing special locally, just commit to the <code>master</code> branch.</p>
+
+<p>When you are ready to push your changes, use:</p>
+
+<pre>
+git pull --rebase
+</pre>
+
+<p>This will bring down all the latest commits made to the central repo, and update <em>origin/master</em>. It will then apply all commits made in your master branch on top of that.</p>
+
+<p>Alternatively, you can do this in two stages:</p>
+
+<pre>
+git fetch
+git rebase origin/master
+</pre>
+
+<p>After the <code>git fetch</code>, you will see that <code>gitk --all</code> shows the new set of commits as a branch separate from your own commits on branch. The <code>git rebase</code> command then applies all your changes on top of that branch. (Your original commits are orphaned and are eventually garbage collected by git).</p>
+
+<h3>Creating a local branch</h3>
+
+<p>If you are working on a branch for a significant period (eg to implement a ticket), then it probably makes sense to create a local branch:</p>
+
+<pre>
+git checkout -b <i>branchname</i>
+</pre>
+
+<p>If you use <code>gitk --all</code>, then you'll see a new tag for the current commit. The command line in the shell also changes.</p>
+
+<p>Any commits made now advance the new branch, but leave the <code>master</code> branch alone.</p>
+
+<p>If you want to switch to some other branch, use:</p>
+
+<pre>
+git checkout <i>branchname</i>
+</pre>
+
+<p>Any changes in your working directory and index/staging area are <em>preserved</em>. This makes it easy to separate out different strands of work... you realize that some set of changes just made should be on a different ticket, so you create a new branch and commit those changes there.</p>
+
+<p>When you want to reintegrate the changes into the branch, use:</p>
+
+<pre>
+git checkout <i>branchname</i>
+git rebase master
+</pre>
+
+<p>This will reapply the commits on top of the <code>master</code> branch. If there are conflicts then they will occur a this point. Conflicts are resolved by editing the file, then:</p>
+
+<pre>
+git add <i>filename</i>
+git rebase --continue
+</pre>
+
+<p>Once the rebase is finished, you'll see the branch <em>branchname</em> as a direct descendent of <code>master</code> (use <code>gitk --all</code> to confirm). You will still be on the <em>branchname</em>. To catch up <code>master</code>, use:</p>
+
+<pre><code>git merge master --ff-only
+</code></pre>
+
+<p>The <code>--ff-only</code> ensures that the merge is a fast-forward; ie all commits will have only a single parent, and no conflicts.</p>
+
+<p>At this point you can delete the branch:</p>
+
+<pre>
+git checkout master
+git branch -d <i>branchname</i>
+</pre>
+
+<h2>Backing up a local branch</h2>
+
+<p>If committing to a local branch, the changes are still just that: local, and run risk of a disk failure or other disaster.</p>
+
+<p>To create a new, similarly named branch on the central repo, use:</p>
+
+<pre>
+git push -u origin <i>branchname</i>
+</pre>
+
+<p>Using <code>gitk --all</code> will show you this new branch, named <em>origin/branchname</em>.</p>
+
+<p>Thereafter, you can push subsequent commits using simply:</p>
+
+<pre><code>git push
+</code></pre>
+
+<p>Doing this also allows others to collaborate on this branch, just as they would for <code>master</code>.</p>
+
+<p>When, eventually, you have reintegrated this branch, you can delete the remote branch using:</p>
+
+<pre>
+git push origin --delete <i>branchname</i>
+</pre>
+
+<p>For more detail, see these blogs/posts <a href="http://www.mariopareja.com/blog/archive/2010/01/11/how-to-push-a-new-local-branch-to-a-remote.aspx">here</a> and <a href="http://stackoverflow.com/questions/2003505/how-do-i-delete-a-git-branch-both-locally-and-in-github">here</a>.</p>
+
+<h3>Quick change: stashing changes</h3>
+
+<p>If you are working on something but are not ready to commit, then use:</p>
+
+<pre><code>git stash
+</code></pre>
+
+<p>If you use <code>gitk --all</code> then you'll see new commits are made that hold the current state of your working directory and staging area.</p>
+
+<p>You can then, for example, pull down the latest changes using <code>git pull --rebase</code> (see above).</p>
+
+<p>To reapply your stash, then use:</p>
+
+<pre><code>git stash pop
+</code></pre>
+
+<p>Note that stashing works even if switching branches</p>
+
+<h2>Ignoring files</h2>
+
+<p>Put file patterns into <code>.gitignore</code>. There is one at the root of the git repo, but they can additionally appear in subdirectories (the results are cumulative).</p>
+
+<p>See also:</p>
+
+<ul>
+<li><a href="https://help.github.com/articles/ignoring-files">github's help page</a></li>
+<li><a href="http://www.kernel.org/pub/software/scm/git/docs/gitignore.html">man page</a></li>
+</ul>
+
+
+
+ </div>
+
+ <div id="edit" class="modal hide fade in" style="display: none; ">
+ <div class="modal-header">
+ <a class="close" data-dismiss="modal">x</a>
+
+ <h3>Thank you for contributing to the documention!</h3>
+ </div>
+ <div class="modal-body">
+ <h4>Any help with the documentation is greatly appreciated.</h4>
+ <p>All edits are reviewed before going live, so feel free to do much more than fix typos or links. If you see a page that could benefit from an entire rewrite, we'd be thrilled to review it. Don't be surprised if we like it so much we ask you for help with other pages :)</p>
+ <small>NOTICE: unless indicated otherwise on the pages in question, all editable content available from apache.org is presumed to be licensed under the Apache License (AL) version 2.0 and hence all submissions to apache.org treated as formal Contributions under the license terms.</small>
+ <!--[if gt IE 6]>
+ <h4>Internet Explorer Users</h4>
+ <p>If you are not an Apache committer, click the Yes link and enter a <i>anonymous</i> for the username and leave the password empty</p>
+ <![endif]-->
+
+ </div>
+ <div class="modal-footer">
+ Do you have an Apache ID?
+ <a href="javascript:void(location.href='https://cms.apache.org/redirect?uri='+escape(location.href))" class="btn">Yes</a>
+ <a href="javascript:void(location.href='https://anonymous:@cms.apache.org/redirect?uri='+escape(location.href))" class="btn">No</a>
+ </div>
+ </div>
+ <script src="./../javascript/bootstrap-modal.js"></script>
+
+ <footer>
+ <p>
+ Copyright © 2012 The Apache Software Foundation, Licensed under the Apache License, Version 2.0.
+ <br/>
+ Apache and the Apache feather logo are trademarks of The Apache Software Foundation.
+ </p>
+ </footer>
+
+ </div> <!-- /container -->
+
+ </body>
+</html>
Modified: websites/staging/isis/trunk/content/documentation.html
==============================================================================
--- websites/staging/isis/trunk/content/documentation.html (original)
+++ websites/staging/isis/trunk/content/documentation.html Thu Nov 29 13:00:12 2012
@@ -218,6 +218,7 @@
<div class="span-one-third"></p>
<h3>Contributors</h3></li>
+<li>[Using Git][contributors/using-git.html)</li>
<li><a href="contributors/coding-conventions.html">Coding Conventions</a></li>
<li><a href="contributors/updating-the-cms-site.html">Updating the CMS site</a></li>
<li><a href="contributors/release-process.html">Release process</a></li>