MAKEPATCH(1p)

📦
version 2.03 · 6 versions
, in debian bookworm, ubuntu noble

okay so bestie, this is MAKEPATCH(1p) — User Contributed Perl Documentation — MAKEPATCH(1p) 💖 no cap, we're about to get into it.

✨ NAME ✨

makepatch — create script to update a source tree. periodt 💅

🌸 SYNOPSIS 🌸

makepatch [ options ] old-src new-src

like, that's the whole command vibe ✨

🦋 Introduction 🦋

Traditionally, source trees are updated with the patch program, processing patch information that is generated by the diff program. Although diff and patch do a very good job at patching file contents, most versions do not handle creating and deleting files and directories, and adjusting of file modes and time stamps. Newer versions of diff and patch seem to be able to create files, and very new versions of patch can remove files. But that's about it. ngl, that's the tea 🍓

Another typical problem is that patch kits are typically downloaded from the Internet, or transmitted via electronic mail. It is often desirable to verify the correctness of a patch kit before even attempting to apply it. vibe check first, bestie ✨

The makepatch package is designed to overcome these limitations. slay 💅

💖 DESCRIPTION 💖

The makepatch package contains two Perl programs: makepatch and applypatch. two icons, one package 👑

makepatch will generate a patch kit from two source trees. It traverses the source directory and runs a diff on each pair of corresponding files, accumulating the output into a patch kit. It knows about the conventions for patch kits: if a file named "patchlevel.h" exists, it is handled first, so patch can check the version of the source tree. Also, to deal with the non-perfect versions of patch that are in use, it supplies "Index:" and "Prereq:" lines, so patch can correctly locate the files to patch, and it relocates the patch to the current directory to avoid problems with creating new files. the way it just handles all that? iconic 🌈

The list of files can be specified in a so called MANIFEST file, but it can also be generated by recursively traversing the source tree. Files can be excluded using shell style wildcards and Perl regex patterns. wildcards and regex? we love a flexible queen 🎀

But that is not it! makepatch also inserts some additional information in the patch kit for use by the applypatch program. not me being extra in the best way 💅

It is important to emphasize that the generated patch kit is still valid input for patch. When used with patch, there are no verifications and problems may arise when new files need to be created. makepatch prepends a small shell script in front of the patch kit that creates the necessary files and directories for the patch process. If you can not run applypatch for some reason, you can run the patch kit as a shell script to prepare the source directory for the patching process. fr fr, that's the backup plan 🫶

The applypatch program will do the following:

  • It will extensively verify that the patch kit is complete and not corrupted during transfer. trust but verify, bestie ✨
  • It will apply some heuristics to verify that the directory in which the patch will be applied does indeed contain the expected sources. vibe check on the directory 👀
  • It creates files and directories as necessary. new file fairy 🧚
  • It applies the patch by running the patch program. the main event 🔥
  • Upon completion, obsolete files, directories and ".orig" files are removed, file modes of new files are set, and the timestamps of all patched files are adjusted. cleanup era 🧹

Note that applypatch only requires the patch program. It does not rely on a shell or shell tools. This makes it possible to apply patches on non-Unix systems. cross-platform queen 👑

✨ General usage ✨

Suppose you have an archive "pkg-1.6.tar.gz"' containing the sources for package "pkg"' version 1.6, and a directory tree "pkg-1.7"' containing the sources for version 1.7. The following command will generate a patch kit that updates the 1.6 sources into their 1.7 versions:

makepatch pkg-1.6.tar.gz pkg-1.7 > pkg-1.6-1.7.patch

To apply this script, go to the directory containing the 1.6 sources and feed the script to applypatch:

cd old/pkg-1.6
applypatch pkg-1.6-1.7.patch

applypatch will verify that it is executing in the right place and make all necessary updates. no cap, it's got your back 🫶

By default, makepatch will provide a few lines of progress information, for example:

Extracting pkg-1.6.tar.gz to /tmp/mp21575.d/old...
Manifest MANIFEST for pkg-1.6 contains 1083 files.
Manifest MANIFEST for pkg-1.7 contains 1292 files.
Processing the filelists ...
Collecting patches ...
  266 files need to be patched.
  216 files and 8 directories need to be created.
  7 files need to be removed.

