diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc --- a/documentation/content/en/articles/committers-guide/_index.adoc +++ b/documentation/content/en/articles/committers-guide/_index.adoc @@ -302,6 +302,105 @@ They assume a basic understanding of Git. There are many primers for Git on the web, but the https://git-scm.com/book/en/v2[Git Book] provides one of the better treatments. +[[git-mini-primer-getting-started]] +==== Getting Started For Developers + +This section describes the read-write access for committers to push the commits from developers or contributors. + +===== Daily use + +* Clone the repository: ++ +[source,shell] +.... +% git clone -o freebsd --config remote.freebsd.fetch='+refs/notes/*:refs/notes/*' https://git.freebsd.org/${repo}.git +.... ++ +Then you should have the official mirrors as your remote: ++ +[source,shell] +.... +% git remote -v +freebsd https://git.freebsd.org/${repo}.git (fetch) +freebsd https://git.freebsd.org/${repo}.git (push) +.... + +* Configure the FreeBSD committer data: ++ +The commit hook in repo.freebsd.org checks the "Commit" field matches the committer's information in FreeBSD.org. +The easiest way to get the suggested config is by executing `/usr/local/bin/gen-gitconfig.sh` script on freefall: ++ +[source,shell] +.... +% gen-gitconfig.sh +[...] +% git config user.name (your name in gecos) +% git config user.email (your login)@FreeBSD.org +.... + +* Set the push URL: ++ +[source,shell] +.... +% git remote set-url --push freebsd git@gitrepo.freebsd.org:${repo}.git +.... ++ +Then you should have separated fetch and push URLs as the most efficient setup: ++ +[source,shell] +.... +% git remote -v +freebsd https://git.freebsd.org/${repo}.git (fetch) +freebsd git@gitrepo.freebsd.org:${repo}.git (push) +.... ++ +Again, note that `gitrepo.freebsd.org` will be canonicalized to `repo.freebsd.org` in the future. + +* Install commit message template hook: ++ +[source,shell] +.... +% fetch https://cgit.freebsd.org/src/plain/tools/tools/git/hooks/prepare-commit-msg -o .git/hooks +% chmod 755 .git/hooks/prepare-commit-msg +.... + +[[admin-branch]] +===== "admin" branch + +The `access` and `mentors` files are stored in an orphan branch, `internal/admin`, in each repository. + +Following example is how to check out the `internal/admin` branch to a local branch named `admin`: + +[source,shell] +.... +% git config --add remote.freebsd.fetch '+refs/internal/*:refs/internal/*' +% git fetch +% git checkout -b admin internal/admin +.... +Alternatively, you can add a worktree for the `admin` branch: + +[source,shell] +.... +git worktree add -b admin ../${repo}-admin internal/admin +.... + +For browsing `internal/admin` branch on web: +https://cgit.freebsd.org/${repo}/log/?h=internal/admin + +For pushing, either specify the full refspec: + +[source,shell] +.... +git push freebsd HEAD:refs/internal/admin +.... + +Or set `push.default` to `freebsd` which will make `git push` to push the current branch back to its upstream by default, which is more suitable for our workflow: + +[source,shell] +.... +git config push.default freebsd +.... + ==== Keeping Current With The FreeBSD src Tree [[keeping_current]] First step: cloning a tree. @@ -2483,7 +2582,7 @@ When the mentor decides that a mentee has learned the ropes and is ready to commit on their own, the mentor announces it with a commit to [.filename]#mentors#. This file is in the [.filename]#admin# orphan branch of each repository. -Detailed information on how to access these branches can be found in link:{handbook}mirror/#admin-branch["admin" branch]. +Detailed information on how to access these branches can be found in <>. [[pre-commit-review]] == Pre-Commit Review diff --git a/documentation/content/en/books/handbook/mirrors/_index.adoc b/documentation/content/en/books/handbook/mirrors/_index.adoc --- a/documentation/content/en/books/handbook/mirrors/_index.adoc +++ b/documentation/content/en/books/handbook/mirrors/_index.adoc @@ -571,107 +571,7 @@ === For Developers -This section describes the read-write access for committers to push the commits from developers or contributors. -For read-only access, please refer to the users section above. - -==== Daily use - -* Clone the repository: -+ -[source,shell] -.... -% git clone -o freebsd --config remote.freebsd.fetch='+refs/notes/*:refs/notes/*' https://git.freebsd.org/${repo}.git -.... -+ -Then you should have the official mirrors as your remote: -+ -[source,shell] -.... -% git remote -v -freebsd https://git.freebsd.org/${repo}.git (fetch) -freebsd https://git.freebsd.org/${repo}.git (push) -.... - -* Configure the FreeBSD committer data: -+ -The commit hook in repo.freebsd.org checks the "Commit" field matches the committer's information in FreeBSD.org. -The easiest way to get the suggested config is by executing `/usr/local/bin/gen-gitconfig.sh` script on freefall: -+ -[source,shell] -.... -% gen-gitconfig.sh -[...] -% git config user.name (your name in gecos) -% git config user.email (your login)@FreeBSD.org -.... - -* Set the push URL: -+ -[source,shell] -.... -% git remote set-url --push freebsd git@gitrepo.freebsd.org:${repo}.git -.... -+ -Then you should have separated fetch and push URLs as the most efficient setup: -+ -[source,shell] -.... -% git remote -v -freebsd https://git.freebsd.org/${repo}.git (fetch) -freebsd git@gitrepo.freebsd.org:${repo}.git (push) -.... -+ -Again, note that `gitrepo.freebsd.org` will be canonicalized to `repo.freebsd.org` in the future. - -* Install commit message template hook: -+ -[source,shell] -.... -% fetch https://cgit.freebsd.org/src/plain/tools/tools/git/hooks/prepare-commit-msg -o .git/hooks -% chmod 755 .git/hooks/prepare-commit-msg -.... - -[[admin-branch]] -==== "admin" branch - -The `access` and `mentors` files are stored in an orphan branch, `internal/admin`, in each repository. - -Following example is how to check out the `internal/admin` branch to a local branch named `admin`: - -[source,shell] -.... -% git config --add remote.freebsd.fetch '+refs/internal/*:refs/internal/*' -% git fetch -% git checkout -b admin internal/admin -.... -Alternatively, you can add a worktree for the `admin` branch: - -[source,shell] -.... -git worktree add -b admin ../${repo}-admin internal/admin -.... - -For browsing `internal/admin` branch on web: -https://cgit.freebsd.org/${repo}/log/?h=internal/admin - -For pushing, either specify the full refspec: - -[source,shell] -.... -git push freebsd HEAD:refs/internal/admin -.... - -Or set `push.default` to `upstream` which will make `git push` to push the current branch back to its upstream by default, which is more suitable for our workflow: - -[source,shell] -.... -git config push.default upstream -.... - -[WARNING] -==== -These internal details may change often. -==== +Please see the link:{committers-guide}#git-mini-primer[Committer's Guide]. [[external-mirrors]] === External mirrors