{"id":15343839,"url":"https://github.com/rocketraman/gitworkflow","last_synced_at":"2025-04-15T02:36:50.173Z","repository":{"id":66674371,"uuid":"128618173","full_name":"rocketraman/gitworkflow","owner":"rocketraman","description":"A documentation repository for gitworkflows https://medium.com/hackernoon/how-the-creators-of-git-do-branches-e6fcc57270fb","archived":false,"fork":false,"pushed_at":"2022-03-15T15:41:52.000Z","size":333,"stargazers_count":109,"open_issues_count":12,"forks_count":8,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-28T15:05:27.704Z","etag":null,"topics":["git","gitworkflow"],"latest_commit_sha":null,"homepage":"","language":null,"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/rocketraman.png","metadata":{"files":{"readme":"README.adoc","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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-08T08:27:56.000Z","updated_at":"2025-02-24T16:36:33.000Z","dependencies_parsed_at":"2023-07-25T12:46:04.117Z","dependency_job_id":null,"html_url":"https://github.com/rocketraman/gitworkflow","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rocketraman%2Fgitworkflow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rocketraman%2Fgitworkflow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rocketraman%2Fgitworkflow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rocketraman%2Fgitworkflow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rocketraman","download_url":"https://codeload.github.com/rocketraman/gitworkflow/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248995101,"owners_count":21195497,"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","gitworkflow"],"created_at":"2024-10-01T10:51:39.319Z","updated_at":"2025-04-15T02:36:49.812Z","avatar_url":"https://github.com/rocketraman.png","language":null,"funding_links":[],"categories":["git"],"sub_categories":[],"readme":"= Gitworkflow\n:homepage: https://github.com/rocketraman/gitworkflows\n\nThe https://git.kernel.org/pub/scm/git/git.git/[git.git] project, responsible for the creation and maintenance of the\nhttps://git-scm.com/[git] tool itself, uses a powerful workflow I call \"gitworkflow\", in deference to its creators\nand the https://git-scm.com/docs/gitworkflows[man page] in which it is described.\n\nI describe the advantages of this workflow, in comparison to the popular\nhttp://nvie.com/posts/a-successful-git-branching-model/[GitFlow] by Vincent Drieesen and Adam Ruka's\nhttp://endoflineblog.com/oneflow-a-git-branching-model-and-workflow[OneFlow] in a blog post titled\nhttps://medium.com/hackernoon/how-the-creators-of-git-do-branches-e6fcc57270fb[How the Creators of Git do Branching].\n\nThis repository is meant to be a place in which tools and documentation related to gitworkflow can be created.\n\n== TL;DR\n\n* link:./docs/concepts-summary.adoc[Concepts Summary]\n* link:./docs/task-oriented-primer.adoc[Task-Oriented Primer]\n* link:./docs/useful-commands.adoc[Useful Commands]\n\n== Key Advantages\n\nThe key advantages gitworkflow over GitFlow and OneFlow all come from treating topics as first-class citizens, not just\ntemporary placeholders for unfinished code.\n\n=== Amazing History\n\nGitworkflow presents a history that code historians, and conscientious developers can love. It can easily present both\nsummary (e.g. \"show me all the topics merged into a release\") and highly detailed views (e.g. \"show me all the commits\nrelated to a topic\").\n\nA graph of a specific topic's history contains all of that topics commits, not interspersed with other topics:\n\nimage:docs/images/topichistory.png[Topic History]\n\nbut all of that detail can be elided to understand what was merged at a high level:\n\nimage:docs/images/integrationhistory.png[Integration History]\n\n(both examples from the git.git repository)\n\n=== Continuous Integration, Done Right\n\nEver struggled with the decision about when to merge a topic branch to the main branch (`develop` in GitFlow / `master`\neverywhere else)?\n\nWith GitFlow and OneFlow, in order to get the benefit of\nhttps://martinfowler.com/articles/continuousIntegration.html[Continuous Integration], you have to either test each topic\nbranch in isolation, OR you have to merge it to the main line. Testing the topic in isolation, well, tests in isolation,\nwhich is \"continuous\", but isn't \"integration\". Waiting to merge until the topic is \"done\" means you can only test it\nalong with other work that is also \"done\". This is \"integration\", but it isn't \"continuous\".\n\nThis tension exists between \"continuous\" and \"integration\" because in most non-trivial projects, topics don't have a\nbinary done/not done state: they are almost always a work in progress, with their stability being an analog continuum,\nnot a digital value. We really want to do \"continuous integration\" of topics, even before they are considered \"done\"\n(i.e. released).\n\nWith gitworkflow, the stability level of a topic is explicit -- and we can do true \"continuous integration\" of all the\nunreleased alpha-quality topics merged together to create an \"alpha\" release, all the unreleased beta-quality topics\nmerged to create a \"beta\" release, and lastly all of the released topics.\n\nThe early \"continuous integration\" of topics before they are \"done\" allows identification of conflicting work on\ndifferent topics early in their development, prompting the right conversations and coordination between devs at the\nright time.\n\n==== Make Your Topics Great\n\nGitworkflow allows the alpha and beta-quality integration branches to be rewound and rebuild. This property allows\ntopics to be massaged via interactive rebase until they form a series of easily understandable and reviewable chunks of\nwork. With other flows, this is only an option until the topic is considered \"done\" and is merged to the main line for\nCI and user testing. Gitworkflow removes the limitation that a topic branch cannot be interactively rebased after it has\nbeen merged for CI and user testing, and especially for alpha-quality topics, this would be expected by most team leads\nand code reviewers, rather than frowned on.\n\n=== Flexibility\n\nSometimes features take longer to develop than expected. Sometimes they don't work well with other work in progress and\nneed to be thrown away and a new approach taken. Sometimes everyone thinks they are \"done\", but they don't test well or\nthey cause regressions.\n\nIn most flows, this code is already on the main line of development. It has to be reverted (which can be easy or hard\ndepending on the flow and the method used to merge the topic).\n\nIn contrast, Gitworkflow defines a range of stability levels that the code \"graduates\" through, from raw unfinished code\n(\"alpha\") to code ready for testing (\"beta\") to code ready for release. Code can spend as much time as it needs to at\neach of these \"levels\", and when code is merged to the main line, it is production-ready. Thus gitworkflow supports\ncontinuous deployment scenarios as well.\n\nGitworkflow allows you to define your own stability levels if you wish: add or remove integration branches as necessary.\n\n== Main Insights\n\nOne key insight that makes gitworkflow work over flows like GitFlow and OneFlow is that: git is smarter than your\naverage source control system. Topics don't have to be merged _only into the branch they were started from_, which seems\nto be the implicit or explicit assumption most flow authors make. In git, the topic can be merged _into any branch that\nit shares a common ancestor with_.\n\nThis means that topic branches can be merged to multiple integration branches, each with a different purpose\ncorresponding to the stability levels defined above.\n\nA related insight is that topics can be merged into other topics to explicitly deal with conflicts and encode\ndependencies.\n\nA second key insight is that, when topics are first-class citizens, early integration branches are just ephemeral\nplaceholders for various combinations of topics, and can easily be recreated (rewind and rebuild). The integration\nbranches are therefore unimportant and don't need to be a limiting factor for work on topics, such as rebasing, and\nwe are free to experiment with moving topics in and out of them.\n\nThe third key insight is that merge commits -- the ability to explicitly join two lines of development -- offer the\nability to accomplish all of the above, as well as to continue to track topic history, long after the topic is no longer\nbeing developed, making code history spelunking great.\n\n== Disadvantages\n\nGitworkfow is more complicated, and harder to understand than most (probably all) other flows. It requires more\nunderstanding of git concepts and capabilities. It offers significant powerful capabilities to complex multi-dimensional\nproducts with a team of developers, but does have more \"overhead\" in the sense of multiple things to track and\nunderstand. This means that:\n\n* Gitworkflow should not be used without significant team maturity using, or willingness to learn, git, and\n* Gitworkflow is serious overkill for trivial or one-man projects (but these might be a good place to try it out).\n\n== Interested in Learning More?\n\n=== Documentation\n\n* link:./docs/concepts-summary.adoc[Concepts Summary]\n* link:./docs/task-oriented-primer.adoc[Task-Oriented Primer]\n* link:./docs/useful-commands.adoc[Useful Commands]\n\n=== Questions?\n\nFeel free to ask questions about gitworkflow in the https://github.com/rocketraman/gitworkflow/issues[issues] of this\nrepository. Please prefix your issue subject with `[Q]`.\n\n=== The Gitworfkow Awesome List\n\nA curated list of related external articles and documentation.\n\n==== Git.git Documentation\n\nAll of the following are git.git resources by the git.git team.\n\n* \"Managing Branches\" in man page https://git-scm.com/docs/gitworkflows[gitworkflows(7)]\n* \"How various branches are used\" in git.git https://github.com/git/git/blob/efc912b23335434674bcfda8199077f8dfa5d6f0/MaintNotes#L144[MaintNotes]\n* \"The Policy\" in git.git https://github.com/git/git/blob/v2.13.0/Documentation/howto/maintain-git.txt#L35[maintain-git.txt]\n\n==== Articles and Blog Posts\n\n* https://hackernoon.com/how-the-creators-of-git-do-branches-e6fcc57270fb[How the Creators of Git do Branching] by Raman Gupta\n\n== TODOs\n\n* Document useful commands with gitworkflow e.g. history spelunking, topic status, etc.\n** Integrate and document aliases in https://gist.github.com/rocketraman/1fdc93feb30aa00f6f3a9d7d732102a9\n* Add more detail to link:./docs/concepts-summary.adoc[Concepts Summary]\n* Lots of work in link:./docs/task-oriented-primer.adoc[Task-Oriented Primer]\n* Lots of work in link:./docs/useful-commands.adoc[Useful Commands]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frocketraman%2Fgitworkflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frocketraman%2Fgitworkflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frocketraman%2Fgitworkflow/lists"}