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

The simplest way to get started with git, today, is to install git from the pre-packaged FreeBSD packages, or to build the same package yourself in the usual fashion:

• the smallest package with least dependencies:

# pkg install -r FreeBSD git-lite

• the full blown git experience with many dependencies:

# pkg install -r FreeBSD git

• install from source build

# cd /usr/ports/devel/git && make install

You're now ready to go.

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
# fetch the prepare-commit-msg hook
fetch https://cgit.freebsd.org/src/plain/tools/tools/git/hooks/prepare-commit-msg -o .git/hooks
chmod +x .git/hooks/prepare-commit-msg

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"

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.

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
...

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

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'

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")

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 specific filenames, a 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:

• made 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.

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 cat/foo/Makefile cat/foo/Makefile
index 641245430b58..be61999c237a 100644
--- cat/foo/Makefile
+++ cat/foo/Makefile
@@ -2,7 +2,7 @@
 
 PORTNAME=      foo
 DISTVERSIONPREFIX=     v
-DISTVERSION=   1.2.2
+DISTVERSION=   1.2.3
...

This is the point of no return. Our local changes (commits) will be pushed up to FreeBSD's official repo, and just like a blockchain, any subsequent commits will need to be appended after our ones.

There's a small problem, though, other diligent committers have already pushed their changes upstream, and we don't have those yet. FreeBSD's git repo doesn't allow diverging versions of history, so we need to catch up the history, and “float” our changes up to the top of the pile before committing. This process is called rebasing, and it sounds a bit scary, but just works. Occasionally, if somebody else has modified the same files and git can't figure out the right thing to do, we'll get an error here, and we will need to fix stuff up. A great example is when two people try to use the same UNIX ID in GIDS/UIDs files, and there's a “merge conflict”. For the moment, let's ignore that, and assume the happy case.

# check there are no unmodified files lying around
$ git status -sb
## main...freebsd/main [ahead 1]

# pull in the upstream changes and float our diff to the top
$ git pull --ff-only freebsd main
remote: Enumerating objects: 137, done.
remote: Counting objects: 100% (137/137), done.
remote: Compressing objects: 100% (136/136), done.
remote: Total 137 (delta 38), reused 0 (delta 0), pack-reused 0
Receiving objects: 100% (137/137), 650.85 KiB | 4.97 MiB/s, done.
Resolving deltas: 100% (38/38), done.
From https://git.freebsd.org/ports
 * branch                      main       -> FETCH_HEAD
   ab8a59366f5a..23642082e10d  main       -> freebsd/main
Successfully rebased and updated refs/heads/main.

Now, we're ready to push our commit up and be the tip (HEAD) commit of the official repo. You don't need the -v flag but it might be interesting the first few times:

$ git push -v freebsd HEAD:main
Pushing to ssh://gitrepo.freebsd.org/ports.git
Enumerating objects: 11, done.
Counting objects: 100% (11/11), done.
Delta compression using up to 8 threads
Compressing objects: 100% (5/5), done.
Writing objects: 100% (6/6), 671 bytes | 671.00 KiB/s, done.
Total 6 (delta 3), reused 3 (delta 1), pack-reused 0
To ssh://gitrepo.freebsd.org/ports.git
   23642082e10d..f190fc172c79  HEAD -> main
updating local tracking ref 'refs/remotes/freebsd/main'

$ git log
commit f190fc172c797a29e799f47373cf7004e30d2de8 (HEAD -> my-ports-changes, freebsd/main, freebsd/HEAD, main)
Author: Dave Cottlehuber <dch@FreeBSD.org>
Date:   Tue Apr 6 12:31:02 2021 +0000

    cat/foo: Update to v1.2.3

At this point, we Crossed The Rubicon. We're live. Not in Kansas. Adults. Congrats!

All we need to do now is clean up and go to the pub. Except COVID, so cup of tea.

• switch back to our original branch
• see what the branches are related to
• bring it up to date with FreeBSD origin
• remove our temporary branch

$ git switch main
Switched to branch 'main'
Your branch is up to date with 'freebsd/main'.

$ git remote -v && git branch -vv

freebsd	https://git.freebsd.org/ports.git (fetch)
freebsd	ssh://git@gitrepo.freebsd.org/ports.git (push)
* main             f190fc172c79 [freebsd/main] cat/foo: Update to v1.2.3
  my-ports-changes f190fc172c79 cat/foo: Update to v1.2.3

$ git pull --ff-only freebsd main
From https://git.freebsd.org/ports
 * branch                      main       -> FETCH_HEAD
Already up to date.

$ git branch -d my-ports-changes 
Deleted branch my-ports-changes (was f190fc172c79).

You'll notice above that, when we pulled changes from FreeBSD main into our main git didn't need to fetch anything – we already have all the changes locally, because we just pushed them up.

• 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

$ 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.