add git

docs/setup/gitInstall.md

@@ -83,101 +83,90 @@ Ensure that you have a version greater than `2.15.0` installed.
 
 ## A short instruction for Git
 
-1. Configure
+### Before we start
 
-   In order to use Github locally, you can configure your user name and email of your Github account in local PC. In your terminal, you can type the following command to configure.
+- Configure
 
-   ```bash
-   # set the author name for your commits
-   git config --global user.name "[name]"
-
-   # set the author email for your commits
-   git config --global user.email "[email address]" 
-
-   # enables colorization for command line output 
-   git config --global color.ui auto
-   ```
+In order to use Github locally, you can configure your user name and email of your Github account in local PC. In your terminal, you can type the following command to configure.
 
-2. Create repositories
+```bash
+# set the author name for your commits
+git config --global user.name "[name]"
 
-   To start, you need to create a new repository once.You can create a local repository and then push to Github, or clone an existing repository from Github to your local PC.
+# set the author email for your commits
+git config --global user.email "[email address]" 
+```
 
-   ```bash
-   # create a git repository from a locally existing directory
-   git init
-
-   # clone an existing repository from Github to local PC
-   git clone "[url]"
-   ```
+When you finish the configuration, you can type `git config --list` to check the user information.
 
-3. Branches
+### A typical workflow
 
-   Branches are key tools for version control. Everyone can make changes to his own working branch, and merge their changes to a master branch. You can use `git status` to check your working branch.
+![git-cycle](git-cycle.png)
+
+1. Create a repository on Github
+
+   To start, you need to create a repository once. You can create a repository on Github and then clone to your local PC. Or you can fork other's repository and then clone to your local PC.
 
-   ``` bash
-   # create a branch [branch-name]
-   git branch [branch-name]
-
-   # switch to s specific branch [branch-name]
-   git checkout [branch-name]
-
-   # merge a specific branch [branch] to the working branch
-   git merge [branch]
 
-   # delete a specific branch [branch-name]
-   git branch -d [branch-name]
+
+   `New repository` or `fork other's repository` ->  copy `[email protected]:username/newrepository.git` -> go to the folder that you want to put the repository locally `cd localfolder` -> 
+
+   ```bash
+   # clone an existing repository from Github to local PC
+   git clone [email protected]:username/newrepository.git
    ```
 
-4. Make changes
+2. Commit local change
 
-   Everytime when you make changes to your project, you can use the following command to browse and inspect changes.
+   Each time when you change you programs, you can record snapshots permanently in version history, so that you can check every version in the future in case. **Commit Frequently!**
 
-   ``` bash
-   # list all version histories of current branch
-   git log
-
-   # present content differences between two branches [first-branch] vs [second-branch]
-   git diff [first-branch]...[second-branch]
-
-   # snapshot the file in preparation for versioning
-   git add [file]
-
+   ```bash
    # record file snapshots permanently in version history
    git commit -m "[descriptive message]"
    ```
 
-5. Sync
+   - You can use `git add filename`  to store your changed file to the stage first, so that git can save every change for further management.
+   - You can use `git status` to check the status of all your changes before `git commit`.
 
-   Everyone can sync their local changes with the remote repository on Github(usually the online master branch). You can also get changes to your local repository from the remote repository.
+3. Push to Github
 
-   ``` bash
-   # download all history from the remote tracking branches
-   git fetch
-
-   # combine remote tracking branch into current local branch
-   git merge
-
+   Since you are cooperating with coauthors, you can share your changes by uploading all local branch commits to GitHub. **Push Frequently!** But less frequent than `Commit`.
+
+   ```bash
    # upload all local branch commits to GitHub
    git push
-
-   # update your local working branch with all new commits from the remote branch on GitHub
-   # `git pull` is a combination of `git fetch` and `git merge`
-   git pull
    ```
 
-   ![Git](git.png)
+### If you prefer graphical UI
 
