[PATCH] Cogito documentation updates

[PATCH] Cogito documentation updates

[Jonas Fonseca]

 - local cg-fetch now works without the cp option -u
 - note the difference between short and long help in cg-help(1)
 - mention the alien repo importers provided by the git core
 - fix typo in cg-update(1)

Signed-off-by: Jonas Fonseca <fonseca@diku.dk>

---
diff --git a/README.osx b/README.osx
index e82ef79..d8df872 100644
--- a/README.osx
+++ b/README.osx
@@ -9,18 +9,6 @@ You may have to deal with md5 mismatches
 your new Portfile or place the new tarball in
 /opt/local/var/db/dports/distfiles/cogito.
 
-Caveats:
-
-cg-fetch on a local repository requires cp -u, a non-portable gnu
-extension.  This means that cg-fetch, cg-clone and cg-update from a
-local repository are broken.
-
-Workaround #1: Use rsync for local clones.  I.e.  "cg-clone
-rsync://localhost/dir" instead of "cg-clone dir".  This loses the disk
-space savings of normally gained by cg-clone.
-
-Workaround #2: Use gnu cp.  "cd /opt/local/bin; sudo ln -s gcp cp".
-
 Recommendations:
 
 The gnu versions of "stat" and "date" are preferred over their BSD
diff --git a/cg-help b/cg-help
index 6ba7657..5fa65ef 100755
--- a/cg-help
+++ b/cg-help
@@ -8,8 +8,9 @@
 # If the argument is left out an overview of all the Cogito commands will
 # be shown.
 #
-# Note help for a command is also available by passing `--help` or `-h`
-# to the command.
+# Note, short help for a command is also available by passing `--help` or
+# `-h` to the command. The complete command manual is shown when passing
+# `--long-help` (and is the same as doing "`cg-help command`").
 #
 # OPTIONS
 # -------
diff --git a/cg-init b/cg-init
index a0a7372..31c2e10 100755
--- a/cg-init
+++ b/cg-init
@@ -9,7 +9,9 @@
 # This command is intended for creating repositories for work on new projects.
 # If you want to clone an existing project, see `cg-clone`. If you want to
 # set up a public repository not for direct work but only for pushing/pulling,
-# see `cg-admin-setuprepo`.
+# see `cg-admin-setuprepo`. It is also possible to import repositories from
+# other SCMs to GIT, see `git-cvsimport(1)`, `git-svnimport(1)` and
+# `git-archimport(1)`.
 #
 # OPTIONS
 # -------
diff --git a/cg-update b/cg-update
index ed93c01..9d82fcb 100755
--- a/cg-update
+++ b/cg-update
@@ -8,7 +8,7 @@
 # This is similar to running cg-fetch and cg-merge commands successively.
 # Please refer to the documentation of those commands for more details
 # about the operation. Note that if you are not doing own development
-# but only following some project, you it is recommended to use this command
+# but only following some project, it is recommended to use this command
 # instead of `cg-fetch` + `cg-merge` since `cg-update` can handle some
 # additional corner cases (in particular, if the remote branch rebases,
 # `cg-update` will fast-forward instead of doing a tree merge and diverging).

-- 
Jonas Fonseca

Re: [PATCH] Cogito documentation updates

[Randal L. Schwartz]

>>>>> "Jonas" == Jonas Fonseca <fonseca@diku.dk> writes:

Jonas>  - local cg-fetch now works without the cp option -u

But it still requires cp -d, unless some other patch fixed that recently.

-- 
Randal L. Schwartz - Stonehenge Consulting Services, Inc. - +1 503 777 0095
<merlyn@stonehenge.com> <URL:http://www.stonehenge.com/merlyn/>
Perl/Unix/security consulting, Technical writing, Comedy, etc. etc.
See PerlTraining.Stonehenge.com for onsite and open-enrollment Perl training!

Re: [PATCH] Cogito documentation updates

[Jonas Fonseca]

Randal L. Schwartz <merlyn@stonehenge.com> wrote Sun, Nov 20, 2005:
> >>>>> "Jonas" == Jonas Fonseca <fonseca@diku.dk> writes:
> 
> Jonas>  - local cg-fetch now works without the cp option -u
> 
> But it still requires cp -d, unless some other patch fixed that recently.

