{"id":28483609,"url":"https://github.com/andrecrjr/dotproj","last_synced_at":"2026-04-07T07:45:55.637Z","repository":{"id":297807163,"uuid":"997958548","full_name":"andrecrjr/dotproj","owner":"andrecrjr","description":"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.","archived":false,"fork":false,"pushed_at":"2025-08-04T23:25:01.000Z","size":1507,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-07T07:45:53.583Z","etag":null,"topics":["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"],"latest_commit_sha":null,"homepage":"https://dotproj.ac-jr.com","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andrecrjr.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-07T15:08:52.000Z","updated_at":"2026-03-10T01:42:47.000Z","dependencies_parsed_at":"2025-06-07T16:29:04.773Z","dependency_job_id":"d8b2e246-18b3-42a5-9b14-501dc3ee90d0","html_url":"https://github.com/andrecrjr/dotproj","commit_stats":null,"previous_names":["andrecrjr/dotproj"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/andrecrjr/dotproj","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrecrjr%2Fdotproj","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrecrjr%2Fdotproj/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrecrjr%2Fdotproj/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrecrjr%2Fdotproj/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andrecrjr","download_url":"https://codeload.github.com/andrecrjr/dotproj/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrecrjr%2Fdotproj/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31504897,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T03:10:19.677Z","status":"ssl_error","status_checked_at":"2026-04-07T03:10:13.982Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2025-06-07T22:05:13.948Z","updated_at":"2026-04-07T07:45:55.612Z","avatar_url":"https://github.com/andrecrjr.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🎯 DotProj - Project-Specific Configuration Manager\n\n**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.\n\n*DotProj uses Git commands (`commit`, `push`, `pull`, `clone`) making it intuitive for developers!*\n\n## Quick Install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/andrecrjr/dotproj/master/install.sh | bash\n```\n\n## Prerequisites:\n* **Git** must be installed and configured:\n    ```bash\n    git config --global user.name \"Your Name\"\n    git config --global user.email \"your.email@example.com\"\n    ```\n* **Curl** must be installed.\n\n## 📋 What It Solves\n\nEliminates the hassle of manually copying configuration files like:\n- **Environment files**: `.env`, `.env.local`, `.env.development`\n- **Editor configurations**: `.vscode`, `.cursor`\n- **Linting \u0026 formatting**: `.eslintrc.json`, `.prettierrc`, `.editorconfig`\n- **Build \u0026 deployment**: `docker-compose.override.yml`, `Dockerfile.dev`\n\n**Key Features**:\n- **Git-like workflow** - familiar commands for developers\n- **Smart auto-detection** - no need to specify project names in most cases\n- **Smart branch selection** - choose configurations from different branches\n- **Centralizes** configurations in organized storage\n- **Symlinks** files for real-time synchronization\n- **Smart backups** - one backup per file, no clutter\n- **Git versioning** for team collaboration\n- **Cross-machine sync** via remote repositories (create a private repo)\n\n## 🎯 Smart Auto-Detection\n\nDotProj automatically detects which project to work with based on your current directory:\n\n- **Single project**: Auto-detects and uses it (shows `🎯 Auto-detected project: name`)\n- **Multiple projects**: Shows numbered list for quick selection\n- **No projects**: Provides helpful guidance on next steps\n\n**Examples**:\n```bash\n# Single project in directory\n$ dotproj status\n🎯 Auto-detected project: my-app\n📊 Status for project 'my-app'...\n\n# Multiple projects in directory  \n$ dotproj commit\n📋 Multiple projects found in current directory:\n 1) frontend\n 2) backend\nSelect project number: 1\n✅ Selected project: frontend\n```\n\nThis makes commands much faster to use while keeping full control when needed.\n\n## 🔒 Security \u0026 Privacy\n\n**⚠️ CRITICAL: Use PRIVATE repositories for sensitive files!**\n\n- **Environment files**: `.env`, `.env.local`, `.env.production` → **PRIVATE REPO ONLY**\n- **API keys \u0026 secrets**: Any file with passwords, tokens, keys → **PRIVATE REPO ONLY**\n- **Team configs**: Shared sensitive settings → **PRIVATE TEAM REPO**\n\n**Repository Security Checklist**:\n- ✅ Create private repository before `dotproj init`\n- ✅ Verify repository visibility is \"Private\" \n- ✅ Only invite trusted team members\n- ✅ Never commit actual secrets to public repos\n\n## 🚀 Essential Workflows\n\n### 🔧 Basic Individual Flow (Git-like)\n\n**Create new project**:\n```bash\n# 0. 🔒 IMPORTANT: Create a PRIVATE repository first!\n#    For projects with sensitive files (.env, API keys, secrets):\n#    → GitHub: Create private repo (avoid adding README)\n#    → GitLab: Create private repo \n#    → Example: https://github.com/username/my-project-config.git\n\n# 1. Initialize project (prompts for files)\ndotproj init my-project\n\n# 2. Select files when prompted: .env.local, .vscode, .cursor, etc.\n#    → Files are copied to storage\n\n# 3. Apply files as symlinks to your project\ndotproj commit           # Auto-detects 'my-project' in current directory\n\n# 4. Work normally - changes auto-saved via symlinks\n\n# 5. Push changes to Git (when ready)\ndotproj push            # Auto-detects 'my-project' in current directory\n```\n\n**Add more files later**:\n```bash\n# Add new files to existing project\ndotproj add              # Auto-detects project, interactive selection\ndotproj commit          # Apply new files as symlinks\ndotproj push            # Push changes to remote\n```\n\n### 👥 Team Shared Flow (Git-like)\n\n**Team member 1 - Create and share**:\n```bash\n# 1. 🔒 Create PRIVATE repository first (for sensitive team configs)\n#    → GitHub/GitLab: Create private repo for team\n#    → Example: https://github.com/team/project-config.git\n\n# 2. Initialize project with Git repo\ndotproj init team-project\n# → Enter PRIVATE Git repo URL when prompted\n\n# 3. Select team files: .env.example, .vscode, .cursor, etc.\n#    ⚠️  SECURITY: Ensure repo is PRIVATE for sensitive files!\n\n# 4. Apply and push to team\ndotproj commit          # Auto-detects 'team-project', apply files as symlinks\ndotproj push            # Push to remote repo\n```\n\n**Team member 2+ - Clone and use**:\n```bash\n# 1. Go to your project directory\ncd /path/to/your-project\n\n# 2. Clone team's configurations\ndotproj clone team-project\n# → Enter repo URL: https://github.com/team/project-config.git\n# → Choose branch if multiple available (e.g., dotproj-frontend, dotproj-backend)\n# → Optionally apply files immediately\n\n# 3. Work and sync changes\n# Edit files normally...\ndotproj push            # Auto-detects project, push your changes\ndotproj pull            # Get latest team changes\n```\n\n### 🌟 Advanced Multi-Branch Workflow\n\n**Different configurations per environment/role**:\n```bash\n# Team has multiple configuration branches:\n# - dotproj-frontend (React/Next.js configs)\n# - dotproj-backend (Node.js/API configs) \n# - dotproj-fullstack (Complete setup)\n\n# Clone and choose specific branch\ndotproj clone my-project https://github.com/team/configs.git\n# → Shows: 1) dotproj-frontend ⭐ 2) dotproj-backend ⭐ 3) main\n# → Select: 1\n# → Gets frontend-specific configs (.vscode React settings, .env.local, etc.)\n\n# Switch to different branch later\ndotproj pull            # Auto-detects 'my-project'\n# → Choose different branch if needed\n# → Updates to new configuration set\n```\n\n## 📖 Commands (Git-like Interface)\n\n```bash\n# Essential Commands (Git-like) - Project name optional when working in project directory\ndotproj init \u003cproject\u003e           # Initialize new project (like 'git init')\ndotproj clone \u003cproject\u003e [url]    # Clone from remote repo (like 'git clone')\ndotproj add [project]            # Add more files to track (like 'git add')\ndotproj commit [project]         # Apply files as symlinks (like 'git commit')\ndotproj status [project]         # Show tracked files and branch (like 'git status')\ndotproj push [project]           # Push changes to remote (like 'git push')\ndotproj pull [project]           # Pull latest changes from remote (like 'git pull')\n\n# Management\ndotproj list                     # Show projects in current directory\ndotproj list all                 # Show all projects and their paths\ndotproj remove \u003cproject\u003e         # Remove project completely\n\n# Setup\ndotproj setup                    # Install dotproj\ndotproj version                  # Show version and system information\n```\n\n### 🔄 Legacy Commands (Deprecated but supported)\n```bash\n# Old commands still work with deprecation warnings:\ndotproj apply \u003cproject\u003e          # → Shows warning, runs 'commit'\ndotproj sync \u003cproject\u003e           # → Shows warning, runs 'push'  \ndotproj remote \u003cproject\u003e         # → Shows warning, runs 'clone'\ndotproj save \u003cproject\u003e           # → Shows warning, runs 'status'\n```\n\n## 💡 Use Cases\n\n**React/Next.js Frontend**:\n```bash\ndotproj init my-nextjs-app\n# Track: .env.local, .vscode, .cursorrules\ndotproj commit          # Auto-detects 'my-nextjs-app'\ndotproj push            # Push to remote\n```\n\n**Full-Stack with Multiple Configs**:\n```bash\n# Clone with branch selection\ndotproj clone fullstack-project https://github.com/team/configs.git\n# Choose: dotproj-fullstack branch\n# Gets: .env, .env.local, .vscode, docker-compose.override.yml, .cursorrules\n\n# Or create new with specific setup\ndotproj init backend-api  \n# Track: .env, .env.local, .vscode, docker-compose.yml\ndotproj commit          # Auto-detects 'backend-api'\ndotproj push            # Push to remote\n```\n\n**AI/ML with Cursor**:\n```bash\ndotproj clone ai-project https://github.com/team/ai-configs.git\n# Choose: dotproj-ai-python branch  \n# Gets: .cursorrules, .cursor/, .env, .vscode, requirements-dev.txt\n```\n\n**Team Collaboration**:\n```bash\n# Frontend developer\ndotproj clone team-project https://github.com/company/project-config.git\n# Selects: dotproj-frontend branch → React/Next.js specific configs\n\n# Backend developer  \ndotproj clone team-project https://github.com/company/project-config.git\n# Selects: dotproj-backend branch → Node.js/API specific configs\n```\n\n## 🔗 How It Works\n\n**Git-like workflow with symlinks**:\n```\nProject Directory                Storage Directory\n├── .env → ~/.dotproj/.../env    ├── .env (actual file)\n├── .vscode/ → ~/.dotproj/...    ├── .vscode/ (actual files)\n├── .cursor/ → ~/.dotproj/...    ├── .cursor/ (actual files)\n```\n\n**Workflow Steps**:\n1. **`init`/`clone`**: Set up project and select files/branch\n2. **`commit`**: Create symlinks (like staging and committing changes)\n3. **`push`**: Sync changes to remote repository\n4. **`pull`**: Get latest changes from team/other machines\n5. **`status`**: Check current state and tracked files\n\n**Benefits**:\n- **Familiar Git commands** for developers\n- **Branch-based configurations** for different setups\n- Edit files in project → changes immediately saved to storage\n- Delete project files → only removes symlinks, data stays safe\n- **Multi-branch support** for different environments/roles\n\n## 🌟 Branch Management\n\n**Smart Branch Selection**:\n- **Clone**: Always shows available branches for selection\n- **Pull**: Choose different branch if multiple remotes available  \n- **Status**: Shows current branch being used\n- **Persistent**: Selected branch remembered for future operations\n\n**Branch Types**:\n- **DotProj branches** (⭐): `dotproj-*` contain project-specific configs\n- **Other branches**: May contain shared or general configurations\n\n**Example Branch Structure**:\n```\nRepository Branches:\n├── main                     # General/shared configs\n├── dotproj-frontend ⭐      # React/Vue specific configs  \n├── dotproj-backend ⭐       # Node.js/API specific configs\n├── dotproj-fullstack ⭐     # Complete development setup\n└── dotproj-production ⭐    # Production-ready configs\n```\n\n## 🛡️ Safety \u0026 Backup System\n\n- **Smart backups**: One backup per file (e.g., `backups/.env_local.backup`)\n- **No clutter**: Backups update in place, no timestamped accumulation\n- **Symlink safety**: Deleting project files only removes symlinks\n- **Git versioning**: Full history and conflict detection\n- **Branch persistence**: Selected branch remembered across operations\n- **Easy restoration**: Predictable backup names\n\n## 🗂️ File Structure\n\n```\n~/.dotproj/\n├── config                      # Project configuration\n│   └── project:branch:dotproj-frontend  # Stores selected branch\n├── dotproj                     # Installed script\n└── projects/                   # Project storage\n    ├── my-project/\n    │   ├── .git/               # Git repository\n    │   ├── dotfiles/           # Tracked files (if using dotfiles/ structure)\n    │   ├── backups/            # Single backup per file\n    │   └── [config files]      # Direct config files (for remote repos)\n```\n\n## 🔍 Troubleshooting\n\n**Git not installed**:\n```bash\n# Ubuntu/Debian: sudo apt install git\n# CentOS/RHEL: sudo yum install git  \n# Fedora: sudo dnf install git\n# macOS: brew install git\n```\n\n**Command not found**:\n```bash\nsource ~/.bashrc  # or ~/.zshrc\nwhich dotproj     # Should show: ~/.dotproj/dotproj\n```\n\n**Branch issues**:\n```bash\ndotproj status \u003cproject\u003e      # Check current branch\ndotproj pull \u003cproject\u003e        # Switch branch if needed\n```\n\n**Backup/restore files**:\n```bash\nls -la backups/   # View backups\ncp backups/.env_local.backup .env.local  # Restore if needed\n```\n\n**Fix broken symlinks**:\n```bash\ndotproj status              # Check integrity (auto-detects project)\ndotproj commit              # Fix broken links\n```\n\n\u003e **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.\n\n\n\n## 📄 License\n\nMIT License - Copyright (c) 2024 Andre Jr (andrecrjr)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrecrjr%2Fdotproj","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandrecrjr%2Fdotproj","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrecrjr%2Fdotproj/lists"}