הוספת תת-פרויקט חדש

Submodule

git submodule add https://github.com/githubtraining/example-submodule

git commit -m "adding new submodule"

הפקודה submodule add מוסיפה קובץ חדש בשם .gitmodules יחד עם תת-תיקייה שמכילה את הקבצים מ-example-submodule. שניהם מתוספים ל-index שלכם (אזור ה-staging) ופשוט צריך לבצע להם קומיט. ההיסטוריה של ה-submodule נשארת עצמאית מפרויקט האב.

Subtree

git subtree add --prefix=example-submodule https://github.com/githubtraining/example-submodule main --squash

הפקודה subtree מוסיפה תת-תיקייה שמכילה את הקבצים מ-example-submodule. הנוהג הנפוץ ביותר הוא להשתמש באופציה --squash כדי לשלב את ההיסטוריה של תת-הפרויקט לקומיט יחיד, שאז מושתל על העץ הקיים של פרויקט האב. אתם יכולים להשמיט את האופציה --squash כדי לשמור על כל ההיסטוריה מהענף המיועד של תת-הפרויקט.

צפייה ב-Diff של תת-הפרויקט

Submodule

כדי לראות diff של ה-submodule:

# show changes to the submodule commit
git diff example-submodule
# show oneline log of new commits in the submodule
git diff --submodule example-submodule
# show changes to the files in the submodule
git diff --submodule=diff

Subtree

לא נדרשת פקודה מיוחדת

שכפול מאגר עם תת-פרויקט

Submodule

כדי לשכפל מאגר יחד עם ה-submodules שלו:

git clone --recurse-submodules URL

אם שכחתם את --recurse-submodules, תוכלו לשכפל ולאתחל את כל ה-submodules:

git submodule update --init --recursive

הוספת --recursive נדרשת רק אם יש ל-submodule עצמו submodules.

Subtree

לא נדרשת פקודה מיוחדת

משיכת עדכונים של Superproject

Submodule

כברירת מחדל, מאגר ה-submodule נשלף (fetched), אבל לא מתעדכן כשאתם מריצים git pull ב-superproject. אתם צריכים להשתמש ב-git submodule update, או להוסיף את הדגל --recurse-submodules ל-pull:

git pull
git submodule update --init --recursive
# or, in one step (Git >= 2.14)
git pull --recurse-submodules

--init נדרש אם ה-superproject הוסיף submodules חדשים, ו---recursive נדרש אם יש ל-submodule עצמו submodules.

אם אי-פעם ה-superproject משנה את ה-URL של ה-submodule, נדרשת פקודה נפרדת:

# copy the new URL to your local config
git submodule sync --recursive
# update the submodule from the new URL
git submodule update --init --recursive

--recursive נדרש רק אם יש ל-submodule עצמו submodules.

Subtree

לא נדרשת פקודה מיוחדת

החלפת ענפים

Submodule

כברירת מחדל, עץ העבודה של ה-submodule לא מתעדכן להתאים לקומיט המתועד ב-superproject כשמחליפים ענפים. אתם צריכים להשתמש ב-git submodule update, או להוסיף את הדגל --recurse-submodules ל-switch:

git switch <branch>
git submodule update --recursive
# or, in one step (Git >= 2.13)
git switch --recurse-submodules <branch>

Subtree

לא נדרשת פקודה מיוחדת

משיכת עדכונים של תת-פרויקט

Submodule

# Update the submodule repository
git submodule update --remote
# Record the changes in the superproject
git commit -am "Update submodule"

אם יש לכם יותר מ-submodule אחד, תוכלו להוסיף את הנתיב ל-submodule בסוף הפקודה git submodule update --remote כדי לציין איזה תת-פרויקט לעדכן.

כברירת מחדל, git submodule update --remote יעדכן את ה-submodule לקומיט האחרון על ענף ה-main של ה-remote של ה-submodule.

אתם יכולים לשנות את ענף ברירת המחדל לקריאות עתידיות עם:

# Git >= 2.22
git submodule set-branch other-branch
# or
git config -f .gitmodules submodule.example-submodule.branch other-branch

Subtree

git subtree pull --prefix=example-submodule https://github.com/githubtraining/example-submodule main --squash

תוכלו לקצר את הפקודה על ידי הוספת ה-URL של ה-subtree כ-remote:

git remote add sub-remote https://github.com/githubtraining/example-submodule.git

תוכלו להוסיף/למשוך מ-refs אחרים על ידי החלפת main ב-ref הרצוי (למשל stable, v1.0).

ביצוע שינויים בתת-פרויקט

ברוב המקרים, זה נחשב לשיטת עבודה מומלצת לבצע שינויים בשכפול נפרד של מאגר תת-הפרויקט ולמשוך אותם לפרויקט האב. כשזה לא מעשי, עקבו אחרי ההוראות האלה:

Submodule

גישה לתיקיית ה-submodule ויצירת ענף:

cd example-submodule

git switch -c branch-name main

שינויים דורשים שני קומיטים, אחד במאגר תת-הפרויקט ואחד במאגר האב.

אל תשכחו לדחוף גם ב-submodule וגם ב-superproject!

Subtree

לא נדרשת פקודה מיוחדת, שינויים יבוצעו קומיט על ענף פרויקט האב.

אפשר ליצור קומיטים שמערבבים שינויים לתת-הפרויקט ולפרויקט האב, אבל זה בדרך כלל לא מומלץ.

דחיפת שינויים למאגר תת-הפרויקט

Submodule

כשאתם בתיקיית ה-submodule:

git push

או כשאתם בתיקיית האב:

git push --recurse-submodules=on-demand

Subtree

git subtree push --prefix=example-submodule https://github.com/githubtraining/example-submodule main

הגדרות שימושיות ל-Submodules

תמיד להציג את לוג ה-submodule כשאתם עושים diff:

git config --global diff.submodule log

להציג סיכום קצר של שינויי submodule בהודעת git status שלכם:

git config --global status.submoduleSummary true

להפוך את push לברירת מחדל עם --recurse-submodules=on-demand:

git config --global push.recurseSubmodules on-demand

להפוך את כל הפקודות (חוץ מ-clone) לברירת מחדל עם --recurse-submodules אם הן תומכות בדגל (זה עובד עבור git pull מאז Git 2.15):

git config --global submodule.recurse true