The following are guidelines for using the Git source tree.

For more information, see GitUsage.

For anonymous access:

git clone https://github.com/isc-projects/kea.git

We have a copy at GitHub: ​http://github.com/isc-projects/kea. github may be convenient if you plan to contribute your patches back to ISC. Our primary internal repo (git.kea.isc.org) is frequently synchronized to GitHub.

If you already have the repo checked out from our old anonymous git repo (that ceased to be publicly accessible around early 2016), you can switch it to use GitHub with:

git remote set-url origin https://github.com/isc-projects/kea.git

For ISC developers:

Retrieve the repo (replace username):

 git clone ssh://username@git.kea.isc.org/git/kea

All the branches will be retrieved. By default it will have the "master" checked out. Git uses label-based branches (instead of directories as branches).

Setup your username and email address:

 git config --global user.name "FirstName LastName"

 git config --global user.email "user@example.com"

(Or define in your environment: GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL, GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL.)

The remote branches can be listed with:

 git branch -r

You can switch to different branch with:

 git checkout BRANCHNAME

(TODO: write about editing a branch here.) To update all the remote branches:

 git fetch

To update plus merge the remote master branch with your current master:

 git pull

The "git pull" may create a new commit as it merges in remote changes with local changes. To temporarily remove your changes, switch the branch to the remote one and re-apply your changes, you can do:

 git pull --rebase

To share your changes:

  git commit FILENAME  # or use -a for all
  git push

Use a brief summary for the first line of the commit message (as it may be used for an email subject and in many situation in git). Start your first line with the branch name in square brackets. If you tend to forget this, we have some scripts you can use to automate this on GitTips.

The "git push" updates the remote repository.

Git revisions are SHA1 hashes (like 419182d7fb28cf1fcd63311f7596700c0d26e364).

To view a specific change:

 git show 6b5c87bc

Kea Premium content

ISC provides premium content for support customers. If you are a developer and would like to develop it, please refer our internal wiki content page KeaPremium. Sorry, no link from public wiki allowed.

Common practices for developers

• After merging a change set to master, add the full 160-bit SHA1 hash for the merge commit to the corresponding ChangeLog entry. e.g.:

    157.  [bug]       vorner
  	One frozen process no longer freezes the whole b10-msgq. It caused the
          whole system to stop working.
  	(Trac #420, git 93697f58e4d912fa87bc7f9a591c1febc9e0d139)
  

  In many cases some first few bits of the hash should be sufficiently unique, but for consistency we use the entire hash.

• When commiting a change for a particular trac ticket, add the corresponding ticket number to the beginning of the commit log. Example:

      [526] Implement returning CNAME
  

  This will help identify the branch point of that work in code review.

Common SVN replacements

These are aproximations at many places (git add serves more purposes than just adding new files, creation of new branch needs a little bit more to get remote, etc).

Task	svn way	git command(s)
Update local copy	svn up	git pull
View commit history	svn log | more	git log
Show working tree status	svn status	git status
Print differences	svn diff	git diff
Add file	svn add foo && svn commit	git add foo
Send local changes to remote repos	svn commit	git commit ; git push
Create branch	svn cp trunk new && cd new	git checkout -b new master
List tags	ls tags	git tag -l
List branches	ls branches	git branch -a