	The Cogito Version Control System
	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Cogito is a version control system layered on top of the git tree history
storage system. Note that you can MOSTLY use it in parallel of other GIT
frontends (e.g. StGIT), as well as the Linus' GIT plumbing and core GIT
tools - they only need to keep HEAD in place and follow the standardized
refs/ hierarchy. The exception is that you should stick with a single
toolkit during a merge and mostly stick with Cogito while your tree is
in cg-seek'd state.

We shall first describe some quick ways to get started using Cogito, then go
over each available command one by one.


	Downloading Cogito From Scratch

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),
and you're ready to go!

The following tools are required by Cogito:

	bash, basic shell environment (sed, grep, textutils, mktemp, ...)
	diff, patch
	merge (e.g. from the RCS package)
	libcurl

The following tools are optional but strongly recommended:

	libcrypto (OpenSSL)
	rsync
	gnu coreutils (the gnu versions of stat, date and cp are
	           preferred over the BSD variants)


        Starting a Fresh GIT Repository

If you want to start your own project using Cogito, there are two basic ways
to do this. You may start a fresh repository with no files in it, or you may
take an existing directory tree and turn it into a GIT repository.

	Starting an Empty Repository

To create a new repository with no files in it, cd into an empty directory,
and give the following command:

	$ cg-init

Your editor will start up, and you will be asked to type in the initial
commit description. Type something cute, and exit your editor.

That's it! You're now in your own GIT repository. Notice there is now a .git
directory. Go into it and look around, but don't change anything in there.
That's what Cogito commands are for.

	Turning an Existing Directory Into a Repository

If you have a directory full of files, you can easily turn this into a
GIT repository. In fact, it is virtually the same as starting an empty
repository. Just cd into the directory you want converted into a GIT
repository, and give the following command:

	$ cg-init

Your editor starts up, you type in an initial commit message, exit your
editor, and you're good to go. All of the files and directories within that
directory are now part of a GIT archive.


	Accessing Someone Else's GIT Repository

	Creating the Repository

If you want to get started tracking an outside GIT repository, you first
must have Cogito's executables on your $PATH. Next, you need the URL (or
local directory path) of the repository you want to track. You can't just
use the URL of a tarball, like the one given above for the Cogito source.
The URL must point specifically to a .git directory somewhere. For instance,
the URL for Cogito's self-hosting repository is

	http://www.kernel.org/pub/scm/cogito/cogito.git

Notice that the final directory, 'cogito.git', is not called '.git'. That is
fine. It still has the same content as your .git directory.

To clone the repository to your local filesystem, use the cg-clone command.
cg-clone can be told to create a new directory for your repository, or to
drop the repository into the current directory.

To have a new directory created, just invoke cg-clone with the URL.  You can
also include the directory in the command to specify exactly how should the
new directory be called, as follows:

	$ cg-clone http://www.kernel.org/pub/scm/cogito/cogito.git cogitodir

You will see a whole bunch of output, and when it is over there will be a
new directory called 'cogitodir' (or whatever name you chose) in the current
directory. cd into it. Because we used the Cogito URL, you will see the
Cogito source tree, with its own .git directory keeping track of everything.

If, instead, you want to clone the repository to the current directory,
first make sure you are in an empty directory. Then give the following
command:

	$ cg-clone -s http://www.kernel.org/pub/scm/cogito/cogito.git

When you get your prompt back, do an ls to see the source tree and .git
directory.


    Tracking Others' Work

Of course, once you have cloned a repository, you don't just want to leave
it at that. The upstream sources are constantly being updated, and you want
to follow these updates. To do this, cd into the working tree directory (not
the .git directory, but the directory that contains the .git directory), and
give the following command:

	$ cg-update

You don't use a URL anymore. Cogito knows which tree you're tracking, because
this information is stored in the .git directory. The above command will track
the 'origin' branch, which represents the repository you originally cloned.
But cg-update can also be used to track specific branches. See below for more
discussion of branches, and how to track them.

When you give the above cg-update command, this performed two actions.
First, it pulled all new changes from the upstream repository into your
local repository. At that point, the changes exist in your local repository
as part of the project history. The changes themselves are not actually
visible in the files you see, but reside in the .git directory's awareness,
just downloaded and ready to be merged somewhere.  The second thing cg-update
does is to merge these changes into the files you see and work with. The end
result is that, when the cg-update has finished, you will see all the upstream
changes reflected in your local files, and the .git directory will be aware
of the history of those changes as well.

It may be that you want to be aware of the history of the upstream work, but
you don't yet want those changes merged with your own local files. To do
this, give the following command:

	$ cg-pull

This does the first part of cg-update's job, but skips the second part.
Now your local files have not been changed, but your .git directory has been
updated with the history of all the changes that have occurred in the
upstream sources.

Using cg-pull is useful for a variety of purposes, for instance if you want
to construct a diff against the latest version of the upstream sources, but
don't want those changes to disturb your ongoing work. cg-pull will update
your .git directory with the history you need to construct your diff,
without merging that history into your tree, potentially breaking your
changes.

Typically, if you are not making changes to the project yourself, but just
want the latest version of a given project for your own use, you would use
cg-update. cg-pull is strictly for development work.

Once you've done a cg-pull, you may decide you want to merge after all. In
this case a cg-update command will do the trick, however you will also
update your local files with any further upstream changes that have occurred
since your cg-pull. The alternative and much more powerful way is using
the cg-merge command, which we shall describe later.


	Other Stuff

If there are any changes, two IDs will be printed (I mean the line saying
"Tree change"). Pass those as parameters to cg-diff and you will get a diff
describing changes from the last time you pulled. You can also

	$ cg-diff -r origin:HEAD

which will show changes between the cloned branch and your current branch
(shall you do any modifications).

Note that you can also access the Linus' official branch, by adding it with
the command

	$ cg-branch-add name repourl

(the repourl can have a fragment part identifying a branch inside of the
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.

It is nice to be able to examine the commit history. We have tool for that too.

	$ cg-log -r origin

will get you the history of my branch. cg-log with no arguments will default
to the history of the current branch. Try prepending the "-c" and "-f" options.

Note that we missed out a lot of stuff here. There is already support
for merging (cg-merge), moving your tree to an older commit (cg-seek), etc.


	Getting Help

Cogito commands come with their own helpful documentation. To get help on
cg-update, for example, give this command:

	$ cg-pull --help

or, for the same information, try this:

	$ cg-help cg-pull
