From patchwork Tue Jan 21 18:58:47 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Richard Earnshaw (lists)" X-Patchwork-Id: 1226705 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=gcc.gnu.org (client-ip=209.132.180.131; helo=sourceware.org; envelope-from=gcc-patches-return-517927-incoming=patchwork.ozlabs.org@gcc.gnu.org; receiver=) Authentication-Results: ozlabs.org; dmarc=none (p=none dis=none) header.from=arm.com Authentication-Results: ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=gcc.gnu.org header.i=@gcc.gnu.org header.a=rsa-sha1 header.s=default header.b=TG196fK9; dkim-atps=neutral Received: from sourceware.org (server1.sourceware.org [209.132.180.131]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 482HrQ6fbwz9sRG for ; Wed, 22 Jan 2020 05:59:00 +1100 (AEDT) DomainKey-Signature: a=rsa-sha1; c=nofws; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender:to:cc :from:subject:message-id:date:mime-version:content-type; q=dns; s=default; b=agfQ4p6viu5mFfULoDG68lGxsVuNaAHxuSMnb6zEo3LDXdNn/f 6hHxD3UaIjcirQNLLZ05C6FWPvB75HHwjOxulczh6e3W710YA/IiE6lofi8/VrMm jVziWV/QR7YLT+Fbwv7mYkZT51IRnoeAxuabLPqa7PUBugTHuP2mQttgg= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender:to:cc :from:subject:message-id:date:mime-version:content-type; s= default; bh=S2CcU4bHX6/9tz1uzEFpQdS1Cs4=; b=TG196fK9iBQzj/FZoXZ9 +alTk+71kViSgs9HAi6tg9+LPC2+O1jcTOjPFwckXb28zPcHJYPu4xUVme5ULmgo 9MozJkhz+rV57QsxGSdLjpyaq8mdtW101nTcsHsIjqWLsciDVJeCRBsoD57Y5SUd eviZYGPemWQBTt8ARpTRi4A= Received: (qmail 126058 invoked by alias); 21 Jan 2020 18:58:52 -0000 Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Delivered-To: mailing list gcc-patches@gcc.gnu.org Received: (qmail 126036 invoked by uid 89); 21 Jan 2020 18:58:52 -0000 Authentication-Results: sourceware.org; auth=none X-Spam-SWARE-Status: No, score=-18.8 required=5.0 tests=AWL, BAYES_00, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, RCVD_IN_DNSWL_LOW, SPF_PASS autolearn=ham version=3.3.1 spammy=userid, Personal, lived, elses X-HELO: foss.arm.com Received: from foss.arm.com (HELO foss.arm.com) (217.140.110.172) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Tue, 21 Jan 2020 18:58:50 +0000 Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id EB8191FB; Tue, 21 Jan 2020 10:58:48 -0800 (PST) Received: from e120077-lin.cambridge.arm.com (e120077-lin.cambridge.arm.com [10.2.78.81]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id 7BAB23F6C4; Tue, 21 Jan 2020 10:58:48 -0800 (PST) To: "gcc-patches@gcc.gnu.org" Cc: GCC Development From: "Richard Earnshaw (lists)" Subject: [PATCH] wwwdocs: document scripts to access personal and vendor spaces Message-ID: <46db7323-1cc9-26e5-03aa-6386a885c12e@arm.com> Date: Tue, 21 Jan 2020 18:58:47 +0000 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.9.0 MIME-Version: 1.0 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. 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.

  • Example check-in session
  • Creating and using branches
  • git-merge-changelog
    • +
  • Personal and Vendor branches
  • Tips&Tricks around your account
    • @@ -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 +
    +

    Personal and vendor branches

    + +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. + +
      +
    • Personal branches live + in refs/users/username/heads with tags + in refs/users/username/tags.
      • +
    • Vendor branches live + in refs/vendors/vendor-name/heads with tags + in refs/vendors/vendor-name/tags.
      • +
    + +Scripts exist the contrib directory to help manage these spaces. + +

    contrib/gcc-git-customization.sh

    + +

    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:

    +
      +
    • Your name - 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.
      • +
    • Your email address - 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.
      • +
    • The local name for the upstream repository - normally, the + default (origin) will be correct. This is the git remote that + connects directly to the gcc.gnu.org server.
      • +
    • Your account name on gcc.gnu.org - 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.
      • +
    • The prefix to use for your personal branches - the default is + me, but you can change this if you prefer. The script + will add configuration information to allow local branches that + start me/<branch> 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.
      • +
    + +

    If you have multiple clones of the gcc repository you can fetch +updates from your personal space by running + git fetch me +(or whatever personal prefix you've chosen). You can also push an +already existing branch using git push me me/branch. +Beware that if you have more than one personal branch set up locally, +simply typing git push me will potentially push all such +personal branches. Use --dry-run to check that what will be pushed is +what you intend.

    + +

    To create a new personal branch, the following sequence of steps can be +used:

    +
    +  git push me <start-ref>:refs/users/<userid>/heads/<topic>
+  git fetch me
+  git checkout -b me/<topic> remotes/me/<topic>
+
    +

    If you've used a different personal prefix to 'me' then use that + in the sequence described above.

    + +

    The script also defines a few useful aliases that can be used with the +repository:

    + +
      +
    • svn-rev - 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 + --oneline option to summarize the commit on a single line. +
      • +
    • gcc-descr - Undocumented
      • +
    • gcc-undescr - Undocumented
      • +
    + +

    The final customization that the script makes is to add a diff rule so +that running git diff on a machine description file (a file +with the suffix .md) 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).

    + +

    contrib/git-fetch-vendor.sh

    + +

    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.

    + +

    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 contrib/gcc-git-customization.sh before you can use +this script.

    + + +

    The script requires one argument, the name of the vendor, and takes +one option, --enable-push, 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.

    + +

    Once the script has been run, a new 'remote' will be configured with the +name vendors/<vendor>. You can use this to fetch updates +to that vendor's branches.

    + +

    To check out an existing vendor branch, you can use:

    +
    +    git checkout -b <vendor>/<topic> remotes/vendors/<vendor>/<topic>
+
    +

    This will create a tracking branch that can be updated with normal git + operations, such as git pull.

    + +

    If you have set up push access, then the branch can similarly be pushed to + using:

    +
    +    git push vendors/<vendor> <vendor>/<topic>
+
    + +

    The script can be re-run with, or without --enable-push + to enable, or disable push operations.

    + +

    contrib/git-add-vendor-branch.sh

    + +

    Before this script can be used contrib/git-fetch-vendor.sh + 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.

    + +

    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 test branch under the vendor megacorp + run and starting from the most recent commit on master:

    + +
    +    contrib/git-add-vendor-branch.sh  <vendor>/<topic> master
+
    + +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 +git checkout or git worktree. +

    Tips&Tricks around your account