# ما هو المستودع (Repository) وكيف تكتب ملف README جيدًا؟

- آدرس: https://di9.ir/blog/ar/%D9%85%D8%A7-%D9%87%D9%88-%D8%A7%D9%84%D9%85%D8%B3%D8%AA%D9%88%D8%AF%D8%B9-%D9%88%D9%83%D9%8A%D9%81-%D8%AA%D9%83%D8%AA%D8%A8-readme
- نویسنده: danidiba
- انتشار: 2026-10-09T14:10:00+03:30
- به‌روزرسانی: 2026-10-09T14:10:00+03:30
- دسته: Git وGitHub
- برچسب‌ها: README، ریپازیتوری، گیت، گیت‌هاب، مستندسازی

> المستودع هو مجلد المشروع مع سجل تغييراته الكامل، وملف README هو أول ما يراه أي شخص فيه. يشرح هذا الدليل ما هو المستودع، والفرق بين المستودع المحلي والبعيد، والأقسام التي يحتاجها README جيد.

أول مرة تفتح فيها صفحة مشروع على GitHub ترى شيئين: قائمة ملفات ومجلدات، وتحتها نصًا يشرح ما هو المشروع. الأول هو المستودع، والثاني هو README. الأول بيت الشيفرة، والثاني اللافتة المعلقة على بابه.