applypatch will provide no feedback information by default. silent but deadly efficient 💅

🎀 Makepatch arguments 🎀

makepatch requires two arguments: old_src and new_src. two besties, one job 💖

  • old-src — This is the name of either a single file or a directory that contains copies of the older version of the target files; in other words, copies of the files prior to any modifications. Alternatively, it may be the name of an archive that holds the files to be processed. Allowable archive formats are gzipped tar (name ends in ".tar.gz" or ".tgz"), bzipped tar (name ends in ".tar.bz2"), plain tar (name ends in ".tar" and zip (name ends in ".zip"). so many formats, we love options ✨
  • new-src — This is the name of either a single file or a directory that contains copies of the newer version of the target files; in other words, copies of the files after the modifications have been made. Alternatively, it may be the name of an archive that holds the files to be processed. same energy, newer files 🦋

The patch script generated by makepatch will take care of creating new files and directories, update existing files, and remove files and directories that are no longer present in the new-src directory. it does it all, bestie 👑

💜 MANIFEST files 💜

The purpose of a manifest file is to provide the list of files that constitute a package. Manifest files are traditionally called "MANIFEST" and reside in the top level directory of the package. the guest list, but for files 📋

Although there is no formal standard for the contents of manifest files, makepatch uses the following rules:

  • If the second line from the manifest file looks like a separator line (e.g. it is empty, or contains only dashes), it is discarded and so is the first line. bye bye separator 👋
  • Empty lines and lines that start with a "#" are ignored. comments? not today 🙈
  • If there are multiple space-separated "words" on a line, the first word is considered to be the filename. first word takes the crown 👑

🌸 Default treatment 🌸

By default, makepatch looks for files named "MANIFEST" in the top level directories of the old and the new source trees. If these files (or one of them) are found, they are used. If no manifest file could be found, the package is assumed to consist of all files in the directory. no manifest? no problem ✨

The default name of the default manifest file can be modified with the command line option -automanifest, see Section "Command line options". customization unlocked 🔓

🦋 Explicitly naming of manifest files 🦋

Command line options -oldmanifest and -newmanifest can be used to explicitly designate old and new manifest files. Option -manifest is a short way to set one manifest file for both the old and new source trees. one for both? efficient queen 💅

✨ Suppress manifest file processing ✨

Command line option -nomanifest can be used to suppress all manifest file processing. The package is assumed to consist of all files in the source directories. manifest? cancelled 🚫

💅 Makepatch options 💅

makepatch takes several options to control its behaviour. Options are usually specified on the command line, but makepatch can take options from three sources in the following order:

  • Environment variable MAKEPATCHINIT. When this environment variable is set its contents are considered to be command line options that are processed upon startup. All normal options are allowed, plus one: -rcfile filename. Option -rcfile can be used to specify an alternate option file, see below. startup vibes ✨
  • Options files. makepatch first tries to process a file named /etc/makepatchrc. (This is a Unix-ism.) It is okay if this file is missing. no pressure if it's not there 🫶 Next, makepatch will process a file named .makepatchrc in the user's home directory, if it exists. home sweet home 🏠 After processing this file, makepatch will process a file named .makepatchrc in the current directory, if it exists. An alternative name for this file can be specified with option -rcfile in environment variable MAKEPATCHINIT. This is the only way to specify an alternative options file name. one special trick, iykyk 🤫 In all option files, empty lines and lines starting with ";" or "#" are ignored. All other lines are considered to contain options exactly as if they had been supplied on the command line. same rules, same vibe 💅
  • The command line. the final say, periodt 👑

💫 Command line options 💫

Okay bestie, quick vibe check before we dive in: options are matched case insensitive, and you're allowed to abbreviate them to uniqueness — so as long as your lil shorthand can't be confused with anything else, you're golden. ✨

  • -description text — hand over a descriptive text for this patch. And guess what, you can stack them: multiple -description options may be supplied. 👑

If you don't provide a description, the program will try to guess one. That's usually possible when both directories are simple names, e.g. "pkg-1.16". And if no description can be determined? It will literally just ask you for one. Not me being interrogated by a patch generator. 😭

  • -diff cmd — if you specify it, cmd is the command used to generate the differences between the two versions of the files. If you don't specify it, this command defaults to diff -c.

For best results, only use diff -c or diff -u. And in any case, it must produce either context or unified diff output. No cap.

  • -patchlevel pfile — if specified, pfile points at an alternate file to be used in lieu of patchlevel.h. 🎀
  • -automanifest mfile — makepatch will automatically use manifest files of the given name if they show up in the directories. The default name is MANIFEST.
  • -nomanifest — suppresses using manifest files. Simple as that. 🙈
  • -manifest mfile — if specified, mfile is the name of the manifest file that consists of a list of the files contained in both the old and the new directories.
  • -oldmanifest omfile — if specified, omfile is the name of the manifest file that consists of a list of the files contained in the old directory. This one is designed to be used in conjunction with the -newmanifest option. Note that the old and new directories must still be indicated. 🫶
  • -newmanifest nmfile — if specified, nmfile is the name of the manifest file that consists of a list of the files contained in the new directory. Designed to pair with the -oldmanifest option. And yes, again: the old and new directories must still be indicated.
  • -[no]recurse — makepatch recurses through directories by default. The option -norecurse prevents recursion beyond the initial directories.
  • -[no]follow — if set, symbolic links to directories are traversed as if they were real directories. 🦋
  • -infocmd command — if specified, the output of running command gets added before each patch chunk. Before that happens, command undergoes the following substitutions: %oP is replaced by the name of the old file, %nP is replaced by the name of the new file. %% is replaced by a single %; other % sequences may be added in future versions. When a new file is being created, the name of the new file will be supplied for both %oP and %nP.

Note that %oP and %nP are modeled after the % sequences of find -printf. iykyk 💅

  • -exclude pattern — if specified, files matching the shell pattern pattern will be excluded. Only the wildcard characters * and ?, and character classes [...], are handled. Multiple -exclude options may be supplied.
  • -exclude-regex pattern — if specified, files and directories matching the Perl regular expression pattern will be excluded. Multiple -exclude-regex options may be supplied. 🔥
  • -[no]exclude-standard — set by default. If set, a common set of files and directories are ignored.

See also the section "Standard Exclude Patterns".

  • -[no]exclude-cvs — if set, files and directories that are usually part of version control system CVS are excluded.

Also, .cvsignore files are honoured just like CVS does it. Respectfully. 🙏

See also the section "Standard Exclude Patterns".

  • -[no]exclude-rcs — if set, files and directories that are usually part of version control system RCS are excluded.

See also the section "Standard Exclude Patterns".

  • -[no]exclude-sccs — if set, files and directories that are usually part of version control system SCCS are excluded.

See also the section "Standard Exclude Patterns".

  • -[no]exclude-vc — short for (re)setting -exclude-rcs, -exclude-cvs, and -exclude-sccs. One option, three jobs. Main character energy. 👑
  • -[no]ignore-cvs-keywords — differences in CVS keyword data (e.g. Id, Header, Revision) are ignored, provided there are no other differences in the same hunk. Heads up: this option passes a very hairy regex to the --ignore-matching-lines option of the diff program, and hence requires GNU diff. This restriction may be lifted in a future version.
  • -[no]ignore-rcs-keywords — same as -[no]ignore-cvs-keywords. Twin behaviour, no notes. 💀
  • -extract pattern=command — defines additional extraction rules for archives. If the name of the source or destination matches the Perl pattern, the command is executed with the archive on standard input and the current directory set to the location where the files must be extracted. Multiple -extract options may be supplied. User defined rules override built-in rules.

Builtin rules are:

.+\.(tar\.gz|tgz)    => "gzip -d | tar xpf -"
.+\.(tar\.bz2)       => "bzip2 -d | tar xpf -"
.+\.tar              => "tar xf -"
.+\.zip              => "unzip -"

The patterns are implicitly anchored to the begin and end of the filename.

  • -[no]ident — if set, the program name and version is reported. Flex those credentials. 🎀
  • -[no]verbose — this is set by default, which makes makepatch display information concerning its activity to stderr.
  • -[no]quiet — the opposite of -verbose. If set, this instructs makepatch to suppress the display of activity information. 🤫
  • -[no]help — if set, this causes a short help message to be displayed, after which the program immediately exits. Wham, bam, thank you ma'am. ✨

🌸 Standard Exclude Patterns 🌸

The following file patterns are always excluded, no matter what:

*~ *.a *.bak *.BAK *.elc *.exe *.gz *.ln *.o *.obj
*.olb *.old *.orig *.rej *.so *.Z
.del-* .make.state .nse_depinfo core
tags TAGS

Option -exclude-sccs adds:

p.* s.* SCCS

Option -exclude-rcs adds:

,* *,v RCS RCSLOG

Option -exclude-cvs adds .cvsignore patterns, and:

.#* #* _$* *$ CVS CVS.adm cvslog.*

Please let me know if I missed some. 🥺

🌈 Environment variables 🌈

  • MAKEPATCHINIT — when this environment variable is set, its contents is considered to be command line options that are processed upon startup. All normal options are allowed, plus one: -rcfile filename. If -rcfile is specified, the file is read and all lines of it are considered to contain option settings as described in the section "Makepatch options".
  • TMPDIR — TMPDIR can be used to designate the area where temporary files are placed. It defaults to /tmp.
  • TEMP — TEMP can be used as an alternative to TMPDIR. ✨

🦋 Examples 🦋

Say you've got a directory tree "pkg-1.6" holding the sources for package "pkg" version 1.6, and a directory tree "pkg-1.7" holding the sources for version 1.7. This command right here will generate a patch kit that updates the 1.6 sources into their 1.7 versions:

makepatch pkg-1.6 pkg-1.7 > pkg-1.6-1.7.patch

To apply this script, go to the pkg-1.6 directory and feed the script to applypatch:

cd old/pkg-1.6
applypatch pkg-1.6-1.7.patch

applypatch will verify that it is executing in the right place and make all necessary updates. Iconic behaviour, honestly. 💅

And this is one way to generate and use manifest files:

(cd pkg-1.6; find . -type f -print > OLDMANIFEST)

(cd pkg-1.7; find . -type f -print > NEWMANIFEST)

makepatch \
  -oldmanifest pkg-1.6/OLDMANIFEST \
  -newmanifest pkg-1.7/NEWMANIFEST \
  pkg-1.6 pkg-1.7 > pkg-1.6-1.7.diff

💀 Bugs and restrictions 💀

Much of the job of makepatch is processing file names. makepatch has been tested extensively on Unix systems, but it is not guaranteed to work on other systems.

applypatch is repeatedly reported to correctly process makepatch generated patch kits on modern 32-bit Windows systems as well. Slay, honestly.

makepatch does not know about symbolic links. These will be treated like plain files. 🫠

Wrong results can be generated if the file lists that are used or generated use different path separators. Consider yourself warned.

🎀 SEE ALSO 🎀

applypatch(1), diff(1), patch(1), perl(1), rm(1).

👑 AUTHOR AND CREDITS 👑

Johan Vromans (jvromans@squirrel.nl) wrote the program, with a little help and inspiration from: Jeffery Small, Ulrich Pfeifer, Nigel Metheringham, Julian Yip, Tim Bunce, Gurusamy Sarathy, Hugo van der Sanden, Rob Browning, Joshua Pritikin, and others. Shoutout to the whole squad. 🫶

This program is Copyright 1992,2004,2006 by Squirrel Consultancy. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of either: a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or b) the "Artistic License" which comes with Perl.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details.

And that's the whole page, bestie — this lil writeup rode in on perl v5.34.0, dated 2022-08-25, wearing its MAKEPATCH(1p) name tag. Go forth and patch. 🌈💜

📦 where this page comes from