Projects

Project structure, repositories, versioning, and collaborative workflows in Ghidra

Project Fundamentals

A Ghidra project serves as a container for organizing reverse engineering work. Projects manage collections of domain files, tool configurations, and optional repository connections for collaboration.

// From ghidra/framework/model/Project.java:26-48
public interface Project extends AutoCloseable, Iterable<DomainFile> {
    String getName();
    ProjectLocator getProjectLocator();
    ProjectData getProjectData();
    ToolManager getToolManager();
    ToolChest getLocalToolChest();
    RepositoryAdapter getRepository();
    void save();
    void close();
}

Project Structure

Physical Layout

A Ghidra project consists of several directories:

MyProject/
├── MyProject.gpr          # Project properties file
├── MyProject.rep/         # Project repository (if shared)
└── data/                  # Domain file storage
    ├── _projectState      # Project metadata
    ├── ~index.bak         # Index backup
    ├── ~index.dat         # File index
    └── [folders]/         # User-created folder hierarchy
        └── *.gbf          # Ghidra binary files (programs)

Domain Files

Domain files are the primary data artifacts in a project:

// From ghidra/framework/model/DomainFile.java
public interface DomainFile {
    String getName();
    String getPathname();
    DomainFolder getParent();
    boolean isCheckedOut();
    boolean isVersioned();
    int getLatestVersion();
    DomainObject getDomainObject(Object consumer, boolean okToUpgrade);
}

Common Domain File Types:

Program

Binary executables with analysis data (*.gzf)

Data Type Archive

Shared data type definitions (*.gdt)

Tool

Saved tool configurations (*.tool)

Folder Link

Links to external project folders

Project Types

Ghidra supports different project configurations:

Local Projects

Standalone projects stored on the local file system:

• No version control
• No collaboration features
• Fastest performance
• Ideal for personal analysis

Shared Projects

Projects connected to a Ghidra Server repository:

• Version control for all files
• Multi-user collaboration
• Check-out/check-in workflow
• Merge conflict resolution
• User access control

public RepositoryAdapter getRepository() {
    // Returns null for local projects
    // Returns RepositoryAdapter for shared projects
}

From ghidra/framework/model/Project.java:76-80

ProjectData Interface

The ProjectData interface provides access to the project’s file system:

// From ghidra/framework/model/ProjectData.java:30-38
public interface ProjectData extends Iterable<DomainFile> {
    DomainFolder getRootFolder();
    DomainFolder getFolder(String path);
    DomainFile getFile(String path);
    int getFileCount();
}

Folder Hierarchy

Projects organize files in a folder tree:

public interface DomainFolder {
    String getName();
    String getPathname();
    DomainFolder getParent();
    DomainFolder[] getFolders();
    DomainFile[] getFiles();
    DomainFolder createFolder(String name);
    DomainFile createFile(String name, DomainObject obj);
}

Use meaningful folder hierarchies to organize your analysis:

/firmware/
    /bootloader/
    /kernel/
    /drivers/
/malware/
    /samples/
    /unpacked/

Version Control

Shared projects provide full version control capabilities.

File Versioning

Each save creates a new version:

public interface DomainFile {
    boolean isVersioned();
    int getLatestVersion();
    Version[] getVersionHistory();
    DomainObject getReadOnlyVersion(int version, Object consumer);
    DomainObject getImmutableDomainObject(Object consumer, int version);
}

Version History:

public class Version {
    int getVersion();              // Version number
    long getCreateTime();          // Timestamp
    String getUser();              // Who created this version
    String getComment();           // Version comment
}

Check-Out Model

Shared projects use an exclusive check-out model:

1. Request Check-Out

   User requests exclusive write access to a file

   boolean checkout(boolean exclusive, TaskMonitor monitor);
   
2. Make Changes

   User modifies the checked-out file locally

3. Check In

   User commits changes back to the repository

   void checkin(CheckinHandler handler, TaskMonitor monitor);
   

Check-Out States:

• Not Versioned - Local file, no repository
• Checked In - Latest version in repository
• Checked Out (Exclusive) - User has write lock
• Checked Out (Non-Exclusive) - Read-only checkout
• Hijacked - Local changes on checked-in file

Merging Changes

When checking in files that are out of date:

public interface CheckinHandler {
    boolean keepCheckedOut();
    String getComment();
    boolean createKeepFile();
    boolean merge(DomainObject resultObj, DomainObject sourceObj);
}

Ghidra provides automatic and manual merge strategies:

• Auto-merge - Combines non-conflicting changes
• Manual merge - User resolves conflicts interactively
• Keep file - Save pre-merge version as backup

