git.kernel.org förklarat: sidans struktur och praktisk användning

git.kernel.org är Git-servern för kernel.org. Här finns Linus Torvalds huvudutvecklingsgren, stabila kärnor, linux-next, hundratals subsystem- och utvecklarträd samt verktyg som git självt, e2fsprogs eller Linux-manualsidorna. Webbgränssnittet är en anpassad version av cgit (anges i sidfoten som cgit 1.3.1-korg). Det är skrivskyddat: det finns inga konton, inga issues och inga pull requests. Kärnutvecklingen sker via e-postlistor, vars arkiv finns på lore.kernel.org; git.kernel.org visar resultatet, alltså de commits som maintainerna har tagit in i sina träd.

Vanliga skäl att besöka sidan är en CVE-post som hänvisar till en kernel-commit, frågan om en viss fix ingår i en kernel-version eller att läsa en enskild källfil utan att klona hela repositoriet.

Startsidan: lista över repositorier

Startsidan listar alla offentliga repositorier i en tabell. Grupperingen följer filsökvägen på servern: varje mellanrubrik som pub/scm/fs eller pub/scm/linux är en katalog, och under den visas repositorierna med sin sökväg relativt denna katalog.

Kolumner i översikt

Kolumn	Innehåll
Namn	Repositoriets sökväg under gruppen, till exempel xfs/xfs-linux.git under pub/scm/fs
Beskrivning	Innehållet i filen description i repositoriet. ”Unnamed repository; edit this file …” är Git-standardtexten och betyder endast att operatören inte har angett någon beskrivning
Ägare	Ansvarig person eller grupp (t.ex. ”XFS FS Group”, ”Infra Team”)
Inaktivitet	Tid sedan senaste commit på någon branch; ett lågt värde visar ett aktivt underhållet träd
Länkar	Direktlänkar till repositoriets vyer summary, log och tree

De viktigaste grupperna:

Listan är mycket lång eftersom varje maintainer med konto kan lägga egna träd enbart under pub/scm/linux/kernel/git/. Sökfältet uppe till höger filtrerar listan efter namn, beskrivning och ägare. Sökningen kan även öppnas direkt som URL, till exempel https://git.kernel.org/?q=xfs.

Sökvägsschemat för kernel-träden

Kernel-repositorier följer mönstret:

https://git.kernel.org/pub/scm/linux/kernel/git/<konto>/<repository>.git/

<konto> är maintainerens användarnamn på kernel.org, inte nödvändigtvis personens fullständiga namn (akpm är Andrew Morton, acme är Arnaldo Carvalho de Melo). För de flesta frågor räcker tre träd:

En fix passerar vanligtvis dessa träd i denna ordning: den hamnar först i det ansvariga subsystemets träd, visas i linux-next, tas under merge window in i mainline av Linus Torvalds via ett pull request-mejl och bakporteras därefter till stable-grenarna. Vilket subsystemträd som ansvarar framgår av filen MAINTAINERS i kernel-källkoden (rader med T: git …).

Vyerna i ett repositorium

Ett klick på ett repositorienamn öppnar vyn summary. Flikraden ovanför leder till övriga vyer; till vänster om den väljer en rullista den branch som alla vyer avser.

Vyer i översikt

Vy	Innehåll
about	Repositoriets README, om den finns
summary	Brancher med senaste commit, de senaste taggarna med nedladdningslänk, de senaste tio commits och klon-URL:er
refs	Fullständig lista över alla brancher och taggar
log	Commit-historik med sökfält; kolumner för ålder, commit-meddelande, författare, ändrade filer och rader
tree	Filträd för vald branch eller commit, med länkar till plain (råfil) och log (filhistorik)
commit	Metadata och diff för en enskild commit
diff	Skillnad mellan två commits eller mellan en commit och dess föregångare
stats	Commit-statistik per författare under en valbar tidsperiod

I vyn summary är taggblocket användbart för att läsa av den aktuella versionen: mainline visar release candidates (v7.3-rc7) och releaser (v7.3). Nedladdningslänkarna skapar ett arkiv på begäran och är därför inte alltid tillgängliga; för färdiga releaser är tarbollarna på kernel.org respektive cdn.kernel.org den avsedda nedladdningsvägen, där även PGP-signaturen finns.

I slutet av vyn summary finns klon-URL:erna. Utöver https:// och det okrypterade git:// anges en spegel hos Google (kernel.googlesource.com) som tillhandahåller samma innehåll.

Söka i historiken

Sökfältet i vyn log har en rullista med fyra lägen. Varje läge finns även som URL-parameter, så att sökningar kan sparas som bokmärken eller länkas i ärenden:

https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/log/?qt=grep&q=CVE

Alternativ förklarade

Parameter	Funktion
qt=grep	Söker i commit-meddelanden (valet ”log msg”)
qt=author	Söker i författarfältet (namn eller e-postadress)
qt=committer	Söker i committer-fältet, alltså efter personen som tog in commiten
qt=range	Visar ett intervall i Git-notation, till exempel q=v7.3-rc6..v7.3-rc7 för alla commits mellan två taggar
q=	Sökterm respektive intervall
h=	Branch som sökningen avser, till exempel h=linux-7.3.y i stable-trädet
ofs=	Förskjutning för sidindelning (git.kernel.org visar 200 commits per sida)

Intervallet v7.3-rc6..v7.3-rc7 besvarar frågan ”Vad ändrades mellan två versioner?” direkt i webbläsaren. I stable-trädet visar qt=range&q=v7.3.1..v7.3.2&h=linux-7.3.y alla fixar som tillkommit med en stable-uppdatering.

Läsa en commit

En enskild commit kan adresseras med sin fullständiga SHA-1-hash:

https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=<sha>

Vyn visar författare, committer, datum, överordnad commit (parent), det fullständiga commit-meddelandet och diffen. I slutet av ett kernel-commit-meddelande finns trailers som Signed-off-by:, Reviewed-by: och Fixes: <sha> ("Titel"). Raden Fixes: anger commiten som introducerade felet; därmed går det att avgränsa från vilken version ett system är påverkat. Link: hänvisar oftast till den tillhörande diskussionen på lore.kernel.org, Cc: stable@vger.kernel.org markerar fixen för bakportering till stable-kärnorna.

Om commit i URL:en ersätts med patch, levererar servern commiten som en patchfil i e-postformat (text/plain), som kan tillämpas med git am eller patch.

Kort-URL:er i CVE-poster

Sedan kernel-projektet självt började tilldela CVE-nummer hänvisar posterna i CVE-listan och NVD till kort-URL:er av formen https://git.kernel.org/stable/c/<sha>. git.kernel.org omdirigerar dessa med HTTP 301 till commit-vyn i rätt träd:

En CVE-post anger vanligen flera sådana länkar: en per stable-gren som fixen har bakporterats till och en för mainline. Hasharna skiljer sig åt eftersom varje bakport är en egen commit. Bakportens commit-meddelande anger originalets hash i mainline, antingen som raden commit <sha> upstream. eller som [ Upstream commit <sha> ].

Kontrollera om en fix ingår i en version

Webbgränssnittet visar inte vilka taggar en commit ingår i. För det krävs en lokal klon. För detta ändamål räcker en klon utan filinnehåll, som endast laddar commit-historiken:

git clone --filter=blob:none --no-checkout https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git

Alternativ förklarade

Alternativ	Funktion
clone	Skapar en lokal kopia av repositoriet
--filter=blob:none	Partiell klon: laddar commits och katalogstrukturer, filinnehåll (blobbar) först vid behov
--no-checkout	Skapar ingen arbetskatalog; behövs inte för frågor om historiken
URL	HTTPS-klon-URL från vyn summary i stable-trädet

Därefter besvarar ett kommando i den klonade katalogen frågan om den första versionen med fixen:

git describe --contains <sha>

Alternativ förklarade

Alternativ	Funktion
describe	Beskriver en commit relativt till en tagg
--contains	Söker efter den äldsta taggen som innehåller commiten i stället för den senaste taggen före den
<sha>	Commitens hash, till exempel från kort-URL:en i CVE-posten

Utdata har formen v7.3.2~14: fixen ingår från och med v7.3.2. Alla taggar som innehåller commiten listas av git tag --contains <sha>. Den som bara behöver en enskild fil eller en version för läsning kan använda vyerna tree och plain i webbläsaren i stället för en klon.

För den fullständiga källkoden för att bygga räcker en grund klon av en tagg:

git clone --depth 1 --branch v7.3 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git

Alternativ förklarade

Alternativ	Funktion
--depth 1	Laddar endast den senaste commiten utan historik; nedladdningen minskar från flera GB till några hundra MB
--branch v7.3	Väljer taggen eller branchen som checkas ut
URL	Klon-URL för mainline

Följa ändringar

Varje repositorium erbjuder ett Atom-flöde för standardbranchen under …/<repository>.git/atom/, för mainline alltså https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/atom/. En flödesläsare visar då nya commits utan att sidan behöver besökas regelbundet. För mainline skapar flödet många poster per dag under merge window; för releaser och stable-uppdateringar är versionsöversikten på kernel.org respektive dess flöde den lugnare källan.