Skip to content

docs(windows): add comprehensive Windows browser profile paths documentation #17

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
theg1239 merged 1 commit into from
Oct 17, 2025
Merged

docs(windows): add comprehensive Windows browser profile paths documentation #17

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@
- [About](#about)
- [Architecture](#architecture)
- [Project Structure](#project-structure)
- [Documentation](#documentation)
- [Prerequisites](#prerequisites)
- [Quick Start](#quick-start)
- [Usage](#usage)
Expand Down Expand Up @@ -85,6 +86,25 @@ open-with-browser/

---

## Documentation

Comprehensive guides for developers and users:

- **[Documentation Hub](docs/README.md)** - Overview of all available documentation
- **[Windows Browser Profiles](docs/windows-browser-profiles.md)** - Complete guide to browser profile paths on Windows

### Quick Reference: Supported Browsers
| Browser | Windows | macOS | Linux | Profile Support |
|---------|---------|--------|-------|-----------------|
| Google Chrome | Documented | Planned | Planned | Documented |
| Microsoft Edge | Documented | Planned | Planned | Documented |
| Brave Browser | Documented | Planned | Planned | Documented |
| Mozilla Firefox | Documented | Planned | Planned | Documented |

**Legend**: Documented | Planned | Not supported

---

## Prerequisites

- Rust toolchain (stable)
Expand Down
66 changes: 66 additions & 0 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
# Open With Browser Documentation

Welcome to the Open With Browser documentation. This collection of guides helps developers and users understand how the application works with different browsers and their profiles across operating systems.

## Browser Profile Documentation

### Platform-Specific Guides
- **[Windows Browser Profiles](./windows-browser-profiles.md)** - Complete guide to browser profile paths on Windows for Chrome, Edge, Brave, and Firefox

### Planned Documentation
- **macOS Browser Profiles** - Browser profile paths for macOS systems
- **Linux Browser Profiles** - Browser profile paths for various Linux distributions
- **Browser Discovery Implementation** - Technical guide for implementing browser detection
- **Profile Launching Guide** - How to launch browsers with specific profiles
- **Cross-platform Browser Paths** - Unified approach to browser discovery across platforms

## Architecture Documentation

### Core Components
- **Rule Engine** - URL pattern matching and routing logic
- **Browser Discovery** - Automatic detection of installed browsers
- **Profile Resolution** - Finding and validating browser profiles
- **Link Opener** - Launching browsers with appropriate arguments

### Development Guides
- **Contributing to Browser Support** - Adding support for new browsers
- **Testing Profile Discovery** - Validation and testing strategies
- **Security Considerations** - Best practices for accessing user data

## Quick Reference

### Supported Browsers
| Browser | Windows | macOS | Linux | Profile Support |
|---------|---------|--------|-------|-----------------|
| Google Chrome | Documented | Planned | Planned | Documented |
| Microsoft Edge | Documented | Planned | Planned | Documented |
| Brave Browser | Documented | Planned | Planned | Documented |
| Mozilla Firefox | Documented | Planned | Planned | Documented |

**Legend**: Documented | Planned | Not supported

---

## Getting Started

1. **For Users**: Start with the platform-specific browser profile guide for your operating system
2. **For Developers**: Review the architecture documentation and implementation guides
3. **For Contributors**: Check the contributing guidelines and development setup instructions

---

## Contributing to Documentation

We welcome improvements to our documentation! Please see our [Contributing Guidelines](../CONTRIBUTING.md) for details on how to submit documentation updates.

### Documentation Standards
- Use clear, concise language
- Include practical examples and code snippets
- Keep platform-specific information separated
- Update the index when adding new documents
- Include version compatibility information
- Add security considerations where relevant

---

*This documentation is part of the Open With Browser project by [ACM-VIT](https://acmvit.in/)*
271 changes: 271 additions & 0 deletions docs/windows-browser-profiles.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,271 @@
# Windows Browser Profile Paths

This document lists the common Windows paths where major browsers store their profile data. This information is essential for the Open With Browser application to automatically discover and launch browser profiles.

## Table of Contents
- [Chrome (Google Chrome)](#chrome-google-chrome)
- [Edge (Microsoft Edge)](#edge-microsoft-edge)
- [Brave Browser](#brave-browser)
- [Firefox (Mozilla Firefox)](#firefox-mozilla-firefox)
- [Profile Discovery Notes](#profile-discovery-notes)
- [Command Line Arguments](#command-line-arguments)

---

## Chrome (Google Chrome)

### Default Profile Location
```
%LOCALAPPDATA%\Google\Chrome\User Data\Default
```

### Named Profiles
```
%LOCALAPPDATA%\Google\Chrome\User Data\Profile 1
%LOCALAPPDATA%\Google\Chrome\User Data\Profile 2
%LOCALAPPDATA%\Google\Chrome\User Data\Profile 3
...
```

### Custom Named Profiles
Chrome also supports custom profile directories with descriptive names:
```
%LOCALAPPDATA%\Google\Chrome\User Data\Profile Work
%LOCALAPPDATA%\Google\Chrome\User Data\Profile Personal
```

**Note**: Custom profile names shown in the Chrome UI (e.g., "Work Profile", "Personal Profile") are for display purposes only. The underlying folder names remain in the `Profile X` format.

### Profile Configuration
- **Preferences file**: `%LOCALAPPDATA%\Google\Chrome\User Data\[Profile]\Preferences`
- **Local State file**: `%LOCALAPPDATA%\Google\Chrome\User Data\Local State`

### Expanded Paths (Examples)
```
C:\Users\[Username]\AppData\Local\Google\Chrome\User Data\Default
C:\Users\[Username]\AppData\Local\Google\Chrome\User Data\Profile 1
```

---

## Edge (Microsoft Edge)

### Default Profile Location
```
%LOCALAPPDATA%\Microsoft\Edge\User Data\Default
```

### Named Profiles
```
%LOCALAPPDATA%\Microsoft\Edge\User Data\Profile 1
%LOCALAPPDATA%\Microsoft\Edge\User Data\Profile 2
%LOCALAPPDATA%\Microsoft\Edge\User Data\Profile 3
...
```

### Work/School Profiles
```
%LOCALAPPDATA%\Microsoft\Edge\User Data\Profile [ProfileName]
```

**Note**: Custom profile names shown in the Edge UI are for display purposes only. The underlying folder names remain in the `Profile X` format.

### Profile Configuration
- **Preferences file**: `%LOCALAPPDATA%\Microsoft\Edge\User Data\[Profile]\Preferences`
- **Local State file**: `%LOCALAPPDATA%\Microsoft\Edge\User Data\Local State`

### Expanded Paths (Examples)
```
C:\Users\[Username]\AppData\Local\Microsoft\Edge\User Data\Default
C:\Users\[Username]\AppData\Local\Microsoft\Edge\User Data\Profile 1
```

---

## Brave Browser

### Default Profile Location
```
%LOCALAPPDATA%\BraveSoftware\Brave-Browser\User Data\Default
```

### Named Profiles
```
%LOCALAPPDATA%\BraveSoftware\Brave-Browser\User Data\Profile 1
%LOCALAPPDATA%\BraveSoftware\Brave-Browser\User Data\Profile 2
%LOCALAPPDATA%\BraveSoftware\Brave-Browser\User Data\Profile 3
...
```

### Profile Configuration
- **Preferences file**: `%LOCALAPPDATA%\BraveSoftware\Brave-Browser\User Data\[Profile]\Preferences`
- **Local State file**: `%LOCALAPPDATA%\BraveSoftware\Brave-Browser\User Data\Local State`

### Expanded Paths (Examples)
```
C:\Users\[Username]\AppData\Local\BraveSoftware\Brave-Browser\User Data\Default
C:\Users\[Username]\AppData\Local\BraveSoftware\Brave-Browser\User Data\Profile 1
```

---

## Firefox (Mozilla Firefox)

### Profile Root Directory
```
%APPDATA%\Mozilla\Firefox\Profiles
```

### Profile Naming Convention
Firefox uses a unique identifier format:
```
%APPDATA%\Mozilla\Firefox\Profiles\[8-character-hash].default-release
%APPDATA%\Mozilla\Firefox\Profiles\[8-character-hash].default
%APPDATA%\Mozilla\Firefox\Profiles\[8-character-hash].[custom-name]
```

### Profile Configuration
- **Profiles.ini file**: `%APPDATA%\Mozilla\Firefox\profiles.ini`
- **Installs.ini file**: `%APPDATA%\Mozilla\Firefox\installs.ini`

### Profile Directory Examples
```
C:\Users\[Username]\AppData\Roaming\Mozilla\Firefox\Profiles\abc12345.default-release
C:\Users\[Username]\AppData\Roaming\Mozilla\Firefox\Profiles\def67890.work
C:\Users\[Username]\AppData\Roaming\Mozilla\Firefox\Profiles\ghi11121.personal
```

### Firefox Profile Discovery
To discover Firefox profiles programmatically, read the `profiles.ini` file:

```ini
[Profile0]
Name=default-release
IsRelative=1
Path=Profiles/abc12345.default-release
Default=1

[Profile1]
Name=work
IsRelative=1
Path=Profiles/def67890.work

[Profile2]
Name=personal
IsRelative=1
Path=Profiles/ghi11121.personal
```

---

## Profile Discovery Notes

### Chromium-based Browsers (Chrome, Edge, Brave)

1. **Local State File**: All Chromium-based browsers store profile information in a `Local State` JSON file located in their respective `User Data` directories.

2. **Profile List**: The Local State file contains a `profile.info_cache` object with profile details:
```json
{
"profile": {
"info_cache": {
"Default": {
"name": "Person 1",
"user_name": "user@example.com"
},
"Profile 1": {
"name": "Work Profile",
"user_name": "work@company.com"
}
}
}
}
```

3. **Profile Validation**: Check if a profile directory exists and contains a `Preferences` file to confirm it's a valid profile.

### Firefox-specific Notes

1. **profiles.ini Parser**: Parse the INI format to discover available profiles.

2. **Profile Paths**: Firefox uses relative paths in `profiles.ini`, so combine with the base profiles directory.

3. **Default Profile**: Look for `Default=1` to identify the default profile.

### General Discovery Algorithm

1. Check if the browser is installed by looking for the executable
2. Locate the user data/profiles directory
3. Parse the configuration files (Local State for Chromium, profiles.ini for Firefox)
4. Enumerate and validate discovered profiles
5. Extract profile names and metadata

---

## Command Line Arguments

### Chrome/Edge/Brave
```bash
# Launch with specific profile
chrome.exe --profile-directory="Profile 1"
msedge.exe --profile-directory="Default"
brave.exe --profile-directory="Profile 2"

# Launch with custom user data directory
chrome.exe --user-data-dir="C:\Custom\Path"
```

### Firefox
```bash
# Launch with specific profile
firefox.exe -P "work"
firefox.exe --profile "C:\Path\To\Profile"

# Launch profile manager
firefox.exe -ProfileManager
```

---

## Environment Variables Reference

| Variable | Path |
|----------|------|
| `%LOCALAPPDATA%` | `C:\Users\[Username]\AppData\Local` |
| `%APPDATA%` | `C:\Users\[Username]\AppData\Roaming` |
| `%USERPROFILE%` | `C:\Users\[Username]` |

---

## Version Compatibility

This documentation covers the current profile path conventions as of October 2024. These paths are stable across browser versions but may change in future major releases.

### Browser Version Notes
- **Chrome**: Stable across versions 80+
- **Edge**: Chromium-based Edge (version 79+)
- **Brave**: All versions since stable release
- **Firefox**: ESR and regular releases (version 70+)

---

## Security Considerations

When accessing browser profiles programmatically:

1. **Read-only Access**: Only read profile configuration files, never modify them while the browser is running
2. **File Locking**: Browser databases may be locked when the browser is active
3. **User Permissions**: Ensure the application has appropriate permissions to access user data directories
4. **Privacy**: Handle profile information with care, as it may contain sensitive user data

---

## See Also

- [Browser Discovery Implementation](./browser-discovery.md) (planned)
- [Profile Launching Guide](./profile-launching.md) (planned)
- [Cross-platform Browser Paths](./cross-platform-paths.md) (planned)

---

*Last updated: October 2024*