first

buildroot/share/git/README.md

@@ -0,0 +1,59 @@
+## Marlin Github Helper Scripts
+
+### Introduction
+
+A Pull Request is often just the start of a longer process of patching and refining the code until it's ready to merge. In that process it's common to accumulate a lot of commits, some of which are non-functional. Before merging any PR, excess commits need to be "squashed" and sometimes rearranged or reworked to produce a well-packaged set of changes and keep the commit history relatively clean.
+
+In addition, while a PR is being worked on other commits may be merged, leading to conflicts that need resolution. For this reason, it's a best practice to periodically refresh the PR so the working copy closely reflects the final merge into upstream `MarlinFirmware`.
+
+#### Merge vs Rebase
+
+If you plan to create PRs and work on them after submission I recommend not using Github Desktop to sync and merge. Use the command line instead. Github Desktop provides a "merge" option, but I've found that "`git rebase`" is much cleaner and easier to manage. Merge applies new work _after_ your commits, which buries them deeper in the commit history and makes it hard to bring them together as a final packaged unit. Rebase helpfully moves your commits to the tip of the branch, ensuring that your commits are adapted to the current code. This makes it easier to keep revising the commits in-place.
+
+### The Scripts
+
+The following scripts can be used on any system with a GNU environment to speed up the process of working with Marlin branches and submitting changes to the project.
+
+#### Remotes
+
+File|Description
+----|-----------
+mfadd [user]|Add and Fetch Remote - Add another Github user's fork of Marlin as a remote, then fetch it. Optionally, check out one of their branches.
+mfinit|Init Working Copy - Create a remote named '`upstream`' (for use by the other scripts) pointing to the '`MarlinFirmware`' fork. This only needs to be used once. Newer versions of Github Desktop may create `upstream` on your behalf.
+
+#### Branches
+
+File|Description
+----|-----------
+mfnew [branch]|New Branch - Creates a new branch based on `upstream/[PR-target]`. All new work should start with this command.
+mffp|Fast Push - Push the HEAD or a commit ID to `upstream` immediately. Requires privileged access to the MarlinFirmware repo.
+firstpush|Push the current branch to 'origin' -your fork on Github- and set it to track '`origin`'. The branch needs to reside on Github before you can use it to make a PR.
+
+#### Making / Amending PRs
+
+File|Description
+----|-----------
+mfpr|Pull Request - Open the Compare / Pull Request page on Github for the current branch.
+mfrb|Do a `git rebase` then `git rebase -i` of the current branch onto `upstream/[PR-target]`. Use this to edit your commits anytime.
+mfqp|Quick Patch - Commit all current changes as "patch", then do `mfrb`, followed by `git push -f` if no conflicts need resolution.
+
+#### Documentation
+
+File|Description
+----|-----------
+mfdoc|Build the documentation and preview it locally.
+mfpub|Build the documentation and publish it to marlinfw.org via Github.
+
+#### Utilities
+
+File|Description
+----|-----------
+ghtp -[h/s]|Set the protocol to use for all remotes. -h for HTTPS, -s for SSL.
+mfinfo|This utility script is used by the other scripts to get:<br/>- The upstream project ('`MarlinFirmware`')<br/>- the '`origin`' project (i.e., your Github username),<br/>- the repository name ('`Marlin`'),<br/>- the PR target branch ('`bugfix-1.1.x`'), and<br/>- the current branch (or the first command-line argument).<br/><br/>By itself, `mfinfo` simply prints these values to the console.
+mfclean&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|Prune your merged and remotely-deleted branches.
+
+---
+
+### Examples
+
+Coming Soon!

