diff --git a/Home.md b/Home.md index 473c202..f463d50 100644 --- a/Home.md +++ b/Home.md @@ -1,32 +1,6 @@ ![](images/cover-art.png) -[]{#navigation-document.xhtml} - -:::: {#navigation-document.xhtml_page} -::: {#navigation-document.xhtml_content} - -```{=html} - -``` - -::: -:::: - -[]{#introduction.xhtml} - -:::: {#introduction.xhtml_page} -::: {#introduction.xhtml_content} - -# Introduction {#introduction.xhtml_introduction} +# Introduction Git is a version control system (VCS) created for a single task: managing changes to your files. It lets you track every change a @@ -34,13 +8,13 @@ software project goes through, as well as where those changes came from. This makes Git an essential tool for managing large projects, but it can also open up a vast array of possibilities for your personal workflow. -## A Brief History of Revision Control {#introduction.xhtml_a-brief-history-of-revision-control} +## A Brief History of Revision Control We'll talk more about the core philosophy behind Git in a moment, but first, let's step through the evolution of version control systems in general. -### Files and Folders {#introduction.xhtml_files-and-folders} +### Files and Folders Before the advent of revision control software, there were only files and folders. The only way to track revisions of a project was to copy @@ -56,7 +30,7 @@ a folder? Or if you overwrite the wrong file? How would you even know that you lost an important piece of code? It didn't take long for software developers to realize they needed something more reliable. -### Local VCS {#introduction.xhtml_local-vcs} +### Local VCS So, developers began writing utility programs dedicated to managing file revisions. Instead of keeping old versions as independent files, these @@ -72,7 +46,7 @@ At this point, versioning only took place on the developer's _local_ computer---there was no way to efficiently share code amongst several programmers. -### Centralized VCS {#introduction.xhtml_centralized-vcs} +### Centralized VCS Enter the centralized version control system (CVCS). Instead of storing project history on the developer's hard disk, these new CVCS programs @@ -98,7 +72,7 @@ updates everyday: development couldn't continue until all merge conflicts were resolved and made available to the entire development team. -### Distributed VCS {#introduction.xhtml_distributed-vcs} +### Distributed VCS The next generation of revision control programs shifted away from the idea of a single centralized repository, opting instead to give every @@ -122,7 +96,7 @@ had a complete copy of the project, the risk of a server crash, a corrupted repository, or any other type of data loss was much lower than that of their CVCS predecessors. -## The Birth of Git {#introduction.xhtml_the-birth-of-git} +## The Birth of Git And so, we arrive at Git, a distributed version control system created to manage the Linux kernel. In 2005, the Linux community lost their free @@ -152,7 +126,7 @@ distributed version control. With this in mind, we'll be sticking to the command-line interface, which is still the most common way to interact with Git. -## Installation {#introduction.xhtml_installation} +## Installation The upcoming modules will explore Git's features by applying commands to real-world scenarios. But first, you'll need a working Git installation @@ -166,22 +140,17 @@ normal shell. To test your installation, open a new command prompt and run `git --version`. It should output something like `git version 1.7.10.2 (Apple Git-33)`. -## Get Ready! {#introduction.xhtml_get-ready} +## Get Ready Remember that _Ry's Git Tutorial_ is designed to _demonstrate_ Git's feature set, not just give you a superficial overview of the most common commands. To get the most out of this tutorial, it's important to actually execute the commands you're reading about. So, make sure you're sitting in front of a computer, and let's get to it! -::: -:::: -[]{#the-basics.xhtml} +[] -:::: {#the-basics.xhtml_page} -::: {#the-basics.xhtml_content} - -# The Basics {#the-basics.xhtml_the-basics} +# The Basics Now that you have a basic understanding of version control systems in general, we can start experimenting with Git. Using Git as a VCS is a @@ -205,7 +174,7 @@ basic knowledge of HTML and CSS will give you a deeper understanding of the purpose underlying various Git commands but is not strictly required. -## Create the Example Site {#the-basics.xhtml_create-the-example-site} +## Create the Example Site Before we can execute any Git commands, we need to create the example project. Create a new folder called `my-git-repo` to store the project, @@ -236,7 +205,7 @@ example project. Feel free to open the `index.html` in a web browser to see what kind of website it translates to. It's not exactly pretty, but it serves our purposes. -## Initialize the Git Repository {#the-basics.xhtml_initialize-the-git-repository} +## Initialize the Git Repository Now, we're ready to create our first Git repository. Open a command prompt (or Git Bash for Windows users) and navigate to the project @@ -269,7 +238,7 @@ is the only difference between a Git repository and an ordinary folder, so deleting it will turn your project back into an unversioned collection of files. -## View the Repository Status {#the-basics.xhtml_view-the-repository-status} +## View the Repository Status Before we try to start creating revisions, it would be helpful to view the status of our new repository. Execute the following in your command @@ -306,7 +275,7 @@ keep a project small and efficient, you should only track _source_ files and omit anything that can be _generated_ from those files. This latter content is part of the build process---not revision control. -## Stage a Snapshot {#the-basics.xhtml_stage-a-snapshot} +## Stage a Snapshot So, we need to explicitly tell Git to add `index.html` to the repository. The aptly named `git add` command tells Git to start @@ -341,7 +310,7 @@ changes into distinct snapshots---a practice that makes it possible to track the _meaningful_ progression of a software project (instead of just arbitrary lines of code). -## Commit the Snapshot {#the-basics.xhtml_commit-the-snapshot} +## Commit the Snapshot We have staged a snapshot, but we still need to **commit** it to the project history. The next command will open a text editor and prompt you @@ -361,7 +330,7 @@ process: 1. **Staging.** Telling Git what files to include in the next commit. 2. **Committing.** Recording the staged snapshot with a descriptive - message. + message. Staging files with the `git add` command doesn't actually affect the repository in any significant way---it just lets us get our files in @@ -374,7 +343,7 @@ control system. ![The stage/commit process](images/1-1.png) -## View the Repository History {#the-basics.xhtml_view-the-repository-history} +## View the Repository History Note that `git status` now tells us that there is `nothing to commit`, which means our current state matches what is stored in the repository. @@ -410,7 +379,7 @@ Git also outputs the date, time, and timezone (`-0600`) of when the commit took place. Finally, we see the commit message that was entered in the previous step. -## Configure Git {#the-basics.xhtml_configure-git} +## Configure Git Before committing any more snapshots, we should probably tell Git who we are. We can do this with the `git config` command: @@ -426,7 +395,7 @@ configuration as a default for all of your repositories. Omitting it lets you specify different user information for individual repositories, which will come in handy later on. -## Create New HTML Files {#the-basics.xhtml_create-new-html-files} +## Create New HTML Files Let's continue developing our website a bit. Start by creating a file called `orange.html` with the following content. @@ -462,7 +431,7 @@ Then, add a `blue.html` page: ``` -## Stage the New Files {#the-basics.xhtml_stage-the-new-files} +## Stage the New Files Next, we can stage the files the same way we created the first snapshot. @@ -491,7 +460,7 @@ _committed_ changes. ![Status output vs. Log output](images/1-2.png) -## Commit the New Files {#the-basics.xhtml_commit-the-new-files} +## Commit the New Files Let's commit our staged snapshot: @@ -513,7 +482,7 @@ relationship between commits (that is, a new commit refers to its parent commit). You'll see this type of diagram many, many times throughout this tutorial. -## Modify the HTML Pages {#the-basics.xhtml_modify-the-html-pages} +## Modify the HTML Pages The `git add` command we've been using to stage _new_ files can also be used to stage _modified_ files. Add the following to the bottom of @@ -540,7 +509,7 @@ Next, add a home page link to the bottom of `orange.html` and You can now navigate between pages when viewing them in a web browser. -## Stage and Commit the Snapshot {#the-basics.xhtml_stage-and-commit-the-snapshot} +## Stage and Commit the Snapshot Once again, we'll stage the modifications, then commit the snapshot. @@ -561,7 +530,7 @@ every time we commit a new snapshot. ![Current project history](images/1-4.png) -## Explore the Repository[']{.apo}s History {#the-basics.xhtml_explore-the-repository} +## Explore the Repository[']{.apo}s History The `git log` command comes with a lot of formatting options, a few of which will be introduced throughout this tutorial. For now, we'll just @@ -583,7 +552,7 @@ This displays only the `blue.html` history. Notice that the initial `Create index page` commit is missing, since `blue.html` didn't exist in that snapshot. -## Conclusion {#the-basics.xhtml_conclusion} +## Conclusion In this module, we introduced the fundamental Git workflow: edit files, stage a snapshot, and commit the snapshot. We also had some hands-on @@ -601,7 +570,7 @@ The next module puts our existing project history to work by reverting to previous snapshots. This is all you need to start using Git as a simple versioning tool for your own projects. -## Quick Reference {#the-basics.xhtml_quick-reference} +## Quick Reference `git init` : Create a Git repository in the current folder. @@ -623,15 +592,12 @@ simple versioning tool for your own projects. `git config --global user.email ` : Define the author email to be used in all repositories. -::: -:::: -[]{#undoing-changes.xhtml} +[] -:::::: {#undoing-changes.xhtml_page} -::::: {#undoing-changes.xhtml_content} +: -# Undoing Changes {#undoing-changes.xhtml_undoing-changes} +# Undoing Changes In the last module, we learned how to record versions of a project into a Git repository. The whole point of maintaining these "safe" copies is @@ -643,21 +609,16 @@ To this end, storing "safe" versions isn't much help without the ability to restore them. Our next task is to learn how to view the previous states of a project, revert back to them, and reset uncommitted changes. -::: {.icon-text .download-icon-text} ![](images/icons/download.png){style="max-width: 45px"} [Download the repository for this module](http://rypress.com/tutorials/git/media/repo-zips/undoing-changes.zip) -::: - -::: {style="clear: both"} -::: If you've been following along from the previous module, you already have everything you need. Otherwise, download the zipped Git repository from the above link, uncompress it, and you're good to go. -## Display Commit Checksums {#undoing-changes.xhtml_display-commit-checksums} +## Display Commit Checksums As a quick review, let's display our repository's history. Navigate a command prompt (or Git Bash) to the `my-git-repo` folder and run the @@ -681,7 +642,7 @@ you can see the full version with the default formatting of `git log`). These first few characters effectively serve as a unique ID for each commit. -## View an Old Revision {#undoing-changes.xhtml_view-an-old-revision} +## View an Old Revision Using the new `git checkout` command, we can view the contents of a previous snapshot. Make sure to change `54650a3` in the following @@ -705,7 +666,7 @@ commit). ![Checking out the 2nd commit](images/2-1.png) -## View an Older Revision {#undoing-changes.xhtml_view-an-older-revision} +## View an Older Revision Let's go even farther back in our history. Be sure to change `b650e4b` to the ID of your _first_ commit. @@ -743,7 +704,7 @@ very brief introduction to branches, but it's all we need to know to navigate between commits. The next module will discuss branches in full detail. -## Return to Current Version {#undoing-changes.xhtml_return-to-current-version} +## Return to Current Version We can use the same `git checkout` command to return to the `master` branch. @@ -760,7 +721,7 @@ history looks like: ![Current project history](images/2-3.png) -## Tag a Release {#undoing-changes.xhtml_tag-a-release} +## Tag a Release Let's call this a stable version of the example website. We can make it official by **tagging** the most recent commit with a version number. @@ -780,7 +741,7 @@ tag**, which lets us record our name, the date, and a descriptive message (specified via the `-m` flag). We'll use this tag to find the stable version after we try some crazy experiments. -## Try a Crazy Experiment {#undoing-changes.xhtml_try-a-crazy-experiment} +## Try a Crazy Experiment We're now free to add experimental changes to the example site without affecting any committed content. Create a new file called `crazy.html` @@ -803,7 +764,7 @@ and add the following HTML. ``` -## Stage and Commit the Snapshot {#undoing-changes.xhtml_stage-and-commit-the-snapshot} +## Stage and Commit the Snapshot Stage and commit the new file as usual. @@ -824,7 +785,7 @@ your log history takes up more than one screen, you can scroll down by pressing `Space` and return to the command line by pressing the letter `q`. -## View the Stable Commit {#undoing-changes.xhtml_view-the-stable-commit} +## View the Stable Commit Let's go back and take a look at our stable revision. Remember that the `v1.0` tag now serves as a user-friendly shortcut to the third commit's @@ -854,7 +815,7 @@ At this point, our history should look like the following: b650e4b Create index page ``` -## Undo Committed Changes {#undoing-changes.xhtml_undo-committed-changes} +## Undo Committed Changes We're ready to restore our stable tag by removing the most recent commit. Make sure to change `514fbe7` to the ID of the _crazy @@ -891,7 +852,7 @@ undo---not the stable commit that you want to return to. It helps to think of this command as saying "undo this commit" rather than "restore this version." -## Start a Smaller Experiment {#undoing-changes.xhtml_start-a-smaller-experiment} +## Start a Smaller Experiment Let's try a smaller experiment this time. Create `dummy.html` and leave it as a blank file. Then, add a link in the "Navigation" section of @@ -916,7 +877,7 @@ In the next section, we're going to abandon this uncommitted experiment. But since the `git revert` command requires a commit ID to undo, we can't use the method discussed above. -## Undo Uncommitted Changes {#undoing-changes.xhtml_undo-uncommitted-changes} +## Undo Uncommitted Changes Before we start undoing things, let's take a look at the status of our repository. @@ -956,7 +917,7 @@ working directory, not on the committed snapshots. Unlike `git revert`, they **_permanently_** undo changes, so make sure you really want to trash what you're working on before you use them. -## Conclusion {#undoing-changes.xhtml_conclusion} +## Conclusion As noted in the previous module, most Git commands operate on one of the three main components of a Git repository: the working directory, the @@ -981,7 +942,7 @@ discussion of the core Git components, and they offer an elegant option for optimizing your development workflow. In the next module, we'll cover the basic Git branch commands. -## Quick Reference {#undoing-changes.xhtml_quick-reference} +## Quick Reference `git checkout ` : View a previous commit. @@ -1000,15 +961,13 @@ cover the basic Git branch commands. `git reset --hard` / `git clean -f` : Permanently undo uncommitted changes. -::::: -:::::: +: -[]{#branches-1.xhtml} +[] -:::::: {#branches-1.xhtml_page} -::::: {#branches-1.xhtml_content} +: -# Branches, Part I {#branches-1.xhtml_branches-part-i} +# Branches, Part I Branches are the final component of Git version control. This gives us four core elements to work with throughout the rest of this tutorial: @@ -1034,21 +993,16 @@ themselves to several standardized workflows for both individual and collaborative development, which will be explored in the latter half of the tutorial. -::: {.icon-text .download-icon-text} ![](images/icons/download.png){style="max-width: 45px"} [Download the repository for this module](http://rypress.com/tutorials/git/media/repo-zips/branches-1.zip) -::: - -::: {style="clear: both"} -::: If you've been following along from the previous module, you already have everything you need. Otherwise, download the zipped Git repository from the above link, uncompress it, and you're good to go. -## View Existing Branches {#branches-1.xhtml_view-existing-branches} +## View Existing Branches Let's start our exploration by listing the existing branches for our project. @@ -1067,7 +1021,7 @@ snapshot in the `master` branch resides in the working directory: Notice that since there's only one working directory for each project, only one branch can be checked out at a time. -## Checkout the Crazy Experiment {#branches-1.xhtml_checkout-the-crazy-experiment} +## Checkout the Crazy Experiment The previous module left out some details about how checking out previous commits actually works. We're now ready to tackle this topic in @@ -1111,7 +1065,7 @@ on the `master` branch since it contains more recent snapshots than the `HEAD`. This is reflected in the `git branch` output, which tells us that we're currently on `(no branch)`. -## Create a New Branch {#branches-1.xhtml_create-a-new-branch} +## Create a New Branch We can't add new commits when we're not on a branch, so let's create one now. This will take our current working directory and fork it into a new @@ -1140,7 +1094,7 @@ Right now, the `crazy` branch, `HEAD`, and working directory are the exact same as the fourth commit. But as soon as we add another snapshot, we'll see a fork in our project history. -## Make a Rainbow {#branches-1.xhtml_make-a-rainbow} +## Make a Rainbow We'll continue developing our crazy experiment by changing `crazy.html` to the following. @@ -1171,7 +1125,7 @@ to the following. ``` -## Stage and Commit the Rainbow {#branches-1.xhtml_stage-and-commit-the-rainbow} +## Stage and Commit the Rainbow Hopefully, you're relatively familiar with staging and committing snapshots by now: @@ -1213,7 +1167,7 @@ individual branch still has a _linear_ history (snapshots occur one after another). This means that we can interact with branches in the exact same way as we learned in the first two modules. -## Rename the Rainbow {#branches-1.xhtml_rename-the-rainbow} +## Rename the Rainbow Let's add one more snapshot to the `crazy` branch. Rename `crazy.html` to `rainbow.html`, then use the following Git commands to update the @@ -1246,7 +1200,7 @@ in `master` after the fork. ![Current project history](images/3-6.png) -## Return to the Master Branch {#branches-1.xhtml_return-to-the-master-branch} +## Return to the Master Branch Let's switch back to the `master` branch: @@ -1265,7 +1219,7 @@ however, share their first four commits. ![Shared branch history](images/3-7.png) -## Create a CSS Branch {#branches-1.xhtml_create-a-css-branch} +## Create a CSS Branch We're going to put our crazy experiment on the backburner for now and turn our attention to formatting the HTML pages with a cascading @@ -1285,7 +1239,7 @@ happens to coincide with the `master` branch: ![Creating the `css` branch](images/3-8.png) -## Add a CSS Stylesheet {#branches-1.xhtml_add-a-css-stylesheet} +## Add a CSS Stylesheet Next, create a file called `style.css` with the following content. This CSS is used to apply formatting to the HTML in our other files. @@ -1315,7 +1269,7 @@ git status git commit -m "Add CSS stylesheet" ``` -## Link the Stylesheet {#branches-1.xhtml_link-the-stylesheet} +## Link the Stylesheet We still need to tell the HTML pages to use the formatting in `style.css`. Add the following text on a separate line after the @@ -1341,7 +1295,7 @@ This results in a repository history that looks like: ![Current project history](images/3-9.png) -## Return to the Master Branch (Again) {#branches-1.xhtml_return-to-the-master-branch-again} +## Return to the Master Branch (Again) The `css` branch let us create and test our formatting without threatening the stability of the `master` branch. But, now we need to @@ -1371,7 +1325,7 @@ f757eb3 Create index page As expected, there is no mention of the CSS additions in the history of `master`, but we're about to change that. -## Merge the CSS Branch {#branches-1.xhtml_merge-the-css-branch} +## Merge the CSS Branch Use the `git merge` command to take the snapshots from the `css` branch and add them to the `master` branch. @@ -1402,7 +1356,7 @@ After the merge, both branches have the exact same history, which makes them redundant. Unless we wanted to keep developing on the `css` branch, we're free to get rid of it. -## Delete the CSS Branch {#branches-1.xhtml_delete-the-css-branch} +## Delete the CSS Branch We can safely delete a branch by passing the `-d` flag to `git branch`. @@ -1422,7 +1376,7 @@ Deleting branches is a relatively "safe" operation in the sense that Git will warn you if you're deleting an unmerged branch. This is just another example of Git's commitment to never losing your work. -## Conclusion {#branches-1.xhtml_conclusion} +## Conclusion This module used two branches to experiment with new additions. In both cases, branches gave us an environment that was completely isolated from @@ -1443,7 +1397,7 @@ Next, we'll practice our branch management skills by examining the typical workflow of veteran Git users. We'll also discover more complicated merges than the fast-forward merge introduced above. -## Quick Reference {#branches-1.xhtml_quick-reference} +## Quick Reference `git branch` : List all branches. @@ -1464,15 +1418,13 @@ branch. `git rm ` : Remove a file from the working directory (if applicable) and stop tracking the file. -::::: -:::::: +: -[]{#branches-2.xhtml} +[] -:::::: {#branches-2.xhtml_page} -::::: {#branches-2.xhtml_content} +: -# Branches, Part II {#branches-2.xhtml_branches-part-ii} +# Branches, Part II Now that we've covered the mechanics behind Git branches, we can discuss the practical impact that they have on the software development process. @@ -1494,21 +1446,16 @@ diverges, a dedicated commit is required to combine the branches. This situation may also give rise to a merge conflict, which must be manually resolved before anything can be committed to the repository. -::: {.icon-text .download-icon-text} ![](images/icons/download.png){style="max-width: 45px"} [Download the repository for this module](http://rypress.com/tutorials/git/media/repo-zips/branches-2.zip) -::: - -::: {style="clear: both"} -::: If you've been following along from the previous module, you already have everything you need. Otherwise, download the zipped Git repository from the above link, uncompress it, and you're good to go. -## Continue the Crazy Experiment {#branches-2.xhtml_continue-the-crazy-experiment} +## Continue the Crazy Experiment Let's start by checking out the `crazy` branch. @@ -1533,7 +1480,7 @@ This brings us to my rule-of-thumb for using Git branches: Following these simple guidelines will have a dramatic impact on your programming efficiency. -## Merge the CSS Updates {#branches-2.xhtml_merge-the-css-updates} +## Merge the CSS Updates Note that the CSS formatting we merged into `master` is nowhere to be found. This presents a bit of a problem if we want our experiment to @@ -1580,7 +1527,7 @@ powerful development tool. We can not only create independent lines of development, but we can also share information between them by tying together their histories with a 3-way merge. -## Style the Rainbow Page {#branches-2.xhtml_style-the-rainbow-page} +## Style the Rainbow Page Now that we have access to the CSS updates from `master`, we can continue developing our crazy experiment. Link the CSS stylesheet to @@ -1607,7 +1554,7 @@ files in the staged snapshot. Combined with the `-m` flag, we can stage and commit snapshots with a single command. However, be careful not to include unintended files when using the `-a` flag. -## Link to the Rainbow Page {#branches-2.xhtml_link-to-the-rainbow-page} +## Link to the Rainbow Page We still need to add a navigation link to the home page. Change the "Navigation" section of `index.html` to the following. @@ -1634,7 +1581,7 @@ git commit -a -m "Link index.html to rainbow.html" git log --oneline ``` -## Fork an Alternative Rainbow {#branches-2.xhtml_fork-an-alternative-rainbow} +## Fork an Alternative Rainbow Next, we're going to brainstorm an alternative to the current `rainbow.html` page. This is a perfect time to create another topic @@ -1654,7 +1601,7 @@ the new branch, our repository's history looks like: ![Creating the `crazy-alt` branch](images/4-2.png) -## Change the Rainbow {#branches-2.xhtml_change-the-rainbow} +## Change the Rainbow Change the colorful list in `rainbow.html` from: @@ -1707,7 +1654,7 @@ omitted for the sake of presentation. ![Committing on the `crazy-alt` branch](images/4-3.png) -## Emergency Update! {#branches-2.xhtml_emergency-update} +## Emergency Update _Our boss called in with some breaking news!_ He needs us to update the site immediately, but what do we do with our `rainbow.html` @@ -1776,7 +1723,7 @@ separate branch isn't really necessary for our trivial example, but in the real world, this would give you the opportunity to run build tests without touching your stable project. -## Publish the News Hotfix {#branches-2.xhtml_publish-the-news-hotfix} +## Publish the News Hotfix Remember that to merge into the `master` branch, we first need to check it out. @@ -1804,7 +1751,7 @@ Also notice that we have another fork in our history (the commit before `master` branches in two directions), which means we should expect to see another merge commit in the near future. -## Complete the Crazy Experiment {#branches-2.xhtml_complete-the-crazy-experiment} +## Complete the Crazy Experiment Ok, let's finish up our crazy experiment with one more commit. @@ -1859,7 +1806,7 @@ ae4e756 Link HTML pages to stylesheet b650e4b Create index page ``` -## Publish the Crazy Experiment {#branches-2.xhtml_publish-the-crazy-experiment} +## Publish the Crazy Experiment We're finally ready to merge our `crazy` branch back into `master`. @@ -1912,7 +1859,7 @@ difference between the two versions of the file. The section labeled `<<<<<<< HEAD` shows us the version in the current branch, while the part after the `=======` shows the version in the `crazy` branch. -## Resolve the Merge Conflicts {#branches-2.xhtml_resolve-the-merge-conflicts} +## Resolve the Merge Conflicts We can change the affected lines to whatever we want in order to resolve the conflict. Edit the news section of `index.html` to keep changes from @@ -1952,7 +1899,7 @@ The final state of our project looks like the following. ![Merging the `crazy` branch into `master`](images/4-5.png) -## Cleanup the Feature Branches {#branches-2.xhtml_cleanup-the-feature-branches} +## Cleanup the Feature Branches Since our crazy experiment has been successfully merged, we can get rid of our feature branches. @@ -1984,7 +1931,7 @@ the tangible distinction between fast-forward merges and 3-way merges. The next module will discuss the appropriate usage of both and the potential complications of a non-linear history. -## Conclusion {#branches-2.xhtml_conclusion} +## Conclusion This module demonstrated the three most common uses of Git branches: @@ -2015,7 +1962,7 @@ Next, we'll learn how to clean up our repository's history. Using a new Git command, we'll be able to better manage merge commits and make sure our history is easy to navigate. -## Quick Reference {#branches-2.xhtml_quick-reference} +## Quick Reference `git commit -a -m ""` : Stage all tracked files and commit the snapshot using the specified @@ -2024,15 +1971,13 @@ message. `git branch -D ` : Force the removal of an unmerged branch (_be careful_: it will be lost forever). -::::: -:::::: +: -[]{#rebasing.xhtml} +[] -:::::: {#rebasing.xhtml_page} -::::: {#rebasing.xhtml_content} +: -# Rebasing {#rebasing.xhtml_rebasing} +# Rebasing Let's start this module by taking an in-depth look at our history. The six commits asterisked below are part of the same train of thought. We @@ -2077,21 +2022,16 @@ To explore Git's rebasing capabilities, we'll need to build up our example project so that we have something to work with. Then, we'll go back and rewrite history using `git rebase`. -::: {.icon-text .download-icon-text} ![](images/icons/download.png){style="max-width: 45px"} [Download the repository for this module](http://rypress.com/tutorials/git/media/repo-zips/rebasing.zip) -::: - -::: {style="clear: both"} -::: If you've been following along from the previous module, you already have everything you need. Otherwise, download the zipped Git repository from the above link, uncompress it, and you're good to go. -## Create an About Section {#rebasing.xhtml_create-an-about-section} +## Create an About Section We'll begin by creating an about page for the website. Remember, we should be doing all of our work in isolated branches so that we don't @@ -2115,7 +2055,7 @@ git commit -m "Add empty page in about section" Note that `git add` can also add entire directories to the staging area. -## Add an About Page {#rebasing.xhtml_add-an-about-page} +## Add an About Page Next, we'll add some HTML to `about/index.html`: @@ -2153,7 +2093,7 @@ following. ![Adding the `about` branch](images/5-2.png) -## Another Emergency Update! {#rebasing.xhtml_another-emergency-update} +## Another Emergency Update _Our boss just gave us some more breaking news!_ Again, we'll use a hotfix branch to update the site without affecting our about page @@ -2216,7 +2156,7 @@ git status git commit -m "Add article for 2nd news item" ``` -## Publish News Hotfix {#rebasing.xhtml_publish-news-hotfix} +## Publish News Hotfix We're ready to merge the news update back into `master`. @@ -2232,7 +2172,7 @@ the following. ![Fast-forwarding `master` to the `news-hotfix`](images/5-3.png) -## Rebase the About Branch {#rebasing.xhtml_rebase-the-about-branch} +## Rebase the About Branch This puts us in the exact same position as we were in before our first 3-way merge. We want to pull changes from `master` into a feature @@ -2258,7 +2198,7 @@ enabling us to do a fast-forward merge later on. Rebasing also allowed us to integrate the most up-to-date version of `master` _without a merge commit_. -## Add a Personal Bio {#rebasing.xhtml_add-a-personal-bio} +## Add a Personal Bio With our news hotfix out of the way, we can now continue work on our about section. Create the file `about/me.html` with the following @@ -2301,7 +2241,7 @@ So, all of our about section commits are grouped together, which would not be the case had we merged instead of rebased. This also eliminates an unnecessary fork in our project history. -## Add Dummy Page for Mary {#rebasing.xhtml_add-dummy-page-for-mary} +## Add Dummy Page for Mary Once again, the next two snapshots are unnecessarily trivial. However, we'll use an _interactive_ rebase to combine them into a single commit @@ -2316,7 +2256,7 @@ git status git commit -m "Add empty HTML page for Mary's bio" ``` -## Link to the About Section {#rebasing.xhtml_link-to-the-about-section} +## Link to the About Section Then, add a link to the about page in `index.html` so that its "Navigation" section looks like the following. @@ -2345,7 +2285,7 @@ Don't forget to commit the change: git commit -a -m "Add link to about section in home page" ``` -## Clean Up the Commit History {#rebasing.xhtml_clean-up-the-commit-history} +## Clean Up the Commit History Before we merge into the `master` branch, we should make sure we have a clean, meaningful history in our feature branch. By rebasing @@ -2385,13 +2325,13 @@ to change along the way. 1. Git moves the `5cf316e` commit to the tip of `master`. 2. Git combines the snapshots of `964e013` and `5cf316e`. 3. Git stops to ask you what commit message to use for the combined - snapshot. It automatically includes the messages of both commits, - but you can delete that and simplify it to just - `Create the about page`. Save and exit the text editor to continue. + snapshot. It automatically includes the messages of both commits, + but you can delete that and simplify it to just + `Create the about page`. Save and exit the text editor to continue. 4. Git repeats this process for commits `89db9ab` and `2bda8e5`. Use - `Begin creating bio pages` for the message. + `Begin creating bio pages` for the message. 5. Git adds the final commit (`915466f`) on top of the commits created - in the previous steps. + in the previous steps. You can see the result of all this activity with `git log --oneline`, as well as in the diagram below. The five commits originally in `about` @@ -2409,7 +2349,7 @@ be transferred to the new base, and its content would be lost forever. In a future module, we'll also see how rewriting history can get you in trouble with public Git repositories. -## Stop to Amend a Commit {#rebasing.xhtml_stop-to-amend-a-commit} +## Stop to Amend a Commit The previous rebase only stopped us to edit the _messages_ of each commit. We can take this one step further and alter a _snapshot_ during @@ -2456,7 +2396,7 @@ You can use the default message created by `git commit`. The new staged snapshot instead of creating a new one. This is also very useful for fixing premature commits that often occur during normal development. -## Continue the Interactive Rebase {#rebasing.xhtml_continue-the-interactive-rebase} +## Continue the Interactive Rebase Remember that we're in the middle of a rebase, and Git still has one more commit that it needs to re-apply. Tell Git that we're ready to move @@ -2476,7 +2416,7 @@ If you ever find yourself lost in the middle of a rebase and you're afraid to continue, you can use the `‑‑abort` flag to abandon it and start over from scratch. -## Publish the About Section {#rebasing.xhtml_publish-the-about-section} +## Publish the About Section The point of all this interactive rebasing is to generate a _meaningful_ history that we can merge back into `master`. And, since we've rebased @@ -2504,7 +2444,7 @@ notion of _how_ we got to our current state. ![Merging and deleting the `about` branch](images/5-7.png) -## Conclusion {#rebasing.xhtml_conclusion} +## Conclusion Rebasing enables fast-forward merges by moving a branch to the tip of another branch. It effectively eliminates the need for merge commits, @@ -2543,7 +2483,7 @@ The next module will get a little bit more involved in our project history. We'll try fixing mistakes via complex rebases and even learn how to recover deleted commits. -## Quick Reference {#rebasing.xhtml_quick-reference} +## Quick Reference `git rebase ` : Move the current branch's commits to the tip of ``, which @@ -2565,15 +2505,13 @@ its former state. `git merge --no-ff ` : Force a merge commit even if Git could do a fast-forward merge. -::::: -:::::: +: -[]{#rewriting-history.xhtml} +[] -:::::: {#rewriting-history.xhtml_page} -::::: {#rewriting-history.xhtml_content} +: -# Rewriting History {#rewriting-history.xhtml_rewriting-history} +# Rewriting History The previous module on rebasing taught us how to move commits around and perform some basic edits while doing so, but now we're going to really @@ -2585,21 +2523,16 @@ Hopefully, this module will get you much more comfortable with the core Git components, as we'll be inspecting and editing the internal makeup of our project. -::: {.icon-text .download-icon-text} ![](images/icons/download.png){style="max-width: 45px"} [Download the repository for this module](http://rypress.com/tutorials/git/media/repo-zips/rewriting-history.zip) -::: - -::: {style="clear: both"} -::: If you've been following along from the previous module, you already have everything you need. Otherwise, download the zipped Git repository from the above link, uncompress it, and you're good to go. -## Create the Red Page {#rewriting-history.xhtml_create-the-red-page} +## Create the Red Page First, let's create a new branch and add a few more HTML pages. @@ -2632,7 +2565,7 @@ Next, create the file `red.html` and add the following content: We'll hold off on committing this page for the moment. -## Create the Yellow Page {#rewriting-history.xhtml_create-the-yellow-page} +## Create the Yellow Page Create a file called `yellow.html`, which should look like the following. @@ -2654,7 +2587,7 @@ following. ``` -## Link and Commit the New Pages {#rewriting-history.xhtml_link-and-commit-the-new-pages} +## Link and Commit the New Pages Next, we'll link both new pages to the home page. Add the following items to the "Navigation" section in `index.html`: @@ -2693,7 +2626,7 @@ since you won't always know what constitutes a "well-defined" addition as you're developing a project. Fortunately, Git lets us go back and fix up these problem commits after the fact. -## Create and Commit the Green Page {#rewriting-history.xhtml_create-and-commit-the-green-page} +## Create and Commit the Green Page Let's create one more page before splitting that "bad" commit: Add the following HTML to a file called `green.html`. @@ -2731,7 +2664,7 @@ git status git commit -m "Add green page" ``` -## Begin an Interactive Rebase {#rewriting-history.xhtml_begin-an-interactive-rebase} +## Begin an Interactive Rebase The commits introduced in our `new-pages` branch are: @@ -2764,7 +2697,7 @@ edit db96c72 Add new HTML pages pick 4c3027c Add green page ``` -## Undo the Generic Commit {#rewriting-history.xhtml_undo-the-generic-commit} +## Undo the Generic Commit First, let's take a look at where we are with `git log --oneline`: @@ -2808,7 +2741,7 @@ course, this results in a repository with uncommitted modifications. We now have the opportunity to add the `red.html` and `yellow.html` files to distinct commits. -## Split the Generic Commit {#rewriting-history.xhtml_split-the-generic-commit} +## Split the Generic Commit Let's start with the red page. Since we only want to commit content that involves the red page, we'll have to manually go in and remove the @@ -2880,7 +2813,7 @@ flag. Then, we committed them in separate snapshots with the usual during a rebase you can add, delete, and edit commits to your heart's content, and the entire result will be moved to the new base. -## Remove the Last Commit {#rewriting-history.xhtml_remove-the-last-commit} +## Remove the Last Commit Next, we're going to "accidentally" remove the green page commit so we can learn how to retrieve it via Git's internal repository data. @@ -2910,7 +2843,7 @@ The commit that we removed from the branch is now a **dangling commit**. Dangling commits are those that cannot be reached from any branch and are thus in danger of being lost forever. -## Open the Reflog {#rewriting-history.xhtml_open-the-reflog} +## Open the Reflog Git uses something called the **reflog** to record every change you make to your repository. Let's take a look at what it contains: @@ -2942,7 +2875,7 @@ The reflog is a _chronological_ listing of our history, without regard for the repository's branch structure. This lets us find dangling commits that would otherwise be lost from the project history. -## Revive the Lost Commit {#rewriting-history.xhtml_revive-the-lost-commit} +## Revive the Lost Commit At the beginning of each reflog entry, you'll find a commit ID representing the `HEAD` after that action. Check out the commit at @@ -2976,7 +2909,7 @@ The above diagram makes it easy to see that the `green-page` branch is an extension of `new-pages`, but how would we figure this out if we weren't drawing out the state of our repository every step of the way? -## Filter the Log History {#rewriting-history.xhtml_filter-the-log-history} +## Filter the Log History To view the differences between branches, we can use Git's log-filtering syntax. @@ -3012,7 +2945,7 @@ syntax shown above. Similarly, `-n 3`, `-n 2`, and `-n 1` would display three, two, and one commit, respectively. This feature becomes very useful once a repository grows beyond one screenful of history. -## Merge in the Revived Branch {#rewriting-history.xhtml_merge-in-the-revived-branch} +## Merge in the Revived Branch We've revived our lost commit, and now we're ready to merge everything back into the `master` branch. Before we do the merge, let's see exactly @@ -3069,7 +3002,7 @@ We can go ahead and delete the green page branch, too. git branch -d green-page ``` -## Conclusion {#rewriting-history.xhtml_conclusion} +## Conclusion This module took an in-depth look at rebasing, resetting, and the reflog. We learned how to split old commits into one or more new @@ -3100,7 +3033,7 @@ We'll revisit Git's internal representation of a repository in the ready to discuss multi-user development, which happens to rely entirely on Git branches. -## Quick Reference {#rewriting-history.xhtml_quick-reference} +## Quick Reference `git reflog` : Display the local, chronological history of a repository. @@ -3119,15 +3052,13 @@ These parameters can be either commit ID's or branch names. `git log --stat` : Include extra information about altered files in the log output. -::::: -:::::: +: -[]{#remotes.xhtml} +[] -:::::: {#remotes.xhtml_page} -::::: {#remotes.xhtml_content} +: -# Remotes {#remotes.xhtml_remotes} +# Remotes Simply put, a **remote repository** is one that is not your own. It can be another Git repository that's on your company's network, the @@ -3151,21 +3082,16 @@ For several parts of this module, we're going to pretend to be Mary, the graphic designer for our website. Mary's actions are clearly denoted by including her name in the heading of each step. -::: {.icon-text .download-icon-text} ![](images/icons/download.png){style="max-width: 45px"} [Download the repository for this module](http://rypress.com/tutorials/git/media/repo-zips/remotes.zip) -::: - -::: {style="clear: both"} -::: If you've been following along from the previous module, you already have everything you need. Otherwise, download the zipped Git repository from the above link, uncompress it, and you're good to go. -## Clone the Repository (Mary) {#remotes.xhtml_clone-the-repository-mary} +## Clone the Repository (Mary) First, Mary needs her own copy of the repository to work with. The [Distributed Workflows](#distributed-workflows.xhtml) module will @@ -3189,7 +3115,7 @@ pretending to be Mary. Run `git log` to verify that Mary's repository is in fact a copy of our original repository. -## Configure The Repository (Mary) {#remotes.xhtml_configure-the-repository-mary} +## Configure The Repository (Mary) First off, Mary needs to configure her repository so that we know who contributed what to the project. @@ -3210,7 +3136,7 @@ folder of Mary's project (you may need to enable hidden files to see Mary's information at the bottom of the file. Note that this overrides the global configuration that we set in [The Basics](#the-basics.xhtml). -## Start Mary's Day (Mary) {#remotes.xhtml_start-marys-day-mary} +## Start Mary's Day (Mary) Today, Mary is going to be working on her bio page, which she should develop in a separate branch: @@ -3226,7 +3152,7 @@ about what's going on in `my-git-repo`. Just as branches are an abstraction for the working directory, the staged snapshot, and a commit history, a repository is an abstraction for branches. -## Create Mary's Bio Page (Mary) {#remotes.xhtml_create-marys-bio-page-mary} +## Create Mary's Bio Page (Mary) Let's complete Mary's biography page. In `marys-repo`, change `about/mary.html` to: @@ -3267,7 +3193,7 @@ The `Author` field in the log output should reflect the local configurations we made for Mary's name and email. Remember that the `-n 1` flag limits history output to a single commit. -## Publish the Bio Page (Mary) {#remotes.xhtml_publish-the-bio-page-mary} +## Publish the Bio Page (Mary) Now, we can publish the bio page by merging into the `master` branch. @@ -3287,7 +3213,7 @@ had any interaction between the two repositories, so we don't see any remote branches yet. Before we switch back to `my-git-repo`, let's examine Mary's remote connections. -## View Remote Repositories (Mary) {#remotes.xhtml_view-remote-repositories-mary} +## View Remote Repositories (Mary) Mary can list the connections she has to other repositories using the following command. @@ -3311,7 +3237,7 @@ This shows the full path to our original repository, verifying that designated as a "fetch" and a "push" location. We'll see what these mean in a moment. -## Return to Your Repository (You) {#remotes.xhtml_return-to-your-repository-you} +## Return to Your Repository (You) Ok, we're done being Mary, and we can return to our own repository. @@ -3326,7 +3252,7 @@ all sorts of other things in `my-git-repo`. We could have even changed her bio page, which would result in a merge conflict when we try to pull her changes in. -## Add Mary as a Remote (You) {#remotes.xhtml_add-mary-as-a-remote-you} +## Add Mary as a Remote (You) Before we can get ahold of Mary's bio page, we need access to her repository. Let's look at our current list of remotes: @@ -3353,7 +3279,7 @@ in the figure below. Now that our remote _repositories_ are setup, we'll spend the rest of the module discussing remote _branches_. -## Fetch Mary's Branches (You) {#remotes.xhtml_fetch-marys-branches-you} +## Fetch Mary's Branches (You) As noted earlier, we can use remote branches to access snapshots from another repository. Let's take a look at our current remote branches @@ -3395,7 +3321,7 @@ The above figure shows the state of _our_ repository. We have access to Mary's snapshots (represented as squares) and her branches, even though we don't have a real-time connection to Mary's repository. -## Check Out a Remote Branch {#remotes.xhtml_check-out-a-remote-branch} +## Check Out a Remote Branch Let's check out a remote branch to review Mary's changes. @@ -3419,7 +3345,7 @@ module](#rewriting-history.xhtml) to revive a "lost" commit, but right now we're just looking at what Mary did, so the `detached HEAD` state doesn't really affect us. -## Find Mary's Changes {#remotes.xhtml_find-marys-changes} +## Find Mary's Changes We can use the same log-filtering syntax from the previous module to view Mary's changes. @@ -3440,7 +3366,7 @@ This won't output anything, since we haven't altered our database since Mary cloned it. In other words, our history hasn't _diverged_---we're just _behind_ by a commit. -## Merge Mary's Changes {#remotes.xhtml_merge-marys-changes} +## Merge Mary's Changes Let's approve Mary's changes and integrate them into our own `master` branch. @@ -3469,7 +3395,7 @@ was ready to be merged. But, since we've designated `master` as a stable branch for the project, it was safe to integrate those updates (assuming Mary was also aware of this convention). -## Push a Dummy Branch {#remotes.xhtml_push-a-dummy-branch} +## Push a Dummy Branch To complement our `git fetch` command, we'll take a brief look at **pushing**. Fetching and pushing are _almost_ opposites, in that @@ -3512,7 +3438,7 @@ cd ../my-git-repo git branch -d dummy ``` -## Push a New Tag {#remotes.xhtml_push-a-new-tag} +## Push a New Tag An important property of `git push` is that it does not automatically push tags associated with a particular branch. Let's examine this by @@ -3543,7 +3469,7 @@ quick `git tag`. It's very easy to forget to push new tags, so if it seems like your project has lost a tag or two, it's most likely because you didn't to push them to the remote repository. -## Conclusion {#remotes.xhtml_conclusion} +## Conclusion In this module, we learned how remote branches can be used to access content in someone else's repository. The remotes listed in `git remote` @@ -3569,7 +3495,7 @@ add some more structure to our multi-user development environment. The next module will show you how to set up and access a shared central repository. -## Quick Reference {#remotes.xhtml_quick-reference} +## Quick Reference `git clone ` : Create a copy of a remote Git repository. @@ -3594,15 +3520,13 @@ repository. `git push ` : Push a tag to another repository. -::::: -:::::: +: -[]{#centralized-workflows.xhtml} +[] -:::::: {#centralized-workflows.xhtml_page} -::::: {#centralized-workflows.xhtml_content} +: -# Centralized Workflows {#centralized-workflows.xhtml_centralized-workflows} +# Centralized Workflows In the previous module, we shared information directly between two developers' repositories: `my-git-repo` and `marys-repo`. This works for @@ -3632,22 +3556,17 @@ but other than that, you can follow this module's instructions as you find them. For everyone else, our network-based Git experience will begin in the next module. -::: {.icon-text .download-icon-text} ![](images/icons/download.png){style="max-width: 45px"} [Download the repositories for this module](http://rypress.com/tutorials/git/media/repo-zips/centralized-workflows.zip) -::: - -::: {style="clear: both"} -::: If you've been following along from the previous module, you already have everything you need. Otherwise, download the zipped Git repositories from the above link, uncompress them, and you're good to go. -## Create a Bare Repository (Central) {#centralized-workflows.xhtml_create-a-bare-repository-central} +## Create a Bare Repository (Central) First, let's create our central "communication hub." Again, make sure to change `/path/to/my-git-repo` to the actual path to your repository. If @@ -3674,7 +3593,7 @@ in our `my-git-repo` project. Git has _literally_ gotten rid of our working directory. The conventional `.git` extension in the directory name is a way to convey this property. -## Update Remotes (Mary and You) {#centralized-workflows.xhtml_update-remotes-mary-and-you} +## Update Remotes (Mary and You) We've successfully set up a central repository that can be used to share updates between us, Mary, and any other developers. Next, we should add @@ -3704,7 +3623,7 @@ to change the `../central-repo.git` path to: username and server location for `user@example.com` and the central repository's location for `path/to/central-repo.git`. -## Push the Master Branch (You) {#centralized-workflows.xhtml_push-the-master-branch-you} +## Push the Master Branch (You) We didn't _clone_ the central repository---we just initialized it as a bare repository. This means it doesn't have any of our project history @@ -3732,7 +3651,7 @@ However, it's safe to create local branches in `central-repo.git` because it has no working directory, which means it's impossible to disturb anyone's development. -## Add News Update (You) {#centralized-workflows.xhtml_add-news-update-you} +## Add News Update (You) Let's see our new centralized collaboration workflow in action by committing a few more snapshots. @@ -3787,7 +3706,7 @@ git status git commit -m "Add 3rd news item" ``` -## Publish the News Item (You) {#centralized-workflows.xhtml_publish-the-news-item-you} +## Publish the News Item (You) Previously, "publishing" meant merging with the local `master` branch. But since we're _only_ interacting with the central repository, our @@ -3815,7 +3734,7 @@ central repository and doing a fetch/fast-forward merge, except `git push` allows us to do everything from inside `my-git-repo`. We'll see some other convenient features of this command later in the module. -## Update CSS Styles (Mary) {#centralized-workflows.xhtml_update-css-styles-mary} +## Update CSS Styles (Mary) Next, let's pretend to be Mary again and add some CSS formatting (she is our graphic designer, after all). @@ -3847,7 +3766,7 @@ And, stage and commit a snapshot. git commit -a -m "Add CSS styles for headings and links" ``` -## Update Another CSS Style (Mary) {#centralized-workflows.xhtml_update-another-css-style-mary} +## Update Another CSS Style (Mary) Oops, Mary forgot to add some formatting. Append the `h3` styling to `style.css`: @@ -3865,7 +3784,7 @@ And of course, stage and commit the updates. git commit -a -m "Add CSS styles for 3rd level headings" ``` -## Clean Up Before Publishing (Mary) {#centralized-workflows.xhtml_clean-up-before-publishing-mary} +## Clean Up Before Publishing (Mary) Before Mary considers pushing her updates to the central repository, she needs to make sure she has a clean history. This _must_ be done by Mary, @@ -3918,7 +3837,7 @@ we discussed in [Undoing Changes](#undoing-changes.xhtml). This creates a new commit with the required modifications instead of re-writing old snapshots. -## Publish CSS Changes (Mary) {#centralized-workflows.xhtml_publish-css-changes-mary} +## Publish CSS Changes (Mary) Now that her history is cleaned up, Mary can publish the changes. @@ -3954,7 +3873,7 @@ fast-forward merge. This prevents us from losing the `Add 3rd news item` commit that would need to be overwritten for `origin/master` to match `mary/master`. -## Pull in Changes (Mary) {#centralized-workflows.xhtml_pull-in-changes-mary} +## Pull in Changes (Mary) Mary can solve this problem by pulling in the central changes before trying to push her CSS changes. First, she needs the most up-to-date @@ -4005,7 +3924,7 @@ changes. ![Updating the central repository's `master`](images/8-6.png) -## Pull in Changes (You) {#centralized-workflows.xhtml_pull-in-changes-you} +## Pull in Changes (You) Finally, we'll switch back to our repository and pull in Mary's CSS formatting. @@ -4043,7 +3962,7 @@ development into a single repository and ensures that no one overwrites another's content, as we discovered while trying to push Mary's CSS updates. -## Conclusion {#centralized-workflows.xhtml_conclusion} +## Conclusion In this module, we introduced another remote repository to serve as the central storage facility for our project. We also discovered bare @@ -4065,22 +3984,20 @@ called GitHub. In addition to introducing network access for Git repositories, this will open the door for another collaboration standard: the integrator workflow. -## Quick Reference {#centralized-workflows.xhtml_quick-reference} +## Quick Reference `git init --bare ` : Create a Git repository, but omit the working directory. `git remote rm ` : Remove the specified remote from your bookmarked connections. -::::: -:::::: +: -[]{#distributed-workflows.xhtml} +[] -:::::: {#distributed-workflows.xhtml_page} -::::: {#distributed-workflows.xhtml_content} +: -# Distributed Workflows {#distributed-workflows.xhtml_distributed-workflows} +# Distributed Workflows Now that we know how to share information via a centralized workflow, we can appreciate some of the drawbacks of this collaboration model. While @@ -4111,22 +4028,17 @@ incorporating a contribution from an anonymous developer named John. Bitbucket is a DVCS hosting provider that makes it very easy to set up a Git repository and start collaborating with a team of developers. -::: {.icon-text .download-icon-text} ![](images/icons/download.png){style="max-width: 45px"} [Download the repositories for this module](http://rypress.com/tutorials/git/media/repo-zips/distributed-workflows.zip) -::: - -::: {style="clear: both"} -::: If you've been following along from the previous module, you already have everything you need. Otherwise, download the zipped Git repositories from the above link, uncompress them, and you're good to go. -## Create a Bitbucket Account {#distributed-workflows.xhtml_create-a-bitbucket-account} +## Create a Bitbucket Account The first part of this module will walk you through setting up a Bitbucket account. Navigate your web browser to @@ -4140,7 +4052,7 @@ should match the one you assigned to your Git installation with your email, you can run another `git config --global user.email you@example.com` command. -## Create a Public Repository (You) {#distributed-workflows.xhtml_create-a-public-repository-you} +## Create a Public Repository (You) To create our first networked Git repository, log into your Bitbucket account, and navigate to _Repositories \> Create repository_. Use @@ -4161,7 +4073,7 @@ repository in the next section. ![Bitbucket's setup instructions](images/9-5.png) -## Push to the Public Repository (You) {#distributed-workflows.xhtml_push-to-the-public-repository-you} +## Push to the Public Repository (You) Before populating this new repository with our existing `my-git-repo` project, we first need to point our `origin` remote to the Bitbucket @@ -4186,7 +4098,7 @@ password, use the one that you signed up with. git push origin master ``` -## Browse the Public Repository (You) {#distributed-workflows.xhtml_browse-the-public-repository-you} +## Browse the Public Repository (You) We should now be able to see our project on the Bitbucket site. The _Source_ tab displays all of the files in the project, and the _Commits_ @@ -4206,7 +4118,7 @@ Having both a public and a private repository for each developer makes it easy to incorporate contributions from third-parties, even if you've never met them before. -## Clone the Repository (John) {#distributed-workflows.xhtml_clone-the-repository-john} +## Clone the Repository (John) Next, we're going to pretend to be John, a third-party contributor to our website. John noticed that we didn't have a pink page and, being the @@ -4235,7 +4147,7 @@ git config user.name "John" git config user.email john.example@rypress.com ``` -## Add the Pink Page (John) {#distributed-workflows.xhtml_add-the-pink-page-john} +## Add the Pink Page (John) Of course, John should be developing his contributions in a dedicated feature branch. @@ -4285,7 +4197,7 @@ git status git commit -m "Add pink page" ``` -## Publish the Pink Page (John) {#distributed-workflows.xhtml_publish-the-pink-page-john} +## Publish the Pink Page (John) Now, John needs to publish his contributions to a public repository. Remember that we don't want him to push to _our_ public repository, @@ -4337,7 +4249,7 @@ remote. Of course, if you're working on a private project, anonymous HTTP access would be disabled for that repository. -## View John's Contributions (You) {#distributed-workflows.xhtml_view-johns-contributions-you} +## View John's Contributions (You) Ok, we're done being John and we're ready to integrate his code into the official project. Let's start by switching back into our repository and @@ -4375,7 +4287,7 @@ file might contain. With that in mind, it's incredibly important to verify its contents. **Never blindly merge content from a third-party contributor.** -## Integrate John's Contributions (You) {#distributed-workflows.xhtml_integrate-johns-contributions-you} +## Integrate John's Contributions (You) Assuming we approve John's updates, we're now ready to merge it into the project. @@ -4397,7 +4309,7 @@ workflow is merely a standardized way of organizing the collaboration effort---nothing has changed about how we develop locally, and we're using the same Git commands as we have been for the last few modules. -## Publish John's Contributions (You) {#distributed-workflows.xhtml_publish-johns-contributions-you} +## Publish John's Contributions (You) We've integrated John's contribution into our local `my-git-repo` repository, but no one else knows what we've done. It's time to publish @@ -4411,7 +4323,7 @@ Since we designated our public Bitbucket repository as the "official" source for our project, everyone (i.e., Mary and John) will now be able to synchronize with it. -## Update Mary's Repository (Mary) {#distributed-workflows.xhtml_update-marys-repository-mary} +## Update Mary's Repository (Mary) Mary should now be pulling changes from our Bitbucket repository instead of the central one from the previous module. This should be fairly easy @@ -4438,7 +4350,7 @@ For Mary, it doesn't really matter that the updates came from John. All she has to know is that the "official" `master` branch moved forward, prompting her to synchronize her private repository. -## Update John's Repository (John) {#distributed-workflows.xhtml_update-johns-repository-john} +## Update John's Repository (John) John still needs to incorporate the pink page into his `master` branch. He should _not_ merge directly from his `pink-page` topic branch because @@ -4465,7 +4377,7 @@ In this way, additions from one contributor can be approved, integrated, and made available to everyone without interrupting anyone's independent developments. -## Conclusion {#distributed-workflows.xhtml_conclusion} +## Conclusion Using the integrator workflow, our private development process largely remains the same (develop a feature branch, merge it into `master`, and @@ -4493,15 +4405,13 @@ to rely upon. In the next module, we'll take a look at an even more flexible way to share commits. This low-level approach will also give us a better understanding of how Git internally manages our content. -::::: -:::::: +: -[]{#patch-workflows.xhtml} +[] -:::::: {#patch-workflows.xhtml_page} -::::: {#patch-workflows.xhtml_content} +: -# Patch Workflows {#patch-workflows.xhtml_patch-workflows} +# Patch Workflows Thus far, all of the collaboration workflows we've seen rely heavily on branches. For example, in the last module, a contributor had to publish @@ -4520,15 +4430,10 @@ contributions). Integrating on the commit level will also give us a deeper understanding of how a Git repository records project history. -::: {.icon-text .download-icon-text} ![](images/icons/download.png){style="max-width: 45px"} [Download the repositories for this module](http://rypress.com/tutorials/git/media/repo-zips/patch-workflows.zip) -::: - -::: {style="clear: both"} -::: If you've been following along from the previous module, you already have everything you need. Otherwise, download the zipped Git @@ -4543,7 +4448,7 @@ cd ../marys-repo git remote add origin http://bitbucket.org//my-git-repo.git ``` -## Change the Pink Page (Mary) {#patch-workflows.xhtml_change-the-pink-page-mary} +## Change the Pink Page (Mary) We'll begin by pretending to be Mary again. Mary didn't like the pink page that John contributed and wants to change it. @@ -4579,7 +4484,7 @@ Patches---like the centralized and integrator workflows---are merely a way to share changes amongst developers. It has little effect on the core Git concepts introduced in the first portion of this tutorial. -## Create a Patch (Mary) {#patch-workflows.xhtml_create-a-patch-mary} +## Create a Patch (Mary) Mary can create a patch from the new commit using the `git format‑patch` command. @@ -4630,7 +4535,7 @@ much easier to pass around than a Git branch. Delete the patch file for now (we'll re-create it later). -## Add a Pink Block (Mary) {#patch-workflows.xhtml_add-a-pink-block-mary} +## Add a Pink Block (Mary) Before learning how to turn patches back into commits, Mary will add one more snapshot. @@ -4662,7 +4567,7 @@ Mary's repository now contains two commits after the tip of `master`: ![Adding two commits on the `pink-page` branch](images/10-1.png) -## Create Patch of Entire Branch (Mary) {#patch-workflows.xhtml_create-patch-of-entire-branch-mary} +## Create Patch of Entire Branch (Mary) Mary can use the same command as before to generate patches for all the commits in her `pink-page` branch. @@ -4706,7 +4611,7 @@ lines indicate that we only added HTML during the second commit. As you can see, this patch is really just a machine-readable summary of our actions from the previous section. -## Mail the Patches (Mary) {#patch-workflows.xhtml_mail-the-patches-mary} +## Mail the Patches (Mary) Now that Mary has prepared a series of patches, she can send them to the project maintainer (us). In the typical patch workflow, she would send @@ -4730,7 +4635,7 @@ repository of whoever wants to add it to their project. For our example, all we need to do is copy the patches into the `my-git-repo` directory that represents our local version of the project. -## Apply the Patches (You) {#patch-workflows.xhtml_apply-the-patches-you} +## Apply the Patches (You) Copy the two patch files from `marys-repo` into `my-git-repo`. Using the new `git am` command, we can use these patches to add Mary's commits to @@ -4769,7 +4674,7 @@ she did, but that didn't necessarily have to be the case. The whole idea behind patches is that they let you isolate a commit and move it around as you please. -## Integrate the Patches (You) {#patch-workflows.xhtml_integrate-the-patches-you} +## Integrate the Patches (You) Once again, we're in the familiar situation of integrating a topic branch into the stable `master` branch. @@ -4787,7 +4692,7 @@ so we can get rid of the patch files with `git clean`. This was also an appropriate time to push changes to the public repository so other developers can access the most up-to-date version of the project. -## Update Mary's Repository (Mary) {#patch-workflows.xhtml_update-marys-repository-mary} +## Update Mary's Repository (Mary) Mary might be tempted to merge her `pink-page` branch directly into her `master` branch, but this would be a mistake. Her `master` branch _must_ @@ -4816,7 +4721,7 @@ following. ![The patch workflow](images/10-2.png) -## Conclusion {#patch-workflows.xhtml_conclusion} +## Conclusion Whereas remote repositories are a way to share entire _branches_, patches are a way to send individual _commits_ to another developer. @@ -4846,7 +4751,7 @@ personal and professional software projects using a centralized, integrator, or patch workflow. In the next module, we'll switch gears and introduce a variety of practical Git commands. -## Quick Reference {#patch-workflows.xhtml_quick-reference} +## Quick Reference `git format-patch ` : Create a patch for each commit contained in the current branch but @@ -4855,15 +4760,13 @@ not in ``. You can also specify a commit ID instead of `git am < ` : Apply a patch to the current branch. -::::: -:::::: +: -[]{#tips-and-tricks.xhtml} +[] -:::::: {#tips-and-tricks.xhtml_page} -::::: {#tips-and-tricks.xhtml_content} +: -# Tips & Tricks {#tips-and-tricks.xhtml_tips-tricks} +# Tips & Tricks This module presents a broad survey of useful Git utilities. We'll take a step back from the theoretical aspects of Git and focus on common @@ -4872,22 +4775,17 @@ While working through this module, your goal shouldn't be to master all of these miscellaneous tools, but rather to understand why they were created and when they might come in handy. -::: {.icon-text .download-icon-text} ![](images/icons/download.png){style="max-width: 45px"} [Download the repositories for this module](http://rypress.com/tutorials/git/media/repo-zips/tips-and-tricks.zip) -::: - -::: {style="clear: both"} -::: If you've been following along from the previous module, you already have everything you need. Otherwise, download the zipped Git repositories from the above link, uncompress them, and you're good to go. -## Archive The Repository {#tips-and-tricks.xhtml_archive-the-repository} +## Archive The Repository First, let's export our repository into a ZIP archive. Run the following command in your local copy of `my-git-repo`. @@ -4912,7 +4810,7 @@ don't have Git installed on their machine. This is also an easy way to create Git-independent backups of important revisions, which is always a good idea. -## Bundle the Repository {#tips-and-tricks.xhtml_bundle-the-repository} +## Bundle the Repository Similar to the `git archive` command, `git bundle` turns a repository into a single file. However, in this case, the file retains the @@ -4951,7 +4849,7 @@ active projects. We won't be needing the `repo.bundle` file and `repo-copy` folder, so go ahead and delete them now. -## Ignore a File {#tips-and-tricks.xhtml_ignore-a-file} +## Ignore a File Remember that Git doesn't automatically track files because we don't want to record generated files like C binaries or compiled Python @@ -4999,7 +4897,7 @@ repository. *.out *.exe -## Stash Uncommitted Changes {#tips-and-tricks.xhtml_stash-uncommitted-changes} +## Stash Uncommitted Changes Next, we'll take a brief look at **stashing**, which conveniently "stashes" away uncommitted changes. Open up `style.css` and change the @@ -5057,7 +4955,7 @@ Let's undo these CSS updates before moving on. git reset --hard ``` -## Hook into Git's Internals {#tips-and-tricks.xhtml_hook-into-gits-internals} +## Hook into Git's Internals Arguably, Git's most useful configuration options are its **hooks**. A hook is a script that Git executes every time a particular event occurs @@ -5127,7 +5025,7 @@ For a detailed description of the available hooks, please consult the [official Git documentation](http://www.kernel.org/pub/software/scm/git/docs/githooks.html). -## View Diffs Between Commits {#tips-and-tricks.xhtml_view-diffs-between-commits} +## View Diffs Between Commits Up until now, we've been using `git log --stat` to view the changes introduced by new commits. However, this doesn't show us which lines @@ -5200,7 +5098,7 @@ to the staging area, but the changes are now visible through the `‑‑cached` flag. These are the three main configurations of the `git diff` command. -## Reset and Checkout Files {#tips-and-tricks.xhtml_reset-and-checkout-files} +## Reset and Checkout Files We've used `git reset` and `git checkout` many times throughout this tutorial; however, we've only seen them work with branches/commits. You @@ -5250,7 +5148,7 @@ both take a committed snapshot as an reference point and make a file in the staging area or the working directory match that reference, respectively. -## Aliases and Other Configurations {#tips-and-tricks.xhtml_aliases-and-other-configurations} +## Aliases and Other Configurations Typing `git checkout` every time you wanted to see a new branch over the last ten modules has been a bit verbose. Fortunately, Git lets you @@ -5305,7 +5203,7 @@ Note that storing your global configurations in a plaintext file makes it incredibly easy to transfer your settings to a new Git installation: just copy `~/.gitconfig` onto your new machine. -## Conclusion {#tips-and-tricks.xhtml_conclusion} +## Conclusion In this module, we learned how to export snapshots, backup repositories, ignore files, stash temporary changes, hook into Git's internals, @@ -5328,7 +5226,7 @@ database by manually inspecting and creating snapshots. Equipped with this low-level knowledge, you'll be more than ready to venture out into the reality of Git-based project management. -## Quick Reference {#tips-and-tricks.xhtml_quick-reference} +## Quick Reference `git archive --format=zip --output=` : Export a single snapshot to a ZIP archive called ``. @@ -5369,15 +5267,13 @@ switching branches. `git config --global alias. ` : Create a shortcut for a command and store it in the global configuration file. -::::: -:::::: +: -[]{#plumbing.xhtml} +[] -:::::: {#plumbing.xhtml_page} -::::: {#plumbing.xhtml_content} +: -# Plumbing {#plumbing.xhtml_plumbing} +# Plumbing In [Rewriting History](#rewriting-history.xhtml), I talked about the internal representation of a Git repository. I may have mislead you a @@ -5398,21 +5294,16 @@ commands even more powerful. We'll start by inspecting Git's object database, then we'll manually create and commit a snapshot using only Git's low-level interface. -::: {.icon-text .download-icon-text} ![](images/icons/download.png){style="max-width: 45px"} [Download the repository for this module](http://rypress.com/tutorials/git/media/repo-zips/plumbing.zip) -::: - -::: {style="clear: both"} -::: If you've been following along from the previous module, you already have everything you need. Otherwise, download the zipped Git repository from the above link, uncompress it, and you're good to go. -## Examine Commit Details {#plumbing.xhtml_examine-commit-details} +## Examine Commit Details First, let's take a closer look at our latest commit with the `git cat-file` plumbing command. @@ -5452,7 +5343,7 @@ Notice that each commit refers to one and only one tree object. From the `git cat-file` output, we can also infer that trees use SHA-1 checksums for their ID's. This will be the case for all of Git's internal objects. -## Examine a Tree {#plumbing.xhtml_examine-a-tree} +## Examine a Tree Next, let's try to inspect a tree using the same `git cat-file` command. Make sure to change `552acd4` to the ID of your tree from the previous @@ -5495,7 +5386,7 @@ we've been using, and their relationship is summed up as follows: ![Commit, tree, and blob objects](images/12-2.png) -## Examine a Blob {#plumbing.xhtml_examine-a-blob} +## Examine a Blob Let's take a look at the blob associated with `blue.html` (be sure to change the following to the ID next to `blue.html` in _your_ tree @@ -5533,7 +5424,7 @@ However, as soon as you change a single line in a file, Git must create a new blob object because its contents will have changed, resulting in a new SHA-1 checksum. -## Examine a Tag {#plumbing.xhtml_examine-a-tag} +## Examine a Tag The fourth and final type of Git object is the **tag object** We can use the same `git cat-file` command to show the details of a tag. @@ -5549,7 +5440,7 @@ diagram: ![Commit, tree, blob, and tag objects](images/12-4.png) -## Inspect Git's Branch Representation {#plumbing.xhtml_inspect-gits-branch-representation} +## Inspect Git's Branch Representation We now have the tools to fully explore Git's branch representation. Using the `-t` flag, we can determine what kind of object Git uses for @@ -5599,7 +5490,7 @@ Let's get back to our `master` branch before moving on: git checkout master ``` -## Explore the Object Database {#plumbing.xhtml_explore-the-object-database} +## Explore the Object Database While we have a basic understanding of Git's object interaction, we have yet to explore where Git keeps all of these objects. In your @@ -5645,7 +5536,7 @@ My object was a blob, but yours may be different. If it's a tree, remember to use `git ls-tree` to turn that ugly binary data into a pretty directory listing. -## Collect the Garbage {#plumbing.xhtml_collect-the-garbage} +## Collect the Garbage As your repository grows, Git may automatically transfer your object files into a more compact form know as a "pack" file. You can force this @@ -5667,7 +5558,7 @@ unaffected. The `git gc` command only changes Git's storage mechanism---not the contents of a repository. Running `git gc` every now and then is usually a good idea, as it keeps your repository optimized. -## Add Files to the Index {#plumbing.xhtml_add-files-to-the-index} +## Add Files to the Index Thus far, we've been discussing Git's low-level representation of committed snapshots. The rest of this module will shift gears and use @@ -5732,7 +5623,7 @@ We've just moved the working directory into the index, which means we have a snapshot prepared for committal. However, the process won't be quite as simple as a mere `git commit`. -## Store the Index in the Database {#plumbing.xhtml_store-the-index-in-the-database} +## Store the Index in the Database Remember that all commits refer to a tree object, which represents the snapshot for that commit. So, before creating a commit object, we need @@ -5761,7 +5652,7 @@ git ls-tree 5f44809 So, we have our tree object, but we have yet to add it to the project history. -## Create a Commit Object {#plumbing.xhtml_create-a-commit-object} +## Create a Commit Object To commit the new tree object, we need to manually figure out the ID of the parent commit. @@ -5802,7 +5693,7 @@ stores its branch information. ![Creating a dangling commit](images/12-5.png) -## Update HEAD {#plumbing.xhtml_update-head} +## Update HEAD Since we're not in a `detached HEAD` state, `HEAD` is a reference to a branch. So, all we need to do to update `HEAD` is move the `master` @@ -5829,7 +5720,7 @@ won't have to use Git's plumbing ever again? ![Manually updating the `master` branch](images/12-6.png) -## Conclusion {#plumbing.xhtml_conclusion} +## Conclusion After this module, you hopefully have a solid grasp of the object database that underlies almost every Git command. We examined commits, @@ -5859,32 +5750,3 @@ scenarios. Good luck! For questions, comments, or suggestions, please [contact us](http://rypress.com/about). - -## Quick Reference {#plumbing.xhtml_quick-reference} - -`git cat-file ` -: Display the specified object, where `` is one of `commit`, -`tree`, `blob`, or `tag`. - -`git cat-file -t ` -: Output the type of the specified object. - -`git ls-tree ` -: Display a pretty version of the specified tree object. - -`git gc` -: Perform a garbage collection on the object database. - -`git update-index [--add] ` -: Stage the specified file, using the optional `--add` flag to denote -a new untracked file. - -`git write-tree` -: Generate a tree from the index and store it in the object database. -Returns the ID of the new tree object. - -`git commit-tree -p ` -: Create a new commit object from the given tree object and parent -commit. Returns the ID of the new commit object. -::::: -::::::