Bug 61654 - Ant Copy Task Documentation Misleading and Inaccurate
Summary: Ant Copy Task Documentation Misleading and Inaccurate
Status: NEW
Alias: None
Product: Ant
Classification: Unclassified
Component: Documentation (show other bugs)
Version: unspecified
Hardware: All All
: P2 normal (vote)
Target Milestone: ---
Assignee: Ant Notifications List
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2017-10-23 18:13 UTC by Nick Condatore
Modified: 2017-10-24 18:22 UTC (History)
0 users



Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Nick Condatore 2017-10-23 18:13:58 UTC
https://ant.apache.org/manual/Tasks/copy.html

tells us "By default, files are only copied if the source file is newer than the destination file, or when the destination file does not exist. However, you can explicitly overwrite files with the overwrite attribute."

So we take a look at the attribute itself:
Attribute:overwrite	Description:Overwrite existing files even if the destination files are newer.	Required:No; defaults to false.

But this is wrong. There are 3 different behaviors this task can perform. Not merely true, or false.

True - Overwrite files, period. Ignores recentness of source or destination.
False - Do not overwrite files, period. Ignore recentness of source or destination.
Default - Only overwrite files if source is more recent than destination.

The current representation in the documentation implies that the default behaves the same as false vie "defaults to false", but that is simply not true. Anyone looking at the documentation for a way to never overwrite, only copy if the destination does not have the file from the source will assume 1 of two things, that the default and false will both never overwrite (and then waste time debugging having chosen the default) or that neither of them are an option, as both will look at recentness, and will resort to a <present> selector, adding unnecessary lines of code and research.

This documentation should be updated to specifically state there are 3 behaviors and that the default results in specific behavior, NOT that it defaults to false.
Comment 1 Stefan Bodewig 2017-10-24 04:51:17 UTC
I don't think you are correct. The overwrite flag is false by default and even with overwrite="false" files are replaced if they are outdated.

$ cat x.xml 
<project>
  <touch file="a"/>
  <sleep seconds="3"/>
  <touch file="b"/>
  <copy file="b" tofile="a" overwrite="false"/>
</project>
$ ant -f x.xml
Buildfile: /tmp/x.xml
    [touch] Creating /tmp/a
    [touch] Creating /tmp/b
     [copy] Copying 1 file to /tmp

BUILD SUCCESSFUL
Total time: 3 seconds

as you can see, a has been replaced even though overwrite was false.
Comment 2 Nick Condatore 2017-10-24 17:59:02 UTC
Perhaps this only applies to directories or filesets.

This is my implementation boiled down to the basics:

<target name="example">
   <copy todir="../" overwrite="false">
      <fileset dir="${source}/>
   </copy>
</target>

This does not overwrite old files in the directories that already exist, but will when overwrite="false" is not present. Perhaps it is only checking the age of the directories and not their contained files?
Comment 3 Stefan Bodewig 2017-10-24 18:22:45 UTC
Hmm,

$ cat x.xml 
<project>
  <mkdir dir="a/example"/>
  <touch file="a/example/file"/>
  <sleep seconds="3"/>
  <mkdir dir="b/example"/>
  <touch file="b/example/file"/>
  <copy todir="a" overwrite="false">
    <fileset dir="b"/>
  </copy>
</project>
$ ant -f x.xml 
Buildfile: /tmp/x.xml
    [mkdir] Created dir: /tmp/a/example
    [touch] Creating /tmp/a/example/file
    [mkdir] Created dir: /tmp/b/example
    [touch] Creating /tmp/b/example/file
     [copy] Copying 1 file to /tmp/a

BUILD SUCCESSFUL
Total time: 3 seconds

If you look at the code, then using overwrite="false" really only sets a boolean variable that us false anyway. There is no difference between the default and setting it explicitly.

Could it be anything else that you are seeing like filesystems on different machines with clocks that differ? Maybe you need to play with the granularity attribute?