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
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.