Ah, yes. I just recently tried local cloning on a FreeBSD box and it
worked fine (apart from it spitting out a few errors, see the log below)
and since the caveat section only mentioned the -u option I thought
everything was fine. However, cloning a specific branch hits the error.
So maybe the caveat section should just be updated to say that the -d
option is required. 

---

$ cg clone cogito cogito-now
defaulting to local storage area
Hard links don't work - using copy
Fetching head...
/home/jonas/src/cogito/.git/HEAD -> .git/refs/heads/.origin-fetching
Fetching objects...
progress: 10289 objects, 16992385 bytes
Fetching tags...
error: missing object referenced by 'refs/tags/junio-gpg-pub'
fatal: protocol error: bad line length character
Failed to find remote refs
unable to get tags list (non-fatal)
New branch: 73874dddeec2d0a8e5cd343eec762d98314def63
Cloned to cogito-now/ (origin /home/jonas/src/cogito available as branch "origin")

$ cg clone cogito#cogito-0.10 cogito-0.10
cp: illegal option -- d
usage: cp [-R [-H | -L | -P]] [-f | -i | -n] [-pv] src target
       cp [-R [-H | -L | -P]] [-f | -i | -n] [-pv] src1 ... srcN
       directory
       cg-fetch: unable to get the head pointer of branch cogito-0.10
       cg-clone: fetch failed

-- 
Jonas Fonseca

Re: [PATCH] Cogito documentation updates

[Randal L. Schwartz]

>>>>> "Jonas" == Jonas Fonseca <fonseca@diku.dk> writes:

Jonas> Ah, yes. I just recently tried local cloning on a FreeBSD box and it
Jonas> worked fine (apart from it spitting out a few errors, see the log below)
Jonas> and since the caveat section only mentioned the -u option I thought
Jonas> everything was fine. However, cloning a specific branch hits the error.
Jonas> So maybe the caveat section should just be updated to say that the -d
Jonas> option is required. 

But instead of targeting GNU tools, why not target POSIX tools where
possible?

I realize I'm being a rebel here.  I want to use git on non-Linux platforms.
I believe git is useful for far more than Linux Kernel development, and
you're this --> <-- close to making it work.

Delete the -d switch, or explain to me why it is there, and let's work
out a POSIX workaround.

I'm not asking for everyone to be cautious when contributing code.
I'll be happy to be "mr portability" and figure out how to make it
still work on OpenBSD and Darwin (my two platforms of choice).

However, as I said in another posting, maybe I just need to understand
the target market first.  (I realize that goal #1 is Linux Kernel
development.)

-- 
Randal L. Schwartz - Stonehenge Consulting Services, Inc. - +1 503 777 0095
<merlyn@stonehenge.com> <URL:http://www.stonehenge.com/merlyn/>
Perl/Unix/security consulting, Technical writing, Comedy, etc. etc.
See PerlTraining.Stonehenge.com for onsite and open-enrollment Perl training!

Re: [PATCH] Cogito documentation updates

[Andreas Ericsson]

Randal L. Schwartz wrote:
>>>>>>"Jonas" == Jonas Fonseca <fonseca@diku.dk> writes:
> 
> 
> Jonas> Ah, yes. I just recently tried local cloning on a FreeBSD box and it
> Jonas> worked fine (apart from it spitting out a few errors, see the log below)
> Jonas> and since the caveat section only mentioned the -u option I thought
> Jonas> everything was fine. However, cloning a specific branch hits the error.
> Jonas> So maybe the caveat section should just be updated to say that the -d
> Jonas> option is required. 
> 
> But instead of targeting GNU tools, why not target POSIX tools where
> possible?
> 
> Delete the -d switch, or explain to me why it is there, and let's work
> out a POSIX workaround.
> 

        -d     same as --no-dereference --preserve=link

        --no-dereference
               never follow symbolic links

        --preserve[=ATTR_LIST]
               preserve   the   specified   attributes  (default:
               mode,ownership,timestamps) and security contexts,
               if possible
               additional attributes: links, all

