What Are Patches?
Finding a Patch
Required Tools
Applying diffs
Applying tars
Tool Sources
Author(s)
tardiff Reference
tardiff Main Page
tardiff Project Page
|
What Are Patches? Finding a Patch Required Tools Applying diffs Applying tars Tool Sources Author(s) tardiff Reference tardiff Main Page tardiff Project Page |
In every modem user's life (I'm still not sure about those broadband users:)), there comes a time when we simply throw up our hands, scream, and search out the nearest developer's neck to wring because of the sheer rediculous size of the files we have to download to upgrade, regardless of if the upgrade is Microsoft's latest patch du jour or FlightGear's newest 80+ MB base package (although at least the source downloads are a reasonable size!) of which maybe 22 MB actually differs from the last version's base package. This is even more maddening when the package isn't even available for a whole day, and we only managed to get... oh, maybe 1/8th?In a search for an answer (and a way to stay somewhat sane...), we try to find ways to speed up our connections or reduce the amount of stuff we need to download. Patches do the second, either by noting specific changes to be made to individual files or including only the things that have changed.
Unfortunately, patches can sometimes cause headaches of their own. This page is here to help you understand the problems, how to avoid them, and (most of all) how to approach applying patches such that we will have the least need for some headache medicine possible. Unfortunately, if you're looking for a way to relieve the headache of dealing with Microsoft's patches, you won't find it here; sorry.
Your situation will depend somewhat on your operating system, the tools you have available, and what patches (if any) are available for the package of interest. Of course, patches are absolutely useless if you don't have the requisite package already.
Patches come in many different forms.Some, like those generated by tardiff, are normal archives that contain only the files that have changed between two versions of a package, plus a script (or two) that complete the transformation -- deleting files that no longer exist in the new release (which can't be done within the confines of the archive format), moving files to their new locations in the directory structure (instead of including an entire copy of a file you should already have), and copying files (accounting for duplicates within the release, again saving space). If you already have an appropriate patch (generated by tardiff, by some other program, or by hand), and just want to know how to use it, just go here.
Others function at a smaller, and therefore possibly more efficient, level. diff, for example, is commonly used to note differences between text files, and especially source code files (which are frequently textual). By operating at the line-by-line level, instead of file-by-file, diff can generate patches that can be applied to many versions of a file, instead of just the original, and it provides some context to the changes as well. If the desired patch is between two versions of source code, unified diff patches are the way to go. If you already have an appropriate unified diff patch, which commonly has an extention of "
.patch", and just want to know how to use it, just go here.Unfortunately, diff patches aren't as useful on binary data as they are on text -- the output of diffing one Windows
.WAVfile with another is usually "erase the entire first file and add the entire second file", also known as "doubling the download time, halving the fun". For this reason, diff usually tries to get away with saying nothing more than "Binary files ... differ" if the files being compared aren't the same, though the diff user can force it to treat the file as text anyway. There may be other patch-generation programs out there that behave similarly to diff, but act on a byte-by-byte level -- I've heard of xdelta and bdiff -- but I don't know anything about them.
In order to find a patch, three bits of information are needed.
First, what package is a patch wanted for?
Second, what revision or version is being used now? (If "none", patches aren't going to help you.)
Third, what revision/version is desired?In other words, it's necessary to know where you're coming from and going to, and on what map. Applying a 1.0 to 1.1 patch will rarely do any good if all you already have is version 0.1, though it may be useful if you have version 1.1 and want to downgrade to 1.0 (if the patch can be "reverse applied" in this way).
Once you know this, you can look for any available patches. Many developers provide patches from one version to the next, so checking the package's web pages can be rewarding. Failing that, try using Google or other search engines to look for the patch; "FlightGear base patch 0.9.4 0.9.5" might find a patch for the FlightGear base package from version 0.9.4 to 0.9.5. If you can find a helpful broadband user who either has or can get both versions of the package, he (or she) may be willing to create a patch for you, but don't pester them. Try to find another source first, or the helpful broadband user might become very annoyed that you didn't do your homework first. If you have to ask, try to be complete; it'll frustrate both you and the helper if she (or he) creates a patch that you can't possibly use.
If you can't get a patch directly from the version you have to the version you want (or need), you may be able to find a series of patches that will get you up to speed -- 0.1 to 0.2, 0.2 to 0.5, 0.5 to 1.0, and 1.0 to 1.1, for example. Before you start downloading, though, be sure to check on the size of each patch and add them up; they may, in total, be larger than a complete download of the package version you're wanting! In general, the longer the patch chain, the less likely it will be shorter than the full version.
Before downloading those new-found patches, it's a good idea to work out what tools will be needed to actually use (or apply) them. If the tool isn't already installed, be sure to install it before getting the patch; it's possible that it won't install on your system, and it would be very frustrating to find this out only after downloading everything.Exactly what tools are available will depend somewhat on your operating system, although there are ways to use Unix tools under Windows, or Windows tools under Unix (for example).
If the tool isn't already installed, be sure to install and (if possible) test it. Especially if the tool is for some other platform, and it's being run under emulation, testing it may save a lot of time and aggrevation. A tool that won't even start -- or worse, causes a segmentation fault when starting up -- is about as useful as a screwdriver that has been bent into a "U" shape.
To know what tools are needed, knowing the kind of patch being dealt with is essential. Having a tool to (all by itself and with no outside help) untar a gzip'd archive doesn't help much when applying a unified diff patch.
Some patches will not need any tools because they are completely self-contained. These will often have instructions on how to use them on the same web page as the link to the patch; read any instructions carefully, as instructions are often written only after someone else has already had a problem. These patches may be intelligent enough to find the previous version and patch it on their own when run; they may ask where to find the previous version; or they may assume that they were run in the correct directory to apply the patch from (and may or may not complain if run from the wrong place); and so on. Some self-contained patches work wonderfully and are well written, and some are not; in general, it's best to assume that it isn't well written (unless previous experience with their patches shows that they are) and try to guess what directory the patch should be run from, and then run it. Self-contained patches (and packages) typically have the extention "
.exe" (on Windows) or ".sh" (on a Unix). (Technically speaking, ".sh" is usually a shell script that uses the shell program, but most Unixen have one, so it isn't usually a concern.)A patch with the extention "
.tar", ".tgz", ".tar.gz", or ".tar.bz2" is usually a normal archive, possibly with completion scripts. These require tar, a very common program on Unixen, to extract them, and are (of course) known as "tar archives." ".tgz" and ".tar.gz" indicate that the archives have been compressed with the gzip program, which will typically be needed to decompress them. ".tar.bz2" indicates the bzip2 program was used to compress the archive, and is typically needed to decompress it. If the archive contains a script to finish up, sh (Unixen) or cmd.exe (Windows) will be needed to run that script, but these programs are typically a part of every installation. Note that cmd.exe won't run.shshell scripts, and sh won't run.batfiles, though. Most patches of this kind should be fairly similar to the patches generated by tardiff, as far as applying them goes. Go here for help on how to apply this kind of patch.A patch with the extention "
.patch" is commonly generated by the diff program; a program called (sensibly enough) patch (on Unixen) is commonly used to apply them. Once the patch program is acquired, the patch can be confirmed as being made by diff by looking at the first few lines of the patch, which should (typically) be similar to or include something similar to:Unlike most other patch applicators listed here, patch is reversible (i.e. a patch from 1.0 to 1.1 can also be used to get from 1.1 to 1.0). Go here for help on how to apply unified diff patches.--- original-filename.c Sun Aug 15 09:46:08 2004 +++ new-filename.c Tue Aug 31 19:05:57 2004 @@ -7,14 +9,12 @@ /* Ground-level atmospheric interface equations: - This equation is only valid for hills and valleys within the lowest slice. + These equations are valid in any slice containing this interface. */There are certainly other kinds of patches, but this page does not cover them.
patch [ -p -p or --strip= : Specify number of directory levels to strip dLevel ] [dLevel : Directory level
This causes patch to strip off (or discard, or ignore) the number of leading directory levels given here. Any number of adjacent slashes count as a single directory level. See "Determining Location of Use" for details on how this argument is important.-b ] [-b or --backup : Create backups
This option causes patch to create a backup of each file it changes. The backup file will (by default) be created with ".orig" tacked to the end of the original filename. Note that a backup is created by default if the patch does not match the file exactly.-d -d or --directory= : Change directory before applying patch directoryName ] [directoryName : New current directory
This causes patch to change to the given directory before doing anything else. This is mostly useful to avoid needing to type in the directory the patch is located in (in favor of typing in the directory the patch will be "based in").-l ] [-l or --ignore-whitespace : Ignore amount/type of white space
Allow the white space (tabs and spaces) in contexts to vary, while still requiring the existance of white space at the same places otherwise.-R ] <-R or --reverse : Reverse direction of the patch
If the patch is from version 1.0 to 1.1, this will cause this application to change version 1.1 to version 1.0 instead. This is also useful if someone accidentally made the patch the wrong way around.patchFile patchFile : name of patch file (source)
cat patchFile [|patchFile : name of patch file (source) cmpProgram ] | patch [cmpProgram : compression program invocation
If the patch file is compressed (i.e. it's filename ends with ".gz" or ".bz2"), it needs to be decompressed for patch to work with it.
If it's not compressed, this stage of the pipeline can be left out.
In case of gzip-compressed files (i.e. filename ends with ".gz"), use gzip -dc -
In case of bzip2-compressed files (i.e. filename ends with ".bz2"), use bzip2 -dc -
Other decompression programs here may have different arguments.-p -p or --strip= : Specify number of directory levels to strip dLevel ] [dLevel : Directory level
This causes patch to strip off (or discard, or ignore) the number of leading directory levels given here. Any number of adjacent slashes count as a single directory level. See "Determining Location of Use" for details on how this argument is important.-b ] [-b or --backup : Create backups
This option causes patch to create a backup of each file it changes. The backup file will (by default) be created with ".orig" tacked to the end of the original filename. Note that a backup is created by default if the patch does not match the file exactly.-d -d or --directory= : Change directory before applying patch directoryName ] [directoryName : New current directory
This causes patch to change to the given directory before doing anything else. This is mostly useful to avoid needing to type in the directory the patch is located in (in favor of typing in the directory the patch will be "based in").-l ] [-l or --ignore-whitespace : Ignore amount/type of white space
Allow the white space (tabs and spaces) in contexts to vary, while still requiring the existance of white space at the same places otherwise.-R ]-R or --reverse : Reverse direction of the patch
If the patch is from version 1.0 to 1.1, this will cause this application to change version 1.1 to version 1.0 instead. This is also useful if someone accidentally made the patch the wrong way around.
patchFile The name of the patch file to apply. cmpProgram If the patch file is compressed (i.e. it's filename ends with ".gz" or ".bz2"), it needs to be decompressed for patch to work with it.
If it's not compressed, this stage of the pipeline can be left out.
In case of gzip-compressed files (i.e. filename ends with ".gz"), use gzip -dc -
In case of bzip2-compressed files (i.e. filename ends with ".bz2"), use bzip2 -dc -
Other decompression programs here may have different arguments.-p dLevel or --strip=dLevel This causes patch to strip off (or discard, or ignore) the number of leading directory levels given here (as dLevel). Any number of adjacent slashes count as a single directory level. See "Determining Location of Use" for details on how this argument is important.
If not present, patch will strip off all directory levels, and will try to find each file to patch in the current directory.-b or --backupThis option causes patch to create a backup of each file it changes. The backup file will (by default) be created with ".orig" tacked to the end of the original filename. Note that a backup is created by default if the patch does not match the file exactly. -d directoryName or --directory=directoryName This causes patch to change to the directory directoryName before doing anything else. This is mostly useful to avoid needing to type in the directory the patch is located in (in favor of typing in the directory the patch will be "based in"). -l or --ignore-whitespaceAllow the white space (tabs and spaces) in contexts to vary, while still requiring the existance of white space at the same places otherwise. -R or --reverseReverses the direction of the patch; if the patch is from version 1.0 to 1.1, this will cause this application to change version 1.1 to version 1.0 instead. This is also useful if someone accidentally made the patch the wrong way around.
Once a patch has been acquired and the tools are ready for use, there are only two steps left: Finding where the patch is to be applied at, and running the patch program appropriately. Because of the -p and -d options, these two steps are somewhat intermingled for this kind of patch.Regardless of the kind of patch being applied, the first step of finding where to apply it to is the same: Most, if not all, patches are installed near where the package being patched was originally installed to.
Next, look at the beginning of the patch for a set of lines similar to:
--- old/location/src/main.c Sun Aug 15 09:46:08 2004 +++ new/location/src/main.c Tue Aug 31 19:05:57 2004 @@ -7,14 +9,12That is, a set of three lines, the first of which begins with "
---", the second begins with "+++", and the third begins with "@@" (followed by two pairs of numbers, the first with a "-" and the second with a "+" before them). In a unified diff patch, each of these sequence of lines sets off a file to be patched. As a patch applier, you'll be interested in the parts that have been underlined above -- the filenames.The names may not always be as similar as shown above; for example, instead of
main.c, the files could be namedmain.c.oldandmain.c, ormain.candmain.c.new. If one of the filenames is/dev/null, the section is for either a new file, or an old one that was deleted; continue looking through the patch for another file to be patched, indicated as above.Once you've found one, it's time to determine what dLevel to use with -p and where to apply the patch at. This is done by searching for a file with either of the file names (forgetting the path given for the moment) within where the package was installed, then "backtracking" the level and location.
In this case, running "
find . -name main.c" would find all files named "main.c" under the current directory; you can look through the choices for the one with the nearest match, i.e. a match of./roadHog-1.0/src/main.cis a better match than./roadHog-1.0/main.cor./atlas/src/main.c(assuming the package of interest is named "roadHog" instead of "atlas"). Next, determine the level of commonality; between./roadHog-1.0/src/main.candold/location/src/main.c, thesrc/main.cis common; theold/location/part of the path needs to be stripped. Counting the number of path separators (/on Unixen) and remembering that///is counted as a single separator to patch, we find that two directory levels need to be stripped, giving us the argument-p2. Finally, we look at the portion of our match that wasn't common (in this example,./roadHog-1.0/); this is the directory the patch needs to be applied to. patch gives two choices; either change directory first (cd ./roadHog-1.0/) before running patch, and give the location of the patch accordingly, or use the-doption (-d ./roadHog-1.0/). Add any other options needed from above to the command line, and go! If neither filename can be found, try looking for another file to be patched within the patch, and try again.Sometimes (though this should be very rare), the patch may not include any changes at all, only additions and removals. In these cases, you may need to guess. Try looking for the last directory in the path of the filenames, and look for commonalities as above. If you can, use more than one of the files to be patched and try to confirm the choices made. In these cases, not all directories given may exist yet, so persistence may be necessary.
While running, patch will provide some commentary on its progress and the problems encountered; it may even ask questions, though this should only happen if the files being patched have been changed between their installation (or last equivalent patch) and the current patch application. If there are problems, or patch had enough uncertainties in applying the patches, it may write files ending with.rej(patch rejects) or.orig(backups). Once the patch has been applied, and the package works properly, these files probably won't be needed any more, and they can be deleted.
patch -p0 < windowMaker.patch
A typical patch in which no levels of directories noted in the patch file will be discarded.
patch -R -p0 < windowMaker.patch
A typical undo of the previous patch application.
patch -p1 < prog-1.0-2.0.patch
Another fairly typical patch; in this case, we're discarding one directory level.
Since most unified diff patches are created using
diff -Naur prog-1.0/ prog-2.0/ > prog-1.0-2.0.patch
(causing the created patch to include the leading directories "prog-1.0/" and "prog-2.0/" in filenames), this would allow the application of the patch despite the source directory having neither name, although the current directory when applying this patch should be inside the top-level source directory for the package.
cat prog-1.0-2.0.patch.bz2 | bzip2 -dc - | patch -p1 -d /usr/src/prog -R
Use a bzip2-compressed patch to undo patching the program in the /usr/src/prog directory.
This section covers all patches that are, in actually, little more than an archive that contains all files that have changed between two versions of a package, plus (possibly) a script or two to complete (or finalize) the changes. tardiff is one program that can be used to automate the creation of these patches, and happens to have been written by the author of this page, but this section also includes hand-made patches as well.The beauty of this kind of patch is its relative ease of movement between platforms. Given a program that can deal with the kind of archive (which may well be needed to install the full package anyway), anyone should be able to use these, at the cost of a little work for the user -- first finding the patch, then determining where to apply it at, and finally applying the patch. Therefore, application on both Windows and Unixen are covered.
Regardless of the operating system, what's involved in the application of these patches are the same, though the tools used may be different. The first step, once any needed tools are installed and the patch has been downloaded, is to find where the patch needs to be applied to. The second step is the actual application of the patch.
Regardless of the kind of patch being applied, the first step of finding where to apply it to is the same: Most, if not all, patches are installed near where the package being patched was originally installed to.The main problem that needs to be solved when using this particular kind of patch is that of getting the directories in the patch to match up with the directories of the package to be patched on the hard drive. To do this, both the directory structure of the patch and that on the hard drive need to be known. Fortunately, only a small part of the directory structure of the patch needs to be known (for command-line tools, use Ctrl-C to stop the listing before reading through the entire patch archive), and the directories on the hard drive are fairly simple to look at.
Most of these patches will be installed in the same place as the original package was, but there are exceptions. Occasionally, the patch will need to be installed in a lower directory than the original; this is more often the case when the original package had a single top-level directory that only contained another directory, which then contained all the data. The other direction may occasionally be seen as well, where the old top-level directory was placed inside another directory (often with a new name). Fortunately, dropping or adding more than one directory level from the beginning of the path seems to be very rare.
The patch archives may contain scripts to finish applying the patch; two possible names are "removed" or "finish", followed by an extention appropriate for the type of script (
.shfor a Unix shell script or.batfor a Windows batch file, for example). Such scripts will usually not be placed into a directory in the archive, so they should not be used to determine proper placement.
Once the place of extraction has been determined (as above), it may be necessary to do some quick preparations. In general, the user must have write permissions to the directories and files being patched. If the user does not have these permissions when extraction and finishing, at best warnings will be displayed and the patch will be properly applied anyway; at worse, the patch will mis-apply, and the package will need to be removed and re-installed; depending on the tools being used, warnings and errors may or may not be displayed.Once any preparations are completed, the archive should be extracted (to the location determined above). If there are no errors or warnings, an appropriate finishing script should be run (if any). Finally, these finishing scripts should usually be erased after the patch has been applied (assuming the scripts didn't erase themselves upon completion).
UNIX TOOL SYNOPSIS
Displaying current directory contents:
ls [ -a |-a or --all : do not hide entries starting with . -A ] [-A or --almost-all : don't list . and .. -C |-C : list entries by columns
This causes ls to display only the filenames, and arranges the display into columns.-l ] [-l : use long listing format
This causes ls to display the permissions, size (in blocks), owning user and group, size (in bytes), last modification date, and filename of each file being displayed. The categories are displayed in columns, and the files are displayed one per line.-d ] [-d or --directory : list directory entries instead of contents
When a directory name is given on the command line, ls usually displays the contents of that directory. This option causes ls to display the directory as a single entry instead.-F ] [-F or --classify : append an indicator to entries
This adds a single character to the end of filenames display to indicate pipes (|), directories (/), symbolic links (@), sockets (=), and executables (*).-R ]-R or --recursive : list subdirectories recursively files files : a list of the files and directories to display Displaying the patch archive contents (tar archives):
tar [ z |z : select gzip decompression
If the patch archive was compressed with gzip (typically indicated by the filename ending in .gz or .tgz), this option is required to inform tar that it needs to use gzip to decompress the archive.j ]j (or, on older versions of tar, I) : select bzip2 decompression
If the patch archive was compressed with bzip2 (typically indicated by the filename ending in .bz2), this option is required to inform tar that it needs to use bzip2 to decompress the archive.t t : test mode
Causes tar to run through the archive as if it were extracting, but without writing anything to disk.v v : verbose
Causes tar to display errors, warnings, and (most importantly) the names and paths of the files being read from the archive.f f : from file
Causes tar to read the archive from a named file.
Without this option, your tape drive may be in danger! :)archive archive : the name of the (patch) archive to be viewed or extracted Changing file/directory permissions:
chmod [ -c ] [-c or --changes : report changes to each files' permissions -R ]-R or --recursive : apply changes recursively
If a directory is given, the permission changes will be applied to all files and directories inside that directory, etc., with the exception of the directories . and ..permChanges permChanges : Permission changes to make
Permission changes are specified as who, operation, and what, possibly followed by a comma (,) and another iteration of who, the operation, and what. There are no spaces in this string.
Who is one or more of u (for the owning user), g (for the owning group), o (for others), and a (shorthand for ugo).
Operation is one of + (for adding permissions), - (for removing permissions), and = (sets the permissions to exactly those given, and no more).
What is one or more of r (read permission), w (write permission), x (execute permission, or access permission for directories), X (execute only if it is a directory or someone already has execute permission for it), s (set user or group ID on execution), u (the same permissions as the owning user), g (the same permissions as the owning group), and o (the same permissions as for "other").files files : a list of the files and directories to change Extracting the patch archive contents (tar archives):
tar [ z |z : select gzip decompression
If the patch archive was compressed with gzip (typically indicated by the filename ending in .gz or .tgz), this option is required to inform tar that it needs to use gzip to decompress the archive.j ]j (or, on older versions of tar, I) : select bzip2 decompression
If the patch archive was compressed with bzip2 (typically indicated by the filename ending in .bz2), this option is required to inform tar that it needs to use bzip2 to decompress the archive.x [x : extract
Causes tar to extract the contents of the archive.v ][v : verbose
Causes tar to display errors, warnings, and (most importantly) the names and paths of the files being read from the archive.U ]Causes tar to delete individual files before extracting over them, instead of simply trying to overwrite them. The author of this page recommends using this option to protect against the effects of overwriting a device node with a regular data file, among other possible type-mismatch problems, but it is no protection against overwriting a directory that is not empty with some other kind of file. It should usually be safe to leave this option out. f f : from file
Causes tar to read the archive from a named file.
Without this option, your tape drive may be in danger! :)archive archive : the name of the (patch) archive to be viewed or extracted Cleaning up leftover scripts:
rm [ -f |-f or --force : do not display warnings when files that don't exist are encountered, and don't ask any questions -i ] [-i or --interactive : ask before every file removal -r ] [-r or -R or --recursive : delete recursively
Causes rm to erase the contents of any directory given on the command line.
Warning: Recursive erasures can be very dangerous, especially when mixed with the --force option. Take care not to erase your entire system by accident! Do NOT leave a stray / sitting around by itself on the command line! (The author admits to having done this once, and hopes that nobody else will experience the panic of suddenly realizing why rm was taking so long to erase [by intent] a fairly small directory...)-- ]-- : Include if the name of any file to be affected begins with a dash. This causes rm to treat all items later on the command line as filenames. files files : a list of the files and directories to erase
files A list of the files and directories to display. -a or --allCauses ls to not hide entries starting with .-A or --almost-allCauses ls to not list .and.., but it will show all other entries starting with.-C This causes ls to display only the filenames, and arranges the display into columns. -l This causes ls to display the permissions, size (in blocks), owning user and group, size (in bytes), last modification date, and filename of each file being displayed. The categories are displayed in columns, and the files are displayed one per line. -d or --directoryWhen a directory name is given on the command line, ls usually displays the contents of that directory. This option causes ls to display the directory as a single entry instead. -F or --classifyThis adds a single character to the end of filenames display to indicate pipes ( |), directories (/), symbolic links (@), sockets (=), and executables (*).-R or --recursiveCauses ls to list subdirectories recursively.
chmod
files A list of the files and directories to change the permissions of. permChanges The permission changes to make, which are specified as who, operation, and what, possibly followed by a comma ( ,) and another iteration of who, the operation, and what. There are no spaces in this string.
Who is one or more ofu(for the owning user),g(for the owning group),o(for others), anda(shorthand forugo).
Operation is one of+(for adding permissions),-(for removing permissions), and=(for setting the permissions to exactly those given, and no more).
What is one or more ofr(read permission),w(write permission),x(execute permission, or access permission for directories),X(execute only if it is a directory or someone already has execute permission for it),s(set user or group ID on execution),u(the same permissions as the owning user),g(the same permissions as the owning group), ando(the same permissions as for "others").-c or --changesCauses chmod to report the changes to each files' permissions. Files and directories which did not need any changes will not be listed. -R or --recursiveIf a directory is given, the permission changes will be applied to all files and directories inside that directory, etc., with the exception of the directories . and ..
rm
files A list of the files and directories to erase. When using -R, be certain not to reference any directory by accident, and especially not the root (/) directory!-f or --forceCauses rm to not display warnings when files that don't exist are encountered. Further, rm will not ask any questions of the user when this option is in force. -i or --interactiveCauses rm to ask if the user is sure before removing every file. This is the default on many systems. -r or -Ror --recursiveCauses rm to erase the contents of any directory given on the command line.
Warning: Recursive erasures can be very dangerous, especially when mixed with the --force option. Take care not to erase your entire system by accident! Do NOT leave a stray / sitting around by itself on the command line! (The author admits to having done this once, and hopes that nobody else will experience the panic of suddenly realizing why rm was taking so long to erase [by intent] a fairly small directory...)-- Include this if the name of any file to be affected begins with a dash. This causes rm to treat all items later on the command line as filenames.
tar
archive This is the name of the (patch) archive to be viewed or extracted. z If the patch archive was compressed with gzip (typically indicated by the filename ending in .gz or .tgz), this option is required to inform tar that it needs to use gzip to decompress the archive. j (or, on older versions of tar, I) If the patch archive was compressed with bzip2 (typically indicated by the filename ending in .bz2), this option is required to inform tar that it needs to use bzip2 to decompress the archive. t Causes tar to run through the archive as if it were extracting, but without writing anything to disk. This is most commonly used to list the contents of the archive. x Causes tar to extract the contents of the archive. v Causes tar to display errors, warnings, and (most importantly) the names and paths of the files being read from the archive. U Causes tar to delete individual files before extracting over them, instead of simply trying to overwrite them. The author of this page recommends using this option to protect against the effects of overwriting a device node with a regular data file, among other possible type-mismatch problems, but it is no protection against overwriting a directory that is not empty with some other kind of file. It should usually be safe to leave this option out. f Causes tar to read the archive from a named file.
Without this option, your tape drive may be in danger! :)
WINDOWS TOOLS SYNOPSIS
Displaying current directory contents:
dir filename [filename : The name of a single file or directory to display, or a path with wildcards in it to display more than one. Only one filename can be given per command. /P ] [/P : Pause
Causes dir to pause the display after each full page./W ] [/W : Wide
Causes dir to display only the file names, rather than the details for each file, and arranges the display into columns of these names./S ]/S : Subdirectories
Causes dir to display the contents of any subdirectories that match the wildcard (or path) as well.Changing permissions:
attrib permChanges permChanges : Changes to be made to file permissions
Each kind of permission can be turned on (+) or off (-) within a single invocation of attrib; "+R -A" would cause the file(s) changed to be read-only, and the archive bit would be reset.
R controls if the file is read-only or not; -R makes the file(s) writable (unless other write-controlling bits are still set).
S controls if the file's "system" bit is set. Files with this bit set are normally invisible and unwritable.
A controls the file's "archive" bit. This only affects programs that check this bit; it was mostly used to flag that the file needed to be backed up.
H controls the file's "hidden" bit. Files with this bit set are normally invisible.filename [filename : The name of a single file or directory to change, or a path with wildcards in it to affect more than one. Only one filename can be given per command. /S ]/S : Subdirectories
Causes attrib to change all files in subdirectories that match the wildcard (or path) as well. All items in matching subdirectories (and all the subdirectories within, regardless of if its name matches) are affected.Cleaning up leftover scripts:
(del|erase) filename [filename : The name of a single file or directory to delete, or a path with wildcards in it to erase more than one. Only one filename can be given per command. /P ]/P : Prompt
Causes del (or erase) to ask if you're sure before erasing each file.Patch archive manipulation:
WinZip
... probably others as well ...
filename The name of a single file or directory to display, or a path with wildcards in it to display more than one. Only one filename can be given per command. /P Causes dir to pause the display after each full page. /W Causes dir to display only the file names, rather than the details for each file, and arranges the display into columns of these names. /S Causes dir to display the contents of any subdirectories that match the wildcard (or path) as well.
attrib
permChanges This is where the changes to be made to file permissions go. Each kind of permission can be turned on ( +) or off (-) within a single invocation of attrib; "+R -A" would cause the file(s) changed to be read-only, and the archive bit would be reset.
Rcontrols if the file is read-only or not;-Rmakes the file(s) writable (unless other write-controlling bits are still set).
Scontrols if the file's "system" bit is set. Files with this bit set are normally invisible and unwritable. Traditionally, they were files that belonged to the operating system that users were not to touch.
Acontrols the file's "archive" bit. This only affects programs that check this bit; it was mostly used to flag that the file needed to be backed up.
Hcontrols the file's "hidden" bit. Files with this bit set are normally invisible.filename The name of a single file or directory to change, or a path with wildcards in it to affect more than one. Only one filename can be given per command. /S Causes attrib to change all files in subdirectories that match the wildcard (or path) as well. All items in matching subdirectories (and all the subdirectories within, regardless of if its name matches) are affected.
del or erase
filename The name of a single file or directory to delete, or a path with wildcards in it to erase more than one. Only one filename can be given per command. /P Causes del (or erase) to ask if you're sure before erasing each file.
WinZip - no further information available; I believe it provides a GUI ?
For this example, we'll assume that FlightGear base 0.9.4 was decompressed from the/usr/localdirectory, expanding into/usr/local/FlightGear-0.9.4/data/on a Linux system. (On a Windows system, it might have been decompressed from theC:\Program Files\Common Filesdirectory, expanding intoC:\Program Files\Common Files\FlightGear-0.9.4\data\, among many other possible places.) When dealing with FlightGear, if in doubt, try to find the script or batch file used to start the program, and look for the parameter "--fg-root" or the environmental variable "FG_ROOT" (or "FGROOT"); it should point to the extracted "data" directory if FlightGear runs properly. This example includes Unix and Windows parts, where possible.In the case of FlightGear, we can conveniently confirm that the current (installed) version is 0.9.4; unfortunately, the developers can sometimes make a small mess (i.e. 0.9.6-pre1 was marked as "0.9.6" in the version file; oops!):
]> cat /usr/local/FlightGear-0.9.4/data/version 0.9.4Windows alternative: You may use Notepad to read this file. Use a file manager to navigate to the directory, then open the version file; if you make any changes, don't save them. Although it won't matter in this case (0.9.4 to 0.9.5 replaces the version file), it may matter with other patches.
C:> type C:\Program Files\Common Files\FlightGear-0.9.4\data\version 0.9.4A cursory glance at the tar archive (using, on a Unix,
tar ztvf base-0.9.4-0.9.5.tar.gz, quickly cut off with a Ctrl-C) reveals:So this archive extracts into the]> tar ztvf base-0.9.4-0.9.5.tar.gz drwxr-xr-x curt/curt 0 2004-06-14 08:26 data/Aircraft/737/ drwxr-xr-x curt/curt 0 2004-06-14 08:26 data/Aircraft/737/Engines/ -rw-r--r-- curt/curt 2603 2004-06-14 04:41 data/Aircraft/737/Engines/CFM56.xml -rw-r--r-- curt/curt 114 2004-06-14 04:41 data/Aircraft/737/Engines/direct.xml
Windows users: This will depend on the archive managing program you're using.
If it has a GUI and will allow you to open the archive without extracting it yet, do so and note the directory locations, similarly to how a Unix user would read the paths from the right-most column of the output above.
If it does not have a GUI, it should have an option to allow you to get a listing of the archive contents for you to use here.data/directory instead of theFlightGear-0.9.4/data/directory; we need to extract into/usr/local/FlightGear-0.9.4/. To be safe, we use tar's U tag, though it really isn't needed for this package (as the package is meant to be for both Windows and Unix, and Windows doesn't have symbolic links, or pipes, sockets, and devices as files). Be warned, however; if the current user can't write to the files or the directories, some parts of the patch won't be properly extracted. In this example, the files are owned by the user "flier".This patch created two new files to complete the patch -- removed.bat (for Windows users) and removed.sh (for Unixen users). (Another pair of names would be finish.bat and finish.sh.) To complete the transformation, the appropriate script should be run, and then (if the script didn't do it by itself) these scripts should be deleted.]> cd /usr/local/FlightGear-0.9.4 ]> su flier Password: flier]> chmod -R u+w . flier]> tar zxvUf ~/downloads/FlightGear/base-0.9.4-0.9.5.tar.gz drwxr-xr-x curt/curt 0 2004-06-14 08:26 data/Aircraft/737/ drwxr-xr-x curt/curt 0 2004-06-14 08:26 data/Aircraft/737/Engines/ -rw-r--r-- curt/curt 2603 2004-06-14 04:41 data/Aircraft/737/Engines/CFM56.xml -rw-r--r-- curt/curt 114 2004-06-14 04:41 data/Aircraft/737/Engines/direct.xml ... [snip] ... -rw-r--r-- srcwiz/tardiff 426 2004-09-11 14:33 removed.bat -rwxr--r-- srcwiz/tardiff 394 2004-09-11 14:33 removed.sh
Windows users: Use a file manager to ensure that no files within the FlightGear data directory are read-only, then use your archive managing program to extract the archive to the proper location; in this example,C:\Program Files\Common Files\FlightGear-0.9.4\. After the archive has been extracted, GUI users will want to exit the program.
C:> C: C:> CD \Program Files\Common Files\FlightGear-0.9.4\This particular patch may ask if it should really some files, unless all files were made writable to the user (as in the example above). Some scripts will use the appropriate options to rm so it won't ask, but this solution isn't available under Windows. Windows users should make sure that no files in the patch tree are read-only before trying to apply patches, as it simply fails to act and moves on when this sort of problem occurs.flier]> ./removed.shAlternative: Instead of navigating the command line to the file, a file manager can usually be used to start a program such as this one.
C:> removed.batIn this case, the user has the choice of renaming or not renaming the overall directory tree; if you do, however, be sure to update any references to the old directory location.flier]> rm removed.sh removed.batAlternative: This is another task that can be done with a file manager instead of the command line.
C:> del removed.sh C:> del removed.batCongratulations! You're applied the FlightGear base 0.9.4 to 0.9.5 patch!flier]> cd .. flier]> mv FlightGear-0.9.4 FlightGear flier]> pico -w /usr/local/bin/gofgfs ... [changes excluded] ... flier]> exit ]>
Steven AndreasonMany of the UNIX tool usage descriptions were prepared from the manual pages for those tools; the manual pages should be consulted for more information on each tool:
Paul Rubin
David MacKenzie
Richard Stallman
Jim Meyering
Larry Wall
| Last updated 2004 October 5 |