# Working with Projects

Feature Showcases

- create a custom toolbar
- create a directory shortcut
- export and import a package
- assign a custom keybinding to a component
- store a template in a project

Komodo projects are containers for files, folders, templates, macros, run commands, snippets and links specific to a particular software project or website. There are two types of Komodo projects:

- Live Projects: A live project does a Live Import of the directory where the project is created, thereby including all the files and sub-directories of that directory. This becomes the live project's base directory. Changes in the filesystem are reflected in the project, and deleting files from the project gives you the option to delete them from the filesystem (the "Move to Trash" option). This kind of project is essentially a top-level live folder.
- Static Projects: Static projects are virtual containers for project components, similar to virtual folders. They can, however, contain live folders.

By default, new Komodo projects are "live". This can be changed with the Live Import preference.

Komodo projects are XML files stored on disk with a ".kpf" extension. If you manually edit the project file, make a backup copy first; invalid project files will not load.

Components can be dragged and dropped between projects and the Toolbox. Context menus are available for the various components and a Project drop-down menu. New items can be added via the Add item drop-down menu in the project tab's toolbar.

## Displaying the Projects Sidebar

The Project sidebar is displayed in the left pane of the Komodo workspace. It is displayed or hidden via:

- View|Tabs & Sidebars|Projects: Opens the left pane with the Project sidebar in the foreground.
- Key Binding: The default key binding for opening and closing the left pane is 'Ctrl'+'Shift'+'P'. See Configuring Key Bindings to alter or view the current assignment.
- Workspace Toolbar: If the Workspace Toolbar is displayed, click the Show/Hide Left Pane button. (Select View|Toolbars|Workspace to display the toolbar.) Alternatively, click the Show Specific Sidebar/Tab button and select Projects.

## Creating Projects

To create a Project, use one of the following methods:

- File Menu: On the File menu, select New|New Project.
- File Menu: On the File menu, select New|New Project From Template..., select the desired project template and click Open.
- Project Menu: On the Project menu, click New Project.
- Project Menu: On the Project menu, click New Project From Template..., select the desired project template and click Open.
- Projects Sidebar: Project Tools|New Project

When creating a new project, you are prompted to select a directory where the project file is stored. The project filename becomes the project name displayed in the Projects Sidebar (without the ".kpf" extension). "Live" projects will automatically import the files and sub-directories in this directory.

### Live Import

The Live Import option in Project Properties and Settings (set globally in Komodo under Edit|Preferences|Directory Import) makes the project behave as a Live Folder. A project created with Live Import enabled is a live project.

## Opening Projects

Existing projects are opened by any of the following methods:

- File|Open Menu: Select File|Open|Project.
- Project Menu: Select Project|Open Project
- Projects Sidebar: Project Tools|Open Project

Recently opened projects can be accessed from the Komodo Start Page, or from the File|Recent Projects menu. (The number of recently opened projects is determined by the Most Recently Used preference.)

The project name and associated files are displayed on the Projects tab. By default, opening a project only opens the project file, not the components associated with the project. The Opening and Closing Projects preferences can change this behavior to automatically open recent project files (and close them when the project is closed).

## Setting the Active Project

Multiple projects can be open at the same time. Components in any open project can be used. However, only one project at a time is "active". The active project is displayed in bold text. When the Add Component button in the Projects sidebar is invoked, the component is added to the active project, regardless of the project that is currently highlighted.

Knowing which project is currently active is important because file preferences can be stored in projects. Komodo chooses a location for saved preferences based on the following criteria:

- When debugging a file in the active project, preferences are stored in the active project.
- When debugging a file in a project which is open but not active, preferences are stored in the first project found containing that file.
- When debugging a file that is not in an open project, preferences are saved as a 'global' preference for that file.

To set the active project, right-click the desired project name and select Make Active Project, or select Project|Make Active Project from the drop-down menu.

## Adding Components to Projects

Projects are organization containers for "components". Components are items like files, folders, snippets, macros, etc. For information about individual components, refer to the relevant section of the documentation for the specific component.

