| Message ID | 46db7323-1cc9-26e5-03aa-6386a885c12e@arm.com |
|---|---|
| State | New |
| Headers | show |
| Series | wwwdocs: document scripts to access personal and vendor spaces | expand |
On 21/01/2020 18:58, Richard Earnshaw (lists) wrote: > This patch documents some of the scripts that I've published for > managing the personal and vendor spaces on the server. It also covers > some of the other features that those scripts enable, so that it's all > in one place. This is a complete rewrite of the material I had written > previously since before we did not have these scripts to make use of. > > I've not filled in the documentation for gcc-descr and gcc-undescr, > Jakub has agreed to provide that at a later date. > > R. I've pushed this. I think it's better to have this in than nothing at all. We can iterate on it as required. R.
On 23/01/20 16:23 +0000, Richard Earnshaw (lists) wrote: >On 21/01/2020 18:58, Richard Earnshaw (lists) wrote: >>This patch documents some of the scripts that I've published for >>managing the personal and vendor spaces on the server. It also >>covers some of the other features that those scripts enable, so that >>it's all in one place. This is a complete rewrite of the material I >>had written previously since before we did not have these scripts to >>make use of. >> >>I've not filled in the documentation for gcc-descr and gcc-undescr, >>Jakub has agreed to provide that at a later date. >> >>R. > >I've pushed this. I think it's better to have this in than nothing at >all. We can iterate on it as required. I've pushed the attached fix for a couple of typos. Do we want to repeat the "do not push changes to that space without their express permission" for user branches? There are no access checks to prevent it, but I hsouldn't be changing things in your branches without your permission. Finally, why does this qualify it as "If you have multiple clones"? <p>If you have multiple clones of the gcc repository you can fetch updates from your personal space by running <code>git fetch me</code> Isn't that the right command even if you only have one clone? commit 182ab16b43b0b40b985e0678891b29debef2c9a2 Author: Jonathan Wakely <jwakely@redhat.com> Date: Fri Jan 24 10:59:14 2020 +0000 Fix typos in gitwrite.html diff --git a/htdocs/gitwrite.html b/htdocs/gitwrite.html index ad073b53..c0fe8526 100644 --- a/htdocs/gitwrite.html +++ b/htdocs/gitwrite.html @@ -391,7 +391,7 @@ configuration steps can give access to them. in <code>refs/vendors/<i>vendor-name</i>/tags</code>.</li> </ul> -Scripts exist the contrib directory to help manage these spaces. +Scripts exist in the contrib directory to help manage these spaces. <h3>contrib/gcc-git-customization.sh</h3> @@ -413,7 +413,7 @@ some aliases that might be useful when developing GCC. The script will work this out based on the URL used to fetch from the git server, or fall back to your local user name if that fails. Using this name on the server for your personal space ensures that your branches will - not conflict with anybody elses.</li> + not conflict with anybody else's.</li> <li><i>The prefix to use for your personal branches</i> - the default is <code>me</code>, but you can change this if you prefer. The script will add configuration information to allow local branches that
On 24/01/2020 11:04, Jonathan Wakely wrote: > On 23/01/20 16:23 +0000, Richard Earnshaw (lists) wrote: >> On 21/01/2020 18:58, Richard Earnshaw (lists) wrote: >>> This patch documents some of the scripts that I've published for >>> managing the personal and vendor spaces on the server. It also >>> covers some of the other features that those scripts enable, so that >>> it's all in one place. This is a complete rewrite of the material I >>> had written previously since before we did not have these scripts to >>> make use of. >>> >>> I've not filled in the documentation for gcc-descr and gcc-undescr, >>> Jakub has agreed to provide that at a later date. >>> >>> R. >> >> I've pushed this. I think it's better to have this in than nothing at >> all. We can iterate on it as required. > > I've pushed the attached fix for a couple of typos. > > Do we want to repeat the "do not push changes to that space without > their express permission" for user branches? There are no access > checks to prevent it, but I hsouldn't be changing things in your > branches without your permission. > Absolutely. I guess I took this as read in the personal spaces. > Finally, why does this qualify it as "If you have multiple clones"? > > <p>If you have multiple clones of the gcc repository you can fetch > updates from your personal space by running > <code>git fetch me</code> > > Isn't that the right command even if you only have one clone? > Well, if you only have one clone, why would you need to pull branches from upstream that you pushed yourself? In fact, why would you even need to push them in that case, unless it's for backup? ... and if you're restoring your backup, then that's a new clone. You might temporally have only only one clone, but across all time you have more than one. It's pedantry, though, so feel free to re-word it. Thanks for the tweaks, anyway. R.
On 24/01/20 11:48 +0000, Richard Earnshaw (lists) wrote: >On 24/01/2020 11:04, Jonathan Wakely wrote: >>On 23/01/20 16:23 +0000, Richard Earnshaw (lists) wrote: >>>On 21/01/2020 18:58, Richard Earnshaw (lists) wrote: >>>>This patch documents some of the scripts that I've published for >>>>managing the personal and vendor spaces on the server. It also >>>>covers some of the other features that those scripts enable, so >>>>that it's all in one place. This is a complete rewrite of the >>>>material I had written previously since before we did not have >>>>these scripts to make use of. >>>> >>>>I've not filled in the documentation for gcc-descr and >>>>gcc-undescr, Jakub has agreed to provide that at a later date. >>>> >>>>R. >>> >>>I've pushed this. I think it's better to have this in than >>>nothing at all. We can iterate on it as required. >> >>I've pushed the attached fix for a couple of typos. >> >>Do we want to repeat the "do not push changes to that space without >>their express permission" for user branches? There are no access >>checks to prevent it, but I hsouldn't be changing things in your >>branches without your permission. >> > >Absolutely. I guess I took this as read in the personal spaces. If we don't document it, somebody will get it wrong :-) Maybe like so, after the "To create a new personal branch" paragraph: <p><em>Personal spaces are controlled by the individual user. Do not push changes to somebody else's space without their express permission.</em> (Rather than pushing to somebody else's personal branch, consider pushing to your own personal branch and having collaborators pull from there). </p> Is the parenthesis going into too much detail, too early? This page doesn't describe how to pull from somebody else's personal branch (and arguably that would be too much info here anyway, but it might make sense for https://gcc.gnu.org/wiki/GitCookbook instead). So maybe just the part in <em>. >>Finally, why does this qualify it as "If you have multiple clones"? >> >><p>If you have multiple clones of the gcc repository you can fetch >>updates from your personal space by running >> <code>git fetch me</code> >> >>Isn't that the right command even if you only have one clone? >> > > >Well, if you only have one clone, why would you need to pull branches >from upstream that you pushed yourself? Good point. >In fact, why would you even >need to push them in that case, unless it's for backup? ... and if So other people can see your work in progress (without the overhead of setting up a devel/* branch for a short-lived topic branch). >you're restoring your backup, then that's a new clone. You might >temporally have only only one clone, but across all time you have more >than one. Right. I was stuck in small-minded, non-distributed thinking :-) >It's pedantry, though, so feel free to re-word it. How about: "You can fetch updates from your personal space into some other clone of the repository (e.g. on a machine used for testing) by running:"
On 24/01/2020 12:19, Jonathan Wakely wrote: > On 24/01/20 11:48 +0000, Richard Earnshaw (lists) wrote: >> On 24/01/2020 11:04, Jonathan Wakely wrote: >>> On 23/01/20 16:23 +0000, Richard Earnshaw (lists) wrote: >>>> On 21/01/2020 18:58, Richard Earnshaw (lists) wrote: >>>>> This patch documents some of the scripts that I've published for >>>>> managing the personal and vendor spaces on the server. It also >>>>> covers some of the other features that those scripts enable, so >>>>> that it's all in one place. This is a complete rewrite of the >>>>> material I had written previously since before we did not have >>>>> these scripts to make use of. >>>>> >>>>> I've not filled in the documentation for gcc-descr and gcc-undescr, >>>>> Jakub has agreed to provide that at a later date. >>>>> >>>>> R. >>>> >>>> I've pushed this. I think it's better to have this in than nothing >>>> at all. We can iterate on it as required. >>> >>> I've pushed the attached fix for a couple of typos. >>> >>> Do we want to repeat the "do not push changes to that space without >>> their express permission" for user branches? There are no access >>> checks to prevent it, but I hsouldn't be changing things in your >>> branches without your permission. >>> >> >> Absolutely. I guess I took this as read in the personal spaces. > > If we don't document it, somebody will get it wrong :-) > > Maybe like so, after the "To create a new personal branch" paragraph: > > <p><em>Personal spaces are controlled by the individual user. Do not push > changes to somebody else's space without their express permission.</em> > (Rather than pushing to somebody else's personal branch, consider pushing > to your own personal branch and having collaborators pull from there). > </p> > > Is the parenthesis going into too much detail, too early? This page > doesn't describe how to pull from somebody else's personal branch (and > arguably that would be too much info here anyway, but it might make > sense for https://gcc.gnu.org/wiki/GitCookbook instead). I think the 'pull' model is probably preferable for personal spaces. At some point we might need to enforce something like that anyway. > > So maybe just the part in <em>. > >>> Finally, why does this qualify it as "If you have multiple clones"? >>> >>> <p>If you have multiple clones of the gcc repository you can fetch >>> updates from your personal space by running >>> <code>git fetch me</code> >>> >>> Isn't that the right command even if you only have one clone? >>> >> >> >> Well, if you only have one clone, why would you need to pull branches >> from upstream that you pushed yourself? > > Good point. > >> In fact, why would you even need to push them in that case, unless >> it's for backup? ... and if > > So other people can see your work in progress (without the overhead of > setting up a devel/* branch for a short-lived topic branch). > >> you're restoring your backup, then that's a new clone. You might >> temporally have only only one clone, but across all time you have more >> than one. > > Right. I was stuck in small-minded, non-distributed thinking :-) > >> It's pedantry, though, so feel free to re-word it. > > How about: > > "You can fetch updates from your personal space into some other clone > of the repository (e.g. on a machine used for testing) by running:" > > Yes, that's fine. Note, that I spotted a problem with the simple "me" remote, in that git gets confused if you have both refs/heads/<me>/<topic> and refs/remotes/<me>/<topic> (checking out me/<topic> results in complaints about an ambiguous ref). I'm currently reworking my scripts to use users/<me> for the remote, much like the 'vendors' space. Watch this space... R.
On 24/01/20 13:55 +0000, Richard Earnshaw (lists) wrote: >On 24/01/2020 12:19, Jonathan Wakely wrote: >>On 24/01/20 11:48 +0000, Richard Earnshaw (lists) wrote: >>>On 24/01/2020 11:04, Jonathan Wakely wrote: >>>>On 23/01/20 16:23 +0000, Richard Earnshaw (lists) wrote: >>>>>On 21/01/2020 18:58, Richard Earnshaw (lists) wrote: >>>>>>This patch documents some of the scripts that I've published >>>>>>for managing the personal and vendor spaces on the server. >>>>>>It also covers some of the other features that those scripts >>>>>>enable, so that it's all in one place. This is a complete >>>>>>rewrite of the material I had written previously since >>>>>>before we did not have these scripts to make use of. >>>>>> >>>>>>I've not filled in the documentation for gcc-descr and >>>>>>gcc-undescr, Jakub has agreed to provide that at a later >>>>>>date. >>>>>> >>>>>>R. >>>>> >>>>>I've pushed this. I think it's better to have this in than >>>>>nothing at all. We can iterate on it as required. >>>> >>>>I've pushed the attached fix for a couple of typos. >>>> >>>>Do we want to repeat the "do not push changes to that space without >>>>their express permission" for user branches? There are no access >>>>checks to prevent it, but I hsouldn't be changing things in your >>>>branches without your permission. >>>> >>> >>>Absolutely. I guess I took this as read in the personal spaces. >> >>If we don't document it, somebody will get it wrong :-) >> >>Maybe like so, after the "To create a new personal branch" paragraph: >> >><p><em>Personal spaces are controlled by the individual user. Do not push >>changes to somebody else's space without their express permission.</em> >>(Rather than pushing to somebody else's personal branch, consider pushing >>to your own personal branch and having collaborators pull from there). >></p> >> >>Is the parenthesis going into too much detail, too early? This page >>doesn't describe how to pull from somebody else's personal branch (and >>arguably that would be too much info here anyway, but it might make >>sense for https://gcc.gnu.org/wiki/GitCookbook instead). > >I think the 'pull' model is probably preferable for personal spaces. >At some point we might need to enforce something like that anyway. > >> >>So maybe just the part in <em>. >> >>>>Finally, why does this qualify it as "If you have multiple clones"? >>>> >>>><p>If you have multiple clones of the gcc repository you can fetch >>>>updates from your personal space by running >>>> <code>git fetch me</code> >>>> >>>>Isn't that the right command even if you only have one clone? >>>> >>> >>> >>>Well, if you only have one clone, why would you need to pull >>>branches from upstream that you pushed yourself? >> >>Good point. >> >>>In fact, why would you even need to push them in that case, unless >>>it's for backup? ... and if >> >>So other people can see your work in progress (without the overhead of >>setting up a devel/* branch for a short-lived topic branch). >> >>>you're restoring your backup, then that's a new clone. You might >>>temporally have only only one clone, but across all time you have >>>more than one. >> >>Right. I was stuck in small-minded, non-distributed thinking :-) >> >>>It's pedantry, though, so feel free to re-word it. >> >>How about: >> >>"You can fetch updates from your personal space into some other clone >>of the repository (e.g. on a machine used for testing) by running:" >> >> > >Yes, that's fine. OK, I've pushed the attached patch. commit 0bce4cca846fa1d79f080d2784f90aaa5c447e2b Author: Jonathan Wakely <jwakely@redhat.com> Date: Fri Jan 24 15:00:57 2020 +0000 Adjust docs on personal Git branches diff --git a/htdocs/gitwrite.html b/htdocs/gitwrite.html index c0fe8526..5b631607 100644 --- a/htdocs/gitwrite.html +++ b/htdocs/gitwrite.html @@ -424,8 +424,8 @@ some aliases that might be useful when developing GCC. The script will settings configured by the script will still be useful.</li> </ul> -<p>If you have multiple clones of the gcc repository you can fetch -updates from your personal space by running +<p>You can fetch updates from your personal space into some other clone +of the repository (e.g. on a machine used for testing) by running <code>git fetch me</code> (or whatever personal prefix you've chosen). You can also push an already existing branch using <code>git push me me/branch</code>. @@ -444,6 +444,12 @@ used:</p> <p>If you've used a different personal prefix to 'me' then use that in the sequence described above.</p> +<p><em>Personal spaces are controlled by the individual user. Do not push +changes to somebody else's space without their express permission.</em> +(Rather than pushing to somebody else's personal branch, consider pushing +to your own personal branch and having collaborators pull from there.) +</p> + <p>The script also defines a few useful aliases that can be used with the repository:</p>
On 24/01/20 15:09 +0000, Jonathan Wakely wrote: >On 24/01/20 13:55 +0000, Richard Earnshaw (lists) wrote: >>On 24/01/2020 12:19, Jonathan Wakely wrote: >>>On 24/01/20 11:48 +0000, Richard Earnshaw (lists) wrote: >>>>On 24/01/2020 11:04, Jonathan Wakely wrote: >>>>>On 23/01/20 16:23 +0000, Richard Earnshaw (lists) wrote: >>>>>>On 21/01/2020 18:58, Richard Earnshaw (lists) wrote: >>>>>>>This patch documents some of the scripts that I've >>>>>>>published for managing the personal and vendor spaces on >>>>>>>the server. It also covers some of the other features >>>>>>>that those scripts enable, so that it's all in one place. >>>>>>>This is a complete rewrite of the material I had written >>>>>>>previously since before we did not have these scripts to >>>>>>>make use of. >>>>>>> >>>>>>>I've not filled in the documentation for gcc-descr and >>>>>>>gcc-undescr, Jakub has agreed to provide that at a later >>>>>>>date. >>>>>>> >>>>>>>R. >>>>>> >>>>>>I've pushed this. I think it's better to have this in than >>>>>>nothing at all. We can iterate on it as required. >>>>> >>>>>I've pushed the attached fix for a couple of typos. >>>>> >>>>>Do we want to repeat the "do not push changes to that space without >>>>>their express permission" for user branches? There are no access >>>>>checks to prevent it, but I hsouldn't be changing things in your >>>>>branches without your permission. >>>>> >>>> >>>>Absolutely. I guess I took this as read in the personal spaces. >>> >>>If we don't document it, somebody will get it wrong :-) >>> >>>Maybe like so, after the "To create a new personal branch" paragraph: >>> >>><p><em>Personal spaces are controlled by the individual user. Do not push >>>changes to somebody else's space without their express permission.</em> >>>(Rather than pushing to somebody else's personal branch, consider pushing >>>to your own personal branch and having collaborators pull from there). >>></p> >>> >>>Is the parenthesis going into too much detail, too early? This page >>>doesn't describe how to pull from somebody else's personal branch (and >>>arguably that would be too much info here anyway, but it might make >>>sense for https://gcc.gnu.org/wiki/GitCookbook instead). >> >>I think the 'pull' model is probably preferable for personal spaces. >>At some point we might need to enforce something like that anyway. >> >>> >>>So maybe just the part in <em>. >>> >>>>>Finally, why does this qualify it as "If you have multiple clones"? >>>>> >>>>><p>If you have multiple clones of the gcc repository you can fetch >>>>>updates from your personal space by running >>>>> <code>git fetch me</code> >>>>> >>>>>Isn't that the right command even if you only have one clone? >>>>> >>>> >>>> >>>>Well, if you only have one clone, why would you need to pull >>>>branches from upstream that you pushed yourself? >>> >>>Good point. >>> >>>>In fact, why would you even need to push them in that case, >>>>unless it's for backup? ... and if >>> >>>So other people can see your work in progress (without the overhead of >>>setting up a devel/* branch for a short-lived topic branch). >>> >>>>you're restoring your backup, then that's a new clone. You >>>>might temporally have only only one clone, but across all time >>>>you have more than one. >>> >>>Right. I was stuck in small-minded, non-distributed thinking :-) >>> >>>>It's pedantry, though, so feel free to re-word it. >>> >>>How about: >>> >>>"You can fetch updates from your personal space into some other clone >>>of the repository (e.g. on a machine used for testing) by running:" >>> >>> >> >>Yes, that's fine. > >OK, I've pushed the attached patch. Oops, wrong patch, *this* is what I pushed. commit f526c4724b183482fc7fe1a5ce78e1597fd1005f Author: Jonathan Wakely <jwakely@redhat.com> Date: Fri Jan 24 15:00:57 2020 +0000 Adjust docs on personal Git branches diff --git a/htdocs/gitwrite.html b/htdocs/gitwrite.html index 55667a2d..b5d7ff35 100644 --- a/htdocs/gitwrite.html +++ b/htdocs/gitwrite.html @@ -436,6 +436,12 @@ you intend. The script <code>contrib/git-add-user-branch.sh</code> can be used to create a new personal branch which can be pushed and pulled from the <i>users/me</i> remote.</p> +<p><em>Personal spaces are controlled by the individual user. Do not push +changes to somebody else's space without their express permission.</em> +(Rather than pushing to somebody else's personal branch, consider pushing +to your own personal branch and having collaborators pull from there.) +</p> + <p>The script also defines a few useful aliases that can be used with the repository:</p>
On 24/01/2020 15:12, Jonathan Wakely wrote: > On 24/01/20 15:09 +0000, Jonathan Wakely wrote: >> On 24/01/20 13:55 +0000, Richard Earnshaw (lists) wrote: >>> On 24/01/2020 12:19, Jonathan Wakely wrote: >>>> On 24/01/20 11:48 +0000, Richard Earnshaw (lists) wrote: >>>>> On 24/01/2020 11:04, Jonathan Wakely wrote: >>>>>> On 23/01/20 16:23 +0000, Richard Earnshaw (lists) wrote: >>>>>>> On 21/01/2020 18:58, Richard Earnshaw (lists) wrote: >>>>>>>> This patch documents some of the scripts that I've published for >>>>>>>> managing the personal and vendor spaces on the server. It also >>>>>>>> covers some of the other features that those scripts enable, so >>>>>>>> that it's all in one place. This is a complete rewrite of the >>>>>>>> material I had written previously since before we did not have >>>>>>>> these scripts to make use of. >>>>>>>> >>>>>>>> I've not filled in the documentation for gcc-descr and >>>>>>>> gcc-undescr, Jakub has agreed to provide that at a later date. >>>>>>>> >>>>>>>> R. >>>>>>> >>>>>>> I've pushed this. I think it's better to have this in than >>>>>>> nothing at all. We can iterate on it as required. >>>>>> >>>>>> I've pushed the attached fix for a couple of typos. >>>>>> >>>>>> Do we want to repeat the "do not push changes to that space without >>>>>> their express permission" for user branches? There are no access >>>>>> checks to prevent it, but I hsouldn't be changing things in your >>>>>> branches without your permission. >>>>>> >>>>> >>>>> Absolutely. I guess I took this as read in the personal spaces. >>>> >>>> If we don't document it, somebody will get it wrong :-) >>>> >>>> Maybe like so, after the "To create a new personal branch" paragraph: >>>> >>>> <p><em>Personal spaces are controlled by the individual user. Do >>>> not push >>>> changes to somebody else's space without their express permission.</em> >>>> (Rather than pushing to somebody else's personal branch, consider >>>> pushing >>>> to your own personal branch and having collaborators pull from there). >>>> </p> >>>> >>>> Is the parenthesis going into too much detail, too early? This page >>>> doesn't describe how to pull from somebody else's personal branch (and >>>> arguably that would be too much info here anyway, but it might make >>>> sense for https://gcc.gnu.org/wiki/GitCookbook instead). >>> >>> I think the 'pull' model is probably preferable for personal spaces. >>> At some point we might need to enforce something like that anyway. >>> >>>> >>>> So maybe just the part in <em>. >>>> >>>>>> Finally, why does this qualify it as "If you have multiple clones"? >>>>>> >>>>>> <p>If you have multiple clones of the gcc repository you can fetch >>>>>> updates from your personal space by running >>>>>> <code>git fetch me</code> >>>>>> >>>>>> Isn't that the right command even if you only have one clone? >>>>>> >>>>> >>>>> >>>>> Well, if you only have one clone, why would you need to pull >>>>> branches from upstream that you pushed yourself? >>>> >>>> Good point. >>>> >>>>> In fact, why would you even need to push them in that case, unless >>>>> it's for backup? ... and if >>>> >>>> So other people can see your work in progress (without the overhead of >>>> setting up a devel/* branch for a short-lived topic branch). >>>> >>>>> you're restoring your backup, then that's a new clone. You might >>>>> temporally have only only one clone, but across all time you have >>>>> more than one. >>>> >>>> Right. I was stuck in small-minded, non-distributed thinking :-) >>>> >>>>> It's pedantry, though, so feel free to re-word it. >>>> >>>> How about: >>>> >>>> "You can fetch updates from your personal space into some other clone >>>> of the repository (e.g. on a machine used for testing) by running:" >>>> >>>> >>> >>> Yes, that's fine. >> >> OK, I've pushed the attached patch. > > Oops, wrong patch, *this* is what I pushed. > Thanks. On reflection, I've reworded this slightly and moved it up to the introduction to the personal and vendor spaces. The same principle applies to both. Pushed. R. diff --git a/htdocs/gitwrite.html b/htdocs/gitwrite.html index b5d7ff35..97d60870 100644 --- a/htdocs/gitwrite.html +++ b/htdocs/gitwrite.html @@ -378,7 +378,7 @@ The GCC git repository is used by many people and the branch and tag namespace would become very polluted if all branches lived at the top-level naming space. To help minimise the amount of data that needs to be fetched the git repository on gcc.gnu.org supports -having personal and vendor branches that developers use to +having personal and vendor spaces that developers use to share their work. These are not pulled by default, but simple configuration steps can give access to them. @@ -391,7 +391,14 @@ configuration steps can give access to them. in <code>refs/vendors/<i>vendor-name</i>/tags</code>.</li> </ul> -Scripts exist in the contrib directory to help manage these spaces. +<p><em>Personal and vendor spaces are controlled by the individual +user or vendor. Do not push changes to somebody else's space without +their express permission.</em> Rather than pushing to somebody +else's branch, consider pushing to your own personal branch and having +collaborators pull from there. +</p> + +<p>Scripts exist in the contrib directory to help manage these spaces.</p> <h3>contrib/gcc-git-customization.sh</h3> @@ -436,12 +443,6 @@ you intend. The script <code>contrib/git-add-user-branch.sh</code> can be used to create a new personal branch which can be pushed and pulled from the <i>users/me</i> remote.</p> -<p><em>Personal spaces are controlled by the individual user. Do not push -changes to somebody else's space without their express permission.</em> -(Rather than pushing to somebody else's personal branch, consider pushing -to your own personal branch and having collaborators pull from there.) -</p> - <p>The script also defines a few useful aliases that can be used with the repository:</p>
diff --git a/htdocs/gitwrite.html b/htdocs/gitwrite.html index 87a18fa7..047c139f 100644 --- a/htdocs/gitwrite.html +++ b/htdocs/gitwrite.html @@ -26,6 +26,7 @@ maintainers and significant developers.</p> <li><a href="#example">Example check-in session</a></li> <li><a href="#branches">Creating and using branches</a></li> <li><a href="#changelog">git-merge-changelog</a></li> + <li><a href="#vendor">Personal and Vendor branches</a></li> <li><a href="#account">Tips&Tricks around your account</a></li> </ol> @@ -370,6 +371,158 @@ git config --global merge.merge-changelog.driver "git-merge-changelog %O %A %B" echo "ChangeLog* merge=merge-changelog" >> $GCCSRCDIR/.git/info/attributes </pre></blockquote> +<hr /> +<h2 id="vendor">Personal and vendor branches</h2> + +The GCC git repository is used by many people and the branch and tag +namespace would become very polluted if all branches lived at the +top-level naming space. To help minimise the amount of data that +needs to be fetched the git repository on gcc.gnu.org supports +having personal and vendor branches that developers use to +share their work. These are not pulled by default, but simple +configuration steps can give access to them. + +<ul> + <li>Personal branches live + in <code>refs/users/<i>username</i>/heads</code> with tags + in <code>refs/users/<i>username</i>/tags</code>.</li> + <li>Vendor branches live + in <code>refs/vendors/<i>vendor-name</i>/heads</code> with tags + in <code>refs/vendors/<i>vendor-name</i>/tags</code>.</li> +</ul> + +Scripts exist the contrib directory to help manage these spaces. + +<h3>contrib/gcc-git-customization.sh</h3> + +<p>This script will help set up your personal area. It will also define +some aliases that might be useful when developing GCC. The script will + first ask a number of questions:</p> +<ul> + <li><i>Your name</i> - git uses this when you commit messages. You + can set this globally, but the script will confirm the setting is + appropriate for GCC as well. If you have not already set this + then git will try to find your name from your account.</li> + <li><i>Your email address</i> - similar to above. If this is not + set globally, the script will not attempt to guess this field, so + you must provide a suitable answer.</li> + <li><i>The local name for the upstream repository</i> - normally, the + default (origin) will be correct. This is the git remote that + connects directly to the gcc.gnu.org server.</li> + <li><i>Your account name on gcc.gnu.org</i> - the script will try to + work this out based on the URL used to fetch from the git server, or + fall back to your local user name if that fails. Using this name + on the server for your personal space ensures that your branches will + not conflict with anybody elses.</li> + <li><i>The prefix to use for your personal branches</i> - the default is + <code>me</code>, but you can change this if you prefer. The script + will add configuration information to allow local branches that + start <code>me/<branch></code> to be pushed or pulled from + your personal space in the gcc git repository on the server. + Do not worry if you do not have an account on gcc.gnu.org. You will + not be able to create a personal space on the server, but other + settings configured by the script will still be useful.</li> +</ul> + +<p>If you have multiple clones of the gcc repository you can fetch +updates from your personal space by running + <code>git fetch me</code> +(or whatever personal prefix you've chosen). You can also push an +already existing branch using <code>git push me me/branch</code>. +Beware that if you have more than one personal branch set up locally, +simply typing <code>git push me</code> will potentially push all such +personal branches. Use --dry-run to check that what will be pushed is +what you intend.</p> + +<p>To create a new personal branch, the following sequence of steps can be +used:</p> +<blockquote><pre> + git push me <start-ref>:refs/users/<userid>/heads/<topic> + git fetch me + git checkout -b me/<topic> remotes/me/<topic> +</pre></blockquote> +<p>If you've used a different personal prefix to 'me' then use that + in the sequence described above.</p> + +<p>The script also defines a few useful aliases that can be used with the +repository:</p> + +<ul> + <li><i>svn-rev</i> - Find the commit in the git repository that was + created from a particular revision number from the SVN era. The + first parameter must be the revision number you wish to look up, + an initial 'r' prefix is optional. You can then pass other + options that are accepted by git log to modify the format of the + output. Of particular use is the + <code>--oneline</code> option to summarize the commit on a single line. + </li> + <li><i>gcc-descr</i> - Undocumented</li> + <li><i>gcc-undescr</i> - Undocumented</li> +</ul> + +<p>The final customization that the script makes is to add a diff rule so +that running <code>git diff</code> on a machine description file (a file +with the suffix <code>.md</code>) will annotate +the diff hunk headers with the name of the pattern being modified (in +much the same way as C function names are used).</p> + +<h3>contrib/git-fetch-vendor.sh</h3> + +<p><em>Vendor spaces are controlled by the named vendor. Unless you are +affiliated with that vendor, do not push changes to that space without +their express permission.</em></p> + +<p>This script will set up a new 'remote' that can be used to access +the area used by a named vendor. You need to +run <code>contrib/gcc-git-customization.sh</code> before you can use +this script.</p> + + +<p>The script requires one argument, the name of the vendor, and takes +one option, <code>--enable-push</code>, to enable pushes to +be made to the space. If invoked with no arguments the script will +build a list of existing vendors from the server.</p> + +<p>Once the script has been run, a new 'remote' will be configured with the +name <code>vendors/<vendor></code>. You can use this to fetch updates +to that vendor's branches.</p> + +<p>To check out an existing vendor branch, you can use:</p> +<blockquote><pre> + git checkout -b <vendor>/<topic> remotes/vendors/<vendor>/<topic> +</pre></blockquote> +<p>This will create a tracking branch that can be updated with normal git + operations, such as <code>git pull</code>.</p> + +<p>If you have set up push access, then the branch can similarly be pushed to + using:</p> +<blockquote><pre> + git push vendors/<vendor> <vendor>/<topic> +</pre></blockquote> + +<p>The script can be re-run with, or without <code>--enable-push</code> + to enable, or disable push operations.</p> + +<h3>contrib/git-add-vendor-branch.sh</h3> + +<p>Before this script can be used <code>contrib/git-fetch-vendor.sh</code> + should be run to set up the vendor-specific workspace. This applies + even if the named vendor space does not yet exist on the server.</p> + +<p>This script can be used to simplify the task of creating an initial + vendor branch. The script takes two arguments, the name of the branch + to create (including the vendor name) and the start point. For example, + to create a <code>test</code> branch under the vendor <code>megacorp</code> + run and starting from the most recent commit on <code>master</code>:</p> + +<blockquote><pre> + contrib/git-add-vendor-branch.sh <vendor>/<topic> master +</pre></blockquote> + +This will create the branch both locally and on the server, but will not +check the branch out locally. You can do that afterwards with +<code>git checkout</code> or <code>git worktree</code>. + <hr /> <h2 id="account">Tips&Tricks around your account</h2>