Contributing - Hintzelab/MABE GitHub Wiki

## Setting Up
    ## create an empty local mabe repository
        mkdir mabe
        cd mabe
        git init

    ## ensure user information is set up
        git config --list ## verify your name and email address
        ## otherwise, set it up, same as github account
        git config user.name "your name"
        git config user.email [email protected]

    ## get public MABE repo on to local machine
        ## Option A) as a public contributor (if you don't know, then do this one)
            git remote add public https://github.com/Hintzelab/MABE.git
            git fetch public

        ## Option B) as a core developer who works in the Hintzelab and has admin privileges
            git remote add public [email protected]:Hintzelab/MABE.git
            git fetch public

    ## get personal MABE or personal fork on to local machine (this can be an empty repo made on github)
        git remote add personal [email protected]:YOUR_USERNAME/MABE.git
        git fetch personal

    ## set up basic development branch
        git checkout -b development --track public/development

## Contributing
    ## Create a feature-, hotfix-*, etc. branch
        ## Start on development branch
        ## Example new world:
        git checkout -b feature-world-blockCooperation
        ## Example hotfix:
        git checkout -b hotfix-updateWikiLink

    ## Create desired changes

    ## Commit your changes in separable chunks if possible
        git add <list of files here>
        git commit -m “short summary message for this chunk”
        ## repeat as necessary for each chunk

    ## Ready to push to public, but first pull in latest development changes
        git checkout development              # switch to dev so next command works
        git pull public development           # updates your local copy of public/development
        git checkout YOUR-BRANCH-NAME         # switch back to your branch
        git merge development                 # bring into your branch any changes others have made
        ## (resolve conflicts, if any, as usual)
        ## repeat the above steps until there are no new changes

    ## Pushing your branch
        ## Option A) as public contributor
            git push personal HEAD ## back up on personal repo if desired at any time
            ## got to your github MABE fork and create a new pull request, but change the comparing branch to ‘development’

        ## Option B) as a core developer
            git push public HEAD
            ## go to https://github.com/Hintzelab/MABE and create a new pull request, but change the comparing branch to ‘development’

## Odds and ends
    ## Preserve history: When github merges branches, it uses the following command, which you should too if you perform a CLI merge
        git merge --no-ff otherBranchName

    ## If you are in the middle of changes (uncommitted changes) but must switch to a different branch to address a different issue, you can stash your changes temporarily:
        git stash save "in the middle of archivist revamp"
        ## now you can safely change branches, then come back to this branch later
        git stash pop
        ## the pop command optionally accepts which stash to pop, if you have to do this multiple times concurrently. Use ‘git stash list’ to see them all.

    ## get back to the unmodified version of file.cpp
        git checkout -- file.cpp

    ## unstage a staged file.cpp
        git reset file.cpp

    ## edit last committed commit message
        git commit --amend

    ## delete a branch
        git branch -d aBranch

    ## rename a branch
        git branch -m oldName newName

    ## push a branch to a specific name on the server (locally feature1, remotely feature-world-bixbee)
        git push public feature1:feature-world-bixbee

    ## delete a remote branch (on the server), “feature-world-bixbee”
        git push public :feature-world-bixbee

    ## adding a new library as a sub-repository
        ## Make sure licensing is okay :)
        ## Use git subtree (as opposed to submodule which would cause problems later)
        ## Your branch must be in a CLEAN state (no modified tracked files, nothing staged)
        git subtree add --prefix=local/clone/path/from/repo/base/here/ --squash https://github.com/someuser/somerepo master

    ## updating a subtree sub-repository
        ## Your branch must be in a CLEAN state (no modified tracked files, nothing staged)
        git subtree pull --prefix=local/clone/path/from/repo/base/here/ --squash https://github.com/someuser/somerepo master

    ## locally modifying the wiki (download the wiki through git clone; includes images)
        git clone https://github.com/Hintzelab/mabe.wiki
        ## Only changes in the master branch will be public

    ## squash previous commits into one (ex: merge small stupid commits into 1 clean)
        ## WARNING: never do this on a branch other people may be using
        git rebase -i HEAD~<number of commits to squash>
        ## if already on the remote, then you'll need to force it up
        git push --force public HEAD

    ## copy some commits X..Y to another branch (ex: to separate commits by topic)
        ## WARNING: never do this onto a branch other people may be using
        ## assuming all branches should be based on development, note commit hashes for X and Y first
        git checkout development
        git checkout -b someNewBranch
        git log  # Note the commit hash of most recent commit (M)
        git rebase --onto M <commit before X> <Y>
        git rebase HEAD someNewBranch