<type>documentation</type>
<domain>proj</domain>
<id>project-types</id>
<title>Sharing Projects</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>pro+</product>

By default Wing Pro stores each project in two similarly named files:

(1) The ``*.wpr`` file contains the sharable data for the project, which can be checked 
    into revision control, used on other machines, and shared with other users.  

(2) The ``*.wpu`` file contains user and machine-specific data.

`Project Type <script:view_project_properties#highlighted_attrib="proj.project-type">`__,
under the ``Options`` tab of ``Project Properties`` can be set to ``Single User (One File)``
in order to store both branches of the project into a single ``*.wpr`` file.  This is rarely 
necessary, except when moving a project to or from Wing Personal, which can only read 
single-user projects.

Making Project Files More Sharable
----------------------------------

In most cases sharing the ``*.wpr`` file will just work.  File paths are stored in a 
platform-independent way, and relative to the project's location on disk, so they 
will work on different hosts and OSes.

If revision control conflicts arise among different users of a ``.wpr`` file,
`environment variables <ref:proj/variable-expansion>`__ can be used in any conflicting
``Project Properties`` to make the shared project file uniform for all users and on 
all machines.  Environment can be inherited from outside of Wing or set using 
``Environment`` in ``Project Properties``. The values for the ``Environment`` 
property are stored in the ``.wpu`` file and thus may vary by user.

Changing Which Properties are Shared
------------------------------------

Another way to make a project more sharable is to alter which properties
are stored in the shared ``*.wpr`` file.  This is done by editing the ``.wpr`` file 
with a text editor and setting the ``proj.shared-attribute-names`` property.  
This is a list of properties to add or remove from the default set of shared properties. 
Each item in the list is an property name preceded by ``-`` to move a shared property 
to the non-shared ``*.wpu`` file, or ``+`` to move a non-shared property to the
shared ``*.wpr`` file.  This specification is applied to the default set of shared 
properties in order to determine which properties to share in this project.

The following example would move the commands defined in the ``OS Commands`` tool into the
user-specific ``*.wpu`` file and would share the ``Python Executable`` and ``Python Path`` 
defined in ``Project Properties`` in the ``*.wpr`` file::

  proj.shared-attribute-names = [
    '-console.toolbox',
    '+proj.pyexec',
    '+proj.pypath',
  ]

Note that sharing the ``Python Executable`` and ``Python Path`` works only if the values
are valid and uniform on all the machines where the project is used. This can be easier to
achieve if the values use `environment variable references
<ref:proj/variable-expansion>`__ such as ``${WING:PROJECT_DIR}/a/b/c`` for a path entry.

The default set of shared properties is::

  proj.shared-attribute-names
  proj.directory-list
  proj.file-list
  proj.file-type
  proj.main-file
  proj.home-dir
  testing.test-file-list
  testing.auto-test-file-specs
  testing.test-framework
  proj.debug-sub-processes
  debug.named-entry-points
  proj.launch-config
  debug.launch-configs
  console.toolbox
  
The names of other potentially sharable properties can be found in the
``.wpu`` file.

File Format
-----------

The ``.wpr`` and ``.wpu`` project files use the same textual file format that is
used Wing's preferences file.  See `Preferences File Format`__ for details.

__ ref:custom/preferences-file-format

Note that only non-empty and non-default values are stored in the project file.  
For example, ``proj.file-list`` will be missing if no files are individually
added to the project.  