From ghidra/framework/data/CheckinHandler.java

Project Views

Projects can include views of other projects:

// From ghidra/framework/model/Project.java:83-94
public ProjectData addProjectView(URL projectURL, boolean visible) 
        throws IOException {
    // Add read-only view of another project
}

public void removeProjectView(URL projectURL);

public ProjectLocator[] getProjectViews();

Use Cases:

• Reference shared libraries across projects
• Access central data type archives
• Compare related programs
• Organize large analysis efforts

Project views are read-only. Changes must be made in the owning project.

Tool Management

Projects manage tool instances and configurations:

public interface ToolManager {
    ToolTemplate[] getToolTemplates();
    PluginTool[] getRunningTools();
    Workspace getActiveWorkspace();
    PluginTool createTool(ToolTemplate template);
}

From ghidra/framework/model/ToolManager.java

Tool Templates

Templates define tool configurations:

public interface ToolTemplate {
    String getName();
    String getToolName();
    Set<String> getSupportedDataTypes();
    PluginInfo[] getPluginInfos();
}

Built-in Tools:

• CodeBrowser - Primary analysis interface
• VersionTracking - Compare program versions
• FunctionGraphTool - Visualize control flow

Workspaces

Workspaces organize running tool windows:

public interface Workspace {
    String getName();
    ToolTemplate[] getToolTemplates();
    void save();
}

Storage Implementation

Understanding the storage layer helps with troubleshooting and administration.

File System Types

Indexed File System (Current):

• Uses ~index.dat for fast lookups
• Supports large projects efficiently
• Required for file count queries

Mangled File System (Legacy):

• Encodes paths in file names
• Slower for large projects
• No file count support

public interface ProjectData {
    Class<? extends LocalFileSystem> getLocalStorageClass();
    int getFileCount(); // Returns -1 for mangled file system
}

From ghidra/framework/model/ProjectData.java:40-96

Database Files

Domain files are stored as database files:

program.gbf/
├── ~index.dat         # Property index
├── program.gzf       # Compressed program data
└── user0.gvf         # User-specific data

Never manually modify files in the project directory. Always use Ghidra’s API or UI to manipulate domain files.

Project Lifecycle

Creating Projects

public interface ProjectManager {
    Project createProject(ProjectLocator projectLocator, 
                         RepositoryAdapter repository,
                         boolean remember);
    
    Project openProject(ProjectLocator projectLocator,
                       boolean doRestore,
                       boolean resetOwner);
}

Closing Projects

public void close() {
    // Saves project state
    // Closes all tools
    // Releases all domain objects
    // Disconnects from repository
}

From ghidra/framework/model/Project.java:108-111

Project Locking

Only one Ghidra instance can open a project at a time:

public class ProjectLock {
    // Prevents concurrent access
    // Lock file: [project].lock
}

From ghidra/framework/data/ProjectLock.java

Repository Server

Shared projects connect to a Ghidra Server:

Server Architecture

• Central Repository - Stores all versioned files
• User Management - Authentication and access control
• File Locking - Manages check-out/check-in
• Event Notification - Notifies clients of changes

Repository Adapter

public interface RepositoryAdapter {
    String getName();
    ServerInfo getServerInfo();
    User getUser();
    RepositoryItem[] getItemList(String folderPath);
    void connect() throws IOException;
    void disconnect();
}

From ghidra/framework/client/RepositoryAdapter.java

Best Practices

Project Organization

• Use descriptive project names
• Create folder hierarchies for related files
• Separate projects by architecture or product
• Archive completed analysis projects

Version Control

• Check in frequently with meaningful comments
• Review version history before checking in
• Resolve conflicts promptly
• Use keep files for major changes

Collaboration

• Communicate with team about check-outs
• Establish naming conventions
• Share data type archives
• Document analysis decisions

Performance

• Keep project file counts reasonable
• Clean up unused files
• Backup regularly
• Monitor repository connection status

Troubleshooting

Lock File Issues

If project won’t open due to lock:

1. Ensure no other Ghidra instances are running
2. Check for zombie processes
3. Manually remove .lock file (use caution)

Repository Connection

If repository connection fails:

• Verify server address and port
• Check firewall settings
• Confirm user credentials
• Test network connectivity

Merge Conflicts

If merge fails:

• Create a keep file
• Manually merge in separate project
• Check in resolved version

Next Steps

Programs

Learn about the program model

Analysis

Understand analysis workflows

Architecture

Explore framework architecture

Overview

Return to framework overview