Cogito documentation updates

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

---

index e82ef79..d8df872 100644
@@ -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

index 6ba7657..5fa65ef 100755
@@ -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
 # -------

index a0a7372..31c2e10 100755
@@ -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
 # -------

index ed93c01..9d82fcb 100755
@@ -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

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
<[email protected]> <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!

Randal L. Schwartz <[email protected]> wrote Sun, Nov 20, 2005:

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

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
<[email protected]> <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!

-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 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                   [email protected]
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231

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

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

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

Dear diary, on Wed, Nov 23, 2005 at 06:29:34PM CET, I got a letter where Linus Torvalds <[email protected]> said that...

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.

- 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

---

index 00e4ce7..51db9e3 100755
@@ -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__

index a50c0ac..4611930 100755
@@ -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..."
 

index 6ba7657..5fa65ef 100755
@@ -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
 # -------

index a0a7372..31c2e10 100755
@@ -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
 # -------

index ed93c01..9d82fcb 100755
@@ -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