├── vim-notes.pdf
├── .github
    └── workflows
    │   ├── markdownlinks.yml
    │   └── markdownlint.yml
├── README.md
├── ssh.md
├── submission.md
├── login.md
├── valgrind.md
├── .markdownlint.yaml
└── git.md


/vim-notes.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/cs3157-borowski/guides/HEAD/vim-notes.pdf


--------------------------------------------------------------------------------
/.github/workflows/markdownlinks.yml:
--------------------------------------------------------------------------------
 1 | name: Check Links
 2 | 
 3 | on:
 4 |   push:
 5 |     branches: [ main ]
 6 |   pull_request:
 7 |     branches: [ main ]
 8 |   schedule:
 9 |     - cron: "0 7 * * *"
10 | 
11 | jobs:
12 |   markdown-link-check:
13 |     runs-on: ubuntu-latest
14 |     steps:
15 |       - uses: actions/checkout@master
16 |       - uses: gaurav-nelson/github-action-markdown-link-check@v1
17 |         with:
18 |           use-verbose-mode: "yes"
19 |           folder-path: "./"


--------------------------------------------------------------------------------
/.github/workflows/markdownlint.yml:
--------------------------------------------------------------------------------
 1 | name: Lint Markdown
 2 | 
 3 | on:
 4 |   push:
 5 |     branches: [ main ]
 6 |   pull_request:
 7 |     branches: [ main ]
 8 | 
 9 | jobs:
10 |   lint-changelog:
11 |     name: Lint Markdown
12 |     runs-on: ubuntu-latest
13 |     steps:
14 |     - name: Check out code
15 |       uses: actions/checkout@v2
16 | 
17 |     - name: Lint changelog file
18 |       uses: docker://avtodev/markdown-lint:v1
19 |       with:
20 |         config: './.markdownlint.yaml'
21 |         args: './'
22 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # COMS 3157 Guides
 2 | 
 3 | This repository is a collection of guides for Advanced Programming (COMS 3157)
 4 | developed by the TAs for Prof. Brian Borowski's offering of the course.
 5 | 
 6 | 
 7 | ## Programming Enviroment
 8 | 
 9 | - [Login](login.md): Introduction and access to the BB server.
10 | - [SSHing into bb](ssh.md): setup ssh keys to login to BB server without password.
11 | - [Git](git.md): Introduction to Git.
12 | - [Vim](vim-notes.pdf): Vim Guide
13 | - [Valgrind](valgrind.md): Understanding Valgrind Messages
14 | - [Submission Clarifications](submission.md): Confirming your HW Submissions
15 | 


--------------------------------------------------------------------------------
/ssh.md:
--------------------------------------------------------------------------------
 1 | # SSHing into bb
 2 | 
 3 | Are you tired of entering your password to log into bb? If so, you’ll want to set up your SSH keys so that you can authenticate without a password. This is highly recommended.
 4 | 
 5 | First, if you haven’t already, generate an Ed25519 key pair on your local machine and add it to your ssh-agent following this [excellent guide by GitHub](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). And while you’re at it, [add your key to your GitHub account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account). This is necessary for authenticating with GitHub since it no longer supports authenticating over HTTPS.
 6 | 
 7 | Now that you have a public key, you can pass it to bb to authenticate logins from your local machine. Assuming that you named your Ed25519 key pair `id_ed25519` (the default), run the following command:
 8 | 
 9 | ```
10 | [local-computer]$ ssh-copy-id <UNI>@bb.cs.columbia.edu
11 | ```
12 | 
13 | At this point, you’ll be able to SSH into bb without being prompted for your password.
14 | 
15 | If you’re interested in GitHub SSH authentication, you’ll want to forward your host’s SSH credentials to bb. This enables you to authenticate with GitHub without entering your password or copying your private key.
16 | 
17 | First, let’s create our SSH `config` file if we haven’t already:
18 | 
19 | ```
20 | [local-computer]$ mkdir -p ~/.ssh
21 | [local-computer]$ touch ~/.ssh/config
22 | ```
23 | 
24 | Here are two configuration options that you can put in `~/.ssh/config` using your favorite text editor:
25 | 
26 | **Specific Rule (Recommended)**
27 | 
28 | ```
29 | Host bb
30 |     HostName bb.cs.columbia.edu
31 |     User <UNI>
32 |     ForwardAgent yes
33 |     AddKeysToAgent yes
34 | ```
35 | 
36 | **Blanket Rule (Not recommended)**
37 | 
38 | ```
39 | Host *
40 |     ForwardAgent yes
41 |     AddKeysToAgent yes
42 | ```
43 | 
44 | This says that for any host you SSH into successfully, forward your credentials. Note that if you decide to do this, you should be careful to only SSH into trusted machines. We avoid having to deal with specifying the target machine’s information by bbplying this blanket rule.
45 | 
46 | After adding one of the two above configurations, you’ll then be able to SSH into bb with the following shorter command:
47 | 
48 | ```
49 | [local-computer]$ ssh bb
50 | ```
51 | 


--------------------------------------------------------------------------------
/submission.md:
--------------------------------------------------------------------------------
 1 | # Submission Clarifications
 2 | 
 3 | The teaching staff noticed that there were a lot of discrepancies between the work that students thought they submitted and what the teaching staff received to grade. The TAs will only grade the code in your main branch, and **unfortunately we can't make any exceptions to this rule**; however, we want to ensure that you get credited for all the work you do in the future, and you have necessary skillset to obtain a good score in the homework assignments which goes beyond just coding skill.
 4 | 
 5 | Let's review the tools you already know about, that will help you ensure that:
 6 | 
 7 | 1. All your code is in the main branch.
 8 | 2. Your directory structure is correct.
 9 | 3. You have the necessary amount of commits.
