GitHowTo

How to use git with Macaulay2

Install git, if necessary, by getting it here:

• http://git-scm.com/

The follow the instructions in one of the following two sections.

For non-package-developers

To get the source code of Macaulay2 if you are not a package developer, one "clones" our git repository with the following shell command:

• git clone https://github.com/Macaulay2/M2

The source code will appear in a directory called M2, which you may rename if you wish. In that directory you can find the following items of interest:

• The source code for the package Foo: the file M2/Macaulay2/packages/Foo.m2 and possibly the directory M2/Macaulay2/packages/Foo/ and its contents.
• The instructions for building Macaulay2: M2/INSTALL

For package developers

Start by "forking" the Macaulay2 repository, by following the following steps in a browser.

• Create a github account at https://github.com/ and log in to it.
  • We'll assume below that your user name is JohnDoe.
• Add your ssh key at https://github.com/settings/ssh
• Fork M2 at https://github.com/Macaulay2/M2/fork

Tell git what your name and email address are, for correct labelling of your updates, with shell commands like the following, except that the name and email address are replaced by yours.

• git config --global user.name "John Doe"
• git config --global user.email [email protected]

Then use the following shell command to get a copy of your copy of the source code of Macaulay2:

• git clone [email protected]:JohnDoe/M2

Now build Macaulay2 according to the instructions in M2/INSTALL and use the result in the following steps.

Edit and test your code. Whenever you want to send your changes to your local copy of M2, proceed as follows:

• Review the status of your files with
  • git status
• Review your changes, if necessary, with git diff
• Add the files whose changes are to be committed with git add FILENAME ...
• Commit the files to your local copy of the repository:
  • Issue the command git commit
  • An editor window will pop up in which you should type a message describing the changes, with this format:
    • First line is 50 characters or less
    • Then a blank line
    • Remaining text should be wrapped at 72 characters
• An alternative to the two steps above, if you are ready to commit all the files that you have changed, is git commit -a
• Push the commited changes to your fork of M2 at github: git push

Repeat at will. Whenever you want to send your changes to the central Macaulay2 repository, do this in a browser:

• Issue a pull request at https://github.com/JohnDoe/M2/pull/new/master, or find the pull request button on the page of your fork at https://github.com/JohnDoe/M2.

To import the latest changes from the Macaulay2 repository into your repository and try to merge your code with them, use:

• git pull https://github.com/Macaulay2/M2 master

To import the latest changes from the Macaulay2 repository into your repository without trying to merge your code with them, use:

• git fetch https://github.com/Macaulay2/M2

To display the history of your changes graphically, use this command:

• gitk

To show the history of all of your branches and any branches imported from the Macaulay2 repository, use:

• gitk --all

Other links:

• Learn all about how to use git by reading the book at http://git-scm.com/book.
• Magit, a useful emacs mode for performing many of the operations above: https://github.com/magit/magit.
• Learn git by trying it out on someone else's machine: https://try.github.io