Filesystem-based components consists of items that exist as entities on the disk: files and templates. Komodo-specific components exist only in Komodo, and are not stored as external disk entities. Komodo-specific components include open shortcuts, folders, snippets, run commands, URL shortcuts, macros and custom menus and toolbars.

Within projects, filesytem-based components are merely references; they cannot be moved or deleted from within Komodo; moving them between projects and the Toolbox, or deleting them from projects or the Toolbox, has no effect on their actual disk-based location or their contents. On the other hand, Komodo-specific components (such as macros and snippets) do not exist outside of Komodo; therefore, they can be moved and copied (for example, from the Toolbox to the Projects sidebar) and deleted independently of the filesystem.

For example, when a snippet (a Komodo-specific component) is copied from the Projects sidebar to the Toolbox, a new copy of the snippet is created; the original version still exists in the original location. Subsequent modifications of the snippet in the Toolbox do not change the version of the snippet stored in a project. On the other hand, when the contents of a file (a filesystem-based component) are changed, the changes apply regardless of the location from which the file is invoked.

To add a component to a project:

- Project|Add: Use the Project drop-down menu. If multiple projects are open, the component is added to the project that is currently active.
- Project|Add|project_name: When a project name is selected in the Projects sidebar, the selected project's name is also displayed in the Project drop-down menu. Components can be added directly to that project.
- Add Button: Use the Add button on the Project tab. If multiple projects are open, the component will be added to the project that is currently selected.
- Context Menu: Right-click a project name and select Add|component.
- Drag and Drop: Drag and drop components from:
  - Drag-and-Drop-Aware Applications: Filenames can be dragged from drag-and-drop applications (such as Windows Explorer).
  - Projects or Toolbox sidebars: Components can be dragged between projects, the Toolbox and container components (such as folders).
  - Editor File Name Tabs: When a file is open in the editor pane, drag and drop from the tab that displays the filename to a project.
- Import from Filesystem: Right-click a project and select Import from File System.
- Cut/Copy/Paste: All components have a right-click menu that includes the options Cut, Copy and Paste. Use these options to move components between projects, the Toolbox and container components.

Some components have special component-specific mechanisms for being added to projects. For example, snippets can be created and added to a project in one step by selecting a block of text in the Editor Pane and dragging it onto a project. URL shortcuts are created by dragging and dropping a URL from a browser address bar or from the Editor Pane onto a project. Refer to the specific component sections for more information about these options.

To remove a component from a project, click the desired component and press 'Delete', or right-click the component and select Delete from the context menu.

Komodo-specific components (such as run commands, macros, etc) are permanently deleted. Filesystem-based components (such as files and dialog projects) are not; only the reference to the component within the project is removed.

## Project Display Settings

Use the button on the top right of the Projects Sidebar to select the fields that are displayed in the Projects sidebar. Click the column headings to organize the items according to the contents of any column.

Column contents depend on the type of component. For example, the Status and Depot Rev display options only have contents if the component is part of a source code control repository.

The following columns can be displayed:

- Date: The date from the filesystem when the component was last saved.
- Size: The filesystem size of the component.
- Status: The source code control status of the component.
- Rev: When a component is part of a source code control repository, this column displays the revision number of the local version of the file.
- Depot Rev: When a component is part of a source code control repository, this column displays the revision number of the repository version of the file.
- Action: When a component is part of a source code control repository, this column displays the current action (if any) being performed on the file. For example, if a file is currently opened for editing, the action is "edit".
- Name: The name of the component. For filesystem-based components (such as files and dialog projects), the name is equivalent to the filename. For Komodo-specific components (such as macros and run commands), the name is the user-defined name assigned to the component.

## Saving Projects

If an asterisk is displayed beside the project name, the project has changed since it was opened or last saved. This happens not only when components are added, edited or removed in the Project Pane, but also when debugging options are changed for files in the project. To save a project:

