Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/andrecrjr/dotproj

Command-line tool stow-like that helps you with git to manage project-specific dotfiles/files with Git versioning. Keep your development environment configurations organized, versioned, and synchronized across different machines and projects in another remote project.
https://github.com/andrecrjr/dotproj

bash bash-script command-line command-line-tool developer-tools development development-environment development-workflow git linux localhost open-source shellscript stow symlink terminal terminal-based zsh

Last synced: 3 months ago
JSON representation

Command-line tool stow-like that helps you with git to manage project-specific dotfiles/files with Git versioning. Keep your development environment configurations organized, versioned, and synchronized across different machines and projects in another remote project.

Awesome Lists containing this project

README 

          
# 🎯 DotProj - Project-Specific Configuration Manager



**DotProj** is a developer-centric CLI tool designed to manage project-specific configuration files with Git versioning. It helps keep your development environment settings organized, versioned, and synchronized across multiple machines and projects.



*DotProj uses Git commands (`commit`, `push`, `pull`, `clone`) making it intuitive for developers!*



## Quick Install



```bash

curl -fsSL https://raw.githubusercontent.com/andrecrjr/dotproj/master/install.sh | bash

```



## Prerequisites:

* **Git** must be installed and configured:

    ```bash

    git config --global user.name "Your Name"

    git config --global user.email "your.email@example.com"

    ```

* **Curl** must be installed.



## 📋 What It Solves



Eliminates the hassle of manually copying configuration files like:

- **Environment files**: `.env`, `.env.local`, `.env.development`

- **Editor configurations**: `.vscode`, `.cursor`

- **Linting & formatting**: `.eslintrc.json`, `.prettierrc`, `.editorconfig`

- **Build & deployment**: `docker-compose.override.yml`, `Dockerfile.dev`



**Key Features**:

- **Git-like workflow** - familiar commands for developers

- **Smart auto-detection** - no need to specify project names in most cases

- **Smart branch selection** - choose configurations from different branches

- **Centralizes** configurations in organized storage

- **Symlinks** files for real-time synchronization

- **Smart backups** - one backup per file, no clutter

- **Git versioning** for team collaboration

- **Cross-machine sync** via remote repositories (create a private repo)



## 🎯 Smart Auto-Detection



DotProj automatically detects which project to work with based on your current directory:



- **Single project**: Auto-detects and uses it (shows `🎯 Auto-detected project: name`)

- **Multiple projects**: Shows numbered list for quick selection

- **No projects**: Provides helpful guidance on next steps



**Examples**:

```bash

# Single project in directory

$ dotproj status

🎯 Auto-detected project: my-app

📊 Status for project 'my-app'...



# Multiple projects in directory  

$ dotproj commit

📋 Multiple projects found in current directory:

 1) frontend

 2) backend

Select project number: 1

✅ Selected project: frontend

```



This makes commands much faster to use while keeping full control when needed.



## 🔒 Security & Privacy



**⚠️ CRITICAL: Use PRIVATE repositories for sensitive files!**



- **Environment files**: `.env`, `.env.local`, `.env.production` → **PRIVATE REPO ONLY**

- **API keys & secrets**: Any file with passwords, tokens, keys → **PRIVATE REPO ONLY**

- **Team configs**: Shared sensitive settings → **PRIVATE TEAM REPO**



**Repository Security Checklist**:

- ✅ Create private repository before `dotproj init`

- ✅ Verify repository visibility is "Private" 

- ✅ Only invite trusted team members

- ✅ Never commit actual secrets to public repos



## 🚀 Essential Workflows



### 🔧 Basic Individual Flow (Git-like)



**Create new project**:

```bash

# 0. 🔒 IMPORTANT: Create a PRIVATE repository first!

#    For projects with sensitive files (.env, API keys, secrets):

#    → GitHub: Create private repo (avoid adding README)

#    → GitLab: Create private repo 

#    → Example: https://github.com/username/my-project-config.git



# 1. Initialize project (prompts for files)

dotproj init my-project



# 2. Select files when prompted: .env.local, .vscode, .cursor, etc.

#    → Files are copied to storage



# 3. Apply files as symlinks to your project

dotproj commit           # Auto-detects 'my-project' in current directory



# 4. Work normally - changes auto-saved via symlinks



# 5. Push changes to Git (when ready)

dotproj push            # Auto-detects 'my-project' in current directory

```