buildroot/share/git/firstpush

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+#
+# firstpush
+#
+# Push a branch to 'origin' and open the
+# commit log to watch Travis CI progress.
+#
+
+[[ $# == 0 ]] || { echo "Usage: `basename $0`" 1>&2 ; exit 1; }
+
+MFINFO=$(mfinfo) || exit 1
+IFS=' ' read -a INFO <<< "$MFINFO"
+FORK=${INFO[1]}
+REPO=${INFO[2]}
+BRANCH=${INFO[5]}
+
+git push --set-upstream origin $BRANCH
+
+TOOL=$(which gnome-open xdg-open open | awk '{ print $1 }')
+URL="https://github.com/$FORK/$REPO/commits/$BRANCH"
+
+if [ -z "$TOOL" ]; then
+  echo "Can't find a tool to open the URL:"
+  echo $URL
+else
+  echo "Viewing commits on $BRANCH..."
+  "$TOOL" "$URL"
+fi

buildroot/share/git/ghtp

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+#
+# ghtp (GitHub Transport Protocol)
+#
+# Set all remotes in the current repo to HTTPS or SSH connection.
+# Useful when switching environments, using public wifi, etc.
+#
+
+GH_SSH="git@github\.com:"
+GH_HTTPS="https:\/\/github\.com\/"
+
+case "$1" in
+  -[Hh]) TYPE=HTTPS ; MATCH="git@" ; FORMULA="$GH_SSH/$GH_HTTPS" ;;
+  -[Ss]) TYPE=SSH ; MATCH="https:" ; FORMULA="$GH_HTTPS/$GH_SSH" ;;
+  *)
+    echo "Usage: `basename $0` -h | -s" 1>&2
+    echo -e " \e[0;92m-h\e[0m to switch to HTTPS" 1>&2
+    echo -e " \e[0;92m-s\e[0m to switch to SSH" 1>&2
+    exit 1
+    ;;
+esac
+
+REMOTES=$(git remote -v | egrep "\t$MATCH" | gawk '{print $1 " " $2}' | sort -u | sed  "s/$FORMULA/")
+
+if [[ -z $REMOTES ]]; then
+  echo "Nothing to do." ; exit
+fi
+
+echo "$REMOTES" | xargs -n2 git remote set-url
+
+echo -n "Remotes set to $TYPE: "
+echo "$REMOTES" | gawk '{printf "%s ", $1}'
+echo

