wiki:GitGuidelines

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

Tasksvn waygit command(s)
Update local copysvn upgit pull
View commit historysvn log | moregit log
Show working tree statussvn statusgit status
Print differencessvn diffgit diff
Add filesvn add foo && svn commit git add foo
Send local changes to remote repossvn commitgit commit ; git push
Create branchsvn cp trunk new && cd newgit checkout -b new master
List tagsls tagsgit tag -l
List branchesls branchesgit branch -a
Last modified 9 months ago Last modified on Nov 2, 2016, 9:04:54 PM