10 | 4. Your code will compile when TAs are grading.
11 | 
12 | ## The main branch
13 | 
14 | After you have pushed to GitHub, an easy way to ensure that all your work has properly been committed is to go to the Github website an open your repo. Please double check that the files listed reflect what you want the TA's to see.
15 | 
16 | ## Directory structure
17 | 
18 | The README for all homeworks will provide the expected directory structure of the submission. For example in HW2, the structure was as follows:
19 | 
20 | ```
21 | part1
22 |     \_ src
23 |         \_ recursive.h
24 |         \_ recursive.c
25 |         \_ iterative.h
26 |         \_ iterative.c
27 |         \_ gcd.c
28 |         \_ Makefile
29 |     \_ instructions.md
30 | part2
31 |     \_ src
32 |         \_ convert.c
33 |         \_ Makefile
34 |     \_ instructions.md
35 | README.md
36 | ```
37 | 
38 | If you recall, the tree command will actually produce a very similar output, so after you are satisfied with your work and have pushed it, you should run the following sequence of commands to verify your directory structure is as expected.
39 | 
40 | First, get a clean copy of your repo, by using the clone command with the correct homework number and team number:
41 | 
42 | ```
43 | git clone git@github.com:cs3157-borowski-s23/hw1-0 ~/cs3157/hw1-submission
44 | ```
45 | 
46 | Then go into the clean copy, and use the tree command:
47 | 
48 | ```
49 | cd ~/cs3157/hw1-submission
50 | tree
51 | ```
52 | 
53 | The output should show the same directory structure as the prompt. Note that extra source files (.h and .c) and/or any executables/.o files/anything else will be considered extraneous and automatically removed. Furthermore, if the assignment is in C, the file names should show up in white if you are using the default color scheme and .bashrc meaning that they do not have the execute permission bit on.
54 | 
55 | Note that manually checking on GitHub by inspecting each directory and the files within it is also a reliable way to test this.
56 | 
57 | ## Commits
58 | 
59 | If you cloned a clean version of the repo, you can just use the `git log` command (or `git log --oneline` if it is easier for you to read) to verify your commit history and commit messages. For all submissions you must have at least 5 meaningful commits with relevant commit messages.
60 | 
61 | Note that manually checking the commits history section (rightmost header above your code) on GitHub is also a reliable way to test this.
62 | 
63 | ## Compilation
64 | 
65 | The TAs will make no effort to compile your code besides running `make`. So if you cloned a clean version of the repo, you should go into the src directories for each part and run nothing but make, which should produce an executable identical to the one the TAs will use for grading. You should run a few tests after generating the executable even if you have tested your code prior to pushing the changes.
66 | 
67 | ## Very Important Reminder
68 | 
69 | As a general reminder, submitting and testing your code is as important as the development of the homework code itself, so it is critical that you apply the skills above for every submission.
70 | 
71 | ### Acknowledgements
72 | 
73 | This guide was developed by Xurxo Riesco and edited by Phillip Le for Spring 2023. It was modified by Palash Sharma for Summer 2024.
74 | 


--------------------------------------------------------------------------------
/login.md:
--------------------------------------------------------------------------------
 1 | # Getting Started in UNIX Coding Environment
 2 | 
 3 | Welcome to COMSW 3157 Advanced Programming with Dr. Brian Borowski! Prior to this course, you may have used various coding environments like Eclipse, Codio, VSCode, etc. You may have some prior experience with using the command line, but this class requires really getting comfortable with it. It is very important that you read through this guide so that you will be able to do the assignments for this course.
 4 | 
 5 | You will be interacting with the UNIX coding environment via the command line.
 6 | 
 7 | ## What is the "Command Line"?
 8 | 
 9 | The command line in a UNIX coding environment allows you to interact with the operating system and execute commands. From the command line, you can navigate file systems and run programs, among other things. Think of this as a very basic way to interact with an operating system and an alternative to a mouse/trackpad.
