save(1)

💖 save(1) · ShapeTools Manual 💖

(part 1 of 2 🎀)

✨ NAME ✨

save is the command that saves a revision of a file 💾

🌸 SYNOPSIS 🌸

save [ version binding options ] [ options ] files ..
Save [ version binding options ] [ options ] files ..

Options: [ -?fglq ] [ -help ] [ -a (or -alias) version alias ]
         [ -delta ] [ -force ] [ -fix generation | alias | date ]
         [ -newgen ] [ -lock ] [ -m (or -logmsg) message ]
         [ -n (or -setvnum) version number ] [ -nodelta ] [ -quiet ]
         [ -setattrs filename ] [ -stdin ] [ -version ]

🦋 DESCRIPTION 🦋

Okay so bestie, save takes a snapshot 📸 of the current state of the files you name, stores them in matching archive files, and gives each new version its own unique version number. By default the original files get removed and unlocked too, which is giving cooperative teamwork vibes 🫶. You can bring a version back as a regular file with the retrv command. Versions sitting in archives are inalterable, meaning they can't be changed 🔒.

⚠️ Heads up: by default the original files get removed after saving (and unlocked too!).

An archive gets created the first time a file is saved, and it lives in a subdirectory named AtFS. That AtFS subdirectory must be present 📁. When an archive is made, save asks you for a short description of the saved document's purpose 📝. If you save a later version, you get prompted for a comment describing the modifications ✍️.

The save command also requires that the version history of a file being saved is locked by the user issuing the command 🔐. This stops different developers from making concurrent updates to the same file and wiping out each other's modifications 💀. The only exception is the first time a file is saved, since there's no archive yet. For more details on locking, see the ShapeTools Tutorial, retrv(1), and vadm(1) 📚.

The save program gives every evolving revision of a file a unique version id 🔢. The version id is a pair of integers separated by a dot, identifying the major and minor revision (<generation>.<revision>) of a version. Each later invocation of save bumps the minor revision number, starting with version 1.0. The generation number goes up when you run Save (see below). There's no explicit branching, because the version control toolkit really wants a linear model 📏.

Instead of branching, save lets you insert new versions into old generations (see -fix). For example, you can fix bugs in major revision N (version numbers N.x), which may be the currently operational release, while development keeps cooking in generation N+1 (or N+n if you like) 🚀.

Before a file is saved, save checks whether it has actually changed with respect to the previously saved version 🔍. If the file hasn't changed, you'll be asked if it should be saved anyway 🤨. The command line option -f (or -force) overrides the prompting 🙅‍♀️.

The version control system has a built-in basic status model for versions 📊. The version status is meant to express different levels of quality, and it aims to give you basic project management functionality 💼. State attributes of software objects can help describe an object's current meaning in the development process, like tested, incompletely implemented, submitted for evaluation, or shipped to customer 🚢.

A newly created version gets the state saved by default 🥱. That's the lowest level of quality, and it basically means it's just saved for possible later retrieval but might be inconsistent 🫠. Versions that meet higher quality standards (or are part of a release) should be marked with an appropriate status instead (see vadm -promote, sbmt, or publ) ⭐.

If the program is invoked as Save (that's capital-S), a new major revision (generation) of the document history is created 👑, provided the programmer issuing the command has permission to do it 🔑. This is for a development model where maintenance of an operational release can happen in parallel with development of the next release (see -fix) 🌈.

---

🎀 OPTIONS 🎀

For version selection, any version binding option described on the vbind(1) manual page can be given 💅. Version bind directives in brackets added to the filename are interpreted differently than they are by vbind(1) 🙃. A version number following the name is treated as if the -n (-setvnum) option was given with that version number as its argument. Any other string in brackets is taken as an alias name (see -alias option) 🏷️.

• -?, -help — pops up a quick summary of how to use this command 🆘 (prints short usage information).
• -a, -alias version alias — slaps a version alias (a symbolic name) onto the new version 🏷️. The attribute __SymbolicName__ gets set to the value of version alias. That alias can't already be assigned to any other version within the same version history 🚫. You can also put the alias in brackets after the filename instead of using -a. Check the -n description for an example of that notation 👀.
• -delta — creates a delta for internal storage. This is the default 💅.
• -f, -force — forces a revision deposit (no asking!) 🚀, even if the busy version hasn't changed since the last time it was saved.
• -fix generation | alias | date — appends a new version after the most recent version within the referenced major revision level 🔧. That level (called "generation") can be referenced explicitly by specifying a number, or implicitly by specifying a version alias (like a release name) or a date 📅. The date form is especially useful for saving a fix that extends over more than one object 🧩.

This option is for maintaining older releases while development keeps going at the logical end of the version chain. To insert a (fixed) version into an old generation, you must have a lock on the most recent version of that generation (the generation lock) 🔒. That lock has to be set with the vadm command. The -fix option is incompatible with -setvnum, -newgen and the Save command option 🙅‍♀️.

• -g, -newgen — creates a major revision of the document 👑. Major revisions are indicated by the first number in the version-id (the generation). Only the archive administrator is allowed to create major revisions 🧑‍💼. The archive administrator is the user who owns the AtFS subdirectory where the version archives reside. Using this switch is identical to calling the program as Save.
• -l, -lock — keeps the lock on the version history 🔐. The saved files will not be removed.
• -m, -logmsg message — sets message as the descriptive note for all document versions that result from running save 📝. When message starts with an at sign (@), it's interpreted as a filename, and the text inside that file becomes the descriptive note for all of those versions 📄.
• -n, -setvnum version number — sets the version number of the newly created revision to version 🔢. The version must be given in the format <generation>.<revision>, where generation and revision are integers. Here's an example:

save -setvnum 4.3 mkattr.c

The specified version must be greater than the highest previously assigned version number in a given object history 📈. Only the archive administrator may set version numbers directly. The archive administrator is the user who owns the AtFS subdirectory where the version archives reside. -setvnum is useful for keeping consistent version numbering across related, physically different object repositories, or for converting archive formats of other revision control systems to this toolkit (see: rcs2atfs) 🔁.

Alternatively to the -n option, the version number can be given in brackets following the name of the file to be saved. The command

save mkattr.c[4.3]

is interpreted the same way as the example above 🧠.

• -nodelta — suppresses delta generation 🙅‍♀️.
• -q, -quiet — quiet operation 🤫. No messages are printed on standard output. If the busy version is unchanged, it won't be saved unless -f is set. The user won't be prompted for a descriptive note. If no message or note is supplied with the command line (see options -m and -t), the log will remain empty. This option is super useful for batch operation 🤖.

✨ AUTHOR ✨

Okay so the two people behind this whole thing are Axel and Andreas 💜, and you can reach them at these addresses:

• Axel: Axel.Mahler@cs.tu-berlin.de 🦋
• Andreas: Andreas.Lampen@cs.tu-berlin.de 🫶

---

That's the whole page, bestie! 🎀 It's save version 4.7 from June 29, 1993, filed under the save(1) manual 🕰️💖 Honestly a total classic, and you handled it like a pro. Stay iconic 👑✨