This is an old revision of the document!
Git Quick Start Guide
This page is to capture issues raised on IRC by other committers and users, so we don't lose that info while it gets added to official documentation. The steps here should mirror the more detailed instructions at the below url:
- https://docs.freebsd.org/en/articles/committers-guide/#git-primer
Quick Start
Getting the Repo
Pick an empty directory, let's call it ~/src/ports for example. A full clone takes about 900MiB space. This step uses HTTPS so your ssh keys aren't yet required.
# pick any GIT_PORTS_DIR you want export GIT_PORTS_DIR=~/src/ports # this step can take a while, in future it will be much quicker git clone -o freebsd -b main https://git.freebsd.org/ports.git $GIT_PORTS_DIR cd $GIT_PORTS_DIR # now we add in your push URL, and fetching the old SVN notes so you can # look for svn revisions in your git log git remote set-url --push freebsd ssh://git@gitrepo.freebsd.org/ports.git git config --add remote.freebsd.fetch "+refs/notes/*:refs/notes/*" # now we enable "rebasing" which will float your latest commits to the top # of the git tree, each time you pull new commits from the ports tree. This # makes it very easy to catch up if somebody else committed in between your # last fetch, and your attempted push. git config pull.rebase true
You'll now need to add your username and user id, exactly as they are on freefall:
ssh you@freefall gen-gitconfig.sh ... git config user.name "A Committer" git config user.email "you@FreeBSD.org" ...
After these steps, you should have this in your $GIT_PORTS_DIR/.git/config :
[core]
repositoryformatversion = 0
filemode = true
bare = false
logallrefupdates = true
[remote "freebsd"]
url = https://git.freebsd.org/ports.git
fetch = +refs/heads/main:refs/remotes/freebsd/main
fetch = +refs/notes/*:refs/notes/*
pushurl = ssh://git@gitrepo.freebsd.org/ports.git
[branch "main"]
remote = freebsd
merge = refs/heads/main
[pull]
rebase=true
[user]
# these entries came from ssh you@freefall gen-gitconfig.sh
name = A Committer
email = you@FreeBSD.org
The First Pull
You can now “pull” in changes since your last update, just like “svn up”, for this specific branch. This first pull will also fetch the svn notes, and any new commits at FreeBSD's ports tree, that we don't yet have locally.
If I have any local commits that have not yet been pushed up to freebsd's git repo, they will automatically be “rebased”, which is floating my local changes up to the tip of the git tree again. This ensures there's no conflicting history on my local branch vs FreeBSD's official history.
$ cd $GIT_PORTS_DIR $ git pull freebsd main remote: Enumerating objects: 45, done. remote: Counting objects: 100% (45/45), done. remote: Compressing objects: 100% (26/26), done. remote: Total 26 (delta 14), reused 0 (delta 0), pack-reused 0 Unpacking objects: 100% (26/26), 4.40 KiB | 112.00 KiB/s, done. From https://git.freebsd.org/ports * branch main -> FETCH_HEAD 7143d361cb6b..ab8a59366f5a main -> freebsd/main Successfully rebased and updated refs/heads/main.
Reviewing local git log
git's log subcommand has many options, but by default it shows you recent commits, in last committed order, for the current branch. By default, the “tip” commit is referred to as “HEAD” – it's the most recent commit in your current working directory. Once we make local changes, the local HEAD commit and the freebsd/main commits won't be the same anymore.
$ git log --oneline ab8a59366f5a (HEAD -> main, freebsd/main, freebsd/HEAD) x11-fonts/league-gothic: Update to 1.601 bafa49e87ea9 update check_ssl_cert to 2.0.0 ...
Making changes
This is best served by following “Making Local Changes” on the official https://docs.freebsd.org/en/articles/committers-guide/#git-primer docs, but this should give you a ports-oriented view of that document.
- make a new branch if our changes are long-lived
- hack away
- stage our changes
- commit locally our changes
- rebase to pick up any upstream commits that we are missing
- push our changes back up
Make a branch
First we need to update our current status, to match the FreeBSD ports tree, and then create a branch to work on. This is not mandatory, you can YOLO on main locally and nobody will ever know, but it allows you to keep work in progress ports in different branches easily, and supports advanced workflows with git worktrees, which are covered in the git primer docs.
- check status
- update from freebsd tree
- create a branch
- get to work
$ git status On branch main Your branch is up to date with 'freebsd/main'. nothing to commit, working tree clean $ git pull --ff-only freebsd main remote: Enumerating objects: 86, done. remote: Counting objects: 100% (86/86), done. remote: Compressing objects: 100% (52/52), done. remote: Total 54 (delta 36), reused 1 (delta 1), pack-reused 0 Unpacking objects: 100% (54/54), 6.57 KiB | 103.00 KiB/s, done. From https://git.freebsd.org/ports * branch main -> FETCH_HEAD 532a4a844263..8ae6e04d5276 main -> freebsd/main Updating 532a4a844263..8ae6e04d5276 Fast-forward devel/ruby-build/Makefile | 2 +- ... 18 files changed, 57 insertions(+), 85 deletions(-) create mode 100644 mail/wmbiff/files/pkg-message.in ... $ git switch -c my-port-changes Switched to a new branch 'my-port-changes'
Hack Hack Hack
You can always reset to the last commit with git reset --hard HEAD.
If you have un-tracked files to purge, you can do so with git clean -ndx
Remove the *-n* which is a dry-run flag.
$ cd cat/port # hack hack hack $ git status On branch main Your branch is up to date with 'freebsd/main'. Changes not staged for commit: (use "git add <file>..." to update what will be committed) (use "git restore <file>..." to discard changes in working directory) modified: Makefile modified: distinfo no changes added to commit (use "git add" and/or "git commit -a")
Staging Changes
This step is one of the most confusing for new-comers to git. Files exist in many states in different places:
- new files, not part of git repo locally yet (untracked files) - stuff you added, but is not “committed” locally in your ports tree (unstaged files) - stuff already commited, that you have modified, but not “committed” locally (modified files) - stuff committed and pushed upstream to FreeBSD official repo
git status will always tell you what's happening, and git log will show you
the tip commit, or HEAD, of your local repo, and of the FreeBSD one too.
For now, remember that “staging changes” needs to be done before “committing changes” and before “pushing my commits upstream”.
$ git add . ## notice how the state of these files has changed from "not staged" to "to be committed": $ git status On branch main Your branch is up to date with 'freebsd/main'. Changes to be committed: (use "git restore --staged <file>..." to unstage) modified: Makefile modified: distinfo
These changes are “staged” - you can have files in partial stages, with some diffs in the file already staged, and other not yet staged. For the moment, just be aware of this, and keep going.
$ git commit . # your $EDITOR is summoned
You can replace . by a specific file, glob pattern, or the -A which is All
The Things.
Your editor will come up, with space for a commit message, and a summary of the files git is expecting to add here. If you exit your editor here, with error code, or the commit message is blank, no changes are made. At this point, all the changes are local so you can keep fiddling until you get this right. Add a suitable message, see https://docs.freebsd.org/en/articles/committers-guide/#commit-log-message for commentary.
cat/foo: update to v1.2.3 - fixes the foobinator - see https://example.org/CHANGELOG for details # Please enter the commit message for your changes. Lines starting # with '#' will be ignored, and an empty message aborts the commit. # # On branch main # Your branch is up to date with 'freebsd/main'. # # Changes to be committed: # modified: Makefile # modified: distinfo #
At this point, we have:
- make some changes
- staged those changes
- committed *locally* those changes
- not yet pushed those upstream
You can safely change anything here - discard commits, re-edit files, as nothing is public.
Reviewing local git log
git's log subcommand has many options, but by default it shows you recent commits, in last committed order, for the current branch. By default, the “tip” commit is referred to as “HEAD” – it's the most recent commit in your current working directory.
Here, you can see I have one *local* commit that hasn't yet been pushed up to FreeBSD - the HEAD commit here is above the “freebsd/main” commit:
$ git log --oneline e7edeb6d7cb7 (HEAD -> main) cat/foo: update to v1.2.3 ab8a59366f5a (freebsd/main, freebsd/HEAD) x11-fonts/league-gothic: Update to 1.601 bafa49e87ea9 update check_ssl_cert to 2.0.0 ...
I can see the diff I'm pushing in several ways. This one shows me the diff of the tip commit:
$ git show HEAD
This one shows me the diff between what's upstream in FreeBSD (as of last git fetch/pull) and my repo clone:“
$ git diff HEAD..freebsd/main git diff HEAD..freebsd/main diff --git databases/erlfdb/Makefile databases/erlfdb/Makefile index 641245430b58..be61999c237a 100644 --- databases/erlfdb/Makefile +++ databases/erlfdb/Makefile @@ -2,7 +2,7 @@ PORTNAME= erlfdb DISTVERSIONPREFIX= v -DISTVERSION= 1.3.1 +DISTVERSION= 1.3.2 ...
Tips
- commit messages should be similar to cat/foo: update to latest too v1.2.3 see https://docs.freebsd.org/en/articles/committers-guide/#commit-log-message
Common Problems
ssh issues
$ git push git@gitrepo.freebsd.org: Permission denied (publickey). fatal: Could not read from remote repository. Please make sure you have the correct access rights and the repository exists.
This means that our git server is not accepting your public key. This should be the same one used for your access to freefall. You can check this easily:
$ ssh git@gitrepo.freebsd.org PTY allocation request failed on channel 1 hello $YOU, this is git@gitrepo running gitolite3 v3.6.12 on git 2.30.1 R W doc R W ports R W src Connection to gitrepo.freebsd.org closed.
You can debug further using GIT_SSH_COMMAND="ssh -v" git ...:
env GIT_SSH_COMMAND="ssh -v" git push OpenSSH_8.4p1, OpenSSL 1.1.1k-freebsd 25 Mar 2021 debug1: Reading configuration data .ssh/config debug1: .ssh/config line 1: Applying options for * debug1: .ssh/config line 17: Applying options for *.freebsd.org debug1: Reading configuration data /usr/local/etc/ssh/ssh_config debug1: auto-mux: Trying existing master debug1: Control socket "/tmp/.ssh-master-git@gitrepo.freebsd.org:22" does not exist debug1: Connecting to gitrepo.freebsd.org [96.47.72.44] port 22. debug1: Connection established. ... debug1: No more authentication methods to try. git@gitrepo.freebsd.org: Permission denied (publickey). fatal: Could not read from remote repository. Please make sure you have the correct access rights and the repository exists.