Untouch 2.6 build: 9639 released: 2014-04-03 compiled with: Java 1.8.0_131 Jet jet12.0-pro-x86/1.8.0_131

Reverts dates on files that have not really changed.

Copyright: (c) 2003-2017 Canadian Mind Products.

Java application.
Download from: http://mindprod.com/products1.html#UNTOUCH

----

Notes:

You must install the Java JRE to use this program.
See http://mindprod.com/jgloss/jgloss/jre.html

This program can only be used from the command prompt, (or via an command
line style icon shortcut) e.g. under Windows command.exe or JPSoft
tcmd.exe, formerly called the DOS box. Just clicking the programs in a
directory listing will not do anything useful. Just typing the program
names at the command prompt will not either.

This program requires a manual install! See below.

This program works with vanilla text files, (e.g. ASCII files or UTF-8
Unicode files). You will need a text editor to create and view them, not a word
processor. e.g. notepad, Visual Slick Edit or other suitable text editor
http://mindprod.com/jgloss/editor.html. You must use a monospaced font
http://mindprod.com/jgloss/monospacedfonts.html (aka fixed pitch, aka
programmer font) to view your files, or they won't look properly aligned.

I put out an avalanche of free software into the world, and submit PAD
files to hundreds of distribution sites, but I rarely hear back from
anyone.  What's happening?  Does it all just work fine?  It is so
complicated nobody can figure out how to use it and they give up on it?
It is it useful?  Since everyone has the source, do people just fix the
programs to their liking themselves?  Did you have trouble installing?  Do
I presume you know too much?  I would be happy to hear from you about your
experiences, positive or negative and your requests for improvements.  A
one-line email to roedy@mindprod.com would be great.

===> Free <===
Full source included.
You may even include the source code, modified or unmodified
in free/commercial open source/proprietary programs that you write and distribute.
May be used freely for any purpose but military.
For more details on this restriction, see
http://mindprod.com/contact/nonmil.html
If you include any Canadian Mind Products code in your own applications,
your app too must be labelled non-military use only.
http://mindprod.com/contact/nonmil.html
All Java jars and source code are included. If you need the class files or Javadoc, you will have to build them yourself. To streamline the zip downloads, class files and Javadoc have been removed.

----

Prerequisites:

This program runs under any OS that supports Java,
(e.g.W2K/XP/W2003/Vista/W2008/W7-32/W7-64/W8-32/W8-64/Linux/LinuxARM/LinuxX86
/LinuxX64/Ubuntu/Solaris/SolarisSPARC/SolarisSPARC64/SolarisX86/SolarisX64/OSX/AIX...)
so long as you have
<><> Java version 1.8 <><> or later installed (32-bit or 64-bit Java).
See http://mindprod.com/jgloss/installingjava.html for details.

----

Installing on a PC:

Download source and compiled jar files to run on your own machine as an application.
First install a recent Java JDK or JVM.
See http://mindprod.com/jgloss/installingjava.html.
To install, extract the zip download with WinZip
(or similar unzip utility) into any directory you please,
often J:\ --  ticking off the <span class="click">use folder names</span> option.
To run as an application, type:
java.exe %JAVA_OPTIONS -ea -jar J:\com\mindprod\untouch\untouch.jar {put any parms here}

adjusting as necessary to account for where the jar file is.

----

Installing on a MacIntosh:

Use Safari to download source and compiled jar files to run on your own machine as an application.
Safari will automatically unpack the zip into ~/Downloads (version 10.5)
[or on the Desktop (version 10.4 and earlier)].
First install a recent Java JDK or JVM.
See http://mindprod.com/jgloss/installingjava.html.
You may optionally move the download tree to a permanent home.
I don't have a MacIntosh, just a PC, so I can't test my Java programs for Mac compatibility.
In theory they should work without problems, but in practice that does not always happen.
If you have problems please, let me know, preferably with screenshots and complete verbatim error messages.
To run as an application, without parameters, just double click the jar file.

To run as an application with parameters, in bash shell type:
open Terminal.app
cd ~/Desktop
java.exe -ea -jar com/mindprod/untouch/untouch.jar {put any parms here}

adjusting as necessary to account for where the jar file is.

----

Rebuilding:

The zip already contains the necessary jar files, so unless you modify
the program, there is no need to recompile the source or rebuild the jar.
Configure.java basedir="E:/" in rebuild.xml to the drive where your files are.
Use ANT and rebuild.xml, not build.xml, to recompile and recreate the jar.

----

Use:

Resets lastChangedDate of files if they have not really
changed back to their original dates.
Primarily used to backdate local copies of a website files
to their original dates if they contain no net changes since
the last upload. This saves pointless uploads and Google
respidering.
To install, Extract the zip download with WinZip, available
from http://www.winzip.com (or similar unzip utility) into
C:\ -- checking off the "user folder names" option. To run
as an application, type:
java.exe -jar C:\com\mindprod\untouch\untouch.jar  mydirectory
adjusting as necessary to account for where the jar file is.
Put name of directory you want files reverted to old dates
if they have not changed since the last time you ran
untouch. To process entire tree use -s mydirectory
You cannot untouch individual files.
Use: untouch.jar [ -flag1 -flag2 ... ] dir1 dir2 ...
Untouch supports the the following command line switches/flags which appear
before the directories.
-c or -clear = Clear history first and take current file times as the new revert-to point.
               start over.
