From owner-dev-commits-doc-all@freebsd.org Tue Jun 29 19:06:09 2021 Return-Path: Delivered-To: dev-commits-doc-all@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id 920D1650A40 for ; Tue, 29 Jun 2021 19:06:09 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4GDv8K3lm0z3mD6; Tue, 29 Jun 2021 19:06:09 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 64FA41DEF9; Tue, 29 Jun 2021 19:06:09 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 15TJ69qd099790; Tue, 29 Jun 2021 19:06:09 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 15TJ69W8099789; Tue, 29 Jun 2021 19:06:09 GMT (envelope-from git) Date: Tue, 29 Jun 2021 19:06:09 GMT Message-Id: <202106291906.15TJ69W8099789@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Warner Losh Subject: git: 443c1ab624 - main - handbook/cutting_edge: document the n-number MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: imp X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 443c1ab6247bc5b63235cb6b52213529b3f1c6f1 Auto-Submitted: auto-generated X-BeenThere: dev-commits-doc-all@freebsd.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: Commit messages for all branches of the doc repository List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 29 Jun 2021 19:06:09 -0000 The branch main has been updated by imp: URL: https://cgit.FreeBSD.org/doc/commit/?id=443c1ab6247bc5b63235cb6b52213529b3f1c6f1 commit 443c1ab6247bc5b63235cb6b52213529b3f1c6f1 Author: Warner Losh AuthorDate: 2021-06-29 14:31:09 +0000 Commit: Warner Losh CommitDate: 2021-06-29 19:02:44 +0000 handbook/cutting_edge: document the n-number Document how to convert a git hash into a 'n' number. I've been asked this a few times and it would be good to have an easy, linkable answer. It seems to fit best here. Feedback from: markj@, Pau Amma Reviewed by: erj@, ceri@ Sponsored by: Netflix Differential Revision: https://reviews.freebsd.org/D30938 --- .../en/books/handbook/cutting-edge/_index.adoc | 43 ++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/documentation/content/en/books/handbook/cutting-edge/_index.adoc b/documentation/content/en/books/handbook/cutting-edge/_index.adoc index 668dabe1d9..e1b9d257bd 100644 --- a/documentation/content/en/books/handbook/cutting-edge/_index.adoc +++ b/documentation/content/en/books/handbook/cutting-edge/_index.adoc @@ -596,6 +596,49 @@ To compile or upgrade to an existing FreeBSD system to FreeBSD-STABLE, use `git` Branch names, such as `stable/9`, are listed at link:https://www.FreeBSD.org/releng/[www.freebsd.org/releng]. . Before compiling or upgrading to FreeBSD-STABLE , read [.filename]#/usr/src/Makefile# carefully and follow the instructions in <>. Read the {freebsd-stable} and [.filename]#/usr/src/UPDATING# to keep up-to-date on other bootstrapping procedures that sometimes become necessary on the road to the next release. +[[translate-n-number]] +=== The N-number +When tracking down bugs it is important to know which versions of the source code have been used to create the system exhibiting an issue. +FreeBSD provides version information compiled into the kernel. +man:uname[1] retrieves this information, for example: +[source,shell] +.... +% uname -a +FreeBSD 14.0-CURRENT #112 main-n247514-031260d64c18: Tue Jun 22 20:43:19 MDT 2021 fred@machine:/usr/home/fred/obj/usr/home/fred/git/head/amd64.amd64/sys/FRED +.... +Looking at the 4th field, it is made up of several parts: +[source,shell] +.... +main-n247514-031260d64c18 + +main <.> +n247514 <.> +031260d64c18 <.> +.... +<.> Git branch name. +Note: comparisons of n-numbers are only valid on branches published by the project (`main`, `stable/XX` and `releng/XX`). +Local branches will have n-numbers that will overlap commits of their parent branch. +<.> The n-number is a linear count of commits back to the start of the Git repository starting with the Git hash included in the line. +<.> Git hash of the checked out tree +<.> Sometimes a suffix of `-dirty` is present when the kernel was built in a tree with uncommitted changes. +It is absent in this example because the FRED kernel was built from a pristine checkout. + +The `git rev-list` command is used to find the n-number corresponding to a Git hash. +For example: +[source,shell] +.... +% git rev-list --first-parent --count 031260d64c18 <.> +247514 <.> +.... +<.> git hash to translate (the hash from the above example is reused) +<.> The n-number. + +Usually this number is not all that important. +However, when bug fixes are committed, this number makes it easy to quickly determine whether the fix is present in the currently running system. +Developers will often refer to the hash of the commit (or provide a URL which has that hash), but not the n-number since the hash is the easily visible identifier for a change while the n-number is not. +Security advisories and errata notices will also note an n-number, which can be directly compared against your system. +When you need to use shallow Git clones, you cannot compare n-numbers reliably as the `git rev-list` command counts all the revisions in the repository which a shallow clone omits. + [[makeworld]] == Updating FreeBSD from Source