**Add more files later**:

```bash

# Add new files to existing project

dotproj add              # Auto-detects project, interactive selection

dotproj commit          # Apply new files as symlinks

dotproj push            # Push changes to remote

```



### 👥 Team Shared Flow (Git-like)



**Team member 1 - Create and share**:

```bash

# 1. 🔒 Create PRIVATE repository first (for sensitive team configs)

#    → GitHub/GitLab: Create private repo for team

#    → Example: https://github.com/team/project-config.git



# 2. Initialize project with Git repo

dotproj init team-project

# → Enter PRIVATE Git repo URL when prompted



# 3. Select team files: .env.example, .vscode, .cursor, etc.

#    ⚠️  SECURITY: Ensure repo is PRIVATE for sensitive files!



# 4. Apply and push to team

dotproj commit          # Auto-detects 'team-project', apply files as symlinks

dotproj push            # Push to remote repo

```



**Team member 2+ - Clone and use**:

```bash

# 1. Go to your project directory

cd /path/to/your-project



# 2. Clone team's configurations

dotproj clone team-project

# → Enter repo URL: https://github.com/team/project-config.git

# → Choose branch if multiple available (e.g., dotproj-frontend, dotproj-backend)

# → Optionally apply files immediately



# 3. Work and sync changes

# Edit files normally...

dotproj push            # Auto-detects project, push your changes

dotproj pull            # Get latest team changes

```



### 🌟 Advanced Multi-Branch Workflow



**Different configurations per environment/role**:

```bash

# Team has multiple configuration branches:

# - dotproj-frontend (React/Next.js configs)

# - dotproj-backend (Node.js/API configs) 

# - dotproj-fullstack (Complete setup)



# Clone and choose specific branch

dotproj clone my-project https://github.com/team/configs.git

# → Shows: 1) dotproj-frontend ⭐ 2) dotproj-backend ⭐ 3) main

# → Select: 1

# → Gets frontend-specific configs (.vscode React settings, .env.local, etc.)



# Switch to different branch later

dotproj pull            # Auto-detects 'my-project'

# → Choose different branch if needed

# → Updates to new configuration set

```



## 📖 Commands (Git-like Interface)



```bash

# Essential Commands (Git-like) - Project name optional when working in project directory

dotproj init            # Initialize new project (like 'git init')

dotproj clone  [url]    # Clone from remote repo (like 'git clone')

dotproj add [project]            # Add more files to track (like 'git add')

dotproj commit [project]         # Apply files as symlinks (like 'git commit')

dotproj status [project]         # Show tracked files and branch (like 'git status')

dotproj push [project]           # Push changes to remote (like 'git push')

dotproj pull [project]           # Pull latest changes from remote (like 'git pull')



# Management

dotproj list                     # Show projects in current directory

dotproj list all                 # Show all projects and their paths

dotproj remove          # Remove project completely



# Setup

dotproj setup                    # Install dotproj

dotproj version                  # Show version and system information

```



### 🔄 Legacy Commands (Deprecated but supported)

```bash

# Old commands still work with deprecation warnings:

dotproj apply           # → Shows warning, runs 'commit'

dotproj sync            # → Shows warning, runs 'push'  

dotproj remote          # → Shows warning, runs 'clone'

dotproj save            # → Shows warning, runs 'status'

```



## 💡 Use Cases



**React/Next.js Frontend**:

```bash

dotproj init my-nextjs-app

# Track: .env.local, .vscode, .cursorrules

dotproj commit          # Auto-detects 'my-nextjs-app'

dotproj push            # Push to remote

```



**Full-Stack with Multiple Configs**:

```bash

# Clone with branch selection

dotproj clone fullstack-project https://github.com/team/configs.git

# Choose: dotproj-fullstack branch

# Gets: .env, .env.local, .vscode, docker-compose.override.yml, .cursorrules



# Or create new with specific setup

dotproj init backend-api  

# Track: .env, .env.local, .vscode, docker-compose.yml

dotproj commit          # Auto-detects 'backend-api'

dotproj push            # Push to remote

```



