The Cogito Version Control System
=================================

Cogito is a version control system layered on top of the git tree history
storage system. It aims at seamless user interface and ease of use, providing
generally smoother user experience than the "raw" Core GIT itself and indeed
many other version control systems.

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

Please note that this document (meant to server as a kind of Cogito tutorial
in the future) is awfully incomplete so far, and the documentation is of a
rather poor quality (since Petr Baudis wrote it). At least the reference
documentation should be of good quality (see the 'Getting help' section
at the bottom of this file).



Installing
----------

If your distribution does not offer Cogito by itself, 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 vitally required by Cogito to do anything useful:

`-------------------------------`----------------------------------------------
Tool				Description
-------------------------------------------------------------------------------
git-core			Cogito is just a frontend for git.
bash				All Cogito executables are scripted in bash.
sed, grep, textutils, etc.	The basic shell environment.
diff, patch			The basic utilities for tracking file changes.
-------------------------------------------------------------------------------

The following tools are very recommended for regular Cogito operation:

`-------------------------------`----------------------------------------------
Tool				Description
-------------------------------------------------------------------------------
merge				E.g. from the RCS package, for merging.
wget				For pulling files with the HTTP backend.
rsync				For pulling files with the rsync backend.
ssh				For pulling files with the git+ssh backend.
-------------------------------------------------------------------------------

The following tools are optional but recommended:

`-------------------------------`----------------------------------------------
Tool				Description
-------------------------------------------------------------------------------
gnu coreutils			The gnu versions of stat, date and cp \
				are preferred over the BSD variants.
asciidoc (>= 7.0), xmlto	For building documentation.
-------------------------------------------------------------------------------



Getting started
---------------

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

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

Note that the 'cogitodir' argument is optional; if you don't specify it,
cg-clone will automatically determine the directory name from the URL - it
would be 'cogito' for the URL we used. (Note that it's safe as cg-clone will
refuse to do anything if the directory already exists.)

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 be also 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 more powerful way is using
the `cg-merge` command, which we shall describe later.



Using Cogito
------------

If there are any changes, two IDs will be printed during `cg-pull` or
`cg-update` run (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 other branches than the one you clones from,
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 pass 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 list 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. (`cg-commit` also has a very convenient command-line
usage.)

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 the branch you cloned from. `cg-log` with no
arguments will default to the history of the current branch. Try also
prepending the `-c` and `-f` options. To only get a brief overview of the
changes, do

	$ cg-log -s


Note that we gave only a glimpse to the basic usage, but there is a lot more
- merging (`cg-merge`), moving your tree to an older commit (`cg-seek`),
pushing (`cg-push`), etc.


Cogito vs. other GIT tools
~~~~~~~~~~~~~~~~~~~~~~~~~~

You can *MOSTLY* use Cogito in parallel with other GIT frontends (e.g. StGIT),
as well as the GIT plumbing and core GIT tools - the tools only need to keep
HEAD in place and follow the standardized `refs/` hierarchy. The only notable
exception is that you should stick with a single toolkit during a merge.



Getting Help
------------

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

	$ cg-pull --help

or, for the same information, try this:

	$ cg-help cg-pull

Alternatively, the man pages for the individual commands can be used as a
reference (their content is equivalent to the cg-help output).
gitlink:cogito[7] is a good starting point.

You can ask thoughtful questions and make suggestions on the GIT mailing list:

	git@vger.kernel.org

or (less preferably) contact the maintainer Petr Baudis <pasky@suse.cz>
directly.