I don't know how to get those options with POSIX only cp.

> I'm not asking for everyone to be cautious when contributing code.
> I'll be happy to be "mr portability" and figure out how to make it
> still work on OpenBSD and Darwin (my two platforms of choice).
> 
> However, as I said in another posting, maybe I just need to understand
> the target market first.  (I realize that goal #1 is Linux Kernel
> development.)
> 

I'm not Junio, but I think the priorities right now are ordererd like 
this; good performance, fast development, portability.

Good performance because it's designed to handle one of the largest open 
projects there is.

Fast development because it's still a young project but has more 
momentum than most projects, open or closed, ever get. If it slows down 
now it will stay slow until the kernel team needs new features and 
there's no way of recycling inertia.

Portability because that's nice but not vital for the project as a whole 
(it's a linuxish tool, so most users run it on linux so far). I think 
portability usually ends up a bit behind in the race because it often 
hinders #1 and #2.

Again, I'm not Junio. I might be dead wrong.

However, most of the plumbing works on just about anything with a CPU, 
so unless you really need cg-clone you should be able to do it with 
git-clone, which AFAIU uses 'tar' and 'cpio' instead of cp to transfer 
files (for portability reasons, I imagine).

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231

Re: [PATCH] Cogito documentation updates

[Junio C Hamano]

Andreas Ericsson <ae@op5.se> writes:

> I'm not Junio, but I think the priorities right now are ordererd like 
> this; good performance, fast development, portability.

I am, but I am not Pasky, so I cannot talk about priority of
Cogito.

> However, most of the plumbing works on just about anything with a CPU, 
> so unless you really need cg-clone you should be able to do it with 
> git-clone, which AFAIU uses 'tar' and 'cpio' instead of cp to transfer 
> files (for portability reasons, I imagine).

Exactly, because people with portability problems tend to feed
good patches directly to me and to the list.

Re: [PATCH] Cogito documentation updates

[Linus Torvalds]

On Wed, 23 Nov 2005, Randal L. Schwartz wrote:
> 
> Delete the -d switch, or explain to me why it is there, and let's work
> out a POSIX workaround.

It's

       -d:     same as --no-dereference --preserve=link

       --no-dereference
              never follow symbolic links

       --preserve[=ATTR_LIST]
              preserve   the   specified   attributes   (default:  mode,owner-
              ship,timestamps) and security contexts, if  possible  additional
              attributes: links, all

so it's basically making sure that the copy copies the _link_, not the 
file it points to.

I think you may have to use "cpio -p" instead of "cp" to be portable. 
Something like

	cpio -plmu $src $dst

might do it.

		Linus

Re: [PATCH] Cogito documentation updates

[Petr Baudis]

Dear diary, on Wed, Nov 23, 2005 at 06:29:34PM CET, I got a letter
where Linus Torvalds <torvalds@osdl.org> said that...
> 
> 
> On Wed, 23 Nov 2005, Randal L. Schwartz wrote:
> > 
> > Delete the -d switch, or explain to me why it is there, and let's work
> > out a POSIX workaround.
> 
> It's
> 
>        -d:     same as --no-dereference --preserve=link
> 
>        --no-dereference
>               never follow symbolic links
> 
>        --preserve[=ATTR_LIST]
>               preserve   the   specified   attributes   (default:  mode,owner-
>               ship,timestamps) and security contexts, if  possible  additional
>               attributes: links, all
> 
> so it's basically making sure that the copy copies the _link_, not the 
> file it points to.
> 
> I think you may have to use "cpio -p" instead of "cp" to be portable. 
> Something like
> 
> 	cpio -plmu $src $dst
> 
> might do it.

Well, but -l links the files instead of copying them, right? That's
certainly not what I want, I want to really _copy_ the files. Also, does
cpio preserve the hardlinks between the copied files? If not, then what
you wrote is equivalent to

	cp -pRP

which should be even POSIX, hopefully. That's what I changed the -dpR to
now.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
VI has two modes: the one in which it beeps and the one in which
it doesn't.

[PATCH] Cogito documentation updates

[Jonas Fonseca]

 - note the difference between short and long help in cg-help(1)
 - mention the alien repo importers provided by the git core
 - fix typo in cg-update(1)
 - fix help options for the cg(1) manpage

Signed-off-by: Jonas Fonseca <fonseca@diku.dk>

---
diff --git a/Documentation/make-cg-asciidoc b/Documentation/make-cg-asciidoc
index 00e4ce7..51db9e3 100755
--- a/Documentation/make-cg-asciidoc
+++ b/Documentation/make-cg-asciidoc
@@ -79,6 +79,21 @@ else
 	fi
 fi
 
+# cg(1) does not answer to the help options in the same way as the
+# rest of the commands
+if [ "$COMMAND" = "cg" ]; then
+	HELP_OPTIONS="
+-h, --help::
+	Print overview of Cogito commands. Same as gitlink:cg-help[1]."
+else
+	HELP_OPTIONS="
+-h, --help::
+	Print usage summary.
+
+--long-help::
+	Print user manual. The same as found in $TITLE."
+fi
+
 cat <<__END__
 $TITLE
 $TITLELINE
@@ -98,12 +113,7 @@ $DESCRIPTION
 OPTIONS
 -------
 $OPTIONS
-
--h, --help::
-	Print usage summary.
-
---long-help::
-	Print user manual. The same as found in $TITLE.
+$HELP_OPTIONS
 
 $MISC
 
@@ -113,6 +123,6 @@ $COPYRIGHT
 
 SEE ALSO
 --------
-$COMMAND command is part of gitlink:${PACKAGE}[7],
+$COMMAND is part of gitlink:${PACKAGE}[7],
 a toolkit for managing gitlink:git[7] trees.
 __END__
diff --git a/cg-add b/cg-add
index a50c0ac..4611930 100755
--- a/cg-add
+++ b/cg-add
@@ -25,9 +25,8 @@
 # -r::	Add files recursively
 #	If you pass cg-add this flag and any directory names, it will try
 #	to add files in those directories recursively (with regard to your
-#	ignore rules - see cg-status documentation for more detailed
-#	description of those). See also above for more notes about cg-add
-#	vs. directories.
+#	ignore rules - see `cg-status` for a more detailed description of
+#	those). See also above for more notes about cg-add vs. directories.
 
 USAGE="cg-add [-N] [-r] FILE..."
 
diff --git a/cg-help b/cg-help
index 6ba7657..5fa65ef 100755
--- a/cg-help
+++ b/cg-help
@@ -8,8 +8,9 @@
 # If the argument is left out an overview of all the Cogito commands will
 # be shown.
 #
-# Note help for a command is also available by passing `--help` or `-h`
-# to the command.
+# Note, short help for a command is also available by passing `--help` or
+# `-h` to the command. The complete command manual is shown when passing
+# `--long-help` (and is the same as doing "`cg-help command`").
 #
 # OPTIONS
 # -------
diff --git a/cg-init b/cg-init
index a0a7372..31c2e10 100755
--- a/cg-init
+++ b/cg-init
@@ -9,7 +9,9 @@
 # This command is intended for creating repositories for work on new projects.
 # If you want to clone an existing project, see `cg-clone`. If you want to
 # set up a public repository not for direct work but only for pushing/pulling,
-# see `cg-admin-setuprepo`.
+# see `cg-admin-setuprepo`. It is also possible to import repositories from
+# other SCMs into GIT, see `git-cvsimport(1)`, `git-svnimport(1)` and
+# `git-archimport(1)`.
 #
 # OPTIONS
 # -------
diff --git a/cg-update b/cg-update
index ed93c01..9d82fcb 100755
--- a/cg-update
+++ b/cg-update
@@ -8,7 +8,7 @@
 # This is similar to running cg-fetch and cg-merge commands successively.
 # Please refer to the documentation of those commands for more details
 # about the operation. Note that if you are not doing own development
-# but only following some project, you it is recommended to use this command
+# but only following some project, it is recommended to use this command
 # instead of `cg-fetch` + `cg-merge` since `cg-update` can handle some
 # additional corner cases (in particular, if the remote branch rebases,
 # `cg-update` will fast-forward instead of doing a tree merge and diverging).

-- 
Jonas Fonseca