Valid XHTML 1.0 Strict
Valid CSS!
Powers this site!
Powers this project!


These installation instructions can be followed when installing from source:

  • Download the latest release from the download page.

  • Go to the directory where the archive has been downloaded and unpack it using the following command:

    tar xvzf ascopy-0.0.0.tar.gz

    0.0.0 should be replaced with the version of AScopy that has been downloaded.

  • Go to the newly created directory and type:

    ./configure && make && make install

    Make sure that you have sufficient rights for the installation.
    The configure script provides some optional settings. Type ./configure --help to view the possibilities.

  • Make sure that the ascopy binary is in your PATH and that the man page can be found through your MANPATH environment variable.

  • AScopy is now ready for use. Please refer to the user's manual below for more information.

User's manual

The documentation below is the user's manual as it is included with the distribution of AScopy. It is always a copy of the documentation included in the latest stable release.


       ascopy - web site maintenance utility


       ascopy [OPTIONS]... [ACTION] SITENAME


       Synchronize files, directories and their permissions between the remote
       location for a web site and its location  on  a  local  machine.   Only
       files and directories that have changed will be transferred. The trans-
       portation is done using an external SFTP client.

       Ascopy recognizes files that have been moved or copied to a  new  loca-
       tion  and  does  not attempt to send these files to the remote site. It
       just copies them directly on the remote site.


       The options for ascopy can be split into two groups: one  option  indi-
       cating the action the program has to take and other options that change
       the behavior during operation. The possible  actions  and  options  are
       listed below:

       -l, --list
              List changes between remote and local sites (default).

       -v, --view
              Display  a list of the site definitions. By default it shows the
              definitions as stored in $HOME/.ascopyrc unless another configu-
              ration file has been specified (see Optional Settings).

       -i, --init, --initialize
              Mark  all files and directories as not updated. This removes the
              local stored information for the remote site  and  makes  ascopy
              think  that there are no files on the remote server. The default
              location   for   the   file   that   will   be    removed    is:
              $HOME/.ascopy/<sitename>. See FILES.

       -f, --fetch
              Find  out what files are on the remote site. This will overwrite
              the locally stored information  on  for  the  remote  site.  The
              default location for this data is: $HOME/.ascopy/<sitename>. See

       -e, --verify
              Verify stored state of site matches real remote state.  If  both
              the local and the remote site are the same ascopy will exit with
              a return value of 0, otherwise it will return with a value of 1.

       -c, --catchup
              Mark  all  files  and directories as updated. This will take the
              state of the local site and write it to the file containing  the
              state  for the site. Default location: $HOME/.ascopy/<sitename>.
              See FILES.

       -s, --synch, --synchronize
              Update the local site from the remote site. This makes the local
              copy  of  the  site equal to the remote copy. Local files may be
              deleted or changed.

       -u, --up, --update
              Update the remote site from the local site.

       -h, --help
              Display this help message.

       -V, --version
              Display version information.

   Optional settings
       -r FILE, --rcfile=FILE
              Use alternate run control file. See FILES for  more  information
              on the format of this file.

       -p PATH, --storepath=PATH
              Use alternate site storage directory. See FILES.

       -y, --prompting
              Request confirmation before making each update.

       -q, --quiet
              Be  quiet  while  performing  the  operation. If confirmation is
              needed or requested (see the -p or --prompting optional setting)
              it will not be suppressed.

       -n, --dry-run
              Display what will be done but do not carry out the operation.


       The program returns 0 if everything went well, 1 otherwise.


       ascopy's behavior is affected by the following environment variables:

              This  variable  holds the path where the data for each site will
              be stored. Its default value is $HOME/.ascopy and  can  also  be
              set using the -p or --storepath option.

              Defines  the  name of the file that holds the configuration data
              of the remote sites. Its default value  is  $HOME/.ascopyrc  and
              can  also  be set using the -r or --rcfile option. See the FILES
              section for information about the content.


       Default run configuration file that contains the site  settings.  Other
       files  can  be  set  using  ASCOPY_CONF_FILE  (see  ENVIRONMENT) or the
       --rcfile command line switch (see OPTIONS).

       The configuration file is a text file that holds the settings  as  key-
       value  pairs  where  the key and value are separated by whitespace. The
       following keys have to be defined:

       site sitename
              Sets the name of the definition for a site. It MUST be the first
              entry  for each definition as aScopy will consider all following
              entries to belong to this definition.

       server servername
              The name of the remote server for the site.

       username username
              The username with which to log in to the remote server.

       local dir
              The directory where the local copy of the site will be stored.

       remote dir
              The directory on the  remote  system  where  the  site  will  be

       exclude pattern
              Files  or  directories  that  can  be excluded when building the
              actual file list from the local machine or  the  remote  system.
              Beware  the  files  that  were  once  correctly but that are now
              excluded, will be deleted from the remote server when an  update
              is done. The exclude option can take three forms:

              To exclude files in any directory that conform to a certain pat-
              tern, the pattern following exclude is  just  the  general  file
              pattern.  The first example excludes all files that end with the
              'bak' extension, the second example  excludes  all  files  start
              with  a  '.'  and  end  with  the  'swp' extension (vi temporary

                  exclude *.bak
                  exclude .*.swp

              To exclude files in a specific  directory,  prefix  the  pattern
              with a slash '/'.  The example below will exclude all files with
              a 'txt' extension in the given directory. The directory is rela-
              tive to the directories specified with local or remote.

                  exclude /personal/*.txt

              It is even possible to exclude entire directories using the syn-
              tax shown before. The following example will exclude  all  files
              and sub-directories in the personal directory:

                  exclude /personal

       Example configuration file:
                username hutch
                local    /home/hutch/htdocs/
                remote   /home/who/htdocs/
                exclude  *.bak
                exclude  .*.swp

              As  stated the configuration file can contain more than one site
              definition.  Whitespace is ignored so it can be used to make the
              file a bit more readable.

   Data files.
       For  each site definition in the configuration file a file will be cre-
       ated that holds the state of that site. The location of these files  is
       by default in the directory $HOME/.ascopy but can be changed by setting
       ASCOPY_SITEDATA_DIR (see ENVIRONMENT) or using the  --storepath  switch
       (see OPTIONS).


   Starting from scratch
       ascopy  needs  a  run  control file where the definitions for the sites
       will be stored and a working directory. Both have to be  created  manu-
       ally.  Use the following command to create the working directory:

              mkdir -m 700 $HOME/.ascopy

       To create an empty run file execute the following commands:

              touch $HOME/.ascopyrc
              chmod 600 $HOME/.ascopyrc

       After  this  has  been  done  the  run  file can be edited and the site
       details can be entered in there. See the FILES section for details.

       Since ascopy uses SSH and SFTP the user will be asked  for  a  username
       and   a  password.  This  can  be  a  bit  cumbersome  and  SSH  allows
       authentication to be automated using a key pair. The ssh(1)  documenta-
       tion contains information on this.

   Starting with an existing remote web site
       It  is  assumed  that  the site configuration already has been set (see
       FILES).  First get the information on the remote site:

              ascopy --fetch sitename

       Then make the local site equal to the remote site:

              ascopy --synchronize sitename

       Beware that might alter and/or destroy files on your local machine.  It
       might be wise to make a backup first.

   Starting with an existing local web site
       Make  sure  that the root directory of the remote site has been created
       by either you or the administrator. The issue the following command:

              ascopy --initialize sitename

   Uploading changes
       To upload the changes made to a local site use the following command:

              ascopy --update sitename


       ssh(1), sftp(1)


       Copyright (C) 2006 Niels Heirbaut <>.


       There are some annoyances and probably also some  bugs.  Please  report
       them to <>.

ascopy 1.0.0 December 2006 ASCOPY(1)