Introduction

This isn't intended to be comprehensive, as there are a LOT of resources out there on the web. That being said, there are some questions that we've found hard to easily answer. We partly address those here. Feel free to improve this topic.

For a quick start guide (possibly all you'll need in order to use git), and how to contribute, see the git-quick-start :doc topic:

http://www.cs.utexas.edu/users/moore/acl2/manuals/current/manual/?topic=ACL2____GIT-QUICK-START

Here's an excellent page on setting up SSH keys to work with github, so you can commit to your fork of ACL2 and then make pull requests:

https://gist.github.com/developius/c81f021eb5c5916013dc

Motivation

The killer features for us that motivated the switch to git are:

• Being able to easily copy changes from one checkout of a repository into another. No more use of mv, diff and patch, etc.

• Being able to save changes to a branch of a local repository, abandon the project for a good while by checking out the master branch again (leaving the changes out of the way in the modified branch), and then being able to easily pickup where we left off many weeks later. This saves disk space and also feels better from the perspective of keeping things tidy.

• Being able to easily review committed changes using gitk, without having to commit them to the shared repo.

We combined the ACL2 System and ACL2 books repositories into one so that we didn't have to worry about keeping different revision numbers in sync (svn externals does nothing to guarantee that revisions stay in sync, and git submodules are a mess). It also provides the illusion that the system and books combine to provide a coherent and usable whole, which is the community's viewpoint on how this technology should be presented.

Introductory Links

• Overview of the basic underlying machinery of git (will help you understand why things work the way they do): http://gitolite.com/gcs.html
• A very pretty intro to git http://rogerdudler.github.io/git-guide/
• A stackoverflow into: http://stackoverflow.com/questions/315911/git-for-beginners-the-definitive-practical-guide?rq=1
• A comprehensive cheat sheet: https://sites.google.com/site/conanyuan/git-cheatsheet

FAQ

• What should I put as my git "user name?" What about my git email address?

We recommend putting your normal name (e.g., "David L Rager") as your "git" user name. Note that this is intentionally different than your github user name. Github will use your email address to determine the github username associated with the commit, so you'll want to use your github account email address as your git email address.

git config --global user.email [email protected]
git config --global user.name "First M Last"

• What is gitk?

A tool for browsing the commits to your local repository. It shows diffs between commits, but see below for how to diff against your edits.

• Should I use git merge or git rebase?

Almost always use git merge. Rebasing is for use with git svn, which we fortunately no longer have to use, and for other obscure tasks.

• How do I clone via ssh?

https://stackoverflow.com/questions/6565357/git-push-requires-username-and-password

• How do I make it so I don't have to enter your password every time? You can use either a .netrc file or ssh keys. For .netrc information see the following two links: http://ithaca.arpinum.org/2010/10/14/fun-with-netrc.html; an example ~/.netrc file: https://gist.github.com/technoweenie/1072829

• How do I setup ssh keys?

https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys--2

• How do I squash commits?

Please be very careful when doing this, as you can really screw up the repository if you rebase commits that have already been pushed.

http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html

• How do I make git not ask me to hit enter when I do a git diff?

Set PAGER to cat in your environment, e.g.,

  export PAGER='cat'

• Is there a nice tool built-in to git for displaying diffs between what I've added/committed and my edits?

Yes! git difftool will automatically search for one of 10+ diff tools that work and use it. For an elaboration see http://stackoverflow.com/questions/255202/how-do-i-view-git-diff-output-with-a-visual-diff-program for more info.

• Is there a build server that shows the status of the builds for ACL2?

Defthm Consulting LLC maintains a server at http://leeroy.defthm.com. If you would like read or write access to that build server, please contact David Rager. It currently checks that ACL2(h) on CCL builds the manual, and that CCL and SBCL build the arithmetic-2 target (on all supported combinations of ACL2).

For people who commit a lot

• We have a build server that you can use to first make sure that your changes still allow the manual to build. Then, after the manual is successfully built, your changes will be automatically committed to the repository. If you are interested in taking advantage of this server, please contact David Rager.

Committing

See :doc topic git-quick-start for information on how to commit to the ACL2 books.