├── Basic Workflow.md ├── Common Commands.md ├── README.md ├── Sample.md ├── Setting Up.md ├── _config.yml └── art ├── clone_btn.png └── fork_button.jpg /Basic Workflow.md: -------------------------------------------------------------------------------- 1 | 2 | #Git Guide for Collaborative Work 3 | 4 | ##Introduction 5 | This page will outline a basic workflow to use when working on collaborative projects, wherein one person sets up the initial project and others are able to work on the same. Let us assume the situtation where there are three people Mo, Meggie and Darius who need to work on a project together and would like to use git/github for collaboration. Assuming they all have gitbash(windows) or git in terminal(linux) or on Mac, these are the steps to follow: 6 | 7 | ##Setting Up The Project 8 | Only one person needs to create the initial project and push it to the remote. Let us assume it is going to be Mo. 9 | 10 | ### Mo's Work: 11 | * Create an account on github. (everyone needs to do this as well) 12 | * Create a new Repository by clicking the **NEW** repository button. 13 | * Give it a name. 14 | * See the initial page and locate the https URL where this repository exists. 15 | * Add Meggie and Darius as **Collaborators**(to give them write permissions to this repository) by going in Settings of this repository. 16 | * Open git bash/terminal and go into the directory where your local project exists(the one on which you plan to work on, create it like you would create any other local project of that kind). Lets say the project they plan to work exists in Mo's machine at `/Documents/PythonProjects/mysite`. The terminal would look something like: 17 | * The following procedure for Mo is: 18 | * `git init` So that git commands start working in this directory 19 | * `git remote add origin URL` Here URL refers to the URL where you created the new repository in github. This is used to connect your local folder(mysite) to the one on github. 20 | * Now when you run `git status` you are able to see all the files that exist in the local folder. As they come in red, it means they are not ready to be sent to the remote. We need tou change that 21 | * Run `git add .` (to add all files at once, in future you can add one file at a time by running `git add ` {without brackets}). Now when you run `git status` you will be able to see your added files in green. 22 | * Now these files need to be committed as only files bound by a commit are sent to the server, added files are not. This is used that in case you have made changes to 5 files and need to send only 3 of them, you can add only those three and then commit them to finalise their sending. 23 | * Run `git commit -m "Commit Message"` The message logically explains what changes you made in this commit. 24 | * Run `git push -u origin master` (The -u is required only on the first commit, afterwards you will only need to use `git push origin master`). What this command does is to push your local changes to the origin (which we added few steps before) and to the **master** branch (All we need to know about branches right now is that git works in form of branches and if none other is specified, all the work takes place on the master branch). 25 | * After doing this, Mo's work is finished (which was a lot!) 26 | 27 | ### Meggie and Darius's Work: 28 | * First of all you will be glad to know that they **dont** need to create a local project, they can get the project uploaded by Mo in their machines. 29 | * Now suppose Meggie wants the project to be in the `/Documents/PythonProjects` directory, she has to go to that directory in her git bash or terminal. 30 | * (One Time Step) Run `git clone URL` where URL is the same URL as used by Mo to upload the project. This is done just once to get a copy of the remote project locally and doesn't have to be done again. 31 | * And voila! The project is with Meggie and she can run it like any other project of that kind. After making any changes to the project she will have to got to the directory `/Documents/PythonProjects/mysite` (all git commands are run from this directory henceforth, this can be the path to your own directory). 32 | 33 | That was it! Now all three, Mo, Darius and Meggie have a syncronised copy of the project and can start working locally. To push their changes to the remote they will need to follow the **Synchronisation** process as described below. 34 | 35 | ##Synchronising the Work 36 | Git is very particular about how you collaborate with others and thus has a strict protocol to follow when uploading your work to the remote server: 37 | 1. You need to pull the work done on the remote server. You **cannot** push your local changes until and unless you have all the changes made on the remote repository. 38 | 2. Add the files you need to send. 39 | 3. Commit the work. 40 | 4. Push. 41 | 42 | Now let us break down each of the steps. 43 | 44 | 1. **Pulling remote work:** 45 | * Assuming you have made some changes to your local repository and when you run `git status` you see some files in red indicating your changes. 46 | * You first of all need to go back to a version of your local repository that was synced to the remote. For that run `git stash`. Now when you run `git status` you won't be able to see any files you made changes to. (Any newly added files will still be seen) 47 | * Now run `git pull origin master` to pull the work done on remote server to your local repository. It should show some files with additions and subtractions if changes have been made remotely, if not, it will return a newline. 48 | * Now you want all your precious work back. Run `git stash pop` and you will see all your files with the changes. 49 | We are synced and up to date with the remote repository. 50 | 51 | 2. **Add your files** 52 | * Run `git add ` to add the files you wish to send. 53 | * Run `git add .` to add all the files you made changes to (Not recommended). 54 | 55 | 3. **Commit your changes** 56 | * Run `git commit -m "Commit Message"` (Make the message more meaningful indicating your changes) 57 | 58 | 4. **Push your changes** 59 | * Run `git push origin master` 60 | * Ideally git should ask for your github username and password everytime you push if you haven't saved it globally (to be covered later). 61 | 62 | And you are done! Now you can push and pull your changes anytime you want it. If you do not wish to push your changes and just pull the changes made at remote, follow only **step 1** of the above. 63 | -------------------------------------------------------------------------------- /Common Commands.md: -------------------------------------------------------------------------------- 1 | #Common Commands 2 | 3 | ##Making changes 4 | * Adding Files 5 | * `git add ` : 6 | * `git add .` 7 | * Stashing Changes 8 | * `git stash` 9 | * `git stash pop` 10 | * Committing Files 11 | * `git commit -m "[descriptive message]"` 12 | * Unstaging Files 13 | * `git reset ` 14 | 15 | ##Reviewing Changes 16 | * `git status` : List the files you've changed and those you still need to add or commit 17 | * Viewing File Differences : 18 | * `git diff` : Shows file differences not yet staged. 19 | * `git diff --base ` : View the changes against the base file. 20 | * `git diff ` : View changes in source branch against a target. 21 | * `git log` : View summary of all commits made so far in the current branch. 22 | 23 | 24 | ##Receiving Files 25 | * `git fetch` : Fetch changes from remote repository 26 | 27 | ##Searching for Files 28 | * `git grep ` : Search the current branch for given term 29 | 30 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Git-Guide For Open Source Contributions 2 | This is a guide containing tools and tricks every developer starting on the open source journey will need. It can also serve as a quick reference for some of the tricky commands for the pros. Feel free to suggest changes or contribute! 3 | 4 |
5 | Starting your own project with others? Learn about the [Basic Workflow](https://github.com/chhavip/Git-Guide/blob/master/Basic%20Workflow.md) when working on collaborative projects. 6 | 7 |
8 | 9 | ##Table of Contents: 10 | * [Setting Up Git/Github on your machine](https://github.com/chhavip/Git-Guide/blob/master/Setting%20Up.md) 11 | 12 | * [Common Terms](#common-terms) 13 | 14 | * [Setting up - First Time User](#set-up) 15 | 16 | * [Forking an existing project and making changes](#forking-a-project-and-making-changes) 17 | 18 | * [Connecting to original project](#setting-up-upstream) 19 | 20 | * [Branching and Pull Requests](#branching-and-pull-requests) 21 | 22 | * [Squashing Commits](#squashing-commits) 23 | 24 | * [Fixing PR when other changes get merged leading to conflicts](#fixing-pr-when-other-changes-get-merged-leading-to-conflicts) 25 | 26 | * [Undoing Commits](#undoing-commits) 27 | 28 | * [Merge Conflicts - why and how to remove](#merge-conflicts) 29 | 30 | 31 | 32 | ##Common Terms 33 | Some of the basic terms used while working with git are: 34 | * **Repository** : A basic folder or a collection of files that represents one project. The name of this repository is **Git-Guide**. When you clone, you clone an entire repository and every repository is identified by a unique URL. 35 | 36 | * **Local Repository** : The project folder which exists in your machine, locally. It is where you make your changes and push them to the github repository. No one can make changes to your local repository directly other than yourself, you need to sync (connect) this local repository with a repository on github (or any VCS system) in order to push and pull changes. 37 | 38 | * **Remote Repository** : This is the respository hosted on github (or any other VCS) to which your local repository is connected. You push your changes to this and others working on the same project can see your changes. Only those with write permissions to this repository can make direct changes to it. Many people can make changes to this repository and you can pull those changes to your local repository and push your own to this. A single local repository can be connected to multiple remote repositories. Remote repositories are referred by keywords like **origin** and **upstream**. 39 | 40 | 41 | * **Fork**: This is how you make a copy of a project owned by someone else. A person or organisation. Apart from the owner of the repository, no one is allowed to make direct changes to the project. So fork is used to make a copy of the project that is owned by you. 42 | 43 | * **Clone**: You got the project in your account, now what? A clone is just that, a copy. It does not care about ownership. It is aimed to bring the copy of the project hosted on github or any other VCS system in your machine. This is where you will make the changes and later update your remote project 44 | 45 | * **Commit**: This is a checkpoint in your project history. All the commits are recorded in git logs with the description provided by user. After you add, modify or remove any files, a commit is made to save these changes in history. 46 | 47 | * **Push**: This is how you send the changes made in your local repository to your remote. All your changes remain unsynced until you have pushed them and this is necessary step to keep the changes parallel. Only the files you commit(as in the previous definition) are pushed and rest of the changes remain local to your project. 48 | 49 | * **Fetch**: This is in very simple terms means to download any updates and changes from a remote repository. This does not mean that you have included the changes in your project. Just download. 50 | 51 | * **Merge**: This means to merge or combine updates fetched from remote repository with your local one. This may lead to merge conflicts if a change in remote is incompatible with a change in your local project. 52 | 53 | * **Pull**: This means to fetch any updates that may have occured in a remote branch in your local repository and merge them. This is basically a fetch followed by a merge. 54 | 55 | * **Pull Request (PR)**: Pull Request or PR as it is generally known, is a method to contribute to open development projects by including bug fixes or adding new features. Its a way of contributing by asking the owner of project to include changes made in the external/forked repository. 56 | 57 | 58 | 59 | ##Set Up 60 | In order to set up the user through terminal: 61 | 62 | `git config --global user.name ` 63 | 64 | `git config --global user.email ` 65 | 66 | This is the user your commits and PR will be shown through. 67 | 68 | ##Forking a Project and Making Changes 69 | In order to work on an existing project that is not owned by you, follow the following steps: 70 | 71 | 1. `Fork` the project from the respective repository. This will redirect you to your fork of the project which is basically a copy of the original project but you are its owner. 72 | 73 |
74 | 76 |
77 |
78 | 79 | 2. Copy the HTTPS link of the project and go to the location through terminal or command prompt where you want to have the repository locally 80 | 3. Run `git clone `. This will give you a local copy of the project which you can work with. 81 | 82 |
83 | 85 |
86 |
87 | 88 | 4. Any changes in the local repository can be tracked by running `git status` in that directory. Files in red will be the ones that have been modified, added or deleted. 89 | 5. To have your remote repository(the one hosted online also referred to as *origin*) reflect the changes, do 90 | `git add ` for all the files who's changes you wish to see in the remote. You can also run `git add .` to add all the files that have been changed (not advisable though). 91 | 6. Run `git status` once again and you will see the files that you have added in green. 92 | 7. In case you need to un-add any file, run `git reset HEAD -- ` 93 | 8. To commit the changes (equivalent to locking down the changes you have made), run `git commit -m "Your commit message"` 94 | 9. So far you have made and saved the changes in your local repository, to send the changes to your fork in github, run 95 | `git push` which will ask for your username and password. Fill and you are ready to go. 96 | 97 | NOTE: This by default pushes all your local branches to remote with the same name. We will go through branching later. 98 | 99 | 100 | ##Setting up Upstream 101 | When a repository is cloned, it has a default remote called `origin` that points to your fork on GitHub, not the original repository it was forked from. To keep track of the original repository, you should add another remote named `upstream`: 102 | 103 | 1. Open terminal or git bash in your local repository and type: 104 | 105 | `git remote add upstream ` 106 | 107 | 1. Run `git remote -v` to check the status, you should see something like the following: 108 | 109 | > origin https://github.com/YOUR_USERNAME/project-name.git (fetch) 110 | 111 | > origin https://github.com/YOUR_USERNAME/project-name.git (push) 112 | 113 | > upstream https://github.com/OWNER_USERNAME/project-name.git (fetch) 114 | 115 | > upstream https://github.com/OWNER_USERNAME/project-name.git (push) 116 | 117 | 1. To update your local copy with remote changes, run the following: 118 | 119 | `git fetch upstream` 120 | 121 | `git merge upstream/master` 122 | 123 | As you may have guessed already, quicker way to the same would be `git pull upstream master`, because Pull is essentially a Fetch operation followed by Merge operation. 124 | 125 | This will give you an exact copy of the current remote, but make sure you don't have any local changes. 126 | 127 | 128 | ##Branching and Pull Requests 129 | 130 | Branches exist in github to enable you to work on different features simultaneously without they interfering with each other and also to preserve the master branch. Usually the master branch of your project should be kept clean and no feature should be developed directly in the master branch. Follow the following steps to create branches and be able to sync them: 131 | 132 | 1. Make sure you are in the master branch : `git checkout master`. 133 | 134 | 2. Sync your copy with remote copy : `git pull`. 135 | 136 | 3. Create a new branch with a meaningful name : `git checkout -b branch_name`. 137 | 138 | 4. Add the files you changed : `git add file_name` (avoid using `git add .`). This is called "staging" the files. 139 | 140 | 5. Commit your changes `git commit -m "Message briefly explaining the feature"`. 141 | 142 | 6. Push to your repo `git push origin branch-name` 143 | 144 | This will push the changes you made to your fork on github under the branch name you gave. 145 | 146 | To have the owner of the original project review your changes, create a Pull Request explaining the changes you made. If it is satisfactory, it will be merged with the original project. 147 | 148 | ###Common Branch Commands: 149 | 150 | `git branch` will give you all the branches your local repository has. 151 | 152 | `git branch -a` will give you all the branches your local and remote repositories have 153 | 154 | `git branch -d the_local_branch` will delete a local branch that you had by the given name. Make sure you dont have any loose ends in the branch or a delete won't be allowed. 155 | After deleting the local branch, if you wish to delete the remote branch of the same name, use: 156 | 157 | `git push origin :the_remote_branch` but be careful while using this. 158 | 159 | ##Squashing Commits 160 | Often it is required while contributing that your entire feature change is in the form of one single commit, this is where squashing comes in. Be aware of the type of commits you are trying to squash. There can be two: 161 | * Commits in your local repository 162 | * Commits you have already pushed to remote 163 | 164 | First of all be sure to run `git log` and see your recent commit history, this will help you decide which commits you wish to squash. 165 | If for example you wish to squash the last two commits into a single one, run: 166 | 167 | `git checkout my_branch` to make sure you are on your required branch 168 | 169 | `git reset --soft HEAD~2` where 2 represents the number of commits to be sqaushed, can be replaced with your need 170 | 171 | `git commit -m "New commit message to represent the squashed commits"` 172 | 173 | The above two instruction will locally squash the number of commits you chose to. In case you had already pushed the commits to your remote repository, run the following command to make your remote reflect the changes: 174 | 175 | `git push --force origin my_branch` 176 | 177 | This is a forced update that makes the remote repository squash the commits into one. 178 | 179 | ###Fixing PR when other changes get Merged leading to Conflicts 180 | This is in continuation with requirement of having a single commit in your PR, suppose you did some work and submitted a PR to the main repository but before your request could be merged, changes were made by other developers in the repository and now your PR presents merge conflicts. You could fetch the work, resolve merge conflicts and push again but that will lead to `MERGE COMMIT` that is undesirable at times. The flow below can be followed to prevent the same: 181 | 182 | This assumes the following: 183 | * You have submitted a PR for a feature 184 | * Changes have been made to remote before your PR got merged and now there are merge conflicts between your PR and remote 185 | 186 | The steps to follow: 187 | * Checkout your branch with the features required `git checkout my_branch` 188 | * Fetch changes from remote `git fetch upstream` 189 | * Stash local changes(if any) `git stash` 190 | * Rebase to the latest branch in upstream (let it be master in our case) `git rebase upstream/master` 191 | * The following two steps are required only if merge conflicts occur: 192 | * If any merge conflicts are occuring, fix them in the project then add the files by using `git add ` or `git checkout -- ` (if you dont want your local changes) 193 | * After the changes have been fixed run `git rebase --continue` 194 | * Now the remote changes have been applied and your work has been applied on top of it 195 | * Force push to your branch to update the PR by using `git push --force origin my_branch` 196 | 197 | 198 | ##Undoing Commits 199 | Undoing commits means to remove the last commit you made from your history tree. This is not needed usually but more in the case a commit was made by mistake or was not complete. The following steps should usually be followed before having pushed to remote repository but you can force push your changes to reflect them on the remote. 200 | Now, getting down to undoing commits and the different scenarios: 201 | ``` 202 | A-B-C 203 | ↑ 204 | master 205 | ``` 206 | ###Completely Removing the last Commit 207 | Suppose C was your last commit and you want to go back to B, removing any work that you done on the way from B to C. 208 | The command for that is: 209 | `git reset --hard HEAD~1` 210 | 211 | The result is: 212 | ``` (F) 213 | A-B 214 | ↑ 215 | master 216 | ``` 217 | 218 | ###Keeping the work of the last Commit 219 | Now if you want just remove the commit but keep all the work you had done till that commit then starting from: 220 | ``` 221 | (F) 222 | A-B-C 223 | ↑ 224 | master 225 | ``` 226 | You need to run: 227 | `git reset HEAD~1` 228 | This will result in the following: 229 | ``` 230 | (F) 231 | A-B-C 232 | ↑ 233 | master 234 | ``` 235 | In both cases HEAD is pointer to the last commit and reset tells git to move it back one place. If you dont use `--hard`, your files will remain as they were and running a `git status` will show you all your changes preserved but the commit will be lost. 236 | 237 | ##Merge Conflicts 238 | 239 | ###Why do they occur? 240 | When working on a shared project, you and your fellow collaborators are bound to make changes to the same file unkowing to each other and one of you might push his/her changes to the original repository while the other is in middle of his/her changes. Now when the latter person will try to fetch the new code into his/her local repository, git won't know who's changes to keep as a given file has been modified by both. 241 | 242 | A typical merge conflict message looks like this: 243 | ``` 244 | $ git checkout style 245 | Switched to branch 'style' 246 | $ git merge master 247 | Auto-merging lib/hello.py 248 | CONFLICT (content): Merge conflict in lib/hello.py 249 | Automatic merge failed; fix conflicts and then commit the result. 250 | ``` 251 | Now your hello.py has merge conflicts as it was modified by you and someone else working on the project. 252 | 253 | ###Removing Merge Conflicts 254 | There are two cases where merge conflicts occur 255 | 256 | * A file is modified by both users 257 | * A file is modified by one or the other user while deleted by the other 258 | 259 | ##Disclaimer: 260 | This guide is aimed particularly at people starting open source contribution for the first time and aims to familiarise them with required patterns and expected contribution behaviour. 261 | -------------------------------------------------------------------------------- /Sample.md: -------------------------------------------------------------------------------- 1 | Enter your names here: 2 | 3 | Chhavi P. Gupta 4 | 5 | Simmmi 6 | Himani 7 | Himanshi 8 | 9 | -------------------------------------------------------------------------------- /Setting Up.md: -------------------------------------------------------------------------------- 1 | ##Setting Up git in your machine 2 | 3 | If you don't already have github installed in your machines, follow the following steps to enable controlling your projects through git (These are instructions to install git and not specific to github, can be used with any version control). 4 | 5 | ###Windows 6 | 7 | Install git for windows from [here](http://git-scm.com/download/win). Your download will start automatically. 8 | 9 | ###Ubuntu 10 | 11 | For instructions on installing git for different Unix flavors see [Download for Linux and Unix](https://git-scm.com/download/linux). 12 | 13 | ###Mac 14 | 15 | Install OSX Git installer from [here](http://git-scm.com/download/mac). Your download will start automatically. 16 | 17 | ##After installation 18 | 19 | Now that you have git installed on your machine you should first set your name and email address. This is important because every Git commit uses this information. 20 | 21 | 1. Open the git bash. 22 | 23 | 2. Tell git your name. Type everything after the `$` here : 24 | 25 | `$ git config --global user.name "YOUR NAME"` 26 | 27 | 3. Tell git your email address. 28 | 29 | ` $ git config --global user.email "YOUR EMAIL ADDRESS"` 30 | 31 | > **Note** : You need to do this only once if you pass the `--global` option, because then Git will always use that information for anything you do on that system. If you want to override this with a different name or email address for specific projects, you can run the command without the `--global` option when you’re in that project. 32 | 33 | If you want to check your git settings, you can use the `git config --list` command to list all the settings Git can find at that point: 34 | ``` 35 | $ git config --list 36 | user.name=YOUR NAME 37 | user.email=YOUR EMAIL ADDRESS 38 | color.status=auto 39 | color.branch=auto 40 | color.interactive=auto 41 | color.diff=auto 42 | ... 43 | ``` 44 | -------------------------------------------------------------------------------- /_config.yml: -------------------------------------------------------------------------------- 1 | theme: jekyll-theme-architect -------------------------------------------------------------------------------- /art/clone_btn.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chhavip/Git-Guide/b5ebd01081b629d2f0d65dbe93502de6fdf22e76/art/clone_btn.png -------------------------------------------------------------------------------- /art/fork_button.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chhavip/Git-Guide/b5ebd01081b629d2f0d65dbe93502de6fdf22e76/art/fork_button.jpg --------------------------------------------------------------------------------