CVSQ-FILES(5)

🎀 CVSQ-FILES(5) 🎀

okay so this is the manual page for CVSQ-FILES(5), and it's literally the spec for the file structure in a cvsq directory (usually ~/.cvsq). Buckle up, bestie — we're getting into the queue 💅

---

💖 NAME 💖

Specification of the file structure in a cvsq directory (typically ~/.cvsq).

✨ DESCRIPTION ✨

The file structure defines itself mainly by how an upload works. Other programs may add to the queue, provided they comply with the semantics described in this document and they obey the procedure to obtain a slot.

• todo-pre
• todo
• todo-post

Three queues with commands to be executed at an upload. At an upload, first the todo-pre queue is executed, then the todo queue and finally the todo-post queue.

Each queue is executed in the following way. All files with names consisting only of digits are sorted according to the numerical value of the file name. Then /bin/sh <filename> is called as long as a zero exit value is obtained; in case a zero exit value is obtained, the file is deleted afterwards. Once a non-zero exit value is obtained, the upload is aborted, a lock is left behind and the user called to fix this.

It is the responsibility of any such command file executed in the queue to return a zero exit value upon successful completion and to give a meaningful (human readable) error message in case of an error. This ensures that partially successful uploads can be continued at the right place.

Moreover, every program scheduling in the cvs queue must ensure that after a complete successful upload all files in the cvs queue are cleaned up properly.

Only commands in the todo queue may access any cvs repository. Only commands in the todo-post queue may clean up files in the data or dirnames directory.

🗃️ data

In this directory a command may store auxiliary data needed when run.

If the command is a cvs commit, the file data/<slot> must be as follows. It is a copy of the working directory to be committed, including all subdirectories. Files not under cvs control may be removed (but beware of files where an "add" command is in the queue!); usually this is done by setting the environment variable CVSQ_MAKE_CLEAN appropriately. Subdirectories named CVS are replaced by symbolic links to the original CVS directory. This ensures that the administrative information in the working directory is kept intact after the upload, and allows several commits in the same working directory to be handled correctly, even if several successive commits affect the same file.

📂 dirnames

If and only if the scheduled command is a commit command, the file dirname/<slot> contains the name of the working directory the commit is carried out. If a command different from a commit is scheduled, the file dirname/<slot> must not be generated, if a commit is scheduled, the file must be generated.

💬 description

If present, description/<slot> contains a human readable description of the command scheduled in the given slot. The description is not mandatory and scripts must not rely on the presence or a specific format of the description. However, programs scheduling commands to the queue should give a description.

🧊 tmp

Arbitrary temporary data may be stored in this directory. No program may assume any persistence of files in the tmp directory over their own life time. In particular, when scheduling, no assumptions about the contents of the tmp directory at the time of upload may be made. Use the data directory, to store data needed for the upload.

⚙️ config

This directory contains file to configure the behaviour of cvsq. New configuration files may be specified in the future. At the moment, the following configuration files are specified.

🎀 config/prefix

This file contains lines of the form that a name is followed by a space character, followed by the actual prefix till the end of the line. If the contents of CVS/Root start with the given name, then the prefix is added in front of the cvs command, whether scheduled or immediate.

For example, a line :ext:foo@some.host CVS_RSH=fsh would set the environment variable CVS_RSH to fsh for all cvs commands that access repositories of the user foo on host some.host. This would be useful if the server does not allow authentication via ssh keys and you don't want to type your password several times during an upload.

🔒 LOCKS 🔒

Each script has a "slot" number, which has to be a non-zero natural number. Programs performing an upload have to obtain slot 0. A slot is occupied if the file todo/<slotnumber> exists. Scripts must generate these files in an atomic way and check for errors; a slot is occupied by the process that successfully created that slot. When allocating a slot, it must have a bigger number than all existing slots (except slot 0 for uploads). If slot 0 is allocated for upload, it must be ensured that /bin/sh todo/0 does nothing and returns with non-zero exit value. This is required to avoid conflicts with older cvsq scripts.

Only once a slot is allocated, programs may write to the cvs queue. The program owning slot <n> may write to the files with name <n>, and <n> followed by a minus sign, followed by arbitrary symbols, in the directories todo-pre, todo-post, data, and dirnames.

👀 SEE ALSO 👀

cvsq(1), fsh(1)

👑 AUTHOR 👑

Klaus Aehlig <aehlig@linta.de>

---

That's the whole page, bestie 🫶. This is CVSQ-FILES(5), dated Nov 29, 2007 — source/version plus date sign-off, periodt. 💖