Skip to content

Commit aa6492f

Browse files
kzndotshkzndotsh
committed
fix: merge
1 parent 7a8889c commit aa6492f

File tree

1 file changed

+139
-34
lines changed

1 file changed

+139
-34
lines changed

‎README.md‎

Lines changed: 139 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,64 +1,169 @@
1-
# [GitCord](https://evolvewithevan.github.io/gitcord/troubleshooting/debug-mode.html)
1+
# GitCord
2+
3+
A Discord bot for GitOps-based Discord server management. Manage your server's channels and categories using YAML templates, version control, and GitHub integration.
24

35
[![Documentation](https://img.shields.io/badge/docs-mdBook-blue)](https://evolvewithevan.github.io/gitcord/)
46
[![License: GPL v3](https://img.shields.io/badge/license-GPLv3-blue.svg)](LICENSE)
57

6-
GitCord is a Discord bot that allows you to manage your Discord server's channel structure and configuration through Git. It provides a seamless way to version control your Discord server setup and automatically sync changes from your GitHub repository.
8+
---
9+
10+
## 🚀 Getting Started
11+
12+
### Option 1: Use Pre-Hosted Bot (Recommended)
13+
14+
The easiest way to get started is to invite the pre-hosted GitCord bot to your Discord server:
15+
16+
**[📥 Invite GitCord Bot](https://discord.com/oauth2/authorize?client_id=1391153955936927824)**
717

8-
## ⚠️ Disclaimer
18+
After inviting the bot, you can start using commands immediately. See the [Quick Start Guide](https://evolvewithevan.github.io/gitcord/getting-started/quick-start.html) for usage examples.
919

10-
**This project is currently in early development and does not have a complete featureset yet.** The bot exists as a basic framework, but some core functionality described in this README is not yet implemented.
11-
**Do not run this on servers with untrusted members present. It is not secure yet.**
20+
### Option 2: Self-Host (Advanced Users)
1221

13-
We have detailed plans and are actively working on bringing these features to life. Check back soon for updates, or feel free to contribute to help accelerate development.
22+
If you prefer to run your own instance of GitCord:
1423

15-
## Getting Started
24+
1. **Clone the repository:**
25+
```bash
26+
git clone https://github.com/evolvewithevan/gitcord.git
27+
cd gitcord
28+
```
29+
2. **Install dependencies (requires Python 3.9+ and [uv](https://github.com/astral-sh/uv))**
30+
```bash
31+
uv sync
32+
```
33+
3. **Set up environment variables:**
34+
```bash
35+
cp .env.example .env
36+
# Edit .env and add your Discord bot token
37+
```
38+
4. **Run the bot:**
39+
```bash
40+
python -m gitcord
41+
```
1642

17-
To get started in using **GitCord**, you can either design your own server channel structure from scratch or fork the **[gitcord-template](https://github.com/evolvewithevan/gitcord-template)**. This template provides a sample structure that demonstrates how to define your server's categories and channels using organized YAML configuration files.
43+
For detailed self-hosting setup, see the [Installation Guide](https://evolvewithevan.github.io/gitcord/getting-started/installation.html).
1844

19-
Once it's ready, you'll have to link the **GitCord** bot to your own repository, finally, you will be able to discuss and organize your Discord server all in a transparent, team-friendly GitHub repository. To manually synchronize with your repository, you can run `/gitcord pull` on the server.
45+
---
2046

47+
## 📝 What is GitCord?
2148

22-
## Planned Features
49+
GitCord is a Discord bot that lets you manage your server's structure using YAML configuration files, stored in Git and optionally synced with GitHub. It enables:
50+
- **Version-controlled server configuration**
51+
- **Automated and manual sync of categories/channels**
52+
- **Bulk creation of channels/categories from templates**
53+
- **Easy server setup and reproducibility**
2354

24-
This list is incomplete, See (all issues)[https://github.com/users/evolvewithevan/projects/4/views/1?pane=info] to see a complete list of all issues or (Feature Issues)[https://github.com/users/evolvewithevan/projects/4/views/8?pane=info] to see feature updates planned.
25-
- [ ] **Version-Controlled Configuration**: Store your Discord server configuration in a Git repository
26-
- [ ] **Automatic Sync**: Webhook-based synchronization when configuration changes are pushed to GitHub
27-
- [ ] **Manual Pull**: Use `/gitcord pull` command to manually sync configuration changes
28-
- [x] **Command Syncing**: Use `/synccommands` (slash) or `!synccommands` (prefix) to manually synchronize slash commands
29-
- [x] **Category and Channel Management**: Organize your server structure through YAML configuration files
55+
---
3056

31-
## Project Status
57+
## ✨ Features
58+
- **Template-based Channel & Category Creation**: Use YAML files to define your server structure
59+
- **Manual & Planned Automatic Sync**: Pull changes from a GitHub repo or local files
60+
- **Slash & Prefix Commands**: Use `/createcategory`, `/createchannel`, `!createcategory`, etc.
61+
- **Permission Management**: Follows Discord's permission system
62+
- **Extensible**: Modular cog system for easy extension
63+
- **Open Source**: GPL-3.0 License
3264

33-
This project is currently in development. See the [roadmap](https://github.com/users/evolvewithevan/projects/4) for current development status and planned features.
65+
See the [full feature list](https://evolvewithevan.github.io/gitcord/introduction.html#key-features).
3466

35-
### Current Development Phase
67+
---
3668

37-
- **Prototype Phase**: Basic Discord bot with manual pull functionality
69+
## 🛠️ Example Usage
70+
71+
- **Create a channel from YAML:**
72+
```yaml
73+
# general.yaml
74+
name: general
75+
type: text
76+
topic: General discussion
77+
position: 0
78+
nsfw: false
79+
```
80+
Use: `!createchannel`
81+
82+
- **Create a category with channels:**
83+
```yaml
84+
# community.yaml
85+
name: Community
86+
type: category
87+
position: 0
88+
channels:
89+
- general
90+
- memes
91+
- off-topic
92+
```
93+
Use: `!createcategory` or `/createcategory`
94+
95+
See [Quick Start](https://evolvewithevan.github.io/gitcord/getting-started/quick-start.html) and [Templates Guide](https://evolvewithevan.github.io/gitcord/templates/category-templates.html).
3896

39-
## Contributing
97+
---
4098

41-
Please see our [CONTRIBUTING.md](./.github/CONTRIBUTING.md) for contribution guidelines
99+
## 🧩 Main Commands
42100

43-
1. Fork the repository
44-
2. Create a branch (`git checkout -b feature/amazing-feature`)
45-
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
46-
4. Push to the branch (`git push origin feature/amazing-feature`)
47-
5. Open a Pull Request
101+
- `!hello` / `/hello` — Greet the bot
102+
- `!ping` / `/slashping` — Check bot latency
103+
- `!createchannel` — Create a channel from YAML
104+
- `!createcategory` / `/createcategory [yaml_path]` — Create a category with channels
105+
- `!fetchurl <url>` / `/fetchurl <url>` — Fetch text from a website (admin)
106+
- `!synccommands` / `/synccommands` — Update slash commands (admin)
107+
- `!help` / `/help` — Show help and links
48108

49-
We aim to personally respond to every PR within 24hr
109+
See [Commands Reference](https://evolvewithevan.github.io/gitcord/user-guide/commands.html).
50110

51-
## License
111+
---
52112

53-
This project is and will remain licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.
113+
## 📁 Project Structure
114+
115+
```
116+
gitcord/
117+
├── src/gitcord/ # Main source code
118+
│ ├── bot.py # Main bot entry point
119+
│ ├── config.py # Configuration management
120+
│ ├── events.py # Discord event handlers
121+
│ ├── cogs/ # Discord.py cogs (command modules)
122+
│ ├── utils/ # Utility functions
123+
│ ├── views/ # Discord UI components
124+
│ └── constants/ # Constants and messages
125+
├── gitcord-template/ # Example template repository
126+
├── docs/ # Documentation (mdBook)
127+
├── requirements.txt # Python dependencies
128+
├── pyproject.toml # Project metadata
129+
└── README.md # Project documentation
130+
```
54131
55-
## Roadmap
132+
---
56133
57-
For detailed development plans and current status, see the [roadmap](https://github.com/users/evolvewithevan/projects/4/views/3?pane=info) and [status-updates](https://github.com/users/evolvewithevan/projects/4/views/3?pane=info&statusUpdateId=134528)
134+
## 📈 Project Status & Roadmap
135+
136+
- **Alpha**: Core features implemented, active development
137+
- See the [Roadmap](https://github.com/users/evolvewithevan/projects/4) for planned features and progress
138+
- [Planned Features](https://evolvewithevan.github.io/gitcord/templates/category-templates.html#future-enhancements):
139+
- Webhook-based automatic sync
140+
- Advanced template features (inheritance, variables)
141+
- More admin tools
142+
143+
---
144+
145+
## 🤝 Contributing
146+
147+
We welcome contributions! Please read [CONTRIBUTING.md](.github/CONTRIBUTING.md) for:
148+
- Coding standards (PEP8, type hints, docstrings)
149+
- How to set up your dev environment
150+
- Testing and documentation guidelines
151+
- Pull request process
152+
153+
---
154+
155+
## 🆘 Support & Troubleshooting
156+
157+
- [Common Issues](https://evolvewithevan.github.io/gitcord/troubleshooting/common-issues.html)
158+
- [Error Messages](https://evolvewithevan.github.io/gitcord/troubleshooting/error-messages.html)
159+
- [GitHub Issues](https://github.com/evolvewithevan/gitcord/issues)
160+
- [Discussions](https://github.com/evolvewithevan/gitcord/discussions)
161+
162+
---
58163
59-
## Support
164+
## 📜 License
60165
61-
If you encounter any issues or have questions, please open an issue on this GitHub repository or open a Discussion page. We aim to respond within 24hr.
166+
This project is licensed under the GNU General Public License v3.0. See [LICENSE](LICENSE).
62167
63168
---
64169

0 commit comments

Comments
 (0)