**AI/ML with Cursor**:

```bash

dotproj clone ai-project https://github.com/team/ai-configs.git

# Choose: dotproj-ai-python branch  

# Gets: .cursorrules, .cursor/, .env, .vscode, requirements-dev.txt

```



**Team Collaboration**:

```bash

# Frontend developer

dotproj clone team-project https://github.com/company/project-config.git

# Selects: dotproj-frontend branch → React/Next.js specific configs



# Backend developer  

dotproj clone team-project https://github.com/company/project-config.git

# Selects: dotproj-backend branch → Node.js/API specific configs

```



## 🔗 How It Works



**Git-like workflow with symlinks**:

```

Project Directory                Storage Directory

├── .env → ~/.dotproj/.../env    ├── .env (actual file)

├── .vscode/ → ~/.dotproj/...    ├── .vscode/ (actual files)

├── .cursor/ → ~/.dotproj/...    ├── .cursor/ (actual files)

```



**Workflow Steps**:

1. **`init`/`clone`**: Set up project and select files/branch

2. **`commit`**: Create symlinks (like staging and committing changes)

3. **`push`**: Sync changes to remote repository

4. **`pull`**: Get latest changes from team/other machines

5. **`status`**: Check current state and tracked files



**Benefits**:

- **Familiar Git commands** for developers

- **Branch-based configurations** for different setups

- Edit files in project → changes immediately saved to storage

- Delete project files → only removes symlinks, data stays safe

- **Multi-branch support** for different environments/roles



## 🌟 Branch Management



**Smart Branch Selection**:

- **Clone**: Always shows available branches for selection

- **Pull**: Choose different branch if multiple remotes available  

- **Status**: Shows current branch being used

- **Persistent**: Selected branch remembered for future operations



**Branch Types**:

- **DotProj branches** (⭐): `dotproj-*` contain project-specific configs

- **Other branches**: May contain shared or general configurations



**Example Branch Structure**:

```

Repository Branches:

├── main                     # General/shared configs

├── dotproj-frontend ⭐      # React/Vue specific configs  

├── dotproj-backend ⭐       # Node.js/API specific configs

├── dotproj-fullstack ⭐     # Complete development setup

└── dotproj-production ⭐    # Production-ready configs

```



## 🛡️ Safety & Backup System



- **Smart backups**: One backup per file (e.g., `backups/.env_local.backup`)

- **No clutter**: Backups update in place, no timestamped accumulation

- **Symlink safety**: Deleting project files only removes symlinks

- **Git versioning**: Full history and conflict detection

- **Branch persistence**: Selected branch remembered across operations

- **Easy restoration**: Predictable backup names



## 🗂️ File Structure



```

~/.dotproj/

├── config                      # Project configuration

│   └── project:branch:dotproj-frontend  # Stores selected branch

├── dotproj                     # Installed script

└── projects/                   # Project storage

    ├── my-project/

    │   ├── .git/               # Git repository

    │   ├── dotfiles/           # Tracked files (if using dotfiles/ structure)

    │   ├── backups/            # Single backup per file

    │   └── [config files]      # Direct config files (for remote repos)

```



## 🔍 Troubleshooting



**Git not installed**:

```bash

# Ubuntu/Debian: sudo apt install git

# CentOS/RHEL: sudo yum install git  

# Fedora: sudo dnf install git

# macOS: brew install git

```



**Command not found**:

```bash

source ~/.bashrc  # or ~/.zshrc

which dotproj     # Should show: ~/.dotproj/dotproj

```



**Branch issues**:

```bash

dotproj status       # Check current branch

dotproj pull         # Switch branch if needed

```



**Backup/restore files**:

```bash

ls -la backups/   # View backups

cp backups/.env_local.backup .env.local  # Restore if needed

```



**Fix broken symlinks**:

```bash

dotproj status              # Check integrity (auto-detects project)

dotproj commit              # Fix broken links

```



> **Tip**: Use `dotproj list` to see projects in current directory, `dotproj list all` to see all projects, and `dotproj status` to check tracked files and current branch.



## 📄 License



MIT License - Copyright (c) 2024 Andre Jr (andrecrjr)