Git authors

Introduction

We need your help to contribute to this project!

If you are interested in moving your script in to the repository, please read through these options.

Github user setup

Create a free account at github

https://github.com/plans

Then go to

https://github.com/Pymol-Scripts/Pymol-script-repo

Near the top right corner, click: Fork

In the top left corner, it should now say: GIT_USER_NAME / Pymol-script-repo. This is your own repository.
Click HTTP in the middle. We will use this, and it should be like.

https://GIT_USER_NAME@github.com/GIT_USER_NAME/Pymol-script-repo.git

You also have to find your Github API-token for the acces.
Locate token at: Account settings -> Account admin -> API Token Configure git

0123456789yourf0123456789token

Online - make changes to a file

You can change a file online, by clicking it, and then at the right side, click Edit this file.
Make changes, write a "commit message", and in the lower right, click Commit changes.
If you want to your changes to be part of the official repository, click Pull Request, and write a message.
This will notify the group of admins to review your changes.
If the changes reasonable and not malicious for the computer, your Pull Request will quickly be in the official repository.
Note, that you can not add files online.

Git setup - Add scripts to the project

The next setup can be followed for both linux and windows users, if windows users use the Bash terminal.
You can paste from the wiki into the Bash window by using the console's window icon (topleft) and choosing Edit -> Paste

1. Navigate to C:/Users/YOURNAME/Documents/Pymol-script-repo OR /home/YOURNAME/Software/pymol/Pymol-script-repo
2. Win users: Right click in folder -> Select: Git Bash
3. Write in terminal

git config --global user.name "Your Name"
git config --global user.email you@example.com
git config --global github.user GIT_USER_NAME
git config --global github.token 0123456789yourf0123456789token
git remote set-url origin https://GIT_USER_NAME@github.com/GIT_USER_NAME/Pymol-script-repo.git
git remote add pymol https://GIT_USER_NAME@github.com/Pymol-Scripts/Pymol-script-repo.git

See your information

cat ~/.gitconfig
git branch
git remote show origin

Daily workflow

We now imagine that you would like to make a script called testscript.py. Remember that the filename should be with small letters, and without minus "-" in the name.
You will like to work on this script, and try it out, until its ready for sharing and make it public at the PyMOL wiki.

To follow the following guidelines, you can consider reading some other introduction pages to git.
Git commands, fork-a-repo, send-pull-requests

First we make branch where we will work with the script testscript.py. We will create the branch testscript, by making a copy of the master branch.

git branch                           # See what branches exist 
git checkout -b testscript master    # Make branch "testscript" from branch "master", and change into the branch "testscript"
git branch                           # The star mark you are in the "testscript" branch
git ls-tree --name-only testscript   # See which files are tracked

Then we create a first initial version of the file

(echo 'from pymol import cmd' && echo 'def testme():' && echo '    print("Hello world")' && echo 'cmd.extend("testme",testme)') > testscript.py

Then we want git to track the file, so we have to add the file. And we then commit it.

git status                           # testscript.py is untracked
git add testscript.py                # To start tracking the file
git status                           # testscript.py is added and staged. 
git commit -m "I added testscript"   # So, now you are done with the first thing.

Then start PyMOL, import the script and initiate the function testme

import testscript                    # To import the functions in the script
help(testscript)                     # To see the defined functions
testme                               # To activate the function. Is write "Hello world"

You then make some changes to your script.
After you have made some changes, you put your changes to the stage area, before you commit.

(echo 'from pymol import cmd' && echo 'def testme():' && echo '    print("Hello changes")' && echo 'cmd.extend("testme",testme)') > testscript.py
git status                           # To see that there has been a change
git stage testscript.py              # To add to stage area
git status                           # See info again
git commit -m "Updated print command"  # Change is now committed
git status                           # Nothing to report

---

Every time you do a change to your script, you stage and commit. Repeatedly through the progress.

git stage testscript.py 
git commit -m "Changed x,y,z"

---

Once you have work isolated in a branch, you will eventually want to incorporate it into your main branch. You can merge any branch into your current branch with the git merge command.

git checkout master                  # First go into the branch, in which you like to merge the changes to.
git branch                           # See branches
git ls-tree --name-only master       # See which files branch "master" is taking care of
git merge testscript                 # To merge into branch "master" from "testscript".
git ls-tree --name-only master       # Now branch "master" is also taking care of testscript.py 
git status                           # Nothing to report
git branch -d testscript             # We are done with the branch and delete it.

Now you want to push your changes to the remote repository at github.

git remote                           # List your aliases for remote repositories
git remote show origin               # List detailed information of the alias "origin".
git push origin master               # Push changes to your remote repository with alias "origin" from your branch "master"

You now want to make you new script part of the official repository by making a Pull request at the github page.

Make Pull request

Go to https://github.com/ and click "Dashboard" at the top.

Click your repository to the right. Click in the near top right "Pull request", and write a message what you have done.
This will notify the group of admins to review your changes.
If the changes reasonable and not malicious for the computer, your Pull Request will quickly be in the official repository.

PyMOL wiki guide lines

You now have to make description at the PyMOL wiki page.
Please read these guidelines, when you create a script PyMOL wiki page.

http://www.pymolwiki.org/index.php/git_script_guidelines

Get latest changes

To fetch the latest changes that happened in the remote official repository, write

git remote                                                                                                  # To see your defined alias for remotes
git remote add pymol https://GIT_USER_NAME@github.com/Pymol-Scripts/Pymol-script-repo.git  # Did you add the this remote?
git fetch pymol                                                                                             # Get from the alias pymol, the official repository
git log pymol/master ^master                                                                                # See the log message
git checkout pymol/master                                                                                   # Checkout the changes, try the script
git checkout master                                                                                         # Go back to master
git merge pymol/master                                                                                      # Merge in, and you are ready