CSE330 Wiki - User contributions [en]

Module 7

2016-11-22T18:51:12Z

Brian: /* Grading */

__NOTOC__
This module will be teaching “Angular JS,” a framework that works with Javascript and HTML to create a front-end of a website much easier and faster. It is part of the oft-used “MEAN stack,” which is a stack that entirely uses Javascript, for the database, back-end, and front-end.

== Optional Reading ==
To learn more about the MEAN stack, as well as using Git to do more than check out and commit repos, check out the old module 7 reference pages:
*[[Git]]
*[[Preparations]]

== Individual Assignment ==
In this assignment you will build an Angular website. To learn Angular, please view and complete [https://code.angularjs.org/1.4.7/docs/tutorial this] tutorial, and focus on steps 0-10. The other steps and the tests at the bottom of each step are helpful and to master Angular you will need to learn these. However, for this module, you are not required to do these parts.

Now that you have finished the tutorial, we will make a coffee rating website!

=== Setting up ===
To help you get started, download a skeleton on which you will build your angular app on, called Angular-Seed. Go [https://github.com/angular/angular-seed/blob/master/README.md here] and follow the instruction to download the seed, naming your project ‘coffees’.

'''Note:''' If you are running the Angular-Seed project from EC2, open the '''package.json''' file in the coffees directory

Find the line that says

<source lang="bash">"start": "http-server -a localhost -p 8000 -c-1", </source>

and change it to

<source lang="bash">"start": "http-server -p 8000 -c-1",</source>

This will allow for connections other than just localhost.

'''Note''': Although you can ignore a lot of these files (the node directory, the karma files, view1/view2, etc), by downloading the seed you can get around issues such as creating the server (this does it for you), and if you were going to use a backend, having node all set up for you is really nice.

Now that you’ve downloaded the seed, you will need to modify the following files: app.js, and index.html. Furthermore, you will add the following files: coffees.html, and reviews.html.

=== Creating the Site ===

Your site will need to use ‘ngRoute’ with two views on top of index.html. One view (coffees.html) will be a list of all coffees in the database, sorted by name. There should be a search box at the top to find a particular coffee. Each listing in the table should include a brand, a name, a location, and a link to see the reviews of that coffee. Here’s what it should look like before CSS:

[[File:Coffees-bare (2).png|upright=2|thumb|center|coffees.html]]

Once you click the link, it should go to the second view (reviews.html). This should be another table, of all of the reviews for the coffee list.

Here’s what your reviews.html should look like before CSS:

[[File:reviews-bare.png|thumb|upright=2|center|reviews.html]]

At all times, there should be a button at the top (not in either view, but in the main page) that takes you home (coffees.html).
In app.js, you will need to copy the following array into your controller:

$scope.coffees =
[
{'id': 1,
'brand': "Average Andy's Coffee",
'name': 'Regular Coffee',
'country': 'Denmark',
'reviews': [
{'rating': 3,
'comment': "Could've been crispier",
'reviewer': "Chris P. Bacon"
}
]
},
{'id': 2,
'brand': "Jimmy's Coffee",
'name': 'Mocha',
'country': 'America',
'reviews': [
{'rating': 10,
'comment': 'What everyone should drink in the morning!',
'reviewer': 'Earl Lee Riser'
},
{'rating': 10,
'comment': 'A genius of everything coffee',
'reviewer': 'Bob'
}
]
},
{'id': 3,
'brand': "We Did Our Best",
'name': 'Latte',
'country': 'France',
'reviews': [
{'rating': 1,
'comment': " a 'latte' yuckiness.",
'reviewer': 'Tim Burr'
},
{'rating': 1,
'comment': 'Is this even coffee?',
'reviewer': 'Sue Flay'
},
{'rating': 1,
'comment': 'The grossest thing I have ever had.',
'reviewer': 'Myles Long'
},
{'rating': 5,
'comment': 'I dont know what the fuss is about, i dont think its too bad!',
'reviewer': 'Sara Bellum'
}
]
},
{'id': 4,
'brand': "Jimmy's Special Coffee",
'name': 'Americano',
'country': 'America',
'reviews': [
{'rating': 10,
'comment': 'If I could rate it higher, I would!',
'reviewer': 'Justin Case'
},
{'rating': 10,
'comment': 'He does it again!',
'reviewer': 'Eileen Dover'
}
]
}];

This will be your “database,” as we are not going to use the “$http” dependency.

=== Style ===

Finally, use CSS (and, if you'd like to make it easier on yourself), UI Bootstrap (view the reference [https://angular-ui.github.io/bootstrap/ here] ), to make the site look pretty.
Although you’re allowed to use whatever CSS/Bootstrap you want, UI Bootstrap makes things really easy. For example, using stars in the rating directives to display ratings instead of a number.

Please follow the installation instructions carefully. Type the following in your command file from the coffees directory:
npm install -g bower
bower install angular-bootstrap

The following should be in your index.html *before you include app.js, but after you put the source files for bower_components/angular...* if you are using UI Bootstrap:

<link rel="stylesheet" href="http://netdna.bootstrapcdn.com/bootstrap/3.0.0/css/bootstrap.min.css">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap.min.css">
<script src= "bower_components/angular-bootstrap/ui-bootstrap.js"></script>
<script src= "bower_components/angular-bootstrap/ui-bootstrap.min.js" type="text/javascript"></script>
<script src= "bower_components/angular-bootstrap/ui-bootstrap-tpls.min.js" type="text/javascript"></script>

After installing and configuring your own css/bootstrap, your coffee site may look something like this (although it can look any way you want, this was just one person's design):

[[File: Coffee-css.png|thumb|upright=2|none|Coffee page]]
[[File: Reviews-css.png|thumb|upright=2|none|Review page]]

== Grading ==

We will be grading the following aspects of your work. There are 55 points total.

'''Assignments must be committed to Bitbucket by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. Assignments must be demoed within 4 days of the due date (Friday at 11:30 AM for Module 7). You are allowed to demo your assignment at TA office hours. However, after Friday at 11:30 AM, you will receive a 0 for the assignment, regardless of your time-stamp.'''

#''You must save your repo as:''
#*"<Season><year>-Module<#>-FirstName-LastName-StudentID"
#*(ie. Spring2025-Module3-John-Doe-201343)

___________

# '''Completed Google Angular Tutorial steps 0-10 (5 points)'''
# '''Completed coffee web application (50 points)'''
#* Index.html (5 points)
#** Working button with back to home button at all times (3 points)
#** Set up Angular correctly (2 points)
#* App.js (10 points)
#** Set up module ( 5 points)
#** Controller (5 points)
#*** Have one or two controller(s) for the project ( 2 points)
#*** Use scope injection (3 points)
#* Coffees.html (15 points):
#** List of all coffees sorted by name (3 points)
#** Search bar, working correctly (4 points)
#** Has Name, Brand, Location, and Review link all displayed in one table (3 points)
#** Review link works, and takes you to another view (5 points)
#* Reviews.html
#** Reviews of correct coffee, and only correct coffee, are listed (10 points)
#** All reviews are listed ( 2 points)
#** Rating, comment, and commenter are listed in the same table. (3 points)
#* BootStrapping
#** Site looks good, intuitive, and professional ( 5 points)

___________

'''Creative Project Rubric'''

You will also be submitting your Creative Project rubric alongside Module 7. Make a new repo <Season><year>-CP-FirstName1-LastName1-StudentID1-FirstName2-LastName2-StudentID2, and place your Creative Project rubric in a README.md in that repository.

Your Creative Project point breakdown should total to 95 points. An additional 5 points come from submitting the rubric on time. You may assign up to 20 points for the creative portion.

The project itself, you will be using a new framework or technology of your choice to build a project.

[[Category:Module 7]]
[[Category:Modules]]

Module 7

2016-11-21T16:52:49Z

Brian: /* Grading */

__NOTOC__
This module will be teaching “Angular JS,” a framework that works with Javascript and HTML to create a front-end of a website much easier and faster. It is part of the oft-used “MEAN stack,” which is a stack that entirely uses Javascript, for the database, back-end, and front-end.

== Optional Reading ==
To learn more about the MEAN stack, as well as using Git to do more than check out and commit repos, check out the old module 7 reference pages:
*[[Git]]
*[[Preparations]]

== Individual Assignment ==
In this assignment you will build an Angular website. To learn Angular, please view and complete [https://code.angularjs.org/1.4.7/docs/tutorial this] tutorial, and focus on steps 0-10. The other steps and the tests at the bottom of each step are helpful and to master Angular you will need to learn these. However, for this module, you are not required to do these parts.

Now that you have finished the tutorial, we will make a coffee rating website!

=== Setting up ===
To help you get started, download a skeleton on which you will build your angular app on, called Angular-Seed. Go [https://github.com/angular/angular-seed/blob/master/README.md here] and follow the instruction to download the seed, naming your project ‘coffees’.

'''Note:''' If you are running the Angular-Seed project from EC2, open the '''package.json''' file in the coffees directory

Find the line that says

<source lang="bash">"start": "http-server -a localhost -p 8000 -c-1", </source>

and change it to

<source lang="bash">"start": "http-server -p 8000 -c-1",</source>

This will allow for connections other than just localhost.

'''Note''': Although you can ignore a lot of these files (the node directory, the karma files, view1/view2, etc), by downloading the seed you can get around issues such as creating the server (this does it for you), and if you were going to use a backend, having node all set up for you is really nice.

Now that you’ve downloaded the seed, you will need to modify the following files: app.js, and index.html. Furthermore, you will add the following files: coffees.html, and reviews.html.

=== Creating the Site ===

Your site will need to use ‘ngRoute’ with two views on top of index.html. One view (coffees.html) will be a list of all coffees in the database, sorted by name. There should be a search box at the top to find a particular coffee. Each listing in the table should include a brand, a name, a location, and a link to see the reviews of that coffee. Here’s what it should look like before CSS:

[[File:Coffees-bare (2).png|upright=2|thumb|center|coffees.html]]

Once you click the link, it should go to the second view (reviews.html). This should be another table, of all of the reviews for the coffee list.

Here’s what your reviews.html should look like before CSS:

[[File:reviews-bare.png|thumb|upright=2|center|reviews.html]]

At all times, there should be a button at the top (not in either view, but in the main page) that takes you home (coffees.html).
In app.js, you will need to copy the following array into your controller:

$scope.coffees =
[
{'id': 1,
'brand': "Average Andy's Coffee",
'name': 'Regular Coffee',
'country': 'Denmark',
'reviews': [
{'rating': 3,
'comment': "Could've been crispier",
'reviewer': "Chris P. Bacon"
}
]
},
{'id': 2,
'brand': "Jimmy's Coffee",
'name': 'Mocha',
'country': 'America',
'reviews': [
{'rating': 10,
'comment': 'What everyone should drink in the morning!',
'reviewer': 'Earl Lee Riser'
},
{'rating': 10,
'comment': 'A genius of everything coffee',
'reviewer': 'Bob'
}
]
},
{'id': 3,
'brand': "We Did Our Best",
'name': 'Latte',
'country': 'France',
'reviews': [
{'rating': 1,
'comment': " a 'latte' yuckiness.",
'reviewer': 'Tim Burr'
},
{'rating': 1,
'comment': 'Is this even coffee?',
'reviewer': 'Sue Flay'
},
{'rating': 1,
'comment': 'The grossest thing I have ever had.',
'reviewer': 'Myles Long'
},
{'rating': 5,
'comment': 'I dont know what the fuss is about, i dont think its too bad!',
'reviewer': 'Sara Bellum'
}
]
},
{'id': 4,
'brand': "Jimmy's Special Coffee",
'name': 'Americano',
'country': 'America',
'reviews': [
{'rating': 10,
'comment': 'If I could rate it higher, I would!',
'reviewer': 'Justin Case'
},
{'rating': 10,
'comment': 'He does it again!',
'reviewer': 'Eileen Dover'
}
]
}];

This will be your “database,” as we are not going to use the “$http” dependency.

=== Style ===

Finally, use CSS (and, if you'd like to make it easier on yourself), UI Bootstrap (view the reference [https://angular-ui.github.io/bootstrap/ here] ), to make the site look pretty.
Although you’re allowed to use whatever CSS/Bootstrap you want, UI Bootstrap makes things really easy. For example, using stars in the rating directives to display ratings instead of a number.
Please follow the installation instructions carefully. Type the following in your command file from the coffees directory:
bower install angular-bootstrap

The following should be in your index.html *before you include app.js, but after you put the source files for bower_components/angular...* if you are using UI Bootstrap:

<link rel="stylesheet" href="http://netdna.bootstrapcdn.com/bootstrap/3.0.0/css/bootstrap.min.css">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap.min.css">
<script src= "bower_components/angular-bootstrap/ui-bootstrap.js"></script>
<script src= "bower_components/angular-bootstrap/ui-bootstrap.min.js" type="text/javascript"></script>
<script src= "bower_components/angular-bootstrap/ui-bootstrap-tpls.min.js" type="text/javascript"></script>

After installing and configuring your own css/bootstrap, your coffee site may look something like this (although it can look any way you want, this was just one person's design):

[[File: Coffee-css.png|thumb|upright=2|none|Coffee page]]
[[File: Reviews-css.png|thumb|upright=2|none|Review page]]

== Grading ==

We will be grading the following aspects of your work. There are 55 points total.

'''Assignments must be committed to Bitbucket by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. Assignments must be demoed within 4 days of the due date (Friday at 11:30 AM for Module 7). You are allowed to demo your assignment at TA office hours. However, after Friday at 11:30 AM, you will receive a 0 for the assignment, regardless of your time-stamp.'''

#''You must save your repo as:''
#*"<Season><year>-Module<#>-FirstName-LastName-StudentID"
#*(ie. Spring2025-Module3-John-Doe-201343)

___________

# '''Completed Google Angular Tutorial steps 0-10 (5 points)'''
# '''Completed coffee web application (50 points)'''
#* Index.html (5 points)
#** Working button with back to home button at all times (3 points)
#** Set up Angular correctly (2 points)
#* App.js (10 points)
#** Set up module ( 5 points)
#** Controller (5 points)
#*** Have one or two controller(s) for the project ( 2 points)
#*** Use scope injection (3 points)
#* Coffees.html (15 points):
#** List of all coffees sorted by name (3 points)
#** Search bar, working correctly (4 points)
#** Has Name, Brand, Location, and Review link all displayed in one table (3 points)
#** Review link works, and takes you to another view (5 points)
#* Reviews.html
#** Reviews of correct coffee, and only correct coffee, are listed (10 points)
#** All reviews are listed ( 2 points)
#** Rating, comment, and commenter are listed in the same table. (3 points)
#* BootStrapping
#** Site looks good, intuitive, and professional ( 5 points)

___________

'''Creative Project Rubric'''

You will also be submitting your Creative Project rubric alongside Module 7. Make a new repo <Season><year>-CP-FirstName-LastName-StudentID, and place your Creative Project rubric in a README.md in that repository.

Your Creative Project point breakdown should total to 95 points. An additional 5 points come from submitting the rubric on time. You may assign up to 20 points for the creative portion.

The project itself, you will be using a new framework or technology of your choice to build a project.

[[Category:Module 7]]
[[Category:Modules]]

Module 5

2016-10-27T18:52:00Z

Brian: /* Grading */

__NOTOC__
In Module 5, you will learn JavaScript, the dominant client-side web language. JavaScript is the third and final programming language you will learn in CSE 330.

This article contains your assignments for Module 5.

'''Warning:'''

''This module takes students a while. It is strongly recommended that you start early and ask questions as they come up.''

== Reading ==

The following articles on the online class wiki textbook contain information that will help you complete the assignments.

* [[JavaScript]]
* [[AJAX and JSON]]
* [[jQuery]]
* [[Web Application Security, Part 3]]

== Individual Assignments ==

'''''IMPORTANT:'' Both of the individual assignments must be completed ''without'' using a JavaScript library like jQuery.''' However, you may (and should) use jQuery for the group portion.

=== JavaScript Calculator ===

In Module 2, you made a calculator using PHP. Now you will be making one using JavaScript.

* The web page should have two input fields and a radio button group for the operation, with the 4 basic math operations represented (add, subtract, multiply, divide).
* JavaScript should monitor all three fields and display the current result whenever the user changes any value in any field, without refreshing the page.
*: '''Tip 1:''' Consider using either the ''change'' or the ''keyup'' event on the text fields, and either the ''change'' or the ''click'' event on the radio buttons.
*: '''Tip 2:''' Re-read [[JavaScript|the JavaScript guide]] if you need help figuring our how to bind callback functions to events, or how to determine which radio button is currently selected. (There are examples for both of these!)
* The calculator should be completely self-contained; i.e., you should not be making any requests to any other server-side or client-side scripts or web pages after the initial page load.

'''Tip:''' You can embed JavaScript code into an HTML document like this:

<source lang="html4strict">
<script type="text/javascript">
// your code here
</script>
</source>

'''Tip:''' If your code isn't working the way you expect, use a JavaScript error console. In Chrome, for example, press Ctrl-Shift-I (or Cmd-Option-I) to open the WebKit inspector.

'''Important:''' It is best practice to fully separate the content, appearance, and behavior. In previous modules, you may have lost points for using HTML tags that change the appearance of things <nowiki>(like <center> and <font>).</nowiki> In this module, make sure that you define your event listeners in JavaScript as in <code>document.getElementById("xyz").addEventListener(...)</code> and '''''not''''' in the HTML like <code><button onclick="badExample();">Bad Example</button></code>.

=== Weather Widget ===

In this section, you will make a web page that displays the weather forecast using AJAX requests to a weather server.

# Make an empty HTML document; name it '''weather.html'''
#: Refer to the [[HTML and CSS]] guide for the skeleton of an HTML document
# Define a function in JavaScript; call it '''fetchWeather()'''. You may write your JavaScript in an embedded script in your HTML document.
# Inside your '''fetchWeather()''' function, make an AJAX request to the weather server.
#: We have a server that outputs the current weather in JSON format. The format is documented in the [[#JSON Structure]] section below.
#: '''URL:''' http://classes.engineering.wustl.edu/cse330/content/weather_json.php
#: We kindly thank Yahoo Weather for providing us with up-to-date weather information.
#* '''IMPORTANT:''' Under normal circumstances, AJAX requests ''cannot'' be performed cross-domain for security reasons. We have set the <code>Access-Control-Allow-Origin</code> header on our server to allow requests from your EC2 instances, or from localhost. '''You will therefore need to upload your code to your EC2, or access it via localhost, in order for the AJAX requests to work.''' This means that you cannot, for example, complete this part of the individual portion in JSFiddle.
# In your callback, process the JSON and use JavaScript to manipulate the HTML DOM to display the following information on your page:
#* Location
#** City, in a <nowiki><strong></nowiki> tag
#** State, not in any tag
#* Humidity
#* Current Temperature
#* Image for Tomorrow's Forecast (see [[#Weather Condition Images]] below for more information)
#* Image for the Day After Tomorrow's Forecast
# Finally, bind '''fetchWeather()''' to the DOMContentLoaded event so that your weather widget is automatically initialized when the page is loaded:
#: <source lang="javascript">document.addEventListener("DOMContentLoaded", fetchWeather, false);</source>
# In addition, add a button that runs your ''fetchWeather'' function when clicked. This should update your widget with the current weather conditions.

Use the following HTML:

<source lang="html4strict">
<div class="weather" id="weatherWidget">
<div class="weather-loc"></div>
<div class="weather-humidity"></div>
<div class="weather-temp"></div>
<img class="weather-tomorrow" />
<img class="weather-dayaftertomorrow" />
</div>
</source>

Include the CSS file from here: http://classes.engineering.wustl.edu/cse330/content/weather.css

When everything is working, the weather widget should look something like this:

[[File:WeatherWidget.png]]

'''Important:''' The widget in this section needs to work in only Firefox and Chrome. It does '''''not''''' need to work Internet Explorer.

==== Tips ====

===== JSON Structure =====

The JSON from our server looks like this:

<source lang="javascript">
{
"updated": "Thu, 11 Oct 2012 5:54 pm CDT",
"location": {
"city": "St. Louis",
"state": "MO"
},
"wind": {
"chill": "62",
"direction": "150",
"speed": "3 mph"
},
"atmosphere": {
"humidity": "50",
"visibility": "10",
"pressure": "30.12 in"
},
"current": {
"code": "28",
"text": "Mostly Cloudy",
"temp": "62°F",
"date": "Thu, 11 Oct 2012 5:54 pm CDT"
},
"tomorrow": {
"code": "29",
"text": "Clouds Early/Clearing Late",
"low": "45°F",
"high": "61°F"
},
"dayafter": {
"code": "30",
"text": "Partly Cloudy",
"low": "53°F",
"high": "65°F"
},
"credit": "http://us.rd.yahoo.com/dailynews/rss/weather/St._Louis__MO/*http://weather.yahoo.com/forecast/USMO0170_f.html"
}
</source>

===== Weather Condition Images =====

Each day's forecast has a code. There are images associated with these codes.

One place to get the images is from here: <nowiki>http://us.yimg.com/i/us/nws/weather/gr/</nowiki>'''##'''<nowiki>ds.png</nowiki>

Replace the '''##''' with the forecast code. For example, for code 32, the URL would be: http://us.yimg.com/i/us/nws/weather/gr/32ds.png

== Group Project ==

I forgot if I already mentioned this, but '''start early on this project!''' It will take longer than you think, I promise!

You are encouraged to use the advanced version control practices you learned in Module 5 when completing this assignment.

=== Calendar ===

Build a simple calendar that allows users to add and remove events dynamically.

You will use JavaScript to process user interactions at the web browser, without ever refreshing the browser after the initial web page load. You may use a JavaScript library of your choice, including Ext JS.

Your application should utilize AJAX to run server-side scripts that query your database to save and retrieve information, including user accounts and events.

We have also written some functions to help you get started: [[JavaScript Calendar Library]]

==== Examples ====

* https://calendar.google.com/
* http://www.zoho.com/calendar/

==== Server Side Language ====

Additionally, you may use a database of your choice. MySQL is probably the logical choice since you have been using it since Module 2, but if you're up for a challenge we encourage you to look at other database options like [[wikipedia:MongoDB|MongoDB]].

==== Requirements ====

* Support a month-by-month view of the calendar.
*: Show one month at a time, with buttons to move forward or backward.
*: There should be no limit to how far forward or backward the user can go.
* Users can register and log in to the website.
*: You may leverage your MySQL project code and database from module 3 to get started.
* Unregistered users should see no events on the calendar.
* Registered users can add events.
*: All events should have a date and time, but do not need to have a duration.
*: You do ''not'' need to support recurring events (where you add an event that repeats, for example, every monday).
* Registered users see only events that they have added.
*: Your AJAX should not ask the server for events from a certain username. Instead, your AJAX should ask the server for events, and the server should respond with the events for only the currently-logged-in user (from the session). Can you think of why?
* Registered users can delete their events, but not the events of others.
*: Again, the server should delete events based on the username present in the session. (If it deletes only based on an Event ID, an attacker could feed any arbitrary Event ID to your server, even if he/she didn't own that event.)
* All user and event data should be kept in a database.
* At no time should the main page need to be reloaded.
*: User registration, user authentication, event addition, and event deletion should all be handled by JavaScript and AJAX requests to your server.
* Your page needs to work in the versions of Firefox and Chrome installed on the lab computers.

'''Tip:''' Run your database schema by a TA before implementing it.

=== Web Security and Validation ===

Your project needs to demonstrate that thought was put into web security and best practice. For more information, see this week's Web Application Security guide: [[Web Application Security, Part 3]]

In particular:

* '''Your application needs to prevent XSS attacks.''' Be careful when transmitting data over JSON that will be reflected in an event title! (Note: JSON data should be sanitized on the client side, not the server side.)
* '''Perform precautionary measures to prevent session hijacking attacks.'''
*: You should specify your session cookie to be HTTP-Only. However, for the means of this module, you need not test for user agent consistency.
* '''Optional:''' Validate your JavaScript code using [http://www.jshint.com/ JSHint] '''''or''''' [http://jslint.com/ JSLint] for up to 3 points of extra credit.

You should continue the practices that you have learned in past weeks:

* Pass tokens in forms to prevent CSRF attacks.
*: '''Hint:''' You will need to send your CSRF tokens in your AJAX requests. Remember that AJAX still submits forms and runs server-side scripts, just like the vanilla forms you've been using in Modules 2 and 3.
* Use prepared queries to prevent SQL Injection attacks.
* If storing passwords in a database, always store them salted and encrypted.
* Your page should validate with no errors through the W3C validator.

== Grading ==

We will be grading the following aspects of your work. There are 100 points total.

'''Assignments must be committed to Bitbucket by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. Assignments must be demoed within 4 days of the due date (Friday at 11:30 AM for Module 5). You are allowed to demo your assignment at TA office hours. However, after Friday at 11:30 AM, you will receive a 0 for the assignment, regardless of your time-stamp.'''

#''You must save your repo as:''
#*"<Season><year>-Module<#>-FirstName-LastName-StudentID"
#*(ie. Spring2025-Module3-John-Doe-201343)
#''For the group project, you must save your repo as:''
#*"<Season><year>-Module<#>-FirstName1-LastName1-StudentID1-FirstName2-LastName2-StudentID2"
#*(ie. Spring2025-Module5-John-Doe-201343-Jane-Doe-201243)

'''If you do not name your repo correctly, or share your repo with cse330, the TA's are not responsible for grading your assignment. If we cannot find it, you will receive a zero.'''

_________

# '''JavaScript Calculator (10 Points):'''
#* Calculator successfully adds, subtracts, multiplies, and divides numbers (3 points)
#* The result is automatically computed when a value in either field is changed (3 points)
#* Calculator is written entirely in pure, conventional JavaScript with no external libraries (4 points)*
#*: ''Note: be sure to fully separate content, appearance, and behavior. This means that you should '''not''' use the event attributes on the HTML elements like onclick, onchange, and onkeyup.''
# '''Weather Widget (15 Points):'''
#* Widget performs an AJAX request to fetch the current weather (4 points)
#* The HTML template is filled with the correct information, including an image (4 points)
#* Button to reload the weather widget (2 points)
#* Widget is written entirely in pure, conventional JavaScript with no external libraries (5 points)*
# '''AJAX Calendar (60 Points):'''
#* '''''Calendar View (10 Points):'''''
#** The calendar is displayed as a table grid with days as the columns and weeks as the rows, one month at a time (5 points)
#** The user can view different months as far in the past or future as desired (5 points)
#* '''''User and Event Management (25 Points):'''''
#** Events can be added, modified, and deleted (5 points)
#** Events have a title, date, and time (2 points)
#** Users can log into the site, and they cannot view or manipulate events associated with other users (8 points)
#**: ''Don't fall into the Abuse of Functionality trap! Check user credentials on the server side as well as on the client side.''
#** All actions are performed over AJAX, without ever needing to reload the page (10 points)
#* '''''Best Practices (20 Points):'''''
#** Code is well formatted and easy to read, with proper commenting (2 points)
#** If storing passwords, they are stored salted and encrypted; if using OpenID, you are storing the user's OpenID identifier in the database (2 points)
#** All AJAX requests that either contain sensitive information or modify something on the server are performed via POST, not GET (3 points)
#** Safe from XSS attacks; that is, all content is escaped on output (3 points)
#** Safe from SQL Injection attacks (2 points)
#** CSRF tokens are passed when editing or removing events (3 points)
#** Session cookie is HTTP-Only (3 points)
#** Page passes the W3C validator (2 points)
#** ''Extra Credit:'' Your code passes ''JSHint'' or ''JSLint'' (+3 bonus points)
#* '''''Usability (5 Points):'''''
#** Site is intuitive to use and navigate (4 points)
#** Site is visually appealing (1 point)
# '''Creative Portion (15 Points)'''
#* '''Additional Calendars Features (worth 15 points):''' Develop some additional features for the calendar, a few examples are provided below.
#** Users can tag an event with a particular category and enable/disable those tags in the calendar view. (5 points)
#** Users can share their calendar with additional users. (5 points)
#** Users can create group events that display on multiple users calendars (5 points)
#* '''Make sure to save a description of your creative portion, and a link to your server in your README.md file.'''
''* These points can be earned only if at least 3 other points have been earned in that category. This is to prevent these points from being "free."''

[[Category:Module 5]]
[[Category:Modules]]

Module 6

2016-09-12T15:11:55Z

Brian: /* Grading */

__NOTOC__
Module 6 builds upon the JavaScript skills you learned in Module 5.

== Reading ==

The following articles on the online class wiki textbook contain information that will help you complete the assignments.

* [[Node.JS]]
* [[Socket.IO]]

== Individual Assignments ==

=== Install Node.JS ===

Install Node.JS from Apt or Yum according to the instructions in the [[Node.JS]] guide.

=== Static File Server in Node.JS ===

The individual portion of Module 6 is short in order to give you enough time to complete the group portion.

# Copy the example code from the Node.JS guide into a file called ''static_server.js'' or something of that nature. Save it on your EC2 instance (but not in a place that Apache can serve!).
#: Ensure that you understand what the static file server script is doing…
# Make a directory parallel to ''static_server.js'' named ''static''.
# Change "<STATIC DIRECTORY NAME>" on line 11 of the static fileserver example code to reflect the name of the directory you just made.
# Save the following files in your ''static'' directory:
#* ''hello.txt'', a text file containing "Hello World"
#* ''brookings.jpg'', an image file you can download from here: http://classes.engineering.wustl.edu/cse330/content/brookings.jpg
#* ''college.html'', an HTML document based on the [[HTML and CSS#Quick and Easy Page Layout|Quick and Easy HTML Layout]] containing an image tag pointing to ''brookings.jpg''
#* ''phpinfo.php'', a PHP file containing the phpinfo command that generates a diagnostic page of the server:
#: <source lang="php"><?php phpinfo(); ?></source>
# Boot up your Node.JS static fileserver, and from your browser, load all four of the files you created in step 4.
#: Which ones work and which ones don't? Why might this be the case?

== Group Project ==

In the group portion of Module 6 you will create a multi-room chat server using Node.JS and Socket.IO.

This chat service will contain a main lobby where users sign on with a nickname and can communicate with each other. Users may also create chat rooms for other to join. The entire app should be displayed on a single webpage, listing the room you are in, all available rooms, and the users in the current room.

The single room chat server and client are provided here: [[Socket.IO]]

== Grading ==

We will be grading the following aspects of your work. There are 75 points total.

'''Assignments must be committed to Bitbucket by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. Assignments must be demoed within 4 days of the due date (Friday at 11:30 AM for Module 6). You are allowed to demo your assignment at TA office hours. However, after Friday at 11:30 AM, you will receive a 0 for the assignment, regardless of your time-stamp.'''

#''You must save your repo as:''
#*"<Season><year>-Module<#>-FirstName-LastName-StudentID"
#*(ie. Spring2025-Module3-John-Doe-201343)
#''For the group project, you must save your repo as:''
#*"<Season><year>-Module<#>-FirstName1-LastName1-StudentID1-FirstName2-LastName2-StudentID2"
#*(ie. Spring2025-Module5-John-Doe-201343-Jane-Doe-201243)

'''If you do not name your repo correctly, the TA's are not responsible for grading your assignment. If we cannot find it, you will receive a zero.'''

_________

# '''Individual Portion (25 Points):'''
#* Node.JS is installed on your EC2 instance (5 points)
#* The ''hello.txt'', ''brookings.jpg'', and ''college.html'' files all load successfully (4 points each)
#* Visiting a file that does not exist inside the ''static'' directory results in a 404 (4 points)
#* You can explain to the TA why ''phpinfo.php'' behaves the way it does when loaded through Node.JS (4 points)
# '''Multi-room Chat Server (50 Points):'''
#* '''''Administration of user created chat rooms (25 Points):'''''
#** Users can create chat rooms with an arbitrary room name(5 points)
#** Users can join an arbitrary chat room (5 points)
#** The chat room displays all users currently in the room (5 points)
#** A private room can be created that is password protected (5 points)
#** Creators of chat rooms can temporarily kick others out of the room (3 points)
#** Creators of chat rooms can permanently ban users from joining that particular room (2 points)
#* '''''Messaging (5 Points):'''''
#** A user's message shows their username and is sent to everyone in the room (1 point)
#** Users can send private messages to another user in the same room (4 points)
#* '''''Best Practices (5 Points):'''''
#** Code is well formatted and easy to read, with proper commenting (2 points)
#** Code passes HTML validation (2 points)
#** node_modules folder is ignored by version control (1 points)
#* '''''Usability (5 Points):'''''
#** Communicating with others and joining rooms is easy and intuitive (4 points)
#** Site is visually appealing (1 point)
# '''Creative Portion (10 Points)'''

[[Category:Module 6]]
[[Category:Modules]]

Apache

2016-09-09T22:15:30Z

Brian: /* The UserDir Module */

''Apache'' is the industry standard web server for Linux distributions. It is highly configurable and has a wide range of modules ready for different needs.

{{XKCD
|name=permanence
|id=910
}}

== What is a web server? ==

A web server is software that listens for connections to your machine, and when a connection is receive, processes the request and responds with the appropriate information. Most web servers listen on port 80, which is reserved for the purpose, and use the HTTP protocol.

For example, when you visit this wiki, you are sending a request over the internet to some machine that is probably located somewhere in EIT (the user seldom knows exactly where the machine is located). The web server receives your request, and it processes the data you sent. Finally, the server prepares a response (the web page), and sends it back to you.

== Installing Apache ==

{{RequiredInstructions|content=

In yum, Apache is distributed under the package name '''httpd''' (for ''hypertext transfer protocol daemon''). In apt, it is distributed under the name '''apache2'''. Use the package manager associated with your distribution to install Apache. (For more information on how to use yum and apt, see [[Linux#Repository-Based Package Managers|the Linux guide]].)

For example:

<source lang="bash">
# Debian version
$ sudo apt-get update
$ sudo apt-get install apache2

# RHEL version
$ sudo yum install httpd
</source>

When Apache is installed through apt, the HTTP Daemon will be automatically to added as a startup item. If you are using the Amazon AMI, you need to run this command to add Apache as a startup item:

<source lang="bash">
$ sudo /sbin/chkconfig --levels 235 httpd on # RHEL only
$
</source>

In RHEL, all Apache configurations are stored in ''/etc/httpd/conf/httpd.conf''. Debian takes a more modular approach, having separate directories for each type of configuration, all located in ''/etc/apache2/''. For more detail on Debian's approach, see http://www.control-escape.com/web/configuring-apache2-debian.html

}}

== Apache Directives ==

You define your settings for Apache using ''directives''. Some of the directives you will likely encounter include:

* '''DocumentRoot:''' The path to the directory where the top level web files are going to be stored.
* '''IfModule:''' The following block would be included if specified module exists.
* '''User:''' Which user apache2 will run as.
* '''Group:''' Which group will have group access to default web files.
* '''AccessFileName:''' The name of the access file (that specifies user names/passwords and other limitations to files/directories).
* '''ErrorLog:''' Where any errors will be written.
* '''Include:''' Include some other files.
* '''LogFormat:''' How to write a log message.
* '''ErrorDocument:''' Files to display for some HTTP errors (500, 404, 402 etc.).
* '''Alias:''' Map a directory URL to some other location on your filesystem. Requires that the ''Alias'' module be loaded.

=== .htaccess Files ===

You can also specify some Apache configurations without delving into the master configuration file. To do this, put a file named ''.htaccess'' in any directory that Apache is serving. All directives in it will be interpreted as if they were in a Directory directive in the master configuration file.

'''VERY IMPORTANT:''' The directory containing ''.htaccess'' must not have the '''AllowOverride None''' directive in the master configuration file in order for '''.htaccess''' to be read. In Debian, '''AllowOverride None''' is enabled by default! The Apache configuration file you need to edit in Debian is ''/etc/apache2/sites-available/default'' (remove the '''AllowOverride None''' located on line 11).

=== Directory Directive ===

Use the Directory directive to assign other directives to a specific directory. For example:

<source lang="apache">
<Directory /var/www/>
Options Indexes FollowSymLinks
AllowOverride None
Order allow,deny
allow from all
RedirectMatch ^/$ /apache2-default/
</Directory>
</source>

This sets options for the ''/var/www'' directory.
# The '''Options''' directive says that:
## If no index page is present in a directory, display a directory index page instead
## Apache will follow symbolic links in the directory
# '''AllowOverride None''' says that ''.htaccess'' files cannot alter the Apache options in this directory and all sub-directories
# '''Order allow,deny''' and '''Allow from all''' specifies that anybody is allowed to access this server via HTTP.

Note that this directory is actually the root directory of the web server.

== The UserDir Module ==

{{RequiredInstructions|content=

The UserDir module lets you access files for any user on the server with a ~, e.g., http://ec2-xxx-xxx-xxx-xx.compute-1.amazonaws.com/~paul/

This module comes installed, but not activated by default.

=== Enabling UserDir in Debian ===

If you are using a Debian-based distribution for your server (like Ubuntu Server), simply run the following command to enable the module:

<source lang="bash">
$ sudo a2enmod userdir
</source>

Then [[#Restarting Apache and Testing|restart Apache]] for the changes to take effect. Now, all users will be able to store their own personal web site in public_html inside their home directory.

To make sure everything is working, create a test file in your home directory under public_html, and then point your browser to it: http://ec2-xxx-xx-xx-xxx.compute-1.amazonaws.com/~yourUserName/hello.txt

'''Note:''' The UserDir configuration file, which already has all the correct settings, is located at ''/etc/apache2/mods-available/userdir.conf''

'''Note:''' Users need to manually create public_html. It is not created automatically.

=== Enabling UserDir in RHEL ===

If you are using an RHEL-based distribution for your server (like the Amazon AMI), you need to edit the master Apache configuration file.

Open ''/etc/httpd/conf/httpd.conf'' in your favorite text editor. For more information on command-line text editors, refer to [[Linux#File Editors|the Linux guide]].

Find the line that says

<source lang="apache">UserDir disabled</source>

and change it to

<source lang="apache">UserDir disabled root</source>

Additionally, find the line that says

<source lang="apache">#UserDir public_html</source>

and uncomment it; that is, remove the # so that you have

<source lang="apache">UserDir public_html</source>

This tells Apache that the directory containing each user's html files is a subdirectory of their home directory called public_html.

'''Note:''' Users need to manually create public_html. It is not created automatically.

You may also need to change the permissions of your user directory and your public_html directory to allow Apache to read and execute inside them. To do this, run the following commands:

<source lang="bash">
$ sudo chmod o+x /home/myusername
$ sudo chmod o+rx /home/myusername/public_html
$
</source>

Finally, [[#Restarting Apache and Testing|restart Apache]].

}}

=== Remapping UserDir ===

If you want to change the name of the UserDir web server root from '''public_html''' to something else like '''.html''', follow these instructions. (You do not need to do this for the purposes of CSE 330; this serves as a reference.)

# Rename your '''public_html''' to '''.html'''
#* The "." in front of the directory name means that the directory is a hidden one. You will not see it with the normal "ls" command. Use "ls -a" to see hidden files as well.
# Edit the UserDir configuration file.
#* In RHEL, edit the master Apache configuration file at ''/etc/httpd/conf/httpd.conf''
#* In Debian, edit the UserDir configuration file at ''/etc/apache2/mods-available/userdir.conf''
# Find the line that reads <code>UserDir public_html</code> and change it to <code>UserDir .html/</code>
# [[#Restarting Apache and Testing|Restart Apache]].

== Apache Logs ==

Apache creates two log files: one for all access attempts to your server, and one for errors. The locations of these log files are:

* '''Debian:'''
** '''Access Log:''' /var/log/apache2/access.log
** '''Error Log:''' /var/log/apache2/error.log
* '''RHEL:'''
** '''Access Log:''' /var/log/httpd/access_log
** '''Error Log:''' /var/log/httpd/error_log

You might find it helpful to see access and errors appear "live" in your terminal window as they are created. To do this, you can use the [[Linux#Command Reference|tail -f]] command. Since the log files have strict permissions, you will need to also use sudo. Example on Debian:

<source lang="bash">
$ sudo tail -f /var/log/apache2/error.log
</source>

== Virtual Hosts ==

'''Virtual Hosts''' are used to run multiple Apache web servers from the same machine. Virtual hosts can listen for connections on different ports and/or different hostnames, serving completely different web sites to each. For example:

<source lang="apache">
<VirtualHost cse330.dyndns.org>
ServerAdmin webmaster@localhost
ServerName cse330.dyndns.org
DocumentRoot /home/www/cse330/
ErrorLog /var/log/httpd/error_log
LogLevel warn
CustomLog /var/log/apache2/access_log combined
ServerSignature On
</VirtualHost>
</source>

This configuration enables any requests that use a host name of ''cse330.dyndns.org'' will use ''/home/www/cse330'' as the root document directory. Make sure that the DocumentRoot directory exists and is readable by the httpd process. In RHEL, Apache runs as the '''apache''' user. In Debian, it runs as the '''www-data''' user.

It is good practice to put raw server configuration files in ''/etc/httpd/sites-available'' in RHEL or ''/etc/apache2/sites-available'' in Debian. To activate a site, create a symlink from the configuration in ''sites-available'' to a sibling directory called ''sites-enabled''. In Debian, these directories are already set up for you, and Debian Apache even provides the '''a2ensite''' and '''a2dissite''' commands to create or destroy the symlinks! In RHEL, you have to do this by hand.

== Restarting Apache and Testing ==

Whenever you make changes to the Apache configuration files, you will need to restart Apache for the changes to take effect. There are several different ways to restart Apache; they all functionally do (almost) the same thing, so choose your favorite:

<source lang="bash">
$ sudo /usr/sbin/apachectl restart # works on both Debian and RHEL
$ sudo apachectl restart # if /usr/sbin is in your PATH (which it is by default in Debian, but not RHEL)
$ sudo /etc/init.d/httpd restart # on RHEL
$ sudo /etc/init.d/apache2 restart # on Debian
$ sudo /sbin/service httpd restart # on RHEL
$ sudo /usr/sbin/service apache2 restart # on Debian
$ sudo service httpd restart # on RHEL
$ sudo service apache2 restart # on Debian
</source>

If you're torn for which version is the "best" to use, the commands involving '''apachectl''' (think "Apache Control") are written by the Apache folks themselves. This has a couple advantages:
* They show you errors in the startup process (if there are any)
* They give you the option to perform a "soft" restart; that is, a restart that allows any pending connections to complete. To perform a soft restart, use ''graceful'': <code>sudo apachectl graceful</code>
In my anecdotal experience, the '''apachectl''' commands are also faster than the '''service''' or '''init.d''' commands.

To make sure everything is working, create a test file in your home directory under public_html, and then point your browser to it: http://ec2-xxx-xx-xx-xxx.compute-1.amazonaws.com/~yourUserName/hello.txt

[[Category:Module 2]]

Module 1

2016-09-09T20:35:12Z

Brian: /* Grading */

__NOTOC__
Module 1 introduces the fundamentals of HTML and CSS. You will first make a static document using HTML and CSS, and then you will make a portal to a DuckDuckGo search. This module is worth 50 points.

== Reading ==

The following articles on the online class wiki textbook contain information that will help you complete the assignment.

* [[HTML and CSS]]
* [[HTML Forms]]

== Assignments ==

=== Write a Birthday Card ===

'''Write a birthday card to a friend or family member using HTML and CSS.''' Use HTML to define the content of the card (like the headings and the paragraphs), and use CSS to define the appearance. Some ideas:

* Make the background-color of the page baby blue and use purple ink to write a card to a little boy
* Make the text big and include pictures of hearts
* Use a font with text shadows (more advanced)

Use this opportunity to experiment with the plethora of CSS properties. Remember that you're in a computer science class (not an art class), so we don't care if your card looks ugly. The main thing is that you learn HTML and CSS and use them appropriately.

==== How to Edit Your File ====

Starting in Module 2, we will be using Komodo Edit as our primary development tool. However, for the purposes of this exercise, we want you to edit your HTML file using a more basic text editor.

* On Windows, consider Notepad++. This is already installed for you in the CEC labs. If you prefer to use your personal computer, you can download it from [http://notepad-plus-plus.org/ here].
* On Mac OS X, consider TextWrangler. You can download it from [http://www.barebones.com/products/textwrangler/ here] or from the Apple App Store.
* Most Linux distributions come with gedit pre-installed, which you can use for this lab.

Please save your file as ''birthday.html'' from the plain text editor of your choice.

'''Important Note:''' Writing your web page in a word processor like Microsoft Word or even WordPad or TextEdit will ''not'' work. What you need is a plain text editor.

==== How to View Your HTML Document ====

Once you have ''birthday.html'', you can open it using your favorite web browser (like Firefox). For the purposes of this exercise, it suffices to right-click the file and tell it to "open with" Firefox. When the file opens, it should be under the file:/// protocol.

In Module 2, we will install a web server that serves up pages on the http:// protocol.

==== Validation ====

'''Your birthday card must pass the W3C Validator with no errors.''' From [http://validator.w3.org/ the validator], you can choose to upload your file.

For more information on validation, see the HTML and CSS guide: [[HTML and CSS#Validation]]

=== Make a Portal to a DuckDuckGo Search ===

'''Write an HTML document containing a form that searches DuckDuckGo's web site.''' You should be able to type in a search term and have your form load the DuckDuckGo search page.

# Visit [https://www.duckduckgo.com/ www.duckduckgo.com]. Search for something easy to spot in the URL, like "QUERY".
# Look at the URL of the search page. What is the script URL? What is the query variable?
# Make an HTML document containing a text field and a submit button. Typing a search query into the text field and pressing the submit button should load the DuckDuckGo search page.

== Grading ==

We will be grading the following aspects of your work. There are 50 points total.

'''Assignments must be committed to Bitbucket by the end of class on the due date (commit early and often). Failing to commit by the end of class on the due date will result in a 0. Assignments must be demoed within 4 days of the due date (Sunday at 11:30 AM for Module 1). You are allowed to demo your assignment at TA office hours. However, after Sunday at 11:30 AM, you will receive a 0 for the assignment, regardless of your time-stamp.'''

# '''Birthday Card (30 Points):'''
#* Correct usage of HTML and CSS in your birthday card (10 points).
#*: ''Make sure that you use HTML for "content" and CSS for "appearance." Don't write inline styles: use a separate stylesheet and link your HTML file to it.''
#* Experimenting with at least 5 different CSS properties in your birthday card (10 points).
#* Birthday card passes the W3C validation for the declared DOCTYPE (e.g., HTML 5) (10 points).
# '''Search Portal (10 Points):'''
#* DuckDuckGo search portal is functional (10 points).
# '''Account Creation and Version Control (10 Points):'''
#* Account Created on Amazon Web Services (5 Points)
#* Bitbucket account created (2 Points)
#* Files pushed to properly named private repo (ex. Fall2016-Module1-FirstName-LastName-StudentID) on Bitbucket using Git (2 Points)
#* Bitbucket repo shared with cse330 user (1 Point)

[[Category:Module 1]]
[[Category:Modules]]

Git

2016-05-03T07:16:24Z

Brian: Format new git ignore information

'''Git''' is a ''distributed version control system''. It enables you to:

# Keep track of revisions to your files
# Push and pull your revisions to other computers or servers
# Collaborate with other people on the same project

Subversion is the version control system you used in CSE 132. However, Subversion does not have the same agility of Git in terms of local revisions, staging, and collaboration. This guide aims to get you up to speed with the power of Git for multi-developer projects.

== Initializing Git ==

To initialize a Git repository inside of a folder, you can use Git's '''init''' command:

<source lang="bash">$ git init</source>

This will create a .git directory, where Git will store information about the repository. This command can be run either in an empty folder, or in a folder where files already exist.

== Local and Remote Branches ==

When you create a branch named "mybranch" on your local repository and ''push'' changes up to the remote repository, they actually get pushed to a remote branch called '''origin/mybranch'''. (Note that '''origin''' is the default name for a remote Git repository.) Even after your collaborators ''pull'' changes from remote to their local repositories, no new branches are created on their own personal local repositories.

Let's say that you and your partner are both working directly in the '''master''' branch (not a great idea for large or professional projects). When you ''push'' your changes up, they get saved in '''origin/master'''. When your partner goes and pulls changes from remote, if '''master''' is still her working copy, your changes will be immediately merged into her local '''master''' branch.

In practice, each collaborator will have their own branch, and when they make new versions of the features they are developing, they will merge those changes into '''master'''. (When '''master''' changes, each collaborator will merge the changes from '''master''' back into their personal branch.) What follows is an example that should help illustrate this process.

== Adding a Remote ==
A project that is being tracked with Git needs to be connected to a remote before files are pushed to version control. To add a remote to an initialized Git project, use the '''git remote add''' command:

<source lang="bash">git remote add origin \<repository URL\></source>

The origin remote is the default server that Git will push to.

== Staging ==

[[File:SourceTree-Staging.jpg|400px|thumb|right|Staging a file in SourceTree]]

Up to this point, you have been using SourceTree to automatically commit all changes. However, Git enables you to not commit every single file if you don't want to. This is where '''staging''' comes into play.

To add a file to the stage, use the '''add''' command:

<source lang="bash">$ git add <filename></source>

Then, when you run ''git commit'', only those files that have been staged will be updated.

'''Note:''' <code>git commit -a</code> commits all files, whether or not they had been staged. <code>git commit</code> (without the ''-a'') only commits those files in the staging area. It is a good idea to run '''git status''' before staging files to avoid staging files that should not be committed.

=== Ignoring Files in Git ===
Some files should not be committed to version control. Sensitive information such as SSH keys and files containing passwords should be ignored. Dependency folders such as node_modules should also be ignored; dependencies contain an enormous number of files that could change and will cause commit conflicts. . Rather, use the appropriate dependency manager to install those packages after cloning a repository (e.g. '''npm install'''). Folders containing virtual environments for frameworks such as Flask should also be ignored, and should instead be generated at will.

To add files to be ignored, edit your .gitignore file:

<source lang="bash">$ vim .gitignore</source>

In this file, add the file or folder to be ignored.

<source lang="text">
node_modules
venv
db_connect.php
</source>

=== Staging in SourceTree ===

Staging in SourceTree is very intuitive. However, before you can use this feature, you need to turn it on. (We had you turn of the staging feature in Module 2.)

# Go to the SourceTree preferences.
# Enter the Git pane.
# Check the box that says "Use the staging area".

You should now be able to use the staging area! In the "File Status View", you can drag and drop files back and forth between Staged and Unstaged. See the screenshot for an example.

== Commits ==

When you want to create a "snapshot" of your project, what you do in Git is called a ''commit''. The commit finds all files under version control, looks for ones that have been changed, and records the changes in a local archive. You learned how to perform a commit in SourceTree [[Workflow|in Module 2]].

If you need to determine what files have been changed since the last commit, you can use Git's '''status''' command:

<source lang="bash">$ git status</source>

In SourceTree, the results of ''git status'' are displayed nicely in the "File Status View".

== Branches and Merging ==

Git enables you to work on different features of the same software suite in isolation from each other. The way to do this is using '''branches'''.

[[File:SourceTree-Checkout.jpg|400px|thumb|right|Checking out an existing branch in SourceTree]]

To create a new branch, use the '''checkout -b''' command:

<source lang="bash">$ git checkout -b my-new-branch</source>

Now, when you next commit, you will be committing to the '''my-new-branch''' branch rather than the default '''master''' branch.

To switch the working copy over to a different branch, use the '''checkout''' command:

<source lang="bash">$ git checkout my-existing-branch</source>

See the screenshot for how to checkout a branch in SourceTree.

To merge changes from a different branch to the current working copy, use the '''merge''' command:

<source lang="bash">$ git merge my-existing-branch</source>

After you merge, if you wish to terminate a branch, use the '''branch -d''' command:

<source lang="bash">$ git branch -d my-existing-branch</source>

Git also has another command called '''rebase''', which is similar to '''merge''' except that it combines the commits of each branch into a single branch, but still keeping the head of each branch. For more information on ''rebase'', read [http://blog.sourcetreeapp.com/2012/08/21/merge-or-rebase/ this article on the SourceTree blog].

This will all make more sense when we go through an example. We will also be using SourceTree in the example.

== Example: Staging and Branches ==

Suppose I have three files under version control: apple.txt, banana.txt, and carrot.txt. The contents is like so (Thanks to [http://www.sumitkhemka.com/ Sumit Khemka] for the humor):

* '''apple.txt:''' How do you make an apple turnover? Push it downhill!
* '''banana.txt:''' What is a ghost's favorite fruit? A boonanaa!
* '''carrot.txt:''' How do you make a soup rich? Add 14 carats to it!

All files have been committed to the HEAD, which is by default the '''master''' branch:

<source lang="bash">
$ git add -A; git commit
...
$ git status
# On branch master
nothing to commit, working directory clean
</source>

=== Staging ===

Now, let's change the Apple joke, and keep the Banana and the Carrot the same:

* '''apple.txt:''' What kind of apple has a short temper? A crab apple!

We can see in Git and SourceTree that there is one file changed: apple.txt.

<source lang="bash">$ git status
# On branch master
# Changes not staged for commit:
# (use "git add <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
#
# modified: apple.txt
#
</source>

[[File:SourceTree-Branching.jpg|400px|thumb|right|Creating a new branch using SourceTree]]

Let's go ahead and stage our file:

<source lang="bash">$ git add apple.txt</source>

In SourceTree, drag a file from the "working tree" pane to the "files staged in index" pane to stage the file.

=== Branching ===

But now, instead of committing this change directly to our '''master''' branch, let's make a new branch, and let's call it '''apple-branch'''.

In SourceTree, press the "Branch" button to bring up a little dialog box. See the screenshot for an example.

If we were using the command line, the command would be:

<source lang="bash">$ git checkout -b apple-branch</source>

Here is what we now see when we run '''git status''':

<source lang="bash">
$ git status
# On branch apple-branch
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
#
# modified: apple.txt
#
</source>

Let's now go ahead and commit the changes:

[[File:SourceTree-ExampleAppleBranch.jpg|400px|thumb|right|Our current tree structure in SourceTree]]

<source lang="bash">
$ git commit -m "First Apple Commit"
[apple-branch c2c1738] First Apple Commit
1 file changed, 1 insertion(+), 1 deletion(-)
</source>

In SourceTree, run the commit as you have been doing in Modules 2-4.

Let's now make a second branch. This branch is going to be rooted at the current version of the '''master''' branch, which of course is still the three original jokes. To switch back to the '''master''' branch, we use the '''checkout''' command:

<source lang="bash">
$ git checkout master
Switched to branch 'master'
</source>

In SourceTree, press the "Checkout" button, and choose the revision or branch that you want to checkout; see the screenshot for an example.

We will now make a revision to the Banana joke:

* '''banana.txt:''' What would you call two bananas? A pair of slippers!

Let's change the file, stage it, and see the current status.

<source lang="bash">
$ git add -A
$ git status
# On branch master
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
#
# modified: banana.txt
#
</source>

We will now create another new branch, and commit our changes to it.

<source lang="bash">
$ git checkout -b banana-branch
$ git commit -m "First Banana Commit"
[banana-branch f876aac] First Banana Commit
1 file changed, 1 insertion(+), 1 deletion(-)
</source>

We can see all branches using '''git branch -v''':

<source lang="bash">
$ git branch -v
apple-branch c2c1738 First Apple Commit
* banana-branch f876aac First Banana Commit
master b770092 Initial Commit
</source>

However, this is where a GUI like SourceTree really comes in handy. Here is what you now see in the Log View:

[[File:SourceTree-ViewBranches.jpg]]

Nifty!

=== Merging ===

Okay, so now we want to take the two newest Apple and Banana jokes and merge them both back into '''master'''. Let's first merge in '''banana-branch'''. We can do this using the '''merge''' command:

<source lang="bash">
$ git checkout master
Switched to branch 'master'
$ git merge banana-branch
Updating b770092..f876aac
Fast-forward
banana.txt | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
</source>

'''''WHEN YOU MERGE, YOU TAKE THE CHANGES FROM THE SPECIFIED BRANCH AND MERGE THEM INTO THE CURRENT WORKING BRANCH.''''' It is easy to get this mixed up. Think of it this way: the currently "open" branch is the only one that will get changed when you perform the merge.

[[File:SourceTree-Merge.jpg|400px|thumb|right|Merging '''apple-branch''' into '''master''']]

We now have the original Apple joke and the new Banana joke in the '''master''' branch.

Now let's merge in '''apple-branch'''. We can use the command line to do it, but let's see how it works in SourceTree. First press the "Merge" button in the toolbar. You will see a window like the one shown in the screenshot to the right. If everything looks good, press "OK" to perform the merge.

We now have both of the new jokes in our '''master''' branch:

<source lang="bash">
$ cat apple.txt
What kind of apple has a short temper? A crab apple!
$ cat banana.txt
What would you call two bananas? A pair of slippers!
$ cat carrot.txt
How do you make a soup rich? Add 14 carats to it!
</source>

Okay, so we are now happy with our Apple joke. Let's ''close'' that branch so that it doesn't show up in the list any more:

<source lang="bash">
$ git branch -d apple-branch
Deleted branch apple-branch (was c2c1738).
$ git branch -v
banana-branch f876aac First Banana Commit
* master 5159c4e Merge branch 'apple-branch'
</source>

Let's switch back to our banana branch, make a new joke, and commit that change to the banana branch:

<source lang="bash">
$ git checkout banana-branch
Switched to branch 'banana-branch'
$ echo 'What is the easiest way to make a banana split? Cut it in half!' > banana.txt
$ git commit -am 'Further revising our Banana joke'
[banana-branch cf6a894] Further revising our Banana joke
1 file changed, 1 insertion(+), 1 deletion(-)
</source>

Remember that '''git commit -a''' is shorthand for '''git add -A''' followed by a plain '''git commit''' in most cases.

But guess what: we changed our mind again! Let's try an ''even better'' banana joke. This time, I made the change using GUI tools:

# Open '''banana.txt''' in your favorite text editor and make the joke say, "Why are bananas never lonely? Because they hang around in bunches!"
# In SourceTree, press "Commit" in the toolbar
# Drag the file to the "Stage" pane, type a commit message like "The best banana joke ever!", and press "Commit"

Finally, let's merge our greatest Banana joke into '''master''' and close up '''banana-branch'''. Here is how to do it in SourceTree:

# Checkout '''master'''
# Press "Merge" in the toolbar
# Select '''banana-branch''' and press "Merge"
# To delete the branch, press "Branch" and then "Delete Branch" in the toolbar
# Select '''banana-branch''' only, press "Delete Branches", and when asked to confirm, press "OK"

We now have the three newest jokes in our '''master''' branch, and all other branches have been cleaned up.

After performing all of the steps in this example, here is how the tree looks in SourceTree:

[[File:SourceTree-Tree.jpg]]

== Conflicts ==

It might be the case that you inadvertently edit the same file on two different branches. If you do, when you merge one branch into another, a '''merge conflict''' will occur.

=== Example ===

Suppose both Apple and Banana change the Carrot joke:

<source lang="bash">
# Change the file in the Apple branch
$ git checkout apple-branch
Switched to branch 'apple-branch'
$ cat carrot.txt
How do you make a soup rich? Add 14 carats to it!
$ echo 'What\'s a Vegetable\'s favourite martial art? Carrotee!' > carrot.txt
$ git commit -am "Apple changing carrot joke"
[apple-branch f76f247] Apple changing carrot joke
1 file changed, 1 insertion(+), 1 deletion(-)

# Change the file in the Banana branch
$ git checkout banana-branch
Switched to branch 'banana-branch'
$ cat carrot.txt
How do you make a soup rich? Add 14 carats to it!
$ echo 'Why did the carrot get an award? Because he was outstanding in his field!' > carrot.txt
$ git commit -am "Banana changing carrot joke"
[banana-branch f565381] Banana changing carrot joke
1 file changed, 1 insertion(+), 1 deletion(-)

# Attempt to merge into master
$ git checkout master
Switched to branch 'master'
$ git merge apple-branch
Updating 7ed050b..f76f247
Fast-forward
carrot.txt | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
$ git merge banana-branch
Auto-merging carrot.txt
CONFLICT (content): Merge conflict in carrot.txt
Automatic merge failed; fix conflicts and then commit the result.
</source>

Yikes! What do we do next?

=== Resolving Merge Conflicts ===

There are two main ways to resolve merge conflicts: by manually editing the file and choosing the lines of code you want to keep, or by choosing one version of the file and replacing the other entirely.

==== Manually Editing the Conflicted File ====

When you open the file after running <code>git merge banana-branch</code> above, you will see something like this:

<source lang="text">
<<<<<<< HEAD
What's a Vegetable's favourite martial art? Carrotee!
=======
Why did the carrot get an award? Because he was outstanding in his field!
>>>>>>> banana-branch
</source>

Git added this notation to help you find which parts of the file were from the current branch (HEAD) and which ones were from the foreign branch (banana-branch). Simply edit the file to reflect the version you prefer, and then commit.

<source lang="bash">
$ emacs carrot.txt # edit the file to reflect the joke you want
$ cat carrot.txt # optionally check to make sure you've got the right version
Why did the carrot get an award? Because he was outstanding in his field!
$ git commit -am "Resolving conflict"
[master 98ba901] Resolving conflict
</source>

==== Keeping One Version and Replacing the Other ====

Git provides commands that will merge a file from a branch.

* If you want to keep the version in the current branch and ignore the version coming from the foreign branch, run <code>git checkout --ours carrot.txt</code>
* If you want to keep the version coming from the foreign branch and ignore the version in the current branch, run <code>git checkout --theirs carrot.txt</code>

Here is an example where we keep Banana's version of the joke:

<source lang="bash">
$ git checkout --theirs carrot.txt
$ cat carrot.txt # optionally check to make sure you've got the right version
Why did the carrot get an award? Because he was outstanding in his field!
$ git commit -am "Resolving conflict"
[master 1669536] Resolving conflict
</source>

Here is an example where we keep the existing version of the joke, which is Apple's version since we had already merged Apple into master:

<source lang="bash">
$ git checkout --ours carrot.txt
$ cat carrot.txt # optionally check to make sure you've got the right version
What's a Vegetable's favourite martial art? Carrotee!
$ git commit -am "Resolving conflict"
[master 1fdcd7b] Resolving conflict
</source>

'''Tip:''' If you are using SourceTree, you can right-click the conflicted file in the file browser and select "keep mine" or "keep theirs".

== Collaboration ==

Using Git's powerful branch and merge tools are ideal for team collaboration.

=== Collaboration Example ===

Here's the idea: everyone working on a feature has their own branch. Changes from each developer's branch are periodically merged in to the '''master''' branch, and developers periodically merge other people's changes from the '''master''' branch into their own branch. When the feature is complete and bug-free, the branch is closed.

Suppose there are three developers on a project: Susan, Caroline, and Rachel. They each have their own branch and are developing separate features. Susan is ready to merge her changes into '''master'''. Here is what might happen:

# Susan ''checks out'' the '''master''' branch locally.
# Susan ''pulls'' any changes that might be on '''origin/master''' into her local copy of '''master'''.
# Susan ''merges'' relevant changes from her branch into '''master'''.
# Susan ''checks out'' her own branch again.
# Susan ''pushes'' her repo updates to the remote repository.
# Caroline and Rachel ''check out'' the '''master''' branch locally.
# Caroline and Rachel ''pull'' the changes from '''origin/master''' to '''master'''.
# Caroline and Rachel ''check out'' their own branches locally.
# Caroline and Rachel ''merge'' '''master''' into their respective branches.
# Finally, Caroline and Rachel ''push'' everything up to the remote repository.

This can be a cumbersome process, but it is important that you perform it at least once per working session to ensure that everyone's branches are up-to-date.

=== Alternatives ===

Fortunately for us, there exist developers who have created additional command-line utilities that automate the above process. One such project is '''[https://github.com/aanand/git-up git-up]'''. You and your partner may elect to use '''git-up''' instead of manual branching and merging.

[[Category:Module 5]]

Git

2016-05-03T07:15:02Z

Brian:

'''Git''' is a ''distributed version control system''. It enables you to:

# Keep track of revisions to your files
# Push and pull your revisions to other computers or servers
# Collaborate with other people on the same project

Subversion is the version control system you used in CSE 132. However, Subversion does not have the same agility of Git in terms of local revisions, staging, and collaboration. This guide aims to get you up to speed with the power of Git for multi-developer projects.

== Initializing Git ==

To initialize a Git repository inside of a folder, you can use Git's '''init''' command:

<source lang="bash">$ git init</source>

This will create a .git directory, where Git will store information about the repository. This command can be run either in an empty folder, or in a folder where files already exist.

=== Local and Remote Branches ===

When you create a branch named "mybranch" on your local repository and ''push'' changes up to the remote repository, they actually get pushed to a remote branch called '''origin/mybranch'''. (Note that '''origin''' is the default name for a remote Git repository.) Even after your collaborators ''pull'' changes from remote to their local repositories, no new branches are created on their own personal local repositories.

Let's say that you and your partner are both working directly in the '''master''' branch (not a great idea for large or professional projects). When you ''push'' your changes up, they get saved in '''origin/master'''. When your partner goes and pulls changes from remote, if '''master''' is still her working copy, your changes will be immediately merged into her local '''master''' branch.

In practice, each collaborator will have their own branch, and when they make new versions of the features they are developing, they will merge those changes into '''master'''. (When '''master''' changes, each collaborator will merge the changes from '''master''' back into their personal branch.) What follows is an example that should help illustrate this process.

=== Adding a Remote ===
A project that is being tracked with Git needs to be connected to a remote before files are pushed to version control. To add a remote to an initialized Git project, use the '''git remote add''' command:

<source lang="bash">git remote add origin \<repository URL\></source>

The origin remote is the default server that Git will push to.

== Staging ==

[[File:SourceTree-Staging.jpg|400px|thumb|right|Staging a file in SourceTree]]

Up to this point, you have been using SourceTree to automatically commit all changes. However, Git enables you to not commit every single file if you don't want to. This is where '''staging''' comes into play.

To add a file to the stage, use the '''add''' command:

<source lang="bash">$ git add <filename></source>

Then, when you run ''git commit'', only those files that have been staged will be updated.

'''Note:''' <code>git commit -a</code> commits all files, whether or not they had been staged. <code>git commit</code> (without the ''-a'') only commits those files in the staging area. It is a good idea to run '''git status''' before staging files to avoid staging files that should not be committed.

=== Ignoring Files in Git ===
Some files should not be committed to version control. Sensitive information such as SSH keys and files containing passwords should be ignored. Dependency folders such as node_modules should also be ignored; dependencies contain an enormous number of files that could change and will cause commit conflicts. . Rather, use the appropriate dependency manager to install those packages after cloning a repository (e.g. '''npm install'''). Folders containing virtual environments for frameworks such as Flask should also be ignored, and should instead be generated at will.

To add files to be ignored, edit your .gitignore file:

<source lang="bash">$ vim .gitignore</source>

In this file, add the file or folder to be ignored.

<source lang="text">
node_modules
venv
db_connect.php
</source>

=== Staging in SourceTree ===

Staging in SourceTree is very intuitive. However, before you can use this feature, you need to turn it on. (We had you turn of the staging feature in Module 2.)

# Go to the SourceTree preferences.
# Enter the Git pane.
# Check the box that says "Use the staging area".

You should now be able to use the staging area! In the "File Status View", you can drag and drop files back and forth between Staged and Unstaged. See the screenshot for an example.

== Commits ==

When you want to create a "snapshot" of your project, what you do in Git is called a ''commit''. The commit finds all files under version control, looks for ones that have been changed, and records the changes in a local archive. You learned how to perform a commit in SourceTree [[Workflow|in Module 2]].

If you need to determine what files have been changed since the last commit, you can use Git's '''status''' command:

<source lang="bash">$ git status</source>

In SourceTree, the results of ''git status'' are displayed nicely in the "File Status View".

== Branches and Merging ==

Git enables you to work on different features of the same software suite in isolation from each other. The way to do this is using '''branches'''.

[[File:SourceTree-Checkout.jpg|400px|thumb|right|Checking out an existing branch in SourceTree]]

To create a new branch, use the '''checkout -b''' command:

<source lang="bash">$ git checkout -b my-new-branch</source>

Now, when you next commit, you will be committing to the '''my-new-branch''' branch rather than the default '''master''' branch.

To switch the working copy over to a different branch, use the '''checkout''' command:

<source lang="bash">$ git checkout my-existing-branch</source>

See the screenshot for how to checkout a branch in SourceTree.

To merge changes from a different branch to the current working copy, use the '''merge''' command:

<source lang="bash">$ git merge my-existing-branch</source>

After you merge, if you wish to terminate a branch, use the '''branch -d''' command:

<source lang="bash">$ git branch -d my-existing-branch</source>

Git also has another command called '''rebase''', which is similar to '''merge''' except that it combines the commits of each branch into a single branch, but still keeping the head of each branch. For more information on ''rebase'', read [http://blog.sourcetreeapp.com/2012/08/21/merge-or-rebase/ this article on the SourceTree blog].

This will all make more sense when we go through an example. We will also be using SourceTree in the example.

== Example: Staging and Branches ==

Suppose I have three files under version control: apple.txt, banana.txt, and carrot.txt. The contents is like so (Thanks to [http://www.sumitkhemka.com/ Sumit Khemka] for the humor):

* '''apple.txt:''' How do you make an apple turnover? Push it downhill!
* '''banana.txt:''' What is a ghost's favorite fruit? A boonanaa!
* '''carrot.txt:''' How do you make a soup rich? Add 14 carats to it!

All files have been committed to the HEAD, which is by default the '''master''' branch:

<source lang="bash">
$ git add -A; git commit
...
$ git status
# On branch master
nothing to commit, working directory clean
</source>

=== Staging ===

Now, let's change the Apple joke, and keep the Banana and the Carrot the same:

* '''apple.txt:''' What kind of apple has a short temper? A crab apple!

We can see in Git and SourceTree that there is one file changed: apple.txt.

<source lang="bash">$ git status
# On branch master
# Changes not staged for commit:
# (use "git add <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
#
# modified: apple.txt
#
</source>

[[File:SourceTree-Branching.jpg|400px|thumb|right|Creating a new branch using SourceTree]]

Let's go ahead and stage our file:

<source lang="bash">$ git add apple.txt</source>

In SourceTree, drag a file from the "working tree" pane to the "files staged in index" pane to stage the file.

=== Branching ===

But now, instead of committing this change directly to our '''master''' branch, let's make a new branch, and let's call it '''apple-branch'''.

In SourceTree, press the "Branch" button to bring up a little dialog box. See the screenshot for an example.

If we were using the command line, the command would be:

<source lang="bash">$ git checkout -b apple-branch</source>

Here is what we now see when we run '''git status''':

<source lang="bash">
$ git status
# On branch apple-branch
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
#
# modified: apple.txt
#
</source>

Let's now go ahead and commit the changes:

[[File:SourceTree-ExampleAppleBranch.jpg|400px|thumb|right|Our current tree structure in SourceTree]]

<source lang="bash">
$ git commit -m "First Apple Commit"
[apple-branch c2c1738] First Apple Commit
1 file changed, 1 insertion(+), 1 deletion(-)
</source>

In SourceTree, run the commit as you have been doing in Modules 2-4.

Let's now make a second branch. This branch is going to be rooted at the current version of the '''master''' branch, which of course is still the three original jokes. To switch back to the '''master''' branch, we use the '''checkout''' command:

<source lang="bash">
$ git checkout master
Switched to branch 'master'
</source>

In SourceTree, press the "Checkout" button, and choose the revision or branch that you want to checkout; see the screenshot for an example.

We will now make a revision to the Banana joke:

* '''banana.txt:''' What would you call two bananas? A pair of slippers!

Let's change the file, stage it, and see the current status.

<source lang="bash">
$ git add -A
$ git status
# On branch master
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
#
# modified: banana.txt
#
</source>

We will now create another new branch, and commit our changes to it.

<source lang="bash">
$ git checkout -b banana-branch
$ git commit -m "First Banana Commit"
[banana-branch f876aac] First Banana Commit
1 file changed, 1 insertion(+), 1 deletion(-)
</source>

We can see all branches using '''git branch -v''':

<source lang="bash">
$ git branch -v
apple-branch c2c1738 First Apple Commit
* banana-branch f876aac First Banana Commit
master b770092 Initial Commit
</source>

However, this is where a GUI like SourceTree really comes in handy. Here is what you now see in the Log View:

[[File:SourceTree-ViewBranches.jpg]]

Nifty!

=== Merging ===

Okay, so now we want to take the two newest Apple and Banana jokes and merge them both back into '''master'''. Let's first merge in '''banana-branch'''. We can do this using the '''merge''' command:

<source lang="bash">
$ git checkout master
Switched to branch 'master'
$ git merge banana-branch
Updating b770092..f876aac
Fast-forward
banana.txt | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
</source>

'''''WHEN YOU MERGE, YOU TAKE THE CHANGES FROM THE SPECIFIED BRANCH AND MERGE THEM INTO THE CURRENT WORKING BRANCH.''''' It is easy to get this mixed up. Think of it this way: the currently "open" branch is the only one that will get changed when you perform the merge.

[[File:SourceTree-Merge.jpg|400px|thumb|right|Merging '''apple-branch''' into '''master''']]

We now have the original Apple joke and the new Banana joke in the '''master''' branch.

Now let's merge in '''apple-branch'''. We can use the command line to do it, but let's see how it works in SourceTree. First press the "Merge" button in the toolbar. You will see a window like the one shown in the screenshot to the right. If everything looks good, press "OK" to perform the merge.

We now have both of the new jokes in our '''master''' branch:

<source lang="bash">
$ cat apple.txt
What kind of apple has a short temper? A crab apple!
$ cat banana.txt
What would you call two bananas? A pair of slippers!
$ cat carrot.txt
How do you make a soup rich? Add 14 carats to it!
</source>

Okay, so we are now happy with our Apple joke. Let's ''close'' that branch so that it doesn't show up in the list any more:

<source lang="bash">
$ git branch -d apple-branch
Deleted branch apple-branch (was c2c1738).
$ git branch -v
banana-branch f876aac First Banana Commit
* master 5159c4e Merge branch 'apple-branch'
</source>

Let's switch back to our banana branch, make a new joke, and commit that change to the banana branch:

<source lang="bash">
$ git checkout banana-branch
Switched to branch 'banana-branch'
$ echo 'What is the easiest way to make a banana split? Cut it in half!' > banana.txt
$ git commit -am 'Further revising our Banana joke'
[banana-branch cf6a894] Further revising our Banana joke
1 file changed, 1 insertion(+), 1 deletion(-)
</source>

Remember that '''git commit -a''' is shorthand for '''git add -A''' followed by a plain '''git commit''' in most cases.

But guess what: we changed our mind again! Let's try an ''even better'' banana joke. This time, I made the change using GUI tools:

# Open '''banana.txt''' in your favorite text editor and make the joke say, "Why are bananas never lonely? Because they hang around in bunches!"
# In SourceTree, press "Commit" in the toolbar
# Drag the file to the "Stage" pane, type a commit message like "The best banana joke ever!", and press "Commit"

Finally, let's merge our greatest Banana joke into '''master''' and close up '''banana-branch'''. Here is how to do it in SourceTree:

# Checkout '''master'''
# Press "Merge" in the toolbar
# Select '''banana-branch''' and press "Merge"
# To delete the branch, press "Branch" and then "Delete Branch" in the toolbar
# Select '''banana-branch''' only, press "Delete Branches", and when asked to confirm, press "OK"

We now have the three newest jokes in our '''master''' branch, and all other branches have been cleaned up.

After performing all of the steps in this example, here is how the tree looks in SourceTree:

[[File:SourceTree-Tree.jpg]]

== Conflicts ==

It might be the case that you inadvertently edit the same file on two different branches. If you do, when you merge one branch into another, a '''merge conflict''' will occur.

=== Example ===

Suppose both Apple and Banana change the Carrot joke:

<source lang="bash">
# Change the file in the Apple branch
$ git checkout apple-branch
Switched to branch 'apple-branch'
$ cat carrot.txt
How do you make a soup rich? Add 14 carats to it!
$ echo 'What\'s a Vegetable\'s favourite martial art? Carrotee!' > carrot.txt
$ git commit -am "Apple changing carrot joke"
[apple-branch f76f247] Apple changing carrot joke
1 file changed, 1 insertion(+), 1 deletion(-)

# Change the file in the Banana branch
$ git checkout banana-branch
Switched to branch 'banana-branch'
$ cat carrot.txt
How do you make a soup rich? Add 14 carats to it!
$ echo 'Why did the carrot get an award? Because he was outstanding in his field!' > carrot.txt
$ git commit -am "Banana changing carrot joke"
[banana-branch f565381] Banana changing carrot joke
1 file changed, 1 insertion(+), 1 deletion(-)

# Attempt to merge into master
$ git checkout master
Switched to branch 'master'
$ git merge apple-branch
Updating 7ed050b..f76f247
Fast-forward
carrot.txt | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
$ git merge banana-branch
Auto-merging carrot.txt
CONFLICT (content): Merge conflict in carrot.txt
Automatic merge failed; fix conflicts and then commit the result.
</source>

Yikes! What do we do next?

=== Resolving Merge Conflicts ===

There are two main ways to resolve merge conflicts: by manually editing the file and choosing the lines of code you want to keep, or by choosing one version of the file and replacing the other entirely.

==== Manually Editing the Conflicted File ====

When you open the file after running <code>git merge banana-branch</code> above, you will see something like this:

<source lang="text">
<<<<<<< HEAD
What's a Vegetable's favourite martial art? Carrotee!
=======
Why did the carrot get an award? Because he was outstanding in his field!
>>>>>>> banana-branch
</source>

Git added this notation to help you find which parts of the file were from the current branch (HEAD) and which ones were from the foreign branch (banana-branch). Simply edit the file to reflect the version you prefer, and then commit.

<source lang="bash">
$ emacs carrot.txt # edit the file to reflect the joke you want
$ cat carrot.txt # optionally check to make sure you've got the right version
Why did the carrot get an award? Because he was outstanding in his field!
$ git commit -am "Resolving conflict"
[master 98ba901] Resolving conflict
</source>

==== Keeping One Version and Replacing the Other ====

Git provides commands that will merge a file from a branch.

* If you want to keep the version in the current branch and ignore the version coming from the foreign branch, run <code>git checkout --ours carrot.txt</code>
* If you want to keep the version coming from the foreign branch and ignore the version in the current branch, run <code>git checkout --theirs carrot.txt</code>

Here is an example where we keep Banana's version of the joke:

<source lang="bash">
$ git checkout --theirs carrot.txt
$ cat carrot.txt # optionally check to make sure you've got the right version
Why did the carrot get an award? Because he was outstanding in his field!
$ git commit -am "Resolving conflict"
[master 1669536] Resolving conflict
</source>

Here is an example where we keep the existing version of the joke, which is Apple's version since we had already merged Apple into master:

<source lang="bash">
$ git checkout --ours carrot.txt
$ cat carrot.txt # optionally check to make sure you've got the right version
What's a Vegetable's favourite martial art? Carrotee!
$ git commit -am "Resolving conflict"
[master 1fdcd7b] Resolving conflict
</source>

'''Tip:''' If you are using SourceTree, you can right-click the conflicted file in the file browser and select "keep mine" or "keep theirs".

== Collaboration ==

Using Git's powerful branch and merge tools are ideal for team collaboration.

=== Collaboration Example ===

Here's the idea: everyone working on a feature has their own branch. Changes from each developer's branch are periodically merged in to the '''master''' branch, and developers periodically merge other people's changes from the '''master''' branch into their own branch. When the feature is complete and bug-free, the branch is closed.

Suppose there are three developers on a project: Susan, Caroline, and Rachel. They each have their own branch and are developing separate features. Susan is ready to merge her changes into '''master'''. Here is what might happen:

# Susan ''checks out'' the '''master''' branch locally.
# Susan ''pulls'' any changes that might be on '''origin/master''' into her local copy of '''master'''.
# Susan ''merges'' relevant changes from her branch into '''master'''.
# Susan ''checks out'' her own branch again.
# Susan ''pushes'' her repo updates to the remote repository.
# Caroline and Rachel ''check out'' the '''master''' branch locally.
# Caroline and Rachel ''pull'' the changes from '''origin/master''' to '''master'''.
# Caroline and Rachel ''check out'' their own branches locally.
# Caroline and Rachel ''merge'' '''master''' into their respective branches.
# Finally, Caroline and Rachel ''push'' everything up to the remote repository.

This can be a cumbersome process, but it is important that you perform it at least once per working session to ensure that everyone's branches are up-to-date.

=== Alternatives ===

Fortunately for us, there exist developers who have created additional command-line utilities that automate the above process. One such project is '''[https://github.com/aanand/git-up git-up]'''. You and your partner may elect to use '''git-up''' instead of manual branching and merging.

[[Category:Module 5]]