Document: feat: support Git repository initialization for existing features files

[flipt-release-bot]

This issue was created to document the following pull request: flipt-io/flipt#4674

[markphelps]

@claude can you add detailed documentation on how to get pre-existing local state working in v2 now that flipt-io/flipt#4674 is merged?

Please see this issue thread for more details also: flipt-io/flipt#4623

Also make sure to document that either features.yaml or features.yml will work, which closes: #361

[claude]

Claude finished @markphelps's task —— View job • claude/issue-358-20250905-1514 • Create PR ➔

---

Documentation Task: Git Repository Initialization for Existing Features ✅

I've successfully added comprehensive documentation for Git repository initialization with pre-existing local state in Flipt v2.

Todo List:

• Set up development environment (install dependencies)
• Research PR #4674 and issue #4623 for technical context
• Analyze current v2 documentation structure
• Identify appropriate location for new documentation
• Write comprehensive documentation covering:
  • Git repository initialization process
  • Working with pre-existing local state
  • Support for both features.yaml and features.yml
• Run linting and formatting commands
• Commit and push changes
• Create PR

📋 What I Created

New Documentation: v2/guides/operations/environments/git-repository-initialization.mdx

The guide covers:

• Overview of the new Git repository initialization feature
• Supported file formats (both .yaml and .yml - closes Document: feat: support .yml extension for features files in addition to .yaml #361)
• Step-by-step workflow for initializing Git repos with existing features
• Repository detection logic (normal vs bare repositories)
• Working directory synchronization features
• Configuration examples for various scenarios
• Docker usage patterns with initialization
• Troubleshooting section for common issues
• Best practices for managing feature flag repositories
• Backward compatibility assurance

Navigation Update: Added the new guide to the v2 Operations Guides > Environments section in docs.json

🎯 Key Features Documented

1. File Format Support: Documents that both features.yaml and features.yml work (addresses issue Document: feat: support .yml extension for features files in addition to .yaml #361)
2. Intuitive Workflow: Clear step-by-step process for users with existing feature files
3. Enhanced Detection: Explains the improved repository detection logic from PR #4674
4. Synchronization: Details how UI changes sync back to filesystem files
5. Docker Integration: Practical examples for containerized deployments
6. Comprehensive Examples: Multiple configuration scenarios and use cases

🔧 Technical Details

The documentation addresses the exact issue described in #4623 where users had existing feature files but encountered "repository does not exist" errors. The new guide explains how the enhanced detection logic in PR #4674 resolves these issues and provides a smooth path for users to get their existing configurations working with Flipt v2.

---

Job run