buildroot/share/git/mfadd

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+#
+# mfadd
+#
+# Add a remote and fetch it. Optionally copy a branch.
+#
+# Example: mfadd thinkyhead:patch-1 copy_of_patch-1
+#
+
+[[ $# > 0 && $# < 3 && $1 != "-h" && $1 != "--help" ]] || { echo "Usage: `basename $0` (user | ref copyname)" 1>&2 ; exit 1; }
+
+# If a colon is included, split the parts
+if [[ $1 =~ ":" ]]; then
+  IFS=':' read -a DATA <<< "$1"
+  USER=${DATA[0]}
+  BRANCH=${DATA[1]}
+  NAME=$2
+else
+  USER=$1
+fi
+
+MFINFO=$(mfinfo) || exit 1
+IFS=' ' read -a INFO <<< "$MFINFO"
+REPO=${INFO[2]}
+
+set -e
+
+echo "Adding and fetching $USER..."
+git remote add "$USER" "git@github.com:$USER/$REPO.git" >/dev/null 2>&1 || echo "Remote exists."
+git fetch "$USER"
+
+[[ ! -z "$BRANCH" && ! -z "$NAME" ]] && git checkout $USER/$BRANCH -b $NAME

buildroot/share/git/mfclean

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+#
+# mfclean
+#
+# Prune all your merged branches and any branches whose remotes are gone
+# Great way to clean up your branches after messing around a lot
+#
+
+KEEP="RC|RCBugFix|dev|master|bugfix-1|bugfix-2"
+
+echo "Fetching latest upstream and origin..."
+git fetch upstream
+git fetch origin
+echo
+
+echo "Pruning Merged Branches..."
+git branch --merged | egrep -v "^\*|$KEEP" | xargs -n 1 git branch -d
+echo
+
+echo "Pruning Remotely-deleted Branches..."
+git branch -vv | egrep -v "^\*|$KEEP" | grep ': gone]' | gawk '{print $1}' | xargs -n 1 git branch -D
+echo
+
+# List fork branches that don't match local branches
+echo "You may want to remove (or checkout) these refs..."
+comm -23 \
+  <(git branch --all | sed 's/^[\* ] //' | grep origin/ | grep -v "\->" | awk '{ print $1; }' | sed 's/remotes\/origin\///') \
+  <(git branch --all | sed 's/^[\* ] //' | grep -v remotes/ | awk '{ print $1; }') \
+  | awk '{ print "git branch -d -r origin/" $1; print "git checkout origin/" $1 " -b " $1; print ""; }'
+echo

buildroot/share/git/mfdoc

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+#
+# mfdoc
+#
+# Start Jekyll in watch mode to work on Marlin Documentation and preview locally
+#
+
+[[ $# == 0 ]] || { echo "Usage: `basename $0`" 1>&2 ; exit 1; }
+
+MFINFO=$(mfinfo "$@") || exit 1
+IFS=' ' read -a INFO <<< "$MFINFO"
+ORG=${INFO[0]}
+REPO=${INFO[2]}
+BRANCH=${INFO[5]}
+
+[[ $ORG == "MarlinFirmware" && $REPO == "MarlinDocumentation" ]] || { echo "Wrong repository." 1>&2; exit 1; }
+
+opensite() {
+  TOOL=$(which gnome-open xdg-open open | awk '{ print $1 }')
+  URL="http://127.0.0.1:4000/"
+  if [ -z "$TOOL" ]; then
+    echo "Can't find a tool to open the URL:"
+    echo $URL
+  else
+    echo "Opening preview site in the browser..."
+    "$TOOL" "$URL"
+  fi
+}
+
+echo "Previewing MarlinDocumentation..."
+
+# wait to open the url for about 8s
+( sleep 45; opensite ) &
+
+bundle exec jekyll serve --watch --incremental

buildroot/share/git/mffp

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+#
+# mffp
+#
+# Push the given commit (or HEAD) upstream immediately.
+# By default: `git push upstream HEAD:bugfix-1.1.x`
+#
+
+[[ $# < 3 && $1 != "-h" && $1 != "--help" ]] || { echo "Usage: `basename $0` [1|2] [commit-id]" 1>&2 ; exit 1; }
+
+if [[ $1 == '1' || $1 == '2' ]]; then
+  MFINFO=$(mfinfo "$1") || exit 1
+  REF=${2:-HEAD}
+else
+  MFINFO=$(mfinfo) || exit 1
+  REF=${1:-HEAD}
+fi
+
+IFS=' ' read -a INFO <<< "$MFINFO"
+ORG=${INFO[0]}
+TARG=${INFO[3]}
+
+if [[ $ORG == "MarlinFirmware" ]]; then
+  git push upstream $REF:$TARG
+else
+  echo "Not a MarlinFirmware working copy."; exit 1
+fi

buildroot/share/git/mfinfo

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+#
+# mfinfo
+#
+# Provide the following info about the working directory:
+#
+#   - Remote (upstream) Org name (MarlinFirmware)
+#   - Remote (origin) Org name (your Github username)
+#   - Repo Name (Marlin, MarlinDev, MarlinDocumentation)
+#   - PR Target branch (bugfix-1.1.x, bugfix-2.0.x, or master)
+#   - Branch Arg (the branch argument or current branch)
+#   - Current Branch
+#
+
+usage() {
+  echo "Usage: `basename $0` [1|2] [branch]" 1>&2
+}
+
+[[ $# < 3 && $1 != "-h" && $1 != "--help" ]] || { usage; exit 1; }
+
+CURR=$(git branch 2>/dev/null | grep ^* | sed 's/\* //g')
+[[ -z $CURR ]] && { echo "No git repository here!" 1>&2 ; exit 1; }
+[[ $CURR == "(no"* ]] && { echo "Git is busy with merge, rebase, etc." 1>&2 ; exit 1; }
+
+REPO=$(git remote get-url upstream 2>/dev/null | sed -E 's/.*\/(.*)\.git/\1/')
+[[ -z $REPO ]] && { echo "`basename $0`: No 'upstream' remote found. (Did you run mfinit?)" 1>&2 ; exit 1; }
+
+ORG=$(git remote get-url upstream 2>/dev/null | sed -E 's/.*[\/:](.*)\/.*$/\1/')
+[[ $ORG == MarlinFirmware ]] || { echo "`basename $0`: Not a Marlin repository." 1>&2 ; exit 1; }
+
+case "$REPO" in
+  Marlin              ) TARG=bugfix-1.1.x ;
+                        [[ $# > 0 ]] && [[ $1 == 2 ]] && TARG=bugfix-2.0.x
+                        ;;
+  MarlinDocumentation ) TARG=master ;;
+esac
+
+FORK=$(git remote get-url origin 2>/dev/null | sed -E 's/.*[\/:](.*)\/.*$/\1/')
+
+# BRANCH can be given as the last argument
+case "$#" in
+  0 ) BRANCH=$CURR ;;
+  1 )
+    case "$1" in
+      1|2) BRANCH=$CURR ;;
+      *) BRANCH=$1 ;;
+    esac
+    ;;
+  2 )
+    case "$1" in
+      1|2) BRANCH=$2 ;;
+      *) usage ; exit 1 ;;
+    esac
+    ;;
+esac
+
+echo "$ORG $FORK $REPO $TARG $BRANCH $CURR"

buildroot/share/git/mfinit

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+#
+# mfinit
+#
+# Create the upstream remote for a forked repository
+#
+
+[[ $# == 0 ]] || { echo "Usage: `basename $0`" 1>&2 ; exit 1; }
+
+[[ -z $(git branch 2>/dev/null | grep ^* | sed 's/\* //g') ]] && { echo "No git repository here!" 1>&2 ; exit 1; }
+
+REPO=$(git remote get-url origin 2>/dev/null | sed -E 's/.*\/(.*)\.git/\1/')
+[[ -z $REPO ]] && { echo "`basename $0`: No 'origin' remote found." 1>&2 ; exit 1; }
+
+echo "Adding 'upstream' remote for convenience."
+git remote add upstream "git@github.com:MarlinFirmware/$REPO.git"
+git fetch upstream

buildroot/share/git/mfnew

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+#
+# mfnew
+#
+# Create a new branch from the default target with the given name
+#
+
+usage() {
+  echo "Usage: `basename $0` [1|2] [name]" 1>&2
+}
+
+[[ $# < 3 && $1 != "-h" && $1 != "--help" ]] || { usage; exit 1; }
+
+MFINFO=$(mfinfo "$@") || exit 1
+IFS=' ' read -a INFO <<< "$MFINFO"
+TARG=${INFO[3]}
+BRANCH=pr_for_$TARG-$(date +"%G-%m-%d_%H.%M.%S")
+
+# BRANCH can be given as the last argument
+case "$#" in
+  1 ) case "$1" in
+        1|2) ;;
+        *) BRANCH=$1 ;;
+      esac
+      ;;
+  2 ) case "$1" in
+        1|2) BRANCH=$2 ;;
+        *) usage ; exit 1 ;;
+      esac
+      ;;
+esac
+
+git fetch upstream
+git checkout --no-track upstream/$TARG -b $BRANCH