-f or -force = Revert files back to previous dates whether the contents have changed or not.
-h or -help  = Display a short summary of the Untouch command syntax.
-r or -remove = Remove option to remove untouch history i.e. untouch.digest and untouch.log files.
                Stop monitoring these directories with untouch.  When synching
                directories, you might delete these files on the target, copy the files,
                then recompute the digest with the times of the recently copied files
                which will match the source.
-s or -sub or -subdir or -subdirs or -t or -tree  = Process files in subdirectories as well.
-l or -log    = Create untouch.log files in each directory logging details of what was done.
-q or -quiet  = Suppress progress messages.
PUT THE SWITCHES *BEFORE* THE DIRECTORY NAMES ON THE COMMAND LINE.
Documentation on the original student project outline
http://mindprod.com/projects/untouchproj.html
This explains how it works and some of its uses.

In A Nutshell
*************
To copy files whose contents have truly changed (not just timestamps
differ) from one directory to another, Untouch both the source and target
directories.  Then copy with /U (avoiding copying the *.digest files).
DON'T COPY *.* or you will include the *.digest files.
Then untouch the target.
If it seems to be copying files it did not really need to, or is not
copying files you think it should, untouch the source directories.  Then
copy without /U.  Then untouch the target with the -c option, to clear and
restart.  All files in source and target should then have the same dates
and sizes.

Synching
********
If you have directory adir and directory bdir, and you copy
files from adir to bdir using copy /u, you should make sure
you untouch the files in adir before the copy. Otherwise the
files in adir will look newer than those in b even when they
are identical, and needlessly copy over. To avoid redundant
copying, periodically untouch both adir and bdir.
To resych two directories, vis a vis untouch, delete the
untouch.digest file in adir and the untouch adir.  Then copy
files from adir to bdir.  Then delete the untouch.digest
file in bdir, and untouch bdir.
The first time untouch runs it will take longer than
usual since it must scan every byte in every file to compute
the digest checksums.
I use a conservative approach.  To keep two directories in sync I
do something like this:
rem keep snippets directory in untouch sync with the example directory
java.exe -jar untouch -q -s  E:\com\mindprod\example  E:\mindprod\jgloss\snippet
rem /U=update /E=no error
copy /U /E E:\com\mindprod\example\*.java E:\mindprod\jgloss\snippet
rem untouch the target directory again
java.exe -jar untouch -q -s  E:\mindprod\jgloss\snippet
If the two directories get out of sync, so you keep copying the same files
over and over every time you do the copy /U, do a untouch -r on both
target and source directories to remove untouch.  Do you copy /U, then do
an untouch on target and source directories to engage untouch again.

The Rounding Problem
********************
Java (and by extension Untouch) only see the file timestamps
accurate to the nearest millisecond.   Windows keeps file
timestamps accurate to 100 nanoseconds with 10,000 times as
much precision as Java's 1 ms.  This means if you copy a
file in Java, the new file will not have the exact same
timestamp as the old. This cause troubles when Java thinks
two timestamps are identical, but Windows, especially COPY
/U does not, because Java works with platfom-independent
rounded off timestamps. This can lead to strange things like
COPY /U repeatedly copying files that have almost the same timestamp, because
untouch rounds them off making the source and target slightly different.
You can normalise a directory like this to even millisecond
timestamps to temporarily get rid of the anomalies.
untouch .
touch *.*
untouch .
In a future version of untouch, I will get untouch to round
off the timestamp of any file it monitors to an even
millisecond to avoid such glitches, effectively doing this
normalising process automatically every time you run
untouch.
Why the backward green arrow icon?  It represents putting
the date back the way it was.
If you use Take Command copy /UF instead of copy /U, it suppresses the
copy if the source and target are dated within 2 seconds of each other.
Normally, even a microsecond difference is enough to trigger the copy.  This
is the easiest way around the rounding problem.

TIP
***
You might consider using untouch ONLY just before you upload
files. That way if you change a file and change it back to
the way it was, or delete it and recreate it the same way,
it will get outouched back to the original date, and thus
will not need to be uploaded.  If you do intermediate
untouches, you won't exploit that opportunity.

LEGEND
******
The legend displayed both tells you what the letter codes mean, and how
many files there were in each category.
         L E G E N D
   23  - There was no change of any kind to the file; shown only in untouch.log.
    3  + File's length changed.
   10  ^ Untouch reverted the file to its old last-modified date/time.
    0  ! File is new, at least to Untouch.
    1  * File's contents changed, but it did not change length.
    1  x File was locked and/or ignored.
    
ICON
****
Why the curly blue arrow icon?  It represents settin the file date back to
what it was.


----

Version History:

 1.7 2009-01-11 round all file timestamps to nearest milli so original/copied/untouched timestamps will match.

 1.8 2009-04-21 (-clear) option to clear history and set a current times as the revert-to times.

 1.9 2009-04-21 (-remove) option to remove untouch history i.e. untouch.digest and untouch.log files

 2.0 2009-05-04 now ignores .svn subversion directories.

 2.1 2009-06-05 add -help flag

 2.2 2011-01-16 fix bug stopping from Untouch rebuilding the digests after a remove.

 2.3 2011-11-07 add display of counts of various categories of files in the legend.

 2.4 2011-11-22 suppress log items for untouch.digest and untouch.log. It was just clutter.

 2.5 2013-04-17 allow slop in matching dates to account for Windows->Java loss of precision.

 2.6 2014-04-03 ensure all files we process have timestamps rounded to match exactly.

-30-