- File Menu: On the File menu, click Save Project.
- Project Menu: On the Project menu, click Save Project. This saves the active project. If a project name is currently highlighted in the Projects sidebar, the Project menu contains an option for saving the selected project (Project|project_name|Save Project).
- Projects Sidebar: Project Tools|Save Project
- Project Context Menu: Right-click the desired project and select Save Project.

The mechanisms described above can also be used to save a project to a new project file by selecting Save Project As... rather than Save. Filesystem-based components (such as files and dialog boxes) are relative references rather than actual entities; in the new project, the reference to the location of the component is preserved. Komodo-specific components (such as macros and run commands) are copied to the new project; there are independent versions of the component in the original project and in the new project.

## Refreshing Project Status

The Refresh Status option checks read/write disk status for the project file and for filesystem-based components (such as files and dialog projects) within the project. If the project contains files of a language for which "code intelligence" is supported and enabled (as configured in the Code Intelligence Preferences), Refresh Status also updates the code intelligence database with the contents of those files.

If the project or its components are stored in a source code control system, Refresh Status also checks the repository status of the file. Komodo determines whether a file is contained in an SCC repository by the following methods:

- Perforce: query of the P4 repository (with the current user's client spec)
- CVS: analysis of the CVS control directories
- Subversion: analysis of the subversion control files

## Importing and Exporting Projects via Packages

Entire projects (including all the components contained in a project) can be exported to a "package" file for distribution to other Komodo users or for the sake of archiving. Packages are compressed archive files that contain the project from which the Export Package option was invoked. The Export Package option differs from the Export as Project File option (provided for project components) in that Export Package creates a self-contained archive file that contains copies of all the filesystem-based components (such as files and dialogs). Export as Project File, on the other hand, only contains Komodo-specific components (such as snippets and run commands).

To export a project and its contents to an archive, select Project|project_name|Export Package from the drop-down menu, or right-click the project and select Export Package.

The Package Export Wizard prompts for a Package Name and a Export Location. The Package Name is the file in which the package is stored; it will have the extension ".kpz", and can be opened by any archiving utility that supports `libz` (for example WinZip).

Exported packages can only be imported into "container" objects in Komodo, such as projects, the Toolbox, and folders within projects and the Toolbox.

To import the contents of a package into a project, right-click the project to which you want to import the package, and click Import Package. The Package Import Wizard prompts for the name of the package and the location on disk where the files will be extracted. Click Next and then click Finish to complete the import.

For information about importing packages to the Toolbox or a folder, see Toolbox - Import Package and Folders - Import Package for more information.

## Importing Files from the File System

This option creates files within a project based on the directory structure and file contents of a local or network filesystem. File references within the project are created for imported files; folders are created for directories (depending on the configuration of the import options). To import a filesystem into a project:

- Project Menu: On the Project menu, click Import from File System. This imports the specified filesystem (according to the criteria described below) into the current active project. If a project name is currently highlighted in the Projects sidebar, the Project menu contains an option for importing into the selected project (Project|project_name|Import from File System).
- Project Context Menu: Right-click the desired project and select Import from File System.

Configure the following import options:

- Directory to import from: Specify the directory from which you want to import files. Use the Browse button to navigate the file system.
- Browse for directory location: Choose Locally... to browse the local filesystem or Remotely... to browse a remote filesystem.
- Files to include: Specify the filenames to include. Use wildcards ("*" and "?") to specify groups of files. Separate multiple file specifications with semicolons. If the field is left blank, all files in the specified directory are imported.
- Files and directories to exclude: Specify the file and directory names to exclude. Use wildcards ("*" and "?") to specify groups of files. Separate multiple file specifications with semicolons. If the field is left blank, no files in the specified directory are excluded.
- Import Subdirectories Recursively: Select this check box to import directories (and files contained in those directories) located beneath the directory specified in the Directory to import from field. This check box must be checked in order to specify the "Import Directory Structure" option as the Type of folder structure to create.
- Type of folder structure to create:
  - Import directory structure: If the Import Subdirectories Recursively box is selected and this option is selected, Komodo creates folders within the project that represent imported directories. Thus, the directory structure is preserved within the project.
  - Make a folder per language: If this option is selected, imported files are organized into folders according to the language indicated by file pattern in the filename. File associations are configured in the Komodo Preferences. Each folder is named after the associated language, for example, "Perl files", "XML files", etc. Files that don't correspond to a known file pattern are stored in a folder called "Other files".
  - Make one flat list: If this option is selected, all the imported files are placed directly under the project from which the Import from File System command was invoked.

## Source Code Control Komodo IDE only

Source code control refers to projects and/or components stored in a source code control depot (such as a CVS or Perforce repository). There are two aspects to source code control within projects: source code control on the project file itself, and source code control on components contained in projects.

When Komodo integration with a source code control system is configured, icons in the Project Manager display the SCC status of the project file and components contained in the project. See file status icons in the source code control documentation for more information about these icons.

Source code control functions (such as adding files to an SCC repository, or opening files contained in a repository for editing) can be performed both on the project file, and on the components contained in the project. To access SCC commands for a project file:

- Project Menu: Click the project name in the Project Manager, then select Project|project_name|Source Control).
- Project Context Menu: Right-click the desired project and select Source Control.