10 | 
11 | ## Logging in to our Class Server
12 | 
13 | Students will receive an account on the BB server, which is a server instance running on Google Cloud Platform. Think of this as logging into a remote computer where you will be able to test your work in the same environment as we will use for grading. You will access the class server using SSH, which allows a secure terminal session with our class server.
14 | 
15 | For those of you using macOS, we recommend using its [Terminal](https://support.apple.com/guide/terminal/welcome/mac).
16 | 
17 | On Windows, we recommend using [Windows Terminal](https://learn.microsoft.com/en-us/windows/terminal/), [cygwin](https://www.cygwin.com/), [PuTTY](https://www.putty.org/), or [MobaX](https://mobaxterm.mobatek.net/), just to name a few.
18 | 
19 | Using one of these programs, type this into the command line to establish your connection to our server:
20 | 
21 | ```yaml
22 | ssh YOUR_UNI@bb.cs.columbia.edu
23 | ```
24 | 
25 | You should be prompted to input your password which you should have received in an email titled `Your BB Server Account`. **Note, you will not see the characters you type when entering the password.**
26 | 
27 | ## Interacting with the Shell
28 | 
29 | The application you interact with in your terminal window – the program that prints the command prompt and carries out the commands that you type – is called a “shell”. There are many different shells. Your account is configured to use the Bash shell by default, so if you run `echo $SHELL`, it should tell you that you are using Bash:
30 | 
31 | ```console
32 | $ echo $SHELL
33 | /bin/bash
34 | ```
35 | 
36 | When you type a command into your shell you're running a program, much like clicking on an icon to launch a program on a GUI based operating system. We just used the `echo` program. `echo` prints out the text that you input as command line arguments. For example:
37 | 
38 | ```console
39 | $ echo Hello BB!
40 | Hello BB!
41 | ```
42 | 
43 | There are many other useful commands. In fact, we've already used one — the `ssh` command when logging into the BB server. A few more examples:
44 | 
45 | ```console
46 | $ date
47 | Sat Jan 14 10:56:27 EST 2023
48 | 
49 | $ ping google.com
50 | PING google.com (142.251.16.101) 56(84) bytes of data.
51 | 64 bytes from bl-in-f101.1e100.net (142.251.16.101): icmp_seq=1 ttl=115 time=1.54 ms
52 | 
53 | $ python3
54 | Python 3.10.7 (main, Nov 24 2022, 19:45:47) [GCC 12.2.0] on linux
55 | Type "help", "copyright", "credits" or "license" for more information.
56 | >>> 
57 | 
58 | $ cowsay Hello BB!
59 |  ___________
60 | < Hello BB! >
61 |  -----------
62 |         \   ^__^
63 |          \  (oo)\_______
64 |             (__)\       )\/\
65 |                 ||----w |
66 |                 ||     ||
67 | ```
68 | 
69 | In AP, we will typically write command line usage in the above format. The shell prompt, which you type commands after, is represented by a `$`. Text that isn't prepended by a `$` is the output of a program.
70 | 
71 | When you're not sure what a command does or how to use it, you should consult the `man` pages. If you wanted to figure out what `ping` does and how to use it, you would type `man ping`. Google is also an option.
72 | 
73 | For a more detailed walkthrough of the command line, we recommend [this video](https://www.youtube.com/watch?v=AWDxfZkGW_w) by a former AP student.
74 | 
75 | ## Writing Code with a Text Editor
76 | 
77 | In this course, you may use any text editor or integrated development environment (IDE) of your choice. Most students use [Visual Studio Code](https://code.visualstudio.com/) when working on their local machine, and `vim`, a command line text editor, when working on the BB server. Regardless of your choice, you should get familiar with the basics of `vim`, as it will come in handy when testing code on the class server. You can use the built-in tutorial by running `vimtutor` in the command-line.
78 | 
79 | Getting comfortable with your text-editor is very important for this course and will make it a lot easier when assignments become more complex, so practice early!
80 | 
81 | 
82 | ### Acknowledgments
83 | 
84 | This guide was originally developed by Jae Woo Lee.
85 | 
86 | It was adapted for Dr. Borowski's version of the class by the following TAs:
87 | 
88 | - Phillip Le and Jeremy Carin (Spring 23)
89 | - Palash Sharma and Carl von Bonin (Spring 25)
90 | 


--------------------------------------------------------------------------------
/valgrind.md:
--------------------------------------------------------------------------------
  1 | # Understanding Valgrind Error Messages
  2 | 
  3 | ## Background
  4 | 
  5 | We use Valgrind to obtain information about two categories of incorrect memory
  6 | management: memory leaks and memory errors.  Memory leaks occur when heap memory
  7 | is not freed, and generally do not cause any kind of misbehavior (unless the
  8 | process runs out of allocatable memory).  Memory errors, in contrast, are a
  9 | common source of undefined behavior---and are the focus of this guide.
 10 | 
 11 | There are four error messages that you should understand:
 12 | 
 13 | 1. Invalid reads
 14 | 2. Invalid writes
 15 | 3. Conditional jumps and moves that depend on uninitialized value(s)
 16 | 4. Segmentation faults (colloquially, "segfaults")
 17 | 
 18 | This guide will provide an explanation and example for each.
 19 | 
 20 | ## Invalid read
 21 | 
 22 | An invalid read occurs when you attempt to read a value from a location in
 23 | memory that is not available to the program (e.g. heap memory outside of
 24 | `malloc()`ed blocks and memory which overruns the top of the stack).  The error
 25 | message always includes the number of bytes your program attempted to read,
 26 | which is useful for debugging the error.  On the AP Server, a size of 1 indicates a
 27 | `char`, 4 indicates an `int`, and 8 usually indicates a pointer.
 28 | 
 29 | Here's a simple program that will lead to an invalid read of size 4 by reading
 30 | 4 bytes (one extra `int`) beyond a heap-allocated array of integers.  The
 31 | program allocates 20 bytes while it attempts to dereference and read from 24.
 32 | 
 33 | ```c
 34 | int main(void) {
 35 |     int *p = malloc(5 * sizeof(int));
 36 | 
 37 |     if (p == NULL)
 38 |         exit(1);
 39 | 
 40 |     for (int i = 0; i < 5; i++)
 41 |         p[i] = i;
 42 | 
 43 |     for (int i = 0; i < 6; i++)
 44 |         printf("%d\n", p[i]);
 45 | 
 46 |     free(p);
 47 | }
 48 | ```
 49 | 
 50 | ## Invalid write
 51 | 
 52 | An invalid write is similar to an invalid read, but it occurs when you attempt
 53 | to write to an illegal memory location.
 54 | 
 55 | Here's a simple program that causes an invalid write of size 4 by writing one
 56 | extra `int` outside of a heap-allocated array.  This program allocates 20 bytes
 57 | (5 `int`s), but tries to write 24 bytes worth of values (6 `int`s).
 58 | 
 59 | ```c
 60 | int main(void) {
 61 |     int *p = malloc(5 * sizeof(int));
 62 | 
 63 |     if (p == NULL)
 64 |         exit(1);
 65 | 
 66 |     for (int i = 0; i < 6; i++)
 67 |         p[i] = i;
 68 | 
 69 | 
 70 |     for (int i = 0; i < 5; i++) {
 71 |         printf("%d\n", p[i]);
 72 |     }
 73 | 
 74 |     free(p);
 75 | }
 76 | ```
 77 | 
 78 | ## Conditional jump or move depends on uninitialized value(s)
 79 | 
 80 | The error message "conditional jump or move depends on uninitialized value(s)"
 81 | indicates that the outcome of some operation depends on a variable that has not
 82 | been initialized.  Because the value of an uninitialized variable is not
 83 | defined, a program whose outcome is dependent on an uninitialized variable will
 84 | have undetermined behavior.
 85 | 
 86 | A conditional jump refers to a statement that determines control flow, such as
 87 | an `if` statement, a `while` loop, or a `for` loop.  A move refers to any other
 88 | kind of read from memory.  Note that conditional jumps and moves may take place
 89 | deep within library code if you pass pointers to uninitialized memory to
 90 | library functions like `printf()`.
 91 | 
 92 | In the following program, `h()` passes a pointer to the uninitialized variable
 93 | `x` to `g()`, which dereferences that pointer.  The value that `g()` reads is
 94 | usually unpredictable; in this case, `g()` may pick up a value of 42 left
 95 | behind by `f()`'s stack frame.
 96 | 
 97 | ```c
 98 | #include <stdio.h>
 99 | 
100 | void f(void) {
101 |     int x = 42;
102 |     printf("f: %p -> %d\n", &x, x);
103 | }
104 | 
105 | void g(int *i) {
106 |     int j = *i + 10;
107 |     printf("g: %d\n", j);
108 | }
109 | 
110 | void h(void) {
111 |     int x; // Uninitialized
112 |     g(&x);
113 | }
114 | 
115 | int main(void) {
116 |     f();
117 |     h();
118 | }
119 | ```
120 | 
121 | This error often occurs when you forget to null-terminate a string.  Here's
122 | a sample program which populates and prints out a `char` array `a`.  However,
123 | it forgets to null-terminate `a` before passing it to `printf()`, leading to
124 | a memory error:
125 | 
126 | ```c
127 | int main(void) {
128 |     char *s = "hello";
129 |     char a[6];
130 | 
131 |     for(int i = 0; i < 5; i++)
132 |         a[i] = s[i];
133 | 
134 |     printf("%s\n", a);
135 | }
136 | ```
137 | 
138 | ## Segmentation fault
139 | 
140 | A segmentation fault occurs when the operating system intervenes after an
141 | invalid read or write, causing your program to crash.  The most common source
142 | of segmentation faults is an attempt to dereference a null pointer, indicated
143 | by an invalid read at `0x0`.  Segmentation faults can be observed without using
144 | Valgrind, but Valgrind will provide more detailed information about where and
145 | why the error occurred.
146 | 
147 | Here's a program which attempts to write to read-only memory. `char *s` points
148 | to the read-only code section of memory, but the `char` arrays `s1` and `s2`
149 | are on the stack, which can be read from and written to.  The first call to
150 | `strcpy()` reads from `s` and writes to `s1`, which is fine.  However, the
151 | second call attempts to write to `s`, which leads to a segmentation fault.
152 | 
153 | ```c
154 | int main(void) {
155 |     char *s = "hi";
156 |     char s1[3] = "no";
157 |     char s2[3] = "ok";
158 | 
159 |     printf("%s %s %s\n", s, s1, s2);
160 | 
161 |     strcpy(s1, s);  // This is OK.
162 | 
163 |     printf("%s %s %s\n", s, s1, s2);
164 | 
165 |     strcpy(s, s2);  // This is not.
166 | 
167 |     printf("%s %s %s \n", s, s1, s2);
168 | }
169 | ```
170 | 
171 | ----
172 | 
173 | ### Acknowledgements
174 | 
175 | This guide was originally written for the listserv by Brennan McManus in Fall 2019.
176 | 


--------------------------------------------------------------------------------
/.markdownlint.yaml:
--------------------------------------------------------------------------------
  1 | # Path to configuration file to extend
  2 | extends: null
  3 | 
  4 | # MD001/heading-increment/header-increment - Heading levels should only increment by one level at a time
  5 | MD001: true
  6 | 
  7 | # MD002/first-heading-h1/first-header-h1 - First heading should be a top-level heading
  8 | MD002:
  9 |   # Heading level
 10 |   level: 1
 11 | 
 12 | # MD003/heading-style/header-style - Heading style
 13 | MD003:
 14 |   # Heading style
 15 |   style: "atx"
 16 | 
 17 | # MD004/ul-style - Unordered list style
 18 | MD004:
 19 |   # List style
 20 |   style: "dash"
 21 | 
 22 | # MD005/list-indent - Inconsistent indentation for list items at the same level
 23 | MD005: true
 24 | 
 25 | # MD006/ul-start-left - Consider starting bulleted lists at the beginning of the line
 26 | MD006: true
 27 | 
 28 | # MD007/ul-indent - Unordered list indentation
 29 | MD007:
 30 |   # Spaces for indent
 31 |   indent: 4
 32 |   # Whether to indent the first level of the list
 33 |   start_indented: false
 34 |   # Spaces for first level indent (when start_indented is set)
 35 |   start_indent: 2
 36 | 
 37 | # MD009/no-trailing-spaces - Trailing spaces
 38 | MD009:
 39 |   # Spaces for line break
 40 |   br_spaces: 2
 41 |   # Allow spaces for empty lines in list items
 42 |   list_item_empty_lines: false
 43 |   # Warn about unnecessary breaks
 44 |   strict: true
 45 | 
 46 | # MD010/no-hard-tabs - Hard tabs
 47 | MD010:
 48 |   # Include code blocks
 49 |   code_blocks: true
 50 |   # Fenced code languages to ignore
 51 |   ignore_code_languages: []
 52 |   # Number of spaces for each hard tab
 53 |   spaces_per_tab: 4
 54 | 
 55 | # MD011/no-reversed-links - Reversed link syntax
 56 | MD011: true
 57 | 
 58 | # MD012/no-multiple-blanks - Multiple consecutive blank lines
 59 | MD012:
 60 |   # Consecutive blank lines
 61 |   maximum: 2
 62 | 
 63 | # MD013/line-length - Line length
 64 | MD013: false
 65 |   # NOTE: this would be nice, but it doesn't know to ignore inline HTML
 66 |   # # Number of characters
 67 |   # line_length: 120
 68 |   # # Number of characters for headings
 69 |   # heading_line_length: 120
 70 |   # # Number of characters for code blocks
 71 |   # code_block_line_length: 120
 72 |   # # Include code blocks
 73 |   # code_blocks: true
 74 |   # # Include tables
 75 |   # tables: true
 76 |   # # Include headings
 77 |   # headings: true
 78 |   # # Include headings
 79 |   # headers: true
 80 |   # # Strict length checking
 81 |   # strict: false
 82 |   # # Stern length checking
 83 |   # stern: false
 84 | 
 85 | # MD014/commands-show-output - Dollar signs used before commands without showing output
 86 | MD014: false
 87 | 
 88 | # MD018/no-missing-space-atx - No space after hash on atx style heading
 89 | MD018: true
 90 | 
 91 | # MD019/no-multiple-space-atx - Multiple spaces after hash on atx style heading
 92 | MD019: true
 93 | 
 94 | # MD020/no-missing-space-closed-atx - No space inside hashes on closed atx style heading
 95 | MD020: true
 96 | 
 97 | # MD021/no-multiple-space-closed-atx - Multiple spaces inside hashes on closed atx style heading
 98 | MD021: true
 99 | 
100 | # MD022/blanks-around-headings/blanks-around-headers - Headings should be surrounded by blank lines
101 | MD022:
102 |   # Blank lines above heading
103 |   lines_above: 1
104 |   # Blank lines below heading
105 |   lines_below: 1
106 | 
107 | # MD023/heading-start-left/header-start-left - Headings must start at the beginning of the line
108 | MD023: true
109 | 
110 | # MD024/no-duplicate-heading/no-duplicate-header - Multiple headings with the same content
111 | MD024:
112 |   # Only check sibling headings
113 |   allow_different_nesting: true
114 |   # Only check sibling headings
115 |   siblings_only: true
116 | 
117 | # MD025/single-title/single-h1 - Multiple top-level headings in the same document
118 | MD025:
119 |   # Heading level
120 |   level: 1
121 |   # RegExp for matching title in front matter
122 |   front_matter_title: ""
123 |   # NOTE: Don't look for front matter
124 | 
125 | # MD026/no-trailing-punctuation - Trailing punctuation in heading
126 | MD026:
127 |   # Punctuation characters
128 |   # NOTE: edited to remove !
129 |   punctuation: ".,;:。，；："
130 | 
131 | # MD027/no-multiple-space-blockquote - Multiple spaces after blockquote symbol
132 | MD027: true
133 | 
134 | # MD028/no-blanks-blockquote - Blank line inside blockquote
135 | MD028: true
136 | 
137 | # MD029/ol-prefix - Ordered list item prefix
138 | MD029:
139 |   # List style
140 |   style: "one_or_ordered"
141 | 
142 | # MD030/list-marker-space - Spaces after list markers
143 | MD030:
144 |   # Spaces for single-line unordered list items
145 |   ul_single: 1
146 |   # Spaces for single-line ordered list items
147 |   ol_single: 1
148 |   # Spaces for multi-line unordered list items
149 |   ul_multi: 3
150 |   # Spaces for multi-line ordered list items
151 |   ol_multi: 2
152 | 
153 | # MD031/blanks-around-fences - Fenced code blocks should be surrounded by blank lines
154 | MD031:
155 |   # Include list items
156 |   list_items: true
157 | 
158 | # MD032/blanks-around-lists - Lists should be surrounded by blank lines
159 | MD032: true
160 | 
161 | # MD033/no-inline-html - Inline HTML
162 | MD033: false
163 | #   # Allowed elements
164 | #   allowed_elements: []
165 | 
166 | # MD034/no-bare-urls - Bare URL used
167 | MD034: true
168 | 
169 | # MD035/hr-style - Horizontal rule style
170 | MD035:
171 |   # Horizontal rule style
172 |   style: "consistent"
173 | 
174 | # MD036/no-emphasis-as-heading/no-emphasis-as-header - Emphasis used instead of a heading
175 | MD036: false
176 |   # Punctuation characters
177 |   # punctuation: ".,;:!?。，；：！？"
178 | 
179 | # MD037/no-space-in-emphasis - Spaces inside emphasis markers
180 | MD037: true
181 | 
182 | # MD038/no-space-in-code - Spaces inside code span elements
183 | MD038: true
184 | 
185 | # MD039/no-space-in-links - Spaces inside link text
186 | MD039: true
187 | 
188 | # MD040/fenced-code-language - Fenced code blocks should have a language specified
189 | MD040: false
190 | 
191 | # MD041/first-line-heading/first-line-h1 - First line in a file should be a top-level heading
192 | MD041:
193 |   # Heading level
194 |   level: 1
195 |   # RegExp for matching title in front matter
196 |   front_matter_title: "^\\s*title\\s*[:=]"
197 | 
198 | # MD042/no-empty-links - No empty links
199 | MD042: true
200 | 
201 | # MD043/required-headings/required-headers - Required heading structure
202 | MD043: false
203 |   # # List of headings
204 |   # headings: []
205 |   # # List of headings
206 |   # headers: []
207 | 
208 | # MD044/proper-names - Proper names should have the correct capitalization
209 | MD044: false
210 |   # # List of proper names
211 |   # names: []
212 |   # # Include code blocks
213 |   # code_blocks: true
214 |   # # Include HTML elements
215 |   # html_elements: true
216 | 
217 | # MD045/no-alt-text - Images should have alternate text (alt text)
218 | MD045: true
219 | 
220 | # MD046/code-block-style - Code block style
221 | MD046:
222 |   # Block style
223 |   style: "fenced"
224 | 
225 | # MD047/single-trailing-newline - Files should end with a single newline character
226 | MD047: true
227 | 
228 | # MD048/code-fence-style - Code fence style
229 | MD048:
230 |   # Code fence style
231 |   style: "backtick"
232 | 
233 | # MD049/emphasis-style - Emphasis style should be consistent
234 | MD049:
235 |   # Emphasis style should be consistent
236 |   style: "underscore"
237 | 
238 | # MD050/strong-style - Strong style should be consistent
239 | MD050:
240 |   # Strong style should be consistent
241 |   style: "asterisk"
242 | 
243 | # MD051/link-fragments - Link fragments should be valid
244 | MD051: true
245 | 
246 | # MD052/reference-links-images - Reference links and images should use a label that is defined
247 | MD052: true
248 | 
249 | # MD053/link-image-reference-definitions - Link and image reference definitions should be needed
250 | MD053:
251 |   # Ignored definitions
252 |   ignored_definitions: [
253 |     "//"
254 |   ]
255 | 


--------------------------------------------------------------------------------
/git.md:
--------------------------------------------------------------------------------
  1 | # Git Tutorial
  2 | 
  3 | Git is a source code version control system. Such a system is most
  4 | useful when you work in a team, but even when you’re working alone,
  5 | it’s a very useful tool to keep track of the changes you have made to
  6 | your code.
  7 | 
  8 | In this class, you are required to use Git for doing your homework
  9 | assignments. You will use Git not only for coding
 10 | your homeworks, but also for cloning the assignment repos and
 11 | submitting your code.
 12 | 
 13 | This tutorial covers not only the basic git operations that you need,
 14 | but also the workflow between you and the TAs -- from our
 15 | preparation of an assignment all the way to the grading of your
 16 | submissions by the TAs. Even if you are already familiar with git,
 17 | you may find the description of the workflow helpful.
 18 | 
 19 | ## Set `EDITOR` environment variable
 20 | 
 21 | Type `echo $EDITOR`. If the shell does not respond with the name of
 22 | your editor -- vim, emacs, or nano -- add the following line at the end of
 23 | the `.bashrc` file in your home directory:
 24 | 
 25 | ```bash
 26 | export EDITOR=your_choice_of_editor
 27 | ```
 28 | 
 29 | After saving your `.bashrc` file, run `source ~/.bashrc`
 30 | in the command line to make sure that your modification
 31 | to `.bashrc` has taken effect.
 32 | 
 33 | ## Configure your git environment
 34 | 
 35 | Tell git your name and email:
 36 | 
 37 | ```bash
 38 | git config --global user.name "Your Full Name"
 39 | git config --global user.email your_uni@columbia/barnard.edu
 40 | ```
 41 | 
 42 | git stores this information in `~/.gitconfig`
 43 | 
 44 | ## Creating a project
 45 | 
 46 | Let’s create a new directory, `~/tmp/test1`, for our first git project.
 47 | 
 48 | ```bash
 49 | cd
 50 | mkdir tmp
 51 | cd tmp
 52 | mkdir test1
 53 | cd test1
 54 | ```
 55 | 
 56 | Put the directory under git revision control:
 57 | 
 58 | ```bash
 59 | git init
 60 | ```
 61 | 
 62 | A git repository exists alongside the normal file system. It allows us to track the changes that we make to files, but only in the directory you've initialized it in and subdirectories. This means, for example, that you could create another git repository in `~/tmp/test2`, and the two repositories would have nothing to do with each other.```
 63 | If you type `ll` (I’ll assume that `ll` is an alias for `ls -alF`), you will
 64 | see that there is a `.git` directory. The git repository for the
 65 | current directory is stashed in the `.git` directory.
 66 | 
 67 | Let’s start our programming project. Write `hello.c` with your editor:
 68 | 
 69 | ```c
 70 | #include <stdio.h>
 71 | int main()
 72 | {
 73 |     printf("%s\n", "hello world");
 74 |     return 0;
 75 | }
 76 | ```
 77 | 
 78 | Compile and run it:
 79 | 
 80 | ```bash
 81 | gcc hello.c
 82 | ./a.out
 83 | ```
 84 | 
 85 | Let’s see what git thinks about what we’re doing:
 86 | 
 87 | ```bash
 88 | git status
 89 | ```
 90 | 
 91 | The `git status` command reports that `hello.c` and `a.out` are "Untracked".
 92 | We can have git track `hello.c` by adding it to the "staging" area (more
 93 | on this later):
 94 | 
 95 | ```bash
 96 | git add hello.c
 97 | ```
 98 | 
 99 | Run `git status` again. It now reports that `hello.c` is "a new file to
100 | be committed." Let’s commit it:
101 | 
102 | ```bash
103 | git commit
104 | ```
105 | 
106 | Git opens up your editor for you to type a commit message. A commit
107 | message should succinctly describe what you’re committing in the first
108 | line. If you have more to say, follow the first line with a blank
109 | line, and then with a more thorough multi-line description.
110 | 
111 | For now, type in the following one-line commit message, save, and exit
112 | the editor: `Added hello-world program`
113 | You can also do this in a one-line command with the `-m` flag. `-m`. specifies the commit message without opening a text editor:
114 | 
115 | ```bash
116 | git commit -m "Added hello-world program"
117 | ```
118 | 
119 | Run `git status` again. It now reports that only `a.out` is untracked.
120 | It has no mention of `hello.c`. When git says nothing about a file, it
121 | means that it is being tracked, and that it has not changed since it
122 | has been last committed.
123 | 
124 | We have successfully put our first coding project under git revision
125 | control.
126 | 
127 | ## Modifying files
128 | 
129 | Modify `hello.c` to print "bye world" instead, and run `git status`. It
130 | reports that the file is "Changed but not updated." This means that
131 | the file has been modified since the last commit, but it is still not
132 | ready to be committed because it has not been moved into the staging
133 | area. In git, a file must first go to the staging area before it can
134 | be committed.
135 | 
136 | Before we move it to the staging area, let’s see what we changed in
137 | the file:
138 | 
139 | ```bash
140 | git diff
141 | ```
142 | 
143 | Or, if your terminal supports color,
144 | 
145 | ```bash
146 | git diff --color
147 | ```
148 | 
149 | The output should tell you that you took out the "hello world" line,
150 | and added a "bye world" line, like this:
151 | 
152 | ```diff
153 | - printf("%s\n", "hello world");
154 | + printf("%s\n", "bye world");
155 | ```
156 | 
157 | We move the file to the staging area with git add command:
158 | 
159 | ```bash
160 | git add hello.c
161 | ```
162 | 
163 | In git, "add" means this: move the change you made to the staging
164 | area. The change could be a modification to a tracked file, or it
165 | could be a creation of a brand new file. This is a point of confusion
166 | for those of you who are familiar with other version control systems
167 | such as Subversion.
168 | 
169 | At this point, `git diff` will report no change. Our change -- from
170 | hello to bye -- has been moved into staging already. So this means that
171 | `git diff` reports the difference between the staging area and the
172 | working copy of the file.
173 | 
174 | To see the difference between the last commit and the staging area,
175 | add `--cached` option:
176 | 
177 | ```bash
178 | git diff --cached
179 | ```
180 | 
181 | Let’s commit our change. If your commit message is a one-liner, you
182 | can skip the editor by giving the message directly as part of the git
183 | commit command:
184 | 
185 | ```bash
186 | git commit -m "changed hello to bye"
187 | ```
188 | 
189 | To see your commit history:
190 | 
191 | ```bash
192 | git log
193 | ```
194 | 
195 | You can add a brief summary of what was done at each commit:
196 | 
197 | ```bash
198 | git log --stat --summary
199 | ```
200 | 
201 | Or you can see the full diff at each commit:
202 | 
203 | ```bash
204 | git log -p
205 | ```
206 | 
207 | And in color:
208 | 
209 | ```bash
210 | git log -p --color
211 | ```
212 | 
213 | ## The tracked, the modified, and the staged
214 | 
215 | A file in a directory under git revision control is either tracked or
216 | untracked. A tracked file can be unmodified, modified but unstaged,
217 | or modified and staged. Confused? Let’s try again.
218 | 
219 | There are four possibilities for a file in a git-controlled directory:
220 | 
221 | 1.  Untracked
222 | 
223 |     - Object files and executable files that can be rebuilt are usually not tracked.
224 | 
225 | 1.  Tracked, unmodified
226 |     - The file is in the git repository, and it has not been modified since the last commit. `git status` says nothing about the file.
227 | 
228 | 1.  Tracked, modified, but unstaged
229 | 
230 |     - You modified the file, but didn’t `git add` the file. The change has not been staged, so it’s not ready for commit yet.
231 | 
232 | 1.  Tracked, modified, and staged
233 | 
234 |     - You modified the file, and did `git add` the file. The change has been moved to the staging area. It is ready for commit.
235 | 
236 | The staging area is also called the "index".
237 | 
238 | ## Other useful git commands
239 | 
240 | Here are some more git commands that you will find useful.
241 | 
242 | To rename a tracked file:
243 | 
244 | ```bash
245 | git mv old-filename new-filename
246 | ```
247 | 
248 | To remove a tracked file from the repository:
249 | 
250 | ```bash
251 | git rm filename
252 | ```
253 | 
254 | The `mv` or `rm` actions are automatically staged for you, but you still
255 | need to `git commit` your actions.
256 | 
257 | Sometimes you make some changes to a file, but regret it, and want to
258 | go back to the version last committed. If the file has not been
259 | staged yet, you can do:
260 | 
261 | ```bash
262 | git checkout -- filename
263 | ```
264 | 
265 | If the file has been staged, you must first unstage it:
266 | 
267 | ```bash
268 | git reset HEAD filename
269 | ```
270 | 
271 | There are two ways to display a manual page for a git command. For
272 | example, for the `git status` command, you can type one of the
273 | following two commands:
274 | 
275 | ```bash
276 | git help status
277 | man git-status
278 | ```
279 | 
280 | Lastly, `git grep` searches for specified patterns in all files in the
281 | repository. To see all places you called `printf()`:
282 | 
283 | ```bash
284 | git grep printf
285 | ```
286 | 
287 | ## Cloning a project
288 | 
289 | You created a brand new project in the test1 directory, added a file,
290 | and modified the file. But more often than not, a programmer starts
291 | with an existing code base. When the code base is under git version
292 | control, you can \*clone\* the whole repository. This is in fact what
293 | you will do to start your homework assignments from my skeleton code.
294 | Let’s move up one directory, clone test1 into test2, and `cd` into the
295 | test2 directory:
296 | 
297 | ```bash
298 | cd ..
299 | git clone test1 test2
300 | cd test2
301 | ```
302 | 
303 | Type `ll` to see that your `hello.c` file is cloned here. Moreover, if
304 | you run `git log`, you will see that the whole commit history is
305 | replicated here. `git clone` not only copies the latest version of
306 | the files, but also copies the entire repository, including the entire
307 | commit history. After cloning, the two repositories are
308 | indistinguishable.
309 | 
310 | Let’s make some changes -- and let’s be bad. Edit `hello.c` to replace
311 | `printf` with `printf%^&`, save and commit:
312 | 
313 | ```bash
314 | vim hello.c
315 | git add hello.c
316 | git commit -m "hello world modification - work in progress"
317 | ```
318 | 
319 | Now run `git log` to see your recent commit carrying on the commit
320 | history that was cloned. If you want to see only the commits after
321 | cloning:
322 | 
323 | ```bash
324 | git log origin..
325 | ```
326 | 
327 | Of course you can add `-p` and `--color` to see the full diff in color:
328 | 
329 | ```bash
330 | git log -p --color origin..
331 | ```
332 | 
333 | Let’s make one more modification. Fix the `printf`, and perhaps change
334 | the "bye world" to "rock my world" while we’re there.
335 | 
336 | ```bash
337 | vim hello.c
338 | git add hello.c
339 | git commit -m "fixed typo & now prints rock my world"
340 | ```
341 | 
342 | Run `git log -p --color origin..` again to see the two commits you
343 | have made after cloning.
344 | 
345 | ## Adding a directory into your repository
346 | 
347 | After the homework deadline, we will publish the solution by adding a subdirectory to the solution repository. Let’s simulate that
348 | process. Go into the original test1 directory, and make the solution
349 | subdirectory and create two files in it:
350 | 
351 | ```bash
352 | cd ../test1
353 | mkdir solution
354 | cd solution
355 | cp ../hello.c .
356 | echo 'hello:' > Makefile
357 | ```
358 | 
359 | Type `ll` to see that two files (`Makefile` and `hello.c`) have been created
360 | in the `solution` directory. (`hello.c` was copied from the parent
361 | directory, and Makefile was created directly on the command line using
362 | the echo command. BTW, the Makefile contains a single line, `hello:`.
363 | Can you see why this is a legitimate Makefile?)
364 | Now, move out of the solution directory, and `git add` and `git commit` the
365 | solution directory:
366 | 
367 | ```bash
368 | cd ..
369 | git add solution
370 | git commit -m "added solution"
371 | ```
372 | 
373 | Note that `git add solution` stages all files in the directory.
374 | 
375 | ## Pushing commits to a remote repository
376 | 
377 | The `git push` command takes two arguments:
378 |     A remote name, for example, origin
379 |     A branch name, for example, main
380 | 
381 | ```bash
382 | git push origin main
383 | ```
384 | 
385 | will do the job, and now your submission is on the remote server.
386 | 
387 | ## Pulling changes from a remote repository
388 | 
389 | Once you hear that the homework solution is available, you will want to
390 | retrieve it and take a look. You do that by "pulling" the changes in
391 | my repository into your repository. Let’s pull the changes we just
392 | made in `test1` into `test2`:
393 | 
394 | ```bash
395 | cd ../test2/
396 | git pull
397 | ```
398 | 
399 | The `git pull` command looks at the original repository that you
400 | cloned from, fetches all the changes made since the cloning, and
401 | merges the changes into the current repository. You now have the
402 | solution right in your repository.
403 | 
404 | ## Branches
405 | 
406 | With group assignments, we recommend that you push work to branches first, and then merge back into main once your group members have reviewed the code. As an example, suppose that you are working on a part of the assignment, you can create a branch separate from main by doing the following:
407 | 
408 | `$ git checkout main`
409 | `$ git checkout -b <branch-name>`
410 | 
411 | You can then commit your changes, and push to the branch by doing the following:
412 | 
413 | `$ git push origin <branch-name>`
414 | 
415 | This will allow multiple members of the team to work on separate features in parallel. When the feature you are working on is complete, you may then create a pull request to allow your team members to review the code, and finally merge the changes back into master. You can read more about using branches and pull requests from [GitHub’s own documentation](https://help.github.com/articles/proposing-changes-to-your-work-with-pull-requests/).
416 | 
417 | ## Learning more about git
418 | 
419 | This tutorial covers everything you need to do your homework assignments.
420 | Git is an extremely powerful tool and a beautifully designed piece of
421 | software. If you want to learn more about it, start with the official
422 | git tutorial:
423 | 
424 | ```bash
425 | man gittutorial
426 | ```
427 | 
428 | There are pointers to further documentations at the end of the tutorial.
429 | 
430 | The documentation page of the Git web site has many links as well:
431 | [http://git-scm.com/documentation](http://git-scm.com/documentation)
432 | 
433 | ### Acknowledgments
434 | 
435 | This guide was originally developed by Jae Woo Lee.
436 | 
437 | Leslie Chang adapted it in Spring 23.
438 | 


--------------------------------------------------------------------------------