diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml new file mode 100644 index 0000000..3aed61a --- /dev/null +++ b/.github/workflows/deploy-docs.yml @@ -0,0 +1,54 @@ +name: Deploy Docs to GitHub Pages + +on: + push: + branches: [main, master] # or your default branch + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '18' + cache: 'npm' + cache-dependency-path: './docs/package-lock.json' + + - name: Install dependencies + run: | + cd docs + npm ci + + - name: Build website + run: | + cd docs + npm run build + + - name: Setup Pages + uses: actions/configure-pages@v3 + + - name: Upload artifact + uses: actions/upload-pages-artifact@v2 + with: + path: './docs/build' + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v2 diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..b2d6de3 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,20 @@ +# Dependencies +/node_modules + +# Production +/build + +# Generated files +.docusaurus +.cache-loader + +# Misc +.DS_Store +.env.local +.env.development.local +.env.test.local +.env.production.local + +npm-debug.log* +yarn-debug.log* +yarn-error.log* diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..b28211a --- /dev/null +++ b/docs/README.md @@ -0,0 +1,41 @@ +# Website + +This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator. + +## Installation + +```bash +yarn +``` + +## Local Development + +```bash +yarn start +``` + +This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. + +## Build + +```bash +yarn build +``` + +This command generates static content into the `build` directory and can be served using any static contents hosting service. + +## Deployment + +Using SSH: + +```bash +USE_SSH=true yarn deploy +``` + +Not using SSH: + +```bash +GIT_USER= yarn deploy +``` + +If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch. diff --git a/docs/docs/commands/gitignore/gitignore-add.md b/docs/docs/commands/gitignore/gitignore-add.md new file mode 100644 index 0000000..b924411 --- /dev/null +++ b/docs/docs/commands/gitignore/gitignore-add.md @@ -0,0 +1,229 @@ +--- +title: "gh-templates gitignore add" +sidebar_label: "gitignore add" +--- + +# Add Gitignore Templates + +Add one or more gitignore templates to your repository. + +## Usage + +```bash +gh-templates gitignore add [OPTIONS] [TEMPLATE]... +``` + +## Arguments + +| Argument | Description | +|-----------------|------------------------------------------------------------------| +| `[TEMPLATE]...` | Gitignore template names to add (e.g., rust, python, global/windows) | + +## Options + +| Option | Description | +|-------------------------------|-----------------------------------------------------------------------------| +| `--dir ` | Directory to save the `.gitignore` file | +| `--force` | Force overwrite existing `.gitignore` file | +| `--all` | Download all available templates | +| `-a, --append` | Append to the existing `.gitignore` file instead of overwriting | +| `--update-cache` | Update the gitignore template cache | +| `-n, --use-remote-name` | Use the remote template file name as the output file name | +| `-o, --output ...` | Output file name(s) (default: `.gitignore`) | +| `-h, --help` | Print help | + +## Examples + +### Add a Single Template + +```bash +gh-templates gitignore add rust +``` + +Downloads the Rust gitignore template and saves it as `.gitignore` in the repository root. + +### Add Multiple Templates + +```bash +gh-templates gitignore add rust docker vscode +``` + +Combines multiple gitignore templates into a single comprehensive file. + +### Custom Output Directory + +```bash +gh-templates gitignore add python --dir backend/ +``` + +Saves the gitignore file to a custom directory (useful for monorepos). + +### Custom File Names + +```bash +gh-templates gitignore add rust python -o .gitignore.rust -o .gitignore.python +``` + +Creates separate gitignore files for each template. + +### Force Overwrite + +```bash +gh-templates gitignore add node --force +``` + +Overwrites existing `.gitignore` file without prompting. + +### Add All Templates + +```bash +gh-templates gitignore add --all +``` + +Downloads and combines all available gitignore templates (creates a very comprehensive file ~ Not Recommended). + +### Append to Existing File + +```bash +gh-templates gitignore add python --append +``` + +Appends the Python template to the existing `.gitignore` file. + +### Use Remote Template Name + +```bash +gh-templates gitignore add rust -n +``` + +Saves the template using its remote file name (e.g., `Rust.gitignore`). + +### Update Template Cache + +```bash +gh-templates gitignore add --update-cache +``` + +Updates the local cache of available gitignore templates. + +### Complex Example + +```bash +gh-templates gitignore add rust docker windows --dir . --force -o .gitignore +``` + +This command: + +- Adds Rust, Docker, and Windows gitignore patterns +- Saves to repository root directory +- Forces overwrite of existing file +- Uses explicit output filename + +## Default Behavior + +- **Output Directory**: Repository root (`.`) +- **File Names**: `.gitignore` (single file containing all patterns) +- **Overwrite**: Prompts before overwriting existing files (unless `--force` is used) +- **Append**: By default, overwrites unless `--append` is specified +- **Combination**: Multiple templates are merged into one file + +## Template Combination + +When adding multiple templates, `gh-templates` intelligently combines them: + +1. **Categorization**: Groups patterns by category with comments + +## Best Practices for Combining + +### Language + OS + Editor + +```bash +gh-templates gitignore add python windows vscode +``` + +### Full Stack Project + +```bash +gh-templates gitignore add javascript python docker +``` + +### Polyglot Repository + +```bash +gh-templates gitignore add rust go python java +``` + +## Monorepo Strategy + +For monorepos with multiple projects: + +```bash +# Root-level common ignores +gh-templates gitignore add windows macos linux + +# Language-specific ignores in subdirectories +gh-templates gitignore add rust --dir rust-service/ +gh-templates gitignore add node --dir web-frontend/ +gh-templates gitignore add python --dir python-api/ +``` + +## Updating Gitignore + +To update an existing `.gitignore`: + +1. **Preview changes** first: + + ```bash + gh-templates gitignore preview rust + ``` + +2. **Backup existing** file: + + ```bash + cp .gitignore .gitignore.backup + ``` + +3. **Update with force**: + + ```bash + gh-templates gitignore add rust --force + ``` + +## Common Combinations + +| Project Type | Recommended Templates | +|-------------------|-----------------------------| +| Rust desktop app | `rust windows macos linux` | +| Python web app | `python docker vscode` | +| Node.js project | `node windows macos` | +| Full-stack app | `javascript python docker` | +| Mobile app | `java kotlin swift xcode` | +| Data science | `python jupyter r` | + +## Troubleshooting + +### File Already Exists + +Without `--force`, you'll be prompted to overwrite. Options: + +- Use `--force` to overwrite +- Use `--append` to add to the existing file +- Use different output name with `-o` +- Manually merge the content + +### Patterns Not Working + +If ignore patterns aren't working: + +1. Ensure file is named `.gitignore` +2. Check file is in repository root or appropriate subdirectory +3. Commit the `.gitignore` file +4. Use `git rm --cached ` to untrack already-tracked files + +## Tips + +1. **Start Early**: Add `.gitignore` before committing code +2. **Be Specific**: Choose templates that match your actual tech stack +3. **Review Content**: Preview templates to understand what they ignore +4. **Combine Wisely**: Don't add unnecessary templates that create noise +5. **Update Regularly**: Refresh gitignore as your project evolves diff --git a/docs/docs/commands/gitignore/gitignore-list.md b/docs/docs/commands/gitignore/gitignore-list.md new file mode 100644 index 0000000..4baeb62 --- /dev/null +++ b/docs/docs/commands/gitignore/gitignore-list.md @@ -0,0 +1,98 @@ +--- +title: "gh-templates gitignore list" +sidebar_label: "gitignore list" +--- + +# List Gitignore Templates + +List all available gitignore templates that can be added to your repository. Templates are sourced from [github/gitignore](https://github.com/github/gitignore). + +## Usage + +```bash +gh-templates gitignore list +``` + +## Options + +| Option | Description | +|----------------------|------------------------------------| +| `-p, --popular` | Show popular templates | +| `-g, --global` | Show global templates | +| `-c, --community` | Show community templates | +| `--update-cache` | Update the gitignore cache | +| `-h, --help` | Print help | + +## Examples + +### List All Available Templates + +```bash +gh-templates gitignore list +``` + +### List Only Popular Templates + +```bash +gh-templates gitignore list --popular +``` + +### List Global Templates + +```bash +gh-templates gitignore list --global +``` + +### List Community Templates + +```bash +gh-templates gitignore list --community +``` + +### Update the Template Cache + +```bash +gh-templates gitignore list --update-cache +``` + +## Sample Output + +```text +✓ Available gitignore templates: + +POPULAR + > actionscript (Actionscript.gitignore) + > ada (Ada.gitignore) + > adventuregamestudio (AdventureGameStudio.gitignore) + > agda (Agda.gitignore) + > al (AL.gitignore) + > android (Android.gitignore) + > angular (Angular.gitignore) + > appceleratortitanium (AppceleratorTitanium.gitignore) + > appengine (AppEngine.gitignore) + > archlinuxpackages (ArchLinuxPackages.gitignore) + > autotools (Autotools.gitignore) + > ballerina (Ballerina.gitignore) + > c (C.gitignore) + > c++ (C++.gitignore) +``` + +## Gitignore Template Categories + +GitHub's `gitignore` repository organizes templates into several categories: + +- **Popular** (root folder): + These are the most commonly used `.gitignore` templates, found directly in the root of the repository. They cover widely-used languages, frameworks, and tools. + +- **Community** (`/community` folder): + Templates contributed and maintained by the community for more specialized or less common technologies. These may be less frequently updated but are valuable for niche use cases. + +- **Global** (`/global` folder): + Templates intended for global use across all repositories on a developer's machine. These typically ignore files generated by operating systems or editors (e.g., macOS, Windows, Vim, Emacs). + +Use the template that best matches your project's needs. For most projects, start with a popular template and supplement with community or global + +## Related Commands + +- [Preview Gitignore Templates](./gitignore-preview.md) - Preview template content +- [Add Gitignore Templates](./gitignore-add.md) - Add templates to your repository diff --git a/docs/docs/commands/gitignore/gitignore-preview.md b/docs/docs/commands/gitignore/gitignore-preview.md new file mode 100644 index 0000000..33720087 --- /dev/null +++ b/docs/docs/commands/gitignore/gitignore-preview.md @@ -0,0 +1,295 @@ +--- +title: "gh-templates gitignore preview" +sidebar_label: "gitignore preview" +--- + +# Preview Gitignore Templates + +Preview the content of one or more gitignore templates before adding them to your repository. + +## Usage + +```bash +gh-templates gitignore preview [TEMPLATES]... +``` + +## Arguments + +| Argument | Description | +|----------|-------------| +| `[TEMPLATES]...` | Names of gitignore templates to preview | + +## Options + +| Option | Description | +|--------|-------------| +| `-h, --help` | Print help | + +## Examples + +### Preview a Single Template + +```bash +gh-templates gitignore preview rust +``` + +This displays the complete content of the Rust gitignore template. + +### Preview Multiple Templates + +```bash +gh-templates gitignore preview rust docker +``` + +Shows the content of both templates to see how they would combine. + +### Compare Similar Templates + +```bash +gh-templates gitignore preview javascript node react +``` + +Compare related templates to understand their differences. + +## Sample Output + +```bash +$ gh-templates gitignore preview rust + + === Preview: rust === + +# Generated by Cargo +# will have compiled files and executables +debug/ +target/ + +# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries +# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html +Cargo.lock + +# These are backup files generated by rustfmt +**/*.rs.bk + +# MSVC Windows builds of rustc generate these, which store debugging information +*.pdb +``` + +### Multiple Template Preview + +```bash +$ gh-templates gitignore preview python vscode + + === Preview: python === + +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# Virtual environments +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + + === Preview: vscode === + +.vscode/* +!.vscode/settings.json +!.vscode/tasks.json +!.vscode/launch.json +!.vscode/extensions.json +!.vscode/*.code-snippets + +# Local History for Visual Studio Code +.history/ + +# Built Visual Studio Code Extensions +*.vsix +``` + +## Why Preview Gitignore Templates? + +Previewing gitignore templates helps you: + +1. **Understand Patterns**: See exactly what files will be ignored +2. **Avoid Conflicts**: Identify patterns that might be too broad +3. **Plan Combinations**: See how multiple templates work together +4. **Customize Effectively**: Understand what might need modification + +## Pattern Analysis + +When previewing, pay attention to: + +### File Patterns + +- Specific files: `Cargo.lock`, `.DS_Store` +- File extensions: `*.log`, `*.tmp` +- Generated files: `debug/`, `target/` + +### Directory Patterns + +- Build outputs: `build/`, `dist/` +- Dependencies: `node_modules/`, `vendor/` +- Caches: `__pycache__/`, `.cache/` + +### Wildcard Usage + +- `*` - Matches any characters +- `**` - Matches directories recursively +- `?` - Matches single character +- `!` - Negates a pattern (includes rather than ignores) + +## Common Pattern Types + +### Language Artifacts + +```gitignore +# Rust +target/ +Cargo.lock + +# Python +__pycache__/ +*.pyc +``` + +### Build Outputs + +```gitignore +# General build +build/ +dist/ +out/ +``` + +### OS-Specific Files + +```gitignore +# Windows +Thumbs.db +desktop.ini + +# macOS +.DS_Store +.AppleDouble +``` + +### IDE/Editor Files + +```gitignore +# VSCode +.vscode/ +!.vscode/settings.json + +# IntelliJ +.idea/ +*.iml +``` + +## Understanding Negation + +Some templates use negation patterns (`!`) to include specific files: + +```gitignore +.vscode/* +!.vscode/settings.json +!.vscode/tasks.json +``` + +This ignores all VSCode files except settings and tasks configurations. + +## Combination Preview + +When previewing multiple templates, consider: + +1. **Overlap**: Are there duplicate patterns? +2. **Conflicts**: Do patterns contradict each other? +3. **Coverage**: Are all your needs covered? +4. **Organization**: How will patterns be grouped? + +## Best Practices + +1. **Preview Before Adding**: Always preview to understand what will be ignored +2. **Check for Overbroad Patterns**: Ensure patterns aren't too restrictive +3. **Understand Negations**: Pay attention to `!` patterns +4. **Consider Project Structure**: Ensure patterns match your project layout + +## Customization Planning + +After previewing, you might want to: + +1. **Add Project-Specific Patterns**: Custom build outputs, config files +2. **Remove Unnecessary Patterns**: Patterns for tools you don't use +3. **Adjust Paths**: Modify patterns for your directory structure +4. **Add Comments**: Document why certain patterns are included + +## Example Workflow + +```bash +# 1. List available templates +gh-templates gitignore list + +# 2. Preview interesting templates +gh-templates gitignore preview rust docker + +# 3. Preview combination +gh-templates gitignore preview rust docker vscode + +# 4. Add if satisfied +gh-templates gitignore add rust docker vscode +``` + +## Troubleshooting Preview + +If patterns seem incorrect: + +1. **Check Template Name**: Ensure you're using the correct template name +2. **Verify Content**: Some templates might be minimal or comprehensive +3. **Consider Alternatives**: Look for similar templates with different coverage + +## Next Steps + +After previewing templates: + +1. **Add templates** if they meet your needs: + + ```bash + gh-templates gitignore add rust docker + ``` + +2. **Plan customization** for project-specific needs: + - Add custom patterns after installation + - Remove unnecessary patterns + - Adjust paths as needed + +3. **Test in practice** to ensure patterns work correctly + +## Related Commands + +- [List Gitignore Templates](./gitignore-list.md) - See all available templates +- [Add Gitignore Templates](./gitignore-add.md) - Add templates to your repository diff --git a/docs/docs/commands/gitignore/gitignore.md b/docs/docs/commands/gitignore/gitignore.md new file mode 100644 index 0000000..65f07dd --- /dev/null +++ b/docs/docs/commands/gitignore/gitignore.md @@ -0,0 +1,99 @@ +--- +title: "gh-templates gitignore" +sidebar_label: "gitignore" +--- + +# Gitignore Templates + +The `gitignore` subcommand provides functionality for managing `.gitignore` templates. Gitignore templates help you quickly set up language and framework-specific ignore patterns to keep your repositories clean and focused. + +The available templates are indexed from [https://github.com/github/gitignore/](https://github.com/github/gitignore/), ensuring up-to-date and comprehensive coverage for a wide range of languages, frameworks, and tools. + +## Usage + +```bash +gh-templates gitignore +``` + +## Available Commands + +| Command | Description | +|---------|-------------| +| `add` | Add one or more gitignore templates to the repository | +| `list` | List available gitignore templates | +| `preview` | Preview a specific gitignore template | + +## Examples + +### List Available Templates + +```bash +gh-templates gitignore list +``` + +### Preview a Template + +```bash +gh-templates gitignore preview rust +``` + +### Add Single Template + +```bash +gh-templates gitignore add python +``` + +### Add Multiple Templates + +```bash +gh-templates gitignore add rust node python +``` + +## Template Categories + +Gitignore templates are available for: +All templates available in [github/gitignore](https://github.com/github/gitignore/) can be used, including those in nested directories such as `Global` and `community`. You can reference templates by their name, or for community templates, use either the `community-