buildroot/share/git/mfpr

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+#
+# mfpr
+#
+# Make a PR of the current branch against RCBugFix or dev
+#
+
+[[ $# < 2 && $1 != "-h" && $1 != "--help" ]] || { echo "Usage: `basename $0` [branch]" 1>&2 ; exit 1; }
+
+MFINFO=$(mfinfo "$@") || exit 1
+IFS=' ' read -a INFO <<< "$MFINFO"
+ORG=${INFO[0]}
+FORK=${INFO[1]}
+REPO=${INFO[2]}
+TARG=${INFO[3]}
+BRANCH=${INFO[4]}
+OLDBRANCH=${INFO[5]}
+
+[[ $BRANCH == $TARG ]] && { echo "Can't create a PR from the PR Target ($BRANCH). Make a copy first." 1>&2 ; exit 1; }
+
+[[ $BRANCH != $OLDBRANCH ]] && { git checkout $BRANCH || exit 1; }
+
+# See if it's been pushed yet
+if [ -z "$(git branch -vv | grep ^\* | grep \\[origin)" ]; then firstpush; fi
+
+TOOL=$(which gnome-open xdg-open open | awk '{ print $1 }')
+URL="https://github.com/$ORG/$REPO/compare/$TARG...$FORK:$BRANCH?expand=1"
+
+if [ -z "$TOOL" ]; then
+  echo "Can't find a tool to open the URL:"
+  echo $URL
+else
+  echo "Opening a New PR Form..."
+  "$TOOL" "$URL"
+fi
+
+[[ $BRANCH != $OLDBRANCH ]] && git checkout $OLDBRANCH

buildroot/share/git/mfpub

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+#
+# mfpub
+#
+# Use Jekyll to generate Marlin Documentation, which is then
+# git-pushed to Github to publish it to the live site.
+# This publishes the current branch, and doesn't force
+# changes to be pushed to the 'master' branch. Be sure to push
+# any permanent changes to 'master'.
+#
+
+[[ $# < 2 && $1 != "-h" && $1 != "--help" ]] || { echo "Usage: `basename $0` [branch]" 1>&2 ; exit 1; }
+
+MFINFO=$(mfinfo "$@") || exit 1
+IFS=' ' read -a INFO <<< "$MFINFO"
+ORG=${INFO[0]}
+FORK=${INFO[1]}
+REPO=${INFO[2]}
+TARG=${INFO[3]}
+BRANCH=${INFO[4]}
+
+if [[ $ORG != "MarlinFirmware" || $REPO != "MarlinDocumentation" ]]; then
+  echo "Wrong repository."
+  exit
+fi
+
+# Check out the named branch (or stay in current)
+git checkout $BRANCH
+
+if [[ $BRANCH == "gh-pages" ]]; then
+  echo "Can't build from 'gh-pages.' Only the Jekyll branches (based on 'master')."
+  exit
+fi
+
+echo "Stashing any changes to files..."
+echo "Don't forget to update and push 'master'!"
+# GOJF Card
+[[ $(git stash) != "No local "* ]] && HAS_STASH=1
+
+COMMIT=$( git log --format="%H" -n 1 )
+
+# Clean out changes and other junk in the branch
+git clean -d -f
+
+# Push 'master' to the fork and make a proper PR...
+if [[ $BRANCH == "master" ]]; then
+
+  # Don't lose upstream changes!
+  git fetch upstream
+
+  # Rebase onto latest master
+  if git rebase upstream/master; then
+
+    # Allow working directly with the main fork
+    echo
+    echo -n "Pushing to origin/master... "
+    git push -f origin
+
+    echo
+    echo -n "Pushing to upstream/master... "
+    git push -f upstream
+
+  else
+
+    echo "Merge conflicts? Stopping here."
+    exit
+
+  fi
+
+else
+
+  if [ -z "$(git branch -vv | grep ^\* | grep \\[origin)" ]; then
+    firstpush
+  else
+    echo
+    echo -n "Pushing to origin/$BRANCH... "
+    git push -f origin
+  fi
+
+  TOOL=$(which gnome-open xdg-open open | awk '{ print $1 }')
+  URL="https://github.com/$ORG/$REPO/compare/$TARG...$FORK:$BRANCH?expand=1"
+
+  if [ -z "$TOOL" ]; then
+    echo "Can't find a tool to open the URL:"
+    echo $URL
+  else
+    echo "Opening a New PR Form..."
+    "$TOOL" "$URL"
+  fi
+
+fi
+
+# Uncomment to compress the final html files
+# mv ./_plugins/jekyll-press.rb-disabled ./_plugins/jekyll-press.rb
+# bundle install
+
+echo
+echo "Generating MarlinDocumentation..."
+
+# build the site statically and proof it
+bundle exec jekyll build --profile --trace --no-watch
+bundle exec htmlproofer ./_site --only-4xx --allow-hash-href --check-favicon --check-html --url-swap ".*marlinfw.org/:/"
+
+# Sync the built site into a temporary folder
+TMPFOLDER=$( mktemp -d )
+rsync -av _site/ ${TMPFOLDER}/
+
+# Clean out changes and other junk in the branch
+git reset --hard
+git clean -d -f
+
+# Copy built-site into the gh-pages branch
+git checkout gh-pages
+rsync -av ${TMPFOLDER}/ ./
+
+# Commit and push the new live site directly
+git add --all
+git commit --message "Built from ${COMMIT}"
+git push upstream
+
+# remove the temporary folder
+rm -rf ${TMPFOLDER}
+
+# Go back to the branch we started from
+git checkout $BRANCH
+
+[[ $HAS_STASH == 1 ]] && git stash pop

buildroot/share/git/mfqp

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+#
+# mfqp
+#
+# Add all changed files, commit as "patch", do `mfrb` and `git push -f`
+#
+
+[[ $# < 2 && $1 != "-h" && $1 != "--help" ]] || { echo "Usage: `basename $0` [1|2]" 1>&2 ; exit 1; }
+
+MFINFO=$(mfinfo "$@") || exit 1
+IFS=' ' read -a INFO <<< "$MFINFO"
+REPO=${INFO[2]}
+TARG=${INFO[3]}
+CURR=${INFO[5]}
+
+git add .
+git commit -m "patch"
+
+if [[ $CURR == $TARG ]]; then
+  if [[ $REPO == "MarlinDocumentation" ]]; then
+    git rebase -i HEAD~2 && git push -f
+  else
+    echo "Don't alter the PR Target branch."; exit 1
+  fi
+else
+  mfrb "$@" && git push -f
+fi

buildroot/share/git/mfrb

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+#
+# mfrb
+#
+# Do "git rebase -i" against the "target" branch (bugfix-1.1.x, bugfix-2.0.x, or master)
+#
+
+[[ $# < 2 && $1 != "-h" && $1 != "--help" ]] || { echo "Usage: `basename $0` [1|2]" 1>&2 ; exit 1; }
+
+MFINFO=$(mfinfo "$@") || exit 1
+IFS=' ' read -a INFO <<< "$MFINFO"
+TARG=${INFO[3]}
+CURR=${INFO[5]}
+
+# If the branch isn't currently the PR target
+if [[ $TARG != $CURR ]]; then
+  git fetch upstream
+  git rebase upstream/$TARG && git rebase -i upstream/$TARG
+fi

buildroot/share/git/mfup

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+#
+# mfup
+#
+# - Fetch latest upstream and replace the PR Target branch with
+# - Rebase the (current or specified) branch on the PR Target
+# - Force-push the branch to 'origin'
+#
+
+[[ $# < 3 && $1 != "-h" && $1 != "--help" ]] || { echo "Usage: `basename $0` [1|2] [branch]" 1>&2 ; exit 1; }
+
+MFINFO=$(mfinfo "$@") || exit 1
+IFS=' ' read -a INFO <<< "$MFINFO"
+ORG=${INFO[0]}
+FORK=${INFO[1]}
+REPO=${INFO[2]}
+TARG=${INFO[3]}
+BRANCH=${INFO[4]}
+CURR=${INFO[5]}
+
+set -e
+
+# Prevent accidental loss of current changes
+[[ $(git stash) != "No local "* ]] && HAS_STASH=1
+
+echo "Fetching upstream ($ORG/$REPO)..."
+git fetch upstream
+
+if [[ $BRANCH != $TARG ]]; then
+  echo ; echo "Rebasing $BRANCH on $TARG..."
+  if [[ $BRANCH == $CURR ]] || git checkout $BRANCH; then
+    if git rebase upstream/$TARG; then
+      git push -f
+    else
+      echo "Looks like merge conflicts. Stopping here."
+      exit
+    fi
+  else
+    echo "No such branch!"
+  fi
+else
+  git reset --hard upstream/$TARG
+fi
+
+echo
+[[ $BRANCH != $CURR ]] && git checkout $CURR
+
+[[ $HAS_STASH == 1 ]] && git stash pop