To access SCC commands for the components contained in a project:

- Project Menu: Click the project name in the Project Manager, then select Project|project_name|Source Control on Contents).
- Project Context Menu: Right-click the desired project and select Source Control on Contents.

See Source Code Control Commands for a description of each of the commands.

## Reverting Projects

If a project has been altered but has not been saved, use the Revert Project option to undo the changes. To access the Revert Project option:

- Project Context Menu: Right-click the desired project and select Revert Project.
- Project Menu: Select Project|Revert Project or Project|project_name|Revert Project. Project|Revert Project reverts the active project. If a project name is currently highlighted in the Projects sidebar, the Project menu contains an option for reverting the selected project (Project|project_name|Revert Project).

## Closing Projects

Closing a project removes it from the Projects sidebar. To close a project:

- File Menu: On the File menu, click Close Project.
- Project Menu: On the Project menu, click Close Project. This closes the active project. If a project name is currently highlighted in the Projects sidebar, the Project menu contains an option for closing the selected project (Project|project_name|Close Project).
- Project Context Menu: Right-click the desired project and select Close Project.

If the project has changed since it was last saved, you are prompted to save it. If files contained in the project are open in the editor, you are asked if you wish to close them.

## Deleting Projects

When a project is deleted, the project file is deleted from disk; Komodo-specific components (such as run commands and macros) stored in the project are also deleted. Filesystem-based components (such as files and dialog projects) are not deleted. To delete a project, delete the project file from the filesystem.

## Project Properties and Settings

The Project Properties and Settings dialog box contains information about the project file, such as its size, its location on disk, its directory import settings, its source code control status, and project-specific language settings.

To access the Project Properties dialog box, right-click the desired project name and select Properties, or click the desired project and select Project|project_name|Properties from the drop-down menu.

The following categories are available:

- Properties: Displays the name, size, and location of the project; the date and time it was created, last modified and last accessed; and indicates if the project is read-only.
- Source Code Control: Displays SCC status as applicable (SCC System, Status, Depot Revision, and My Revision).
- Debugging: Displays a subset of the settings available in the Debugging Options dialog box. These settings will take precedence over the default debugging settings for files in the project.
- Directory Import: Defines how Komodo dynamically imports files and directories into the project. These settings override those configured in Komodo's global Directory Import preferences. Select the Live Import check box to keep the imported directories and files current with the file system via Live Folders.
- Languages: Allows you to add additional directories to a language's path for Komodo to use when debugging, syntax checking, or in the interactive shell. Komodo will also scan these directories for autocomplete and calltip information.

## Project Templates

Project templates are useful if you find yourself repeatedly creating the same types of projects. See the Project Templates documentation for information on using Komodo's sample project templates, and saving your own.