**[المستودع](https://di9.ir/blog/%D9%88%D8%A7%DA%98%D9%87/%D8%B1%DB%8C%D9%BE%D8%A7%D8%B2%DB%8C%D8%AA%D9%88%D8%B1%DB%8C) (Repository) هو مجلد المشروع مع السجل الكامل لكل التغييرات التي طرأت عليه.** كل ملف وكل تغيير، ومن أجراه ولماذا، يُسجل في المستودع. والأداة التي تحفظ هذا السجل هي عادة [Git](https://di9.ir/blog/%D9%88%D8%A7%DA%98%D9%87/%DA%AF%DB%8C%D8%AA).

## ماذا يخزن المستودع بالضبط؟

لنفترض أنك تعمل على إضافة ووردبريس. دون مستودع ستحفظ النسخ بأسماء مثل `plugin-final` و`plugin-final-2` و`plugin-final-new`، وبعد شهر لن تتذكر أيها كان يعمل.

مع المستودع لديك مجلد واحد. في كل مرة تسجل تغييرًا (commit) يحفظ Git لقطة من المشروع مع وصف قصير. ومتى احتجت يمكنك أن ترى متى تغير سطر ما، أو تعود إلى نسخة سابقة، أو تجرب شيئًا على فرع منفصل. إذا كانت هذه المفاهيم جديدة عليك فاقرأ [Git للمبتدئين](https://di9.ir/blog/%D8%A2%D9%85%D9%88%D8%B2%D8%B4-%DA%AF%DB%8C%D8%AA-%D8%A8%D8%B1%D8%A7%DB%8C-%D8%B4%D8%B1%D9%88%D8%B9).

يحتوي المستودع عادة على:

- **شيفرة المشروع وملفاته:** ما تبنيه فعلًا.
- **السجل:** كل الـ commits في المجلد المخفي `.git`.
- **الفروع (branches):** خطوط تطوير متوازية.
- **ملفات متعارف عليها:** README وLICENSE و`.gitignore` وأحيانًا CONTRIBUTING.

## المستودع المحلي والمستودع البعيد

يمكن أن يوجد المستودع في مكانين، وغالبًا يوجد في الاثنين:

| النوع | أين يوجد | فيمَ يفيد |
| --- | --- | --- |
| محلي (local) | على حاسوبك | العمل اليومي، الـ commit، التجربة دون إنترنت |
| بعيد (remote) | على خدمة مثل GitHub أو GitLab أو خادمك الخاص | النسخ الاحتياطي، العمل الجماعي، النشر على الخادم |

بالأمر `clone` تحصل على نسخة محلية من المستودع البعيد، وبالأمر `push` ترسل تغييراتك، وبالأمر `pull` تجلب تغييرات الآخرين:

```bash
git clone https://github.com/USERNAME/my-plugin.git
cd my-plugin
git add .
git commit -m "Add settings page"
git push
```

في العمل الجماعي، بدل الدفع مباشرة إلى الفرع الرئيسي، تفتح عادة [طلب دمج](https://di9.ir/blog/%D9%88%D8%A7%DA%98%D9%87/%D9%BE%D9%88%D9%84-%D8%B1%DB%8C%DA%A9%D9%88%D8%A6%D8%B3%D8%AA) (Pull Request) لتتم مراجعة الشيفرة؛ والتفاصيل في [GitHub للعمل الجماعي](https://di9.ir/blog/%DA%AF%DB%8C%D8%AA-%D9%87%D8%A7%D8%A8-%D8%A8%D8%B1%D8%A7%DB%8C-%DA%A9%D8%A7%D8%B1-%D8%AA%DB%8C%D9%85%DB%8C). ويمكن أن يكون المستودع البعيد وسيلة نقل الشيفرة إلى الاستضافة أيضًا؛ راجع [نشر الموقع باستخدام Git على استضافة مشتركة](https://di9.ir/blog/%D8%A7%D8%B3%D8%AA%D9%82%D8%B1%D8%A7%D8%B1-%D8%A8%D8%A7-%DA%AF%DB%8C%D8%AA-%D8%B1%D9%88%DB%8C-%D9%87%D8%A7%D8%B3%D8%AA).

## ما هو README ولماذا هو مهم إلى هذا الحد؟

README ملف نصي في جذر المستودع، اسمه عادة `README.md`. الامتداد `md` يعني أنه مكتوب بلغة Markdown، وتعرضه GitHub والخدمات المشابهة منسقًا أسفل قائمة الملفات.

يُكتب README لثلاثة أشخاص:

1. **الزائر لأول مرة:** يريد أن يفهم في ثوانٍ ما هو المشروع وهل يفيده.
2. **من يريد استخدامه:** يبحث عن أوامر التثبيت ومثال بسيط.
3. **أنت بعد ستة أشهر:** وقد نسيت كيف كنت تشغل المشروع.

المشروع الذي لا README له يبقى خفيًا عن معظم الناس مهما كانت شيفرته ممتازة.

## أقسام README الجيد

لا يلزم أن يكون README طويلًا، لكن يجب أن يضم هذه الأقسام بهذا الترتيب تقريبًا:

| القسم | ماذا تكتب |
| --- | --- |
| الاسم وجملة واحدة | ما هو المشروع وما المشكلة التي يحلها، في جملة واحدة |
| الميزات | من ثلاث إلى ست ميزات رئيسية في قائمة |
| المتطلبات | الحد الأدنى من إصدار PHP أو ووردبريس أو Node.js أو غيرها |
| التثبيت | أوامر أو خطوات دقيقة قابلة للنسخ |
| الاستخدام | مثال قصير يعمل فعلًا |
| الإعدادات | الإعدادات ومتغيرات البيئة دون القيم السرية الحقيقية |
| المساهمة | إذا كنت ترحب بالمساعدة، كيف يبلغون عن الأخطاء |
| الترخيص | نوع [الترخيص](https://di9.ir/blog/%D9%88%D8%A7%DA%98%D9%87/%D9%84%D8%A7%DB%8C%D8%B3%D9%86%D8%B3-%D9%86%D8%B1%D9%85-%D8%A7%D9%81%D8%B2%D8%A7%D8%B1) والإشارة إلى ملف LICENSE |

إذا كان للمشروع واجهة مستخدم، فلقطة شاشة واحدة للصفحة الرئيسية تشرح أكثر من عدة فقرات.

## نصائح لملف README أفضل

- **اكتب الجملة الأولى لشخص غريب:** «إضافة لإرسال رسائل تأكيد الطلب النصية في WooCommerce» أفضل من «أداة قوية ومرنة».
- **اجعل الأوامر قابلة للنسخ:** كل أمر يجب تشغيله يوضع في كتلة شيفرة لا في وسط جملة.
- **قدّم مثالًا حقيقيًا:** مخرجات نموذجية أو مقطع شيفرة يعمل دون تعديل.
- **حدّث README مع الشيفرة:** كلما تغيرت طريقة التثبيت أو الإعدادات، عدّل README في الـ commit نفسه.
- **استعن بالذكاء الاصطناعي للمسودة لا للادعاءات:** أعطه بنية الملفات واطلب مسودة، ثم راجع كل جملة بنفسك.

```prompt
هذه بنية المجلدات وملف composer.json لمشروع Laravel. اكتب ملف README بالعربية يضم هذه الأقسام: جملة تعريفية، الميزات، المتطلبات، خطوات التثبيت بأوامر دقيقة، مثال استخدام واحد، إعدادات ملف env دون قيم حقيقية، والترخيص. لا تخمن أي شيء غير موجود في الملفات؛ اكتب مكانه «يُستكمل».
```

## ملفات أخرى بجوار README

ليس README الملف المتعارف عليه الوحيد في المستودع. هناك ملفات أخرى تتعرف عليها خدمات مثل GitHub، ويجيب كل منها عن سؤال محدد:

| الملف | السؤال الذي يجيب عنه |
| --- | --- |
| `LICENSE` | ما الذي يُسمح للآخرين بفعله بهذه الشيفرة؟ |
| `.gitignore` | ما الملفات التي يجب ألا تدخل المستودع؟ |
| `CHANGELOG.md` | ما الذي تغير في كل إصدار؟ |
| `CONTRIBUTING.md` | إذا أردت المساعدة، من أين أبدأ؟ |
| `.env.example` | ما الإعدادات المطلوبة، دون القيم السرية الحقيقية؟ |

لمشروع شخصي صغير يكفي README و`.gitignore`. وكلما صار المشروع أكثر انفتاحًا والفريق أكبر، زادت قيمة بقية الملفات. والمهم أن يشير README إلى هذه الملفات لا أن يكرر محتواها؛ هكذا تُحدَّث كل معلومة في مكان واحد فقط.

## أخطاء شائعة

- **وضع كلمات المرور والمفاتيح في المستودع:** ملف `.env` ومفاتيح API وكلمة مرور قاعدة البيانات يجب ألا تُضاف إلى أي commit. ضعها في `.gitignore` واذكر في README أسماء المتغيرات فقط. إذا أضفتها بالخطأ فحذفها من آخر نسخة لا يكفي لأنها تبقى في السجل؛ غيّر المفتاح.
- **README فارغ أو افتراضي:** النص الذي تضعه الخدمة عند إنشاء المستودع هو اسم المشروع فقط ولا يقول شيئًا.
- **عدم توثيق المتطلبات:** عبارة «لا يتثبت» تعني غالبًا أن إصدار PHP أو إضافة مطلوبة لم تُذكر.
- **إضافة مجلدات يمكن إعادة بنائها:** مجلدات مثل `vendor` و`node_modules` يمكن إعادة إنشائها عبر [Composer](https://di9.ir/blog/composer-%DA%86%DB%8C%D8%B3%D8%AA) وnpm؛ مكانها في `.gitignore`.
- **غياب ملف LICENSE في مشروع عام:** دون ترخيص لا يعرف الآخرون قانونيًا هل يُسمح لهم باستخدام الشيفرة.

## الخلاصة

- المستودع هو مجلد المشروع مع سجل تغييراته الكامل.
- لديك عادة نسخة محلية على حاسوبك ونسخة بعيدة على GitHub أو خدمة مشابهة.
- README أول ما يراه الجميع، ويجب أن يقول ما هو المشروع وكيف يُثبت وكيف يُستخدم.
- أقسام README الأساسية: التعريف، الميزات، المتطلبات، التثبيت، الاستخدام، الإعدادات، الترخيص.
- كلمات المرور والمفاتيح لا تدخل المستودع أبدًا؛ استخدم `.gitignore`.
- حدّث README مع الشيفرة باستمرار.

## پرسش‌های متداول

### ما الفرق بين المستودع والمجلد العادي؟

المجلد العادي يحتفظ بالحالة الحالية للملفات فقط. أما المستودع فيحتفظ أيضًا بسجل التغييرات كاملًا: من غيّر كل سطر ومتى ولماذا. يخزن Git هذا السجل في مجلد مخفي اسمه .git داخل المشروع.

### بأي لغة يُكتب ملف README؟

بلغة الجمهور الأساسي للمشروع. إذا كان المشروع عامًا ومفتوح المصدر فالإنجليزية توسع دائرة القراء. أما لمشروع داخلي لفريق أو عميل عربي فالعربية الواضحة أفضل. يمكنك كتابة README الأساسي بلغة ووضع نسخة بلغة أخرى في ملف منفصل.

### ما هو ملف README.md ولماذا امتداده md؟

الامتداد md يعني أن الملف مكتوب بلغة Markdown، وهي صيغة نصية بسيطة تستخدم رموزًا قليلة مثل # و* لإنشاء العناوين والقوائم والشيفرة. تعرض GitHub والخدمات المشابهة ملف README.md تلقائيًا أسفل قائمة ملفات المستودع.

### هل الأفضل أن يكون المستودع عامًا أم خاصًا؟

يعتمد على المشروع. شيفرة العملاء والمشاريع التجارية وكل ما فيه إعدادات حساسة يجب أن يكون خاصًا. أما المكتبة أو الأداة المساعدة أو نموذج الأعمال الذي تريد أن يراه الناس فيمكن أن يكون عامًا. وفي الحالتين لا تضع كلمات المرور أو المفاتيح في المستودع أبدًا.