GothenburgBitFactory/taskwarrior
1
0
Fork 0
mirror of https://github.com/GothenburgBitFactory/taskwarrior.git synced 2025-06-26 10:54:26 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Documentation Update - git usage doc

Browse source 
- Added a page that describes how to use git to contribute to task.
This commit is contained in:
Paul Beckingham 2009-05-12 22:28:42 -04:00
parent 3f97bb0663
commit cc5d44ee9d
2 changed files with 410 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

409
html/git.html Normal file
View file

@ -0,0 +1,409 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>git</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rel="stylesheet" href="task.css" type="text/css" />
</head>
<body>
<div id="container">
<table>
<tr>
<td>
<div id="toolbar">
<a href="task.html">Home</a>
<a href="setup.html">Setup</a>
<a href="30second.html">30-second Tutorial</a>
<a href="simple.html">Simple</a>
<a href="advanced.html">Advanced</a>
<a href="shell.html">Shell</a>
<a href="config.html">Configuration</a>
<a href="color.html">Colors</a>
<a href="recur.html">Recurrence</a>
<a href="date.html">Date Handling</a>
<a href="faq.html">FAQ</a>
<a href="versions.html">Old Versions</a>
<a href="links.html">Task on the Web</a>
</div>
<div id="content">
<br />
<br />
<br />
<h2 class="title"><a name="simple">Using git</a></h2>
<div class="content">
<p>
First you need to tell git who you are. These commands will
write to ~/.gitconfig, and will be used to identify you when
you commit changes. Plus, I like color.
</p>
<pre><code>% git config --global user.name "John Doe"
% git config --global user.email "john@doe.com"
% git config --global color.ui=always</code></pre>
<p>
Now we will clone the repository, which involves downloading
about 2MB of files. Git repositories are very compact. We
will clone the repository from github. This takes a minute or
so.
</p>
<pre><code>% cd
% git clone git://github.com/pbeckingham/task.git task.git
% cd task.git</code></pre>
<p>
You just pulled the entire history of task changes since it
was uploaded to github. That will be missing about a year and
a half of prior changes, which were in Subversion. Let's
build task:
</p>
<pre><code>% autoreconf
...
% ./configure --prefix=/usr/local
...
% make
...</code></pre>
<p>
The task binary will be in the src directory. If you run:
</p>
<pre><code>% sudo make install</code></pre>
<p>
Then task will be copied to /usr/local/bin, according the
--prefix argument used above. /usr/local is the default
prefix, so that argument wasn't necessary, but illustrates
it's use.
</p>
<p>
Meanwhile, you have just created a local copy of the
repository. You can do anything to this copy except push to
github. Only the repository owner can push to github, or
additional users identified by the owner (with additional
monthly github fee). In order to get your changes back to
github, they have to go through the owner, either in the form
of a patch via email, or by creating your own github account,
pushing to you own task repository clone (github calls it a
fork), then asking the owner to pull directly from your
repository.
</p>
<p>
You only need to clone once, unless you feel like starting
over, or creating additional clones. Ordinarily, you update
your local copy by pulling changes from github with:
</p>
<pre><code>% git pull</code></pre>
<p>
Right now, nothing new should be pulled, because you just
cloned. Sometimes you'll see changes that have either been
made by the owner, or merged in from others, by the owner.
Let's take a look at the commit history:
</p>
<pre><code>% git log</code></pre>
<p>
You see a whole series of commits. Each commit is a set of
file changes that were made somewhere. Let's look at branches.
Try this:
</p>
<pre><code>% git branch
* master</code></pre>
<p>
This is telling you that you have only one branch, called
master. The asterisk tells you that this is your current
branch, which is redundant because you only have one. But
there are other branches on github. See those with:
</p>
<pre><code>% git branch -a
* master
remotes/origin/1.6.1
remotes/origin/1.7.0
remotes/origin/HEAD -&gt; origin/master
remotes/origin/master</code></pre>
<p>
A remote is what git calls another repository. The origin
remote is the repository that this clone originated from.
This output tells you that there is a 1.6.1 branch on github,
a 1.7.0 branch on github, and a master branch on github. It's
not obvious, but your local master (the first one shown) is
tracking remotes/origin/master, which means changes on the
remote will get merged to the local tracking branch on pull.
</p>
<p>
The convention used by task is to create a new branch whenever
work begins on a new version. When that version is released,
the branch is merged to master, but retained. At time of
writing, 1.6.1 is the currently released version of task, and
so remotes/origin/1.6.1 and remotes/origin/master are
currently identical, with all new development happening on the
1.7.0 branch. When 1.7.0 is released, it will get merged to
master, and the 1.6.1 branch will be deleted. Nothing will be
lost, because 1.6.1 is already merged to master. Let's look
at tags:
</p>
<pre><code>% git tag</code></pre>
...
v1.4.3
v1.5.0
v1.6.0
v1.6.1
<p>
Those tags are just labels that represent the last commit for
that version. You may notice that a change in the tag naming
convention, that occurred when the owner realized that git
will not allow a tag and a branch of the same name at the same
time, so now there is a "v" in the tags.
</p>
<p>
Let's make a branch called 1.7.0 that tracks changes to
remotes/origin/1.7.0. That means you can pull 1.7.0 changes
from github into your local branch, to keep up to date.
</p>
<pre><code>% git checkout -b 1.7.0 origin/1.7.0
Branch 1.7.0 set up to track remote branch 1.7.0 from origin.
Switched to a new branch '1.7.0'
% git branch -a
* 1.7.0
master
remotes/origin/1.6.1
remotes/origin/1.7.0
remotes/origin/HEAD -&gt; origin/master
remotes/origin/master</code></pre>
<p>
Now you can see that 1.7.0 is your current branch (*). That
means you are looking at the 1.7.0 codebase. Let us now
assume you intend to make a change, and submit the patch. We
will add Solaris 8 as a supported OS. This will affect two
files. First check status:
</p>
<pre><code>% git status
# On branch 1.7.0
nothing to commit (working directory clean)</code></pre>
<p>
No changes. That's what we expect. Now make the changes (any
editor will suffice, but assume vi):
</p>
<pre><code>% vi NEWS
% vi html/task.html</code></pre>
<p>
Now we expect to see changes. Status says:
</p>
<pre><code>% git status
# On branch 1.7.0
# Changed but not updated:
# (use "git add &lt;file&gt;..." to update what will be committed)
# (use "git checkout -- &lt;file&gt;..." to discard changes in working directory)
#
# modified: NEWS
# modified: html/task.html
#
no changes added to commit (use "git add" and/or "git commit -a")</code></pre>
<p>
Git sees that those two files have changed, but as git states,
they are not added to the commit. Git allows you to stage
changes, then commit the staged changes - a two-step process
that gives you complete control. Git also allows you to
commit all changes and bypass the staging, but that's a
shortcut that is risky, because you can inadvertently commit
things you didn't want to. Let's see what git thinks changed:
</p>
<pre><code>% git diff
diff --git a/NEWS b/NEWS
index 74adecd..30d4f8f 100644
--- a/NEWS
+++ b/NEWS
@@ -12,6 +12,7 @@ Task has been built and tested on the following configurations:
- Ubuntu 8.10 Intrepid Ibex
- Ubuntu 9.04 Jaunty Jackalope
- Arch Linux
+ - Solaris 8
- Solaris 10
- Cygwin 1.5.25-14
diff --git a/html/task.html b/html/task.html
index 66ee777..a2254f6 100644
--- a/html/task.html
+++ b/html/task.html
@@ -193,6 +193,7 @@
&lt;li&gt;Ubuntu 8.10 Intrepid Ibex
&lt;li&gt;Ubuntu 9.04 Jaunty Jackalope
&lt;li&gt;Arch Linux
+ &lt;li&gt;Solaris 8
&lt;li&gt;Solaris 10
&lt;li&gt;Cygwin 1.5.25-14
&lt;/ul&gt;</code></pre>
<p>
Git has correctly spotted the changes. The "git diff" command
always tells you the difference between the last commit and
the current state. Now we will stage the two changes:
</p>
<pre><code>% git add NEWS html/task.html
% git diff</code></pre>
<p>
No changes are reported. That's because if files are staged,
then diff shows the difference between the staged files and
the current state. We staged all changes, hence no diff. If
we wanted to see the difference between the last commit and
the staged files, try this:
</p>
<pre><code>% git diff --cached
(same as unstaged diff)</code></pre>
<p>
Now the status shows that the files are staged:
</p>
<pre><code>% git status
# On branch 1.7.0
# Changes to be committed:
# (use "git reset HEAD &lt;file&gt;..." to unstage)
#
# modified: NEWS
# modified: html/task.html
#</code></pre>
<p>
Now a commit command will commit the staged files:
</p>
<pre><code>% git commit -m "Added Solaris 8 as a supported platform"
[1.7.0 03308eb] Added Solaris 8 as a suported platform
2 files changed, 2 insertions(+), 0 deletions(-)</code></pre>
<p>
Now make a patch:
</p>
<pre><code>% git format-patch HEAD^
0001-Added-Solaris-8-as-a-supported-platform.patch</code></pre>
<p>
HEAD is a label that means the current head of the branch, or
in other words, what was last committed. HEAD^ means the
commit before that. HEAD~2 is the one before that, HEAD~3
etc. When we say create a patch of HEAD^, it means the same
as:
</p>
<pre><code>% git diff HEAD^</code></pre>
<p>
Which means show the difference between the previous commit
and the current commit, but the patch has extra identifying
information in it. Take a look at that patch file. If you
ran:
</p>
<pre><code>% git format-patch HEAD~10</code></pre>
<p>
Git will create 10 patch files, one for each commit. To get
the patch applied to the repository, email it to the owner.
The owner will then apply the patch with:
</p>
<pre><code>owner&gt; git apply 0001-Added-Solaris-8-as-a-supported-platform.patch</code></pre>
<p>
Then push the changes with:
</p>
<pre><code>owner&gt; git push</code></pre>
<p>
And that makes them available on github, which means in turn
that the next time you run:
</p>
<pre><code>% git pull</code></pre>
<p>
Your changes will have come full circle.
</p>
</div>
<br />
<br />
<div class="content">
<p>
Copyright 2006-2009, P. Beckingham. All rights reserved.
</p>
</div>
</div>
</td>
<td align="right" valign="top" width="200px">
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<script type="text/javascript"><!--
google_ad_client = "pub-9709799404235424";
/* Task Main */
google_ad_slot = "8660617875";
google_ad_width = 120;
google_ad_height = 600;
//-->
</script>
<script type="text/javascript"
src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
</script>
</td>
</tr>
</table>
</div>
<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
var pageTracker = _gat._getTracker("UA-4737637-1");
pageTracker._initData();
pageTracker._trackPageview();
</script>
</body>
</html>

1
html/task.html
View file

@ -59,6 +59,7 @@
<li><a href="faq.html">Frequently Asked Questions</a>
<li><a href="sequence.html">ID Sequences</a>
<li><a href="tab_completion.html">Tab Completion</a>
<li><a href="git.html">How to use git and contribute to task</a>
</ul>
<p>