* [PATCH 3/5] Generate Documentation/introduction.html from the README file
2005-08-13 16:23 [PATCHSET] Cogito documentation updates Jonas Fonseca
2005-08-13 16:25 ` [PATCH 1/5] Also install cg-*.txt files Jonas Fonseca
2005-08-13 16:25 ` [PATCH 2/5] Add SEE ALSO section to cogito(7) which mentions git(7) Jonas Fonseca
@ 2005-08-13 16:26 ` Jonas Fonseca
2005-08-13 16:30 ` [PATCH 4/5] Add more AsciiDoc markup to " Jonas Fonseca
2005-08-13 16:31 ` [PATCH 5/5] Ignore patch backup files when finding cg-* manpage scripts Jonas Fonseca
4 siblings, 0 replies; 6+ messages in thread
From: Jonas Fonseca @ 2005-08-13 16:26 UTC (permalink / raw)
To: Petr Baudis; +Cc: git
Convert section names to use AsciiDoc markup. Fix a typo and refer to the
cg-* manpages.
Signed-off-by: Jonas Fonseca <fonseca@diku.dk>
---
Documentation/Makefile | 5 ++++-
README | 36 ++++++++++++++++++++++++------------
2 files changed, 28 insertions(+), 13 deletions(-)
diff --git a/Documentation/Makefile b/Documentation/Makefile
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -4,7 +4,7 @@ CG_SRC=$(filter-out $(CG_IGNORE), $(wild
MAN1_TXT=$(patsubst ../cg-%,cg-%.txt,$(CG_SRC))
MAN7_TXT=cogito.txt
-DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN7_TXT))
+DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN7_TXT)) introduction.html
DOC_MAN1=$(patsubst %.txt,%.1,$(MAN1_TXT))
DOC_MAN7=$(patsubst %.txt,%.7,$(MAN7_TXT))
@@ -54,6 +54,9 @@ clean:
.PRECIOUS: %.txt
+introduction.html: ../README
+ asciidoc -b xhtml11 -d article -f asciidoc.conf -o $@ $<
+
%.html : %.txt
asciidoc -b xhtml11 -d manpage -f asciidoc.conf $<
diff --git a/README b/README
--- a/README
+++ b/README
@@ -1,5 +1,5 @@
- The Cogito Version Control System
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+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
@@ -13,7 +13,8 @@ We shall first describe some quick ways
over each available command one by one.
- Downloading Cogito From Scratch
+Downloading Cogito From Scratch
+-------------------------------
Cogito can be obtained as a tarball from
@@ -39,13 +40,15 @@ The following tools are optional but str
preferred over the BSD variants)
- Starting a Fresh GIT Repository
+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
+Starting an Empty Repository
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To create a new repository with no files in it, cd into an empty directory,
and give the following command:
@@ -59,7 +62,8 @@ 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.
- Turning an Existing Directory Into a Repository
+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
@@ -73,9 +77,11 @@ editor, and you're good to go. All of th
directory are now part of a GIT archive.
- Accessing Someone Else's GIT Repository
+Accessing Someone Else's GIT Repository
+---------------------------------------
- Creating the 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
@@ -114,7 +120,8 @@ When you get your prompt back, do an ls
directory.
- Tracking Others' Work
+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
@@ -170,7 +177,8 @@ since your cg-pull. The alternative and
the cg-merge command, which we shall describe later.
- Other Stuff
+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
@@ -222,10 +230,11 @@ Note that we missed out a lot of stuff h
for merging (cg-merge), moving your tree to an older commit (cg-seek), etc.
- Getting Help
+Getting Help
+------------
Cogito commands come with their own helpful documentation. To get help on
-cg-update, for example, give this command:
+cg-pull, for example, give this command:
$ cg-pull --help
@@ -233,6 +242,9 @@ or, for the same information, try this:
$ cg-help cg-pull
+Additionally, the man pages for the individual commands can be used as a
+reference.
+
You can ask thoughtful questions and make suggestions on the GIT mailing list:
git@vger.kernel.org
--
Jonas Fonseca
^ permalink raw reply [flat|nested] 6+ messages in thread
* [PATCH 4/5] Add more AsciiDoc markup to the README file
2005-08-13 16:23 [PATCHSET] Cogito documentation updates Jonas Fonseca
` (2 preceding siblings ...)
2005-08-13 16:26 ` [PATCH 3/5] Generate Documentation/introduction.html from the README file Jonas Fonseca
@ 2005-08-13 16:30 ` Jonas Fonseca
2005-08-13 16:31 ` [PATCH 5/5] Ignore patch backup files when finding cg-* manpage scripts Jonas Fonseca
4 siblings, 0 replies; 6+ messages in thread
From: Jonas Fonseca @ 2005-08-13 16:30 UTC (permalink / raw)
To: Petr Baudis; +Cc: git
Signed-off-by: Jonas Fonseca <fonseca@diku.dk>
---
I've separated these because they make the README file less readable.
Pick the ones you like, and I will make a new patch.
README | 76 ++++++++++++++++++++++++++++++++++++----------------------------
1 files changed, 43 insertions(+), 33 deletions(-)
diff --git a/README b/README
--- a/README
+++ b/README
@@ -2,10 +2,10 @@ 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
+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
+`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.
@@ -18,27 +18,36 @@ Downloading Cogito From Scratch
Cogito can be obtained as a tarball from
- http://www.kernel.org/pub/software/scm/cogito/
+ - 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),
+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:
- git-core (Cogito is a frontend for git)
- bash, basic shell environment (sed, grep, textutils, mktemp, ...)
- diff, patch
- merge (e.g. from the RCS package)
- wget
+`-------------------------------`----------------------------------------------
+Tool Description
+-------------------------------------------------------------------------------
+git-core Cogito is 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.
+merge E.g. from the RCS package.
+wget For pulling files with the HTTP backend.
+-------------------------------------------------------------------------------
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)
-
+`-------------------------------`----------------------------------------------
+Tool Description
+-------------------------------------------------------------------------------
+rsync For pulling files with the rsync backend.
+gnu coreutils The gnu versions of stat, date and cp \
+ are preferred over the BSD variants.
+ssh For pulling files with the git+ssh backend.
+asciidoc (>= 7.0), xmlto For building documentation.
+-------------------------------------------------------------------------------
Starting a Fresh GIT Repository
-------------------------------
@@ -50,7 +60,7 @@ take an existing directory tree and turn
Starting an Empty Repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-To create a new repository with no files in it, cd into an empty directory,
+To create a new repository with no files in it, `cd` into an empty directory,
and give the following command:
$ cg-init
@@ -58,7 +68,7 @@ and give the following command:
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
+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.
@@ -67,7 +77,7 @@ Turning an Existing Directory Into a Rep
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. Just `cd` into the directory you want converted into a GIT
repository, and give the following command:
$ cg-init
@@ -84,16 +94,16 @@ 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
+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 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.
+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
@@ -107,8 +117,8 @@ new directory be called, as follows:
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.
+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
@@ -116,7 +126,7 @@ 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
+When you get your prompt back, do an ls to see the source tree and `.git`
directory.
@@ -125,14 +135,14 @@ 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
+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
+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.
@@ -141,11 +151,11 @@ When you give the above cg-update comman
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,
+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
+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
@@ -155,14 +165,14 @@ 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
+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,
+your `.git` directory with the history you need to construct your diff,
without merging that history into your tree, potentially breaking your
changes.
@@ -196,7 +206,7 @@ the command
(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.
+it anywhere where you could use the 'origin' name.
When you do some local changes, you can do
@@ -224,7 +234,7 @@ It is nice to be able to examine the com
$ 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.
+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.
--
Jonas Fonseca
^ permalink raw reply [flat|nested] 6+ messages in thread