-6. Reset
+The typicla workflow can be realized by graphical *Github Desktop*. [Download GIthub Desktop](https://desktop.github.com).
 
-   You may want to reset your changes and replace them with historical version.
+- Log in your Github account
 
-   ``` bash
-   # undo all commits after [commit], preserving changes locally
-   git reset [commit]
-
-   # drop all history and changes back to the specified commit
-   git reset --hard [commit]
-   ```
+- `file`->`clone repository`->choose `repository` and `local path`, then `clone`
 
-   
+  ![](clonedesk.png)
 
+- `commit` with a description message on the down left, then `push` on the up right.
+
+  ![](pushdesk.png)
+
+
+
+### Branches for Cooperation
+
+Branches are key tools for version control. Every cooperator can make changes to his own working branch, and merge their changes to a master branch. You can use `git status` to check your working branch.
+
+``` bash
+  # create a branch [branch-name]
+  git branch [branch-name]
+
+  # switch to s specific branch [branch-name]
+  git checkout [branch-name]
+
+  # merge a specific branch [branch] to the working branch
+  git merge [branch]
+
+  # delete a specific branch [branch-name]
+  git branch -d [branch-name]
+```

docs/setup/perl.md

@@ -0,0 +1,70 @@
+# Installing Perl
+
+Perl is a proprietary statistical software frequently used by scientific users.
+First check with your local IT support whether your institution has Stata licenses
+available.
+
+
+## Making Stata Available on the Command Prompt
+
+You have just installed Stata. Later, we'd like to access Stata from the
+command prompt to automatically execute our source code. That way, you will
+be able to run a series of scripts in batch - which will significantly ease the burden of
+building complex data workflows.
+
+### Windows users
+For you to be able to use Stata from the command prompt, follow the steps below.
+
+!!! danger "Making Stata available via the PATH settings on Windows"
+    We need to update our PATH settings; these settings are a set of directories that Windows uses to "look up" software to startup.
+
+    - Right-click on Computer.
+    - Go to "Properties" and select the tab "Advanced System settings".
+    - Choose "Environment Variables" and select `Path` from the list of system variables.
+    - Choose `Edit`.
+    	- **Windows 7 and 8 machines:**
+    		If you chose the default installation directory, copy and paste the following string without spaces at the start or end:
+
+            `;c:\Program Files (x86)\Stata15`
+
+    	  Using a different Stata version? Change the version number then in the path above.
+
+    	- **Windows 10 machines:**
+    		- Click `New` and paste the following string:
+
+            `c:\Program Files (x86)\Stata15`
+
+    		- Click on `OK` as often as needed.
+
+### Mac users
+
+For you to be able to use Stata from the command line, you have to add Stata to your bash file. A tutorial follows.
+
+!!! danger "Making Stata available via the PATH settings on Mac"
+
+```
+Step 1: add Stata to bash file
+- Open `Terminal`.
+- Type `echo "export PATH=$PATH: Your Stata Path" >> ~/.bash_profile`. For example,
+		`export PATH=$PATH: /Applications/Stata/StataMP.app/Contents/MacOS/  >> ~/.bash_profile`
+
+Step 2: Evaluate bash changes
+- Type `echo $PATH` to check whether Stata is added to your path.
+```
+
+
+
+<!--- Linux users not available yet
+-->
+
+
+## Verifying that the installation was successful
+
+To verify that Stata has been correctly installed and configured via your PATH settings,
+open a **new** terminal interface and enter:
+
+```bash
+StataSE-64.exe
+```
+
+followed by hitting the `Return` key. Stata will now start.

docs/setup/stata.md

@@ -44,13 +44,14 @@ For you to be able to use Stata from the command line, you have to add Stata to
 !!! danger "Making Stata available via the PATH settings on Mac"
 
 ```
-Step 1: add Stata to bash file
-- Open `Terminal`.
-- Type `echo "export PATH=$PATH: Your Stata Path" >> ~/.bash_profile`. For example,
-		`export PATH=$PATH: /Applications/Stata/StataMP.app/Contents/MacOS/  >> ~/.bash_profile`
-
-Step 2: Evaluate bash changes
-- Type `echo $PATH` to check whether Stata is added to your path.
+- open Terminal
+- type `vi ~/.bash_profile`
+- add Stata so that it can be called in the command line
+	- type `i` to input mode of vim
+	- add `export STATA_BIN=/Applications/Stata/StataMP.app/Contents/MacOS/stataMP`. You may need to replace stataMP to stataSE or so, which depends on which Stata you install on Mac.
+	- press `esc` and type `:w` to save the change
+	- close the ternimal and reopen one terminal. Then type `source ~/.bash_profile` to bring the new .bash_profile into effect.
+- type `$STATA_BIN -v` to check availability. Remember to type the `$` before `STATA_BIN`. 
 ```
 
 

mkdocs.yml

@@ -1,47 +1,48 @@
 site_name: Reproducible Science and Programming Practices for Researchers
 nav:
-- Getting Started: index.md
-- Software Setup:
-  - Installation Guide Overview: setup/index.md
-  #- Terminology: setup/terminology.md
-  #- Command Line Tools: setup/commandLine.md
-  - R: setup/r.md
-  - Stata: setup/stata.md
-  - Git: setup/gitInstall.md
-  - Text Editor: setup/textEditor.md
-  - Python: setup/python.md
-  - Python Extras: setup/python-more.md
-  - Build Tools/Make:
-    - Why Build Tools?: setup/make-intro.md
-    - Automation with Make: setup/make.md
-#    - Automation with Waf: setup/waf.md
-    - Automation with Snakemake: setup/snakemake.md
-  - Webscraping: setup/webscraping_drivers.md
-  - Teamviewer: setup/teamviewer.md
-#  - Pandoc: setup/pandoc.md
+  - Getting Started: index.md
+  - Software Setup:
+      - Installation Guide Overview: setup/index.md
+      #- Terminology: setup/terminology.md
+      #- Command Line Tools: setup/commandLine.md
+      - R: setup/r.md
+      - Stata: setup/stata.md
+      - Perl: setup/perl.md
+      - Git: setup/gitInstall.md
+      - Text Editor: setup/textEditor.md
+      - Python: setup/python.md
+      - Python Extras: setup/python-more.md
+      - Build Tools/Make:
+          - Why Build Tools?: setup/make-intro.md
+          - Automation with Make: setup/make.md
+          #    - Automation with Waf: setup/waf.md
+          - Automation with Snakemake: setup/snakemake.md
+      - Webscraping: setup/webscraping_drivers.md
+      - Teamviewer: setup/teamviewer.md
+  #  - Pandoc: setup/pandoc.md
   # - Matlab: setup/matlab.md
   # - Path Settings: setup/path-setting.md
-- Project Setup and Workflow Management:
-  - Getting Started: workflow/index.md
-  - Module/Directory Structure: workflow/directories.md
-  #- Alternative module structure: workflow/directories_alt.md
-  - Automation: workflow/automation.md
-  - Documentation:
-    - Documentation of Code and Workflow: workflow/doc.md
-    - Documentation of New Data: workflow/doc_data.md
-    #- Overview:
-    #- Workflow in make: workflow/automation_workflow.md
-  #- Versioning: workflow/versioning.md
-  #- Data storage: workflow/data.md
-  #- Documentation: workflow/doc.md
-  #- Housekeeping: workflow/housekeeping.md
-  #- Portability: workflow/portability.md
-  - Checklist with Summary: workflow/checklist.md
-- Contact: contact.md
-- Acknowledgements: acknowledgement.md
+  - Project Setup and Workflow Management:
+      - Getting Started: workflow/index.md
+      - Module/Directory Structure: workflow/directories.md
+      #- Alternative module structure: workflow/directories_alt.md
+      - Automation: workflow/automation.md
+      - Documentation:
+          - Documentation of Code and Workflow: workflow/doc.md
+          - Documentation of New Data: workflow/doc_data.md
+        #- Overview:
+        #- Workflow in make: workflow/automation_workflow.md
+      #- Versioning: workflow/versioning.md
+      #- Data storage: workflow/data.md
+      #- Documentation: workflow/doc.md
+      #- Housekeeping: workflow/housekeeping.md
+      #- Portability: workflow/portability.md
+      - Checklist with Summary: workflow/checklist.md
+  - Contact: contact.md
+  - Acknowledgements: acknowledgement.md
 
 theme:
-  name: 'material'
+  name: "material"
 
 markdown_extensions:
   - admonition