{"id":15361075,"url":"https://github.com/asmeurer/git-workflow","last_synced_at":"2025-07-11T20:01:51.043Z","repository":{"id":32261029,"uuid":"35835478","full_name":"asmeurer/git-workflow","owner":"asmeurer","description":"The git workflow for contributing to open source repositories.","archived":false,"fork":false,"pushed_at":"2022-04-27T17:15:11.000Z","size":4437,"stargazers_count":220,"open_issues_count":6,"forks_count":53,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-06-22T05:05:52.117Z","etag":null,"topics":["git","github","newusers","workflow"],"latest_commit_sha":null,"homepage":"https://www.asmeurer.com/git-workflow/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/asmeurer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-05-18T18:34:18.000Z","updated_at":"2025-06-15T22:35:48.000Z","dependencies_parsed_at":"2022-08-14T23:30:19.206Z","dependency_job_id":null,"html_url":"https://github.com/asmeurer/git-workflow","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/asmeurer/git-workflow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asmeurer%2Fgit-workflow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asmeurer%2Fgit-workflow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asmeurer%2Fgit-workflow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asmeurer%2Fgit-workflow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/asmeurer","download_url":"https://codeload.github.com/asmeurer/git-workflow/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asmeurer%2Fgit-workflow/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264890029,"owners_count":23678825,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["git","github","newusers","workflow"],"created_at":"2024-10-01T12:53:15.275Z","updated_at":"2025-07-11T20:01:50.941Z","avatar_url":"https://github.com/asmeurer.png","language":"HTML","readme":"# Git workflow\n\nThis document describes the git workflow that should be used when contributing\nto open source projects on GitHub. It assumes a very basic understanding of\ngit (commits, branches, etc.) using the command line.\n\n*Note: This workflow is designed for open source (i.e., public)\nrepositories. The workflow for private repositories may be slightly different,\nin particular, the repository's team may prefer for you to not fork the repo\nbut rather push branches to it directly (although note that GitHub does allow\nyou to fork private repositories that you have push access to and keeps the\nfork private).*\n\nFor this document, we will suppose that you want to contribute a patch to\n[sympy/sympy](https://github.com/sympy/sympy).\n\n**NOTE: If you want to test out this guide without making an\nactual fix, please test against THIS REPO (`asmeurer/git-workflow`). Do not\nmake a pull request against `sympy/sympy` unless you are making an actual\nchange.**\n\n## Cloning and forking the repository\n\n**Note: The steps in this section only need to be performed once per\nrepository (e.g., if you contribute a second change to sympy/sympy, you would\nnot need to repeat them, but if you contribute to\n[sympy/sympy-live](https://github.com/sympy/sympy-live) you will need to\nrepeat them for that repository).**\n\n1. **Clone the repository.** Click the green \"\u003cfont color=\"green\"\u003eClone or download\u003c/font\u003e\" button \u003cfont color=\"blue\"\u003e①\u003c/font\u003e,\n   and copy the url \u003cfont color=\"blue\"\u003e②\u003c/font\u003e and type\n\n   \u003ccode\u003egit clone \u003ci\u003eclone-url\u003c/i\u003e\u003c/code\u003e\n\n   at the terminal. Replace *`clone-url`* with the url that has been copied to\n   your clipboard. For sympy/sympy, it will be\n   `git@github.com:sympy/sympy.git`. If you have not set up your ssh keys with\n   GitHub, use the https url by first clicking the `https` button \u003cfont\n   color=\"blue\"\u003e③\u003c/font\u003e.\n\n   ![clone.png](clone.png)\n\n   *Note: It is important that you clone from the repo you are contributing\n   to (like sympy/sympy),* not *your fork of the repo.*\n\n2. **Fork the repo on GitHub to your personal account.** Click the `Fork`\n   button on the sympy/sympy page.\n\n   ![fork.png](fork.png)\n\n   If you are presented with a list of organizations, click on your GitHub\n   username.\n\n3. **Add your fork as a remote.** This remote will be named after your github\n   username.  Go to the fork of your repository, in this case,\n   \u003ccode\u003ehttps://github.com/\u003ci\u003eyour-username\u003c/i\u003e/sympy\u003c/code\u003e (replace *`your-username`* with\n   your GitHub username), and copy the clone url as in step 1. `cd` to your\n   clone from step 1 and run\n\n   \u003ccode\u003e\n   git remote add \u003ci\u003eyour-github-username\u003c/i\u003e \u003ci\u003efork-url\u003c/i\u003e\n   \u003c/code\u003e\n\n   (replace *`your-github-username`* with your GitHub username and\n   *`fork-url`* with the url that was copied to your clipboard). You will be\n   able to tell it is your fork url because it will have your GitHub username\n   in it. For instance, if your username is `github_user`, you would run the\n   command `git remote add github_user git@github.com:github_user/sympy.git`.\n\nRemember, the above three steps only need to be performed once per\nrepository. Once you have cloned and forked a repository once, there is no\nneed to clone or fork it again.\n\n## Making changes\n\nBefore you make any changes, you should make a branch. Remember to **never\ncommit to master**. The command `git status` will tell you what branch you are\non. I recommend putting the git branch in your command prompt, so that you\nwill always know what branch you are on. See\n[this guide](http://stackoverflow.com/a/24716445/161801) on how to do this.\n\nIt is important that you never commit to master because master will be the\nbranch that you pull upstream changes from (e.g., changes from\nsympy/sympy).\n\n1. **Update master.** Before you make any changes, first checkout master\n\n   ```\n   git checkout master\n   ```\n\n   and pull in the latest changes\n\n   ```\n   git pull\n   ```\n\n   This will make it so that your changes are against the very latest master,\n   which will reduce the likelihood of merge conflicts due to your changes\n   conflicting with changes made by someone else.\n\n2. **Create a branch.** Once you have done this, create a new branch. You\n   should make a branch name that is short, descriptive, and unique. Some\n   examples of good branch names are `fix-install`, `docs-cleanup`, and\n   `add-travis-ci`. Some examples of bad branch names are `feature`, `fix`,\n   and `patch`. The branch name choice is not too important, so don't stress\n   over it, but it is what people will use to reference your changes if they\n   want to pull them down on their own computers to test them, so a good name\n   will make it easier for others to understand what your branch does. In this\n   example, the branch name is `fix-install`.\n\n   To create the branch, run\n\n   \u003ccode\u003e\n   git checkout -b \u003ci\u003ebranch-name\u003c/i\u003e\n   \u003c/code\u003e\n\n   (replace *`branch-name`* with the branch name you chose). This will create a\n   new branch and check it out. You can verify this with `git status`.\n\n3. **Make your changes and commit them.** Once you have created your branch,\n   make your changes and commit them. Remember to keep your commits atomic,\n   that is, each commit should represent a single unit of change. Also,\n   remember to write helpful commit messages, so that someone can understand\n   what the commit does just from reading the message without having to read\n   the diff.\n\n   For example, at the command line, this might look like\n\n   \u003cpre\u003e\u003ccode\u003egit add \u003ci\u003efilename [filename ...]\u003c/i\u003e\n   git commit\n   \u003c/code\u003e\u003c/pre\u003e\n\n   This will open an editor where you can write your commit message.\n\n4. **Push up your changes.**  Push your changes to your fork. Do this by\n   running\n\n   \u003ccode\u003e\n   git push \u003ci\u003eyour-github-username\u003c/i\u003e \u003ci\u003ebranch-name\u003c/i\u003e\n   \u003c/code\u003e\n\n   (replace *`your-github-username`* with your GitHub username and\n   *`branch-name`* with the name of the branch).\n\n5. **Make a pull request.** If you then go to your fork on GitHub, you should\n   see a button to create a pull request from your branch. It will look\n   something like this:\n\n   ![pull.png](pull.png)\n\n   If you do not see this, go to the GitHub page for your fork \u003cfont\n   color=\"blue\"\u003e①\u003c/font\u003e, select the branch from the branch popup \u003cfont\n   color=\"blue\"\u003e②\u003c/font\u003e and click the pull request button \u003cfont\n   color=\"blue\"\u003e③\u003c/font\u003e.\n\n   ![pull2.png](pull2.png)\n\n   Once doing this, you will be presented with a page. This page will show you\n   the diff of the changes. Double check them to make sure you are making a\n   pull request against the right branch.\n\n   Things to check here are that the base fork is the upstream repo \u003cfont\n   color=\"blue\"\u003e①\u003c/font\u003e (in this case, sympy/sympy) and the branch for the\n   upstream repo is master, and that the head fork is your fork \u003cfont\n   color=\"blue\"\u003e②\u003c/font\u003e and the branch is the branch you wish to make the\n   pull request from.\n\n   Enter a descriptive title in the title field \u003cfont color=\"blue\"\u003e③\u003c/font\u003e.\n   This is very important, as it is what will show up in the pull request\n   listing and in email notifications to the people in the repo. Pull requests\n   with undescriptive titles are more likely to be passed by. If the pull\n   request fixes an issue, I recommend putting the issue number in the pull\n   request description \u003cfont color=\"blue\"\u003e④\u003c/font\u003e, not the title. People\n   generally do not know issues by number, so a pull request that is just\n   titled \"fix for issue #1234\" is more likely to be passed by, as it is\n   unclear what it does from the title.\n\n   If there is more description or discussion about the pull request than\n   what fits in the title field use the description field \u003cfont\n   color=\"blue\"\u003e④\u003c/font\u003e.\n\n   If the pull request fixes an issue, you can add \"fixes #**1234**\" (replace\n   **1234** with the actual issue number) in the pull request description \u003cfont\n   color=\"blue\"\u003e④\u003c/font\u003e.  This exact format, \"fixes #**1234**\" is important, as\n   it will cause GitHub to automatically close the issue when the pull request\n   is merged.\n\n   Once you are done, click the \"create pull request\" button \u003cfont\n   color=\"blue\"\u003e⑤\u003c/font\u003e.\n\n   ![pull3.png](pull3.png)\n\n6. **Pushing additional changes**. Once you have created the pull request, it\n   will likely be reviewed and some additional fixes will be necessary. **Do\n   not create a new pull request.** Rather, simply make more commits to your\n   branch and push them up as in steps 3 and 4. They will be added to the pull\n   request automatically. Note that although GitHub does notify people when\n   you push new changes to a branch, many people have these notifications\n   disabled as they can be quite noisy. So it is a good idea to make a comment\n   on the pull request whenever you do so to notify people that it is ready to\n   be reviewed again.\n\nOnce the pull request has been reviewed successfully, someone with push access\nto the main repository will merge it in. At this point you are done. You can\ncheckout master and pull as described in step 1 and your changes should be\nthere.\n\n## Important points\n\nThe important things to remember from this document are\n\n1. You only need to clone and fork once per repository.\n\n2. Always clone from the main repository and add your fork as a remote.\n\n3. Never commit to master. Create a branch and commit to it.\n\n4. Use `git status` often to check what branch you are on and see if you have\n   any uncommitted changes.\n\n5. Be descriptive in your branch names, commit messages, and pull request\n   title and descriptions.\n\n6. Once you have a pull request for a branch, you can push additional changes\n   to the same branch and they will be added to the pull request\n   automatically. You should never create a new pull request for the same\n   branch.\n\n7. Comment on the pull request when you want people to know that you have\n   pushed new changes. Although GitHub does notify people of commit pushes,\n   people are more likely notice your changes if you leave a comment.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasmeurer%2Fgit-workflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fasmeurer%2Fgit-workflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasmeurer%2Fgit-workflow/lists"}