Patch to make README more newbie-friendly

Patch to make README more newbie-friendly

[Jerry Seutter]

[-- Attachment #1: Type: text/plain, Size: 1004 bytes --]

Hi,

Attached to this email is a patch that expands the README file a bit, 
including info about basic Cogito commands at the beginning of the file. 
  I also added an distributed VCS paragraph at the beginning for people 
like me who are typically stuck in CVS-land.

Comments/critiques/flames welcome.

I'd also like to include stuff about branches, but I haven't gotten my 
head wrapped around how they work yet.  cg-branch-add expects a location
after the branch name and I'm not sure what to give it.  I have a test 
project containing hello_world.py and was trying to get 2 branches going 
and be able to switch between them.  What do you use for a location in 
this case?  I tried using ".", but switching between branches didn't 
seem to have any affect.

On another note, I thought I heard that man pages are desired.  Is the a 
certain group of commands I should start with?  Do you want dirt simple 
man pages, or are you looking for some <insert-buzzword-here> formatted 
source docs?

Jerry

[-- Attachment #2: expand_README.patch --]
[-- Type: text/plain, Size: 4781 bytes --]

diff --git a/README b/README
--- a/README
+++ b/README
@@ -1,12 +1,24 @@
 	Cogito and GIT: Quick Introduction
 	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-This document describes the Cogito VCS as well as GIT.  The GIT itself is
-merely an extremely fast and flexible filesystem-based database designed to
-store directory trees with regard to their history.  The top layer is a
-SCM-like tool Cogito which enables human beings to work with the database in a
-manner to a degree similar to other SCM tools (like CVS, BitKeeper or
-Monotone).
+This document describes the Cogito VCS as well as GIT.  The GIT itself
+is merely an extremely fast and flexible filesystem-based database
+designed to store directory trees with regard to their history.  The
+top layer is a SCM-like tool Cogito which enables human beings to work
+with the database in a manner to a degree similar to other SCM tools
+(like CVS, BitKeeper or Monotone).  Mere Human Beings will seldom use
+the GIT tools directly, but use the Cogito tools instead.
+
+If you've only used a centralized version control system like CVS
+before, this package may require a change in how you visualize source
+code management.  With Cogito/GIT, every directory with a checked out
+project is also a repository for that project.  When you commit your
+changes, you are committing them into the repository in the current
+directory, not to the main repository.  In order to have your changes
+show up in the main repository they need to be merged in by a person
+that manages that repository.  This can either be done by mailing them
+a patch containing your changes or by giving them access to your 
+repository and having them pull in your changes.
 
 
 	The Cogito Version Control System
@@ -30,8 +42,11 @@ Cogito can be obtained as a tarball from
 
 	http://www.kernel.org/pub/software/scm/cogito/
 
-Download and unpack the latest version, build with make, put the executables
-somewhere in your $PATH (or add your Cogito directory itself to your $PATH),
+Download and unpack the latest version, build with 
+
+        $ make
+        $ sudo make install
+
 and you're ready to go!
 
 The following tools are required by Cogito:
@@ -43,7 +58,9 @@ The following tools are required by Cogi
 
 The following tools are optional but strongly recommended:
 
-	libcrypto (OpenSSL)
+	libcrypto (OpenSSL) (Cogito also contains an OpenSSL implementation
+        from the Mozilla project.  To use it instead of OpenSSL, build
+        with "make MOZILLA_SHA1=1"
 	rsync
 
 
@@ -67,6 +84,46 @@ That's it! You're now in your own GIT re
 directory. Go into it and look around, but don't change anything in there.
 That's what Cogito commands are for.
 
+Files that you want to add to the repository can be added with
+
+    $ cg-add newfile1 newfile2 ...
+
+When you do some local changes, you can do
+
+	$ cg-diff
+
+to display them.  You can also just show which files have changed by
+
+    $ cg-status
+
+Once you have decided that you want to commit your changes, use the
+
+    $ cg-commit
+
+command, which will present you with the editor of your choice for composing
+the commit message.
+
+If you want to see the changes made to the repository by a certain commit,
+the first thing you need to know is the commit names.  A commit name in
+Cogito/Git is the hash of the commit.  The commit history of the repository
+is displayed with
+
+    $ cg-log
+
+Once you know the name of the commit you want to see, use
+
+    $ cg-diff -r FROM_COMMIT_ID[:TO_COMMIT_ID]
+
+To tag the repository, use cg-tag.  cg-tag defaults to tagging HEAD, but
+you can also give it the name of a commit to tag
+
+    $ cg-tag TAG_NAME [COMMIT_ID]
+
+To display the tags you have in your repository, use
+
+    $ cg-tag-ls
+
+
 	Turning an Existing Directory Into a Repository
 
 If you have a directory full of files, you can easily turn this into a
@@ -198,24 +255,6 @@ the command
 repository). Then you can specify the name to cg-update and cg-pull, or use
 it anywhere where you could use the "origin" name.
 
-When you do some local changes, you can do
-
-	$ cg-diff
-
-to display them.  Of course you will want to commit. If you added any new
-files, do
-
-	$ cg-add newfile1 newfile2 ...
-
-first. Then examine your changes by cg-diff or just show what files did you
-change by
-
-	$ cg-status
-
-and feel free to commit by the
-
-	$ cg-commit
-
 command, which will present you with the editor of your choice for composing
 the commit message.
 
@@ -247,6 +286,9 @@ or, for the same information, try this:
 	The "core GIT"
 	~~~~~~~~~~~~~~
 
+Note that if all you care about is committing some small bits of code
+to a repository, you can stop reading now.
+
 	GIT - the stupid content tracker
 
 "git" can mean anything, depending on your mood.

Re: Patch to make README more newbie-friendly

[Matthias Urlichs]

Hi, Jerry Seutter wrote:

> I'd also like to include stuff about branches, but I haven't gotten my 
> head wrapped around how they work yet.  cg-branch-add expects a location
> after the branch name and I'm not sure what to give it.

Cogito branch creation is based on the idea that you have a different
archive _somewhere_else_ that you pull from, so it wants to store the
source URL in .git/branches/<name>.

Git doesn't have that assumption; "git checkout -b <name>" simply
creates a new branch and switches to it. However, the git branch idea came
somewhat later, so there's a bit of a mismatch at the moment.

Simply switching branches isn't supposed to have any effect unless you
actually have changes in different branches. I tend to work along these
lines:

#!/bin/sh

cd /tmp
rm -rf test.$$
mkdir test.$$
cd test.$$
git-init-db
echo not-quite-empty >testfile
cg-add testfile
echo Created test | cg-commit
git checkout -b one
echo foo >>testfile
echo added foo to testfile | cg-commit
git checkout -b two master
echo bar >> testfile
echo added bar to testfile | cg-commit
cg-diff -r one:two | cat
git checkout master
cg-merge one
cg-merge two

The first merge fast-forwards your master tree to "one"; the second 
creates a conflict (lines were added at the same location) which you'll
have to resolve (edit the file).

vi testfile
echo Merged one and two | cg-commit
gitk

-- 
Matthias Urlichs   |   {M:U} IT Design @ m-u-it.de   |  smurf@smurf.noris.de
Disclaimer: The quote was selected randomly. Really. | http://smurf.noris.de
 - -
Apollo, the God of light, of reason, of proportion, harmony, number --
Apollo blinds those who press too close in worship. Don't look straight
at the sun. Go into a dark bar and have a beer with Dionysos, every now
and then. -- Ursula K. LeGuin