Skip to content
Newer
Older
100644 219 lines (153 sloc) 8.3 KB
6c2d30b @nvie Structurally replace gitflow by git-flow, as a true git extension.
authored Jan 26, 2010
1 git-flow
2 ========
12c4ab4 @nvie Update README file to mention new available features.
authored Jan 26, 2010
3 A collection of Git extensions to provide high-level repository operations
4fc0bc1 @nvie Use a more friendly URL for the original blog post URL.
authored Feb 24, 2010
4 for Vincent Driessen's [branching model](http://nvie.com/git-model "original
78c73dc @nvie Add initial project outline and guidelines.
authored Jan 21, 2010
5 blog post").
6
7
12c4ab4 @nvie Update README file to mention new available features.
authored Jan 26, 2010
8 Installing git-flow
9 -------------------
4f0f539 @nvie Added Rick Osborne's super-easy gitflow installer oneliner to the pro…
authored Jul 10, 2010
10 The easiest way to install git-flow is using Rick Osborne's excellent
11 git-flow installer, which can be run using the following command:
12
13 $ wget -q -O - http://github.com/nvie/gitflow/raw/develop/contrib/gitflow-installer.sh | sudo sh
14
c213052 @defeated added OSX instructions using curl (because wget isn't available by de…
defeated authored Sep 5, 2010
15 For __OSX__ users, the `wget` command isn't available by default, but `curl` is, so you can run:
16
17 $ curl http://github.com/nvie/gitflow/raw/develop/contrib/gitflow-installer.sh | sudo sh
18
19 For __Windows__ users who wish to use the automated install, it is suggested that you install [Cygwin](http://www.cygwin.com/)
ea738ef @jptoto Added installation instructions for Windows users
jptoto authored Aug 20, 2010
20 first to install tools like sh and wget. Then simply follow the command:
21
22 c:\Users\<user> wget -q -O - http://github.com/nvie/gitflow/raw/develop/contrib/gitflow-installer.sh | sh
23
4f0f539 @nvie Added Rick Osborne's super-easy gitflow installer oneliner to the pro…
authored Jul 10, 2010
24 If you prefer a manual installation, please use the following instructions.
13c9482 @nvie Added instructions to first fetch submodules before installing.
authored Feb 15, 2010
25 After downloading the sources from Github, also fetch the submodules:
26
27 $ git submodule init
28 $ git submodule update
29
30 Then, you can install `git-flow`, using:
78c73dc @nvie Add initial project outline and guidelines.
authored Jan 20, 2010
31
12c4ab4 @nvie Update README file to mention new available features.
authored Jan 26, 2010
32 $ sudo make install
f206ba6 @nvie Update README file to match the 0.1 release status.
authored Jan 26, 2010
33
e0b54c0 @nvie Strip the GIT_EXEC_PATH Makefile parameter. Replaced it by the more U…
authored Mar 19, 2010
34 By default, git-flow will be installed in /usr/local. To change the prefix
35 where git-flow will be installed, simply specify it explicitly, using:
12c4ab4 @nvie Update README file to mention new available features.
authored Jan 26, 2010
36
e0b54c0 @nvie Strip the GIT_EXEC_PATH Makefile parameter. Replaced it by the more U…
authored Mar 19, 2010
37 $ sudo make prefix=/opt/local install
dd720be @nvie Dynamically collect the true git exec path and only if that can not b…
authored Jan 27, 2010
38
39 Or simply point your `PATH` environment variable to your git-flow checkout
40 directory.
78c73dc @nvie Add initial project outline and guidelines.
authored Jan 20, 2010
41
b17b898 @nvie Add installation note on how to install getopt.
authored Aug 25, 2010
42 *Installation note:*
43 git-flow depends on the availability of the command line utility `getopt`,
44 which may not be available in your Unix/Linux environment. Please use your
45 favorite package manager to install `getopt`. For Cygwin, install the
47d1b9d @nvie Made a note on the apt-get installer's package name.
authored Oct 8, 2010
46 `util-linux` package to get `getopt`. If you use `apt-get` as your install
47 manager, the package name is `opt`.
b17b898 @nvie Add installation note on how to install getopt.
authored Aug 25, 2010
48
78c73dc @nvie Add initial project outline and guidelines.
authored Jan 20, 2010
49
ec0b854 @nvie Add link to git-flow-completion project.
authored Jul 22, 2010
50 Integration with your shell
51 ---------------------------
25def71 @nvie Mention the ZSH support for git-flow-completion.
authored Aug 25, 2010
52 For those who use the [Bash](http://www.gnu.org/software/bash/) or
53 [ZSH](http://www.zsh.org) shell, please check out the excellent work on the
ec0b854 @nvie Add link to git-flow-completion project.
authored Jul 22, 2010
54 [git-flow-completion](http://github.com/bobthecow/git-flow-completion) project
55 by [bobthecow](http://github.com/bobthecow). It offers tab-completion for all
56 git-flow subcommands and branch names.
57
25def71 @nvie Mention the ZSH support for git-flow-completion.
authored Aug 25, 2010
58 For Windows users, [msysgit](http://code.google.com/p/msysgit/) is a good
59 starting place for installing git.
ac949bf @jptoto Fixed link to Cygwin and msysgit
jptoto authored Aug 20, 2010
60
ec0b854 @nvie Add link to git-flow-completion project.
authored Jul 22, 2010
61
11965b3 @nvie Added two FAQs.
authored Sep 6, 2010
62 FAQ
63 ---
64 * **Can I still do manual branches and merges when I use git-flow?**
0c92777 @nvie Fix more Markdown syntax.
authored Sep 6, 2010
65 Of course you can. `git-flow` does not forbid you to keep using vanilla Git
11965b3 @nvie Added two FAQs.
authored Sep 6, 2010
66 commands!
67
68 So if you want to merge `master` into `develop` for whatever reason you want
69 to, you can safely do so without breaking `git-flow` compatibility. Do you
70 want to manually merge a feature branch X into another feature branch Y? Not
71 a problem. As long as you do it conciously and realize what this means for
72 finishing those branches later on.
73
f8b34b2 @nvie Add another FAQ.
authored Sep 6, 2010
74 * **Why does git-describe not work for me?**
75 When finishing release and hotfix branches, that branch's HEAD is first
76 merged into `master` and then into `develop`. It is not the resulting new
77 merge commit from `master` that is merged back into `develop`. This means
78 that a linear path from the new `develop` branch to the new `master` commit
79 is not created. Even worse, a linear path is created from the new `develop`
80 branch to the *previous* `master` commit. Although unintended, this is
81 simply an effect of using the current branching rules.
82
83 When using `git-describe` in these cases, you can get very confusing and
84 misleading results, since `git-describe` scans the current commits linear
85 history for the most recent tag it finds, which will always be the *previous*
86 tag.
87
88 I will change this behaviour in the next version of the branching model
89 explicitly and I will include this behavioural change in the first version of
90 the Python rewrite.
91
92 For more references to this problem, see:
93
94 - Issue [#49](http://github.com/nvie/gitflow/issues/49)
95 - These
96 [two](http://groups.google.com/group/gitflow-users/browse\_thread/thread/9920a7df3d1c4908/0bb18a0bf7275ad6#0bb18a0bf7275ad6)
97 [discussions](http://groups.google.com/group/gitflow-users/browse\_thread/thread/19efac724bb6418a)
98 on the [git-flow-users](http://groups.google.com/group/gitflow-users)
99 mailinglist.
100
11965b3 @nvie Added two FAQs.
authored Sep 6, 2010
101 * **I'm getting errors when I use flags with git-flow!**
0c92777 @nvie Fix more Markdown syntax.
authored Sep 6, 2010
102 `git-flow` uses the [shFlags](http://code.google.com/p/shflags/) library to
11965b3 @nvie Added two FAQs.
authored Sep 6, 2010
103 provide platform independent flag parsing (using wichever low-level flag
104 parsing libraries like `getopt` or `getopts` are available). However,
105 `shFlags` does not work too well on a few platforms that haven't been tested
106 originally. This results in errors like this:
107
108 flags:WARN getopt: option invalide -- 'f' -- 'init' flags:FATAL unable to parse provided options with getopt
109
110 The platforms that suffer these errors include:
111
112 - Gentoo
113 - Ubuntu
114 - Redhat Enterprise Linux
115
f74a3a7 @nvie Fix markdown links to issues.
authored Sep 6, 2010
116 There are open issues related to this:
117 [#28](http://github.com/nvie/gitflow/issues/28) and
118 [#39](http://github.com/nvie/gitflow/issues/39). Unfortunately, there is no
119 simple fix for it and all hope is placed on the Python rewrite of `git-flow`,
120 see issue [#33](http://github.com/nvie/gitflow/issues/33).
11965b3 @nvie Added two FAQs.
authored Sep 6, 2010
121
cb92228 @nvie Add FAQ note for Windows users.
authored Sep 22, 2010
122 * **Can I use it with Windows?**
123 There have been reports of Windows users using `git-flow`.
124 <del>Un</del>fortunately, I have no Windows environment to test it on, but
125 this [issue](http://github.com/nvie/gitflow/issues/issue/25) should be
126 helpful in setting it up.
127
11965b3 @nvie Added two FAQs.
authored Sep 6, 2010
128
f206ba6 @nvie Update README file to match the 0.1 release status.
authored Jan 26, 2010
129 Please help out
130 ---------------
c49c793 @nvie Dotted i's and crossed t's in the README file, for release.
authored Feb 24, 2010
131 This project is still under development. Feedback and suggestions are very
132 welcome and I encourage you to use the [Issues
133 list](http://github.com/nvie/gitflow/issues) on Github to provide that
f206ba6 @nvie Update README file to match the 0.1 release status.
authored Jan 26, 2010
134 feedback.
135
d79a0d4 @nvie Added referral link to the AUTHORS file.
authored Apr 4, 2010
136 Feel free to fork this repo and to commit your additions. For a list of all
137 contributors, please see the [AUTHORS](AUTHORS) file.
78c73dc @nvie Add initial project outline and guidelines.
authored Jan 20, 2010
138
1fd5bcf @nvie Added link to Google group.
authored Jul 15, 2010
139 Any questions, tips, or general discussion can be posted to our Google group:
4d8b379 @nvie Make the links manually.
authored Aug 19, 2010
140 [http://groups.google.com/group/gitflow-users](http://groups.google.com/group/gitflow-users)
1fd5bcf @nvie Added link to Google group.
authored Jul 16, 2010
141
78c73dc @nvie Add initial project outline and guidelines.
authored Jan 20, 2010
142
5d1dbe7 @nvie Added (BSD) licensing terms to the project.
authored Apr 4, 2010
143 License terms
144 -------------
145 git-flow is published under the liberal terms of the BSD License, see the
146 [LICENSE](LICENSE) file. Although the BSD License does not require you to share
147 any modifications you make to the source code, you are very much encouraged and
148 invited to contribute back your modifications to the community, preferably
149 in a Github fork, of course.
150
151
c49c793 @nvie Dotted i's and crossed t's in the README file, for release.
authored Feb 24, 2010
152 Typical usage:
153 --------------
b731e6f @nvie Mention Jeff's great article on the README file.
authored Aug 19, 2010
154 For the best introduction to get started to `git flow`, please read Jeff
155 Kreeftmeijer's blog post:
156
4d8b379 @nvie Make the links manually.
authored Aug 19, 2010
157 [http://jeffkreeftmeijer.com/2010/why-arent-you-using-git-flow/](http://jeffkreeftmeijer.com/2010/why-arent-you-using-git-flow/)
b731e6f @nvie Mention Jeff's great article on the README file.
authored Aug 19, 2010
158
c49c793 @nvie Dotted i's and crossed t's in the README file, for release.
authored Feb 24, 2010
159
160 ### Initialization
78c73dc @nvie Add initial project outline and guidelines.
authored Jan 20, 2010
161
c49c793 @nvie Dotted i's and crossed t's in the README file, for release.
authored Feb 24, 2010
162 To initialize a new repo with the basic branch structure, use:
12c4ab4 @nvie Update README file to mention new available features.
authored Jan 26, 2010
163
c49c793 @nvie Dotted i's and crossed t's in the README file, for release.
authored Feb 24, 2010
164 git flow init
f9ebb07 @nvie Added 'git flow init' to the README file.
authored Feb 22, 2010
165
c49c793 @nvie Dotted i's and crossed t's in the README file, for release.
authored Feb 24, 2010
166 This will then interactively prompt you with some questions on which branches
167 you would like to use as development and production branches, and how you
168 would like your prefixes be named. You may simply press Return on any of
169 those questions to accept the (sane) default suggestions.
170
171
172 ### Creating feature/release/hotfix/support branches
12c4ab4 @nvie Update README file to mention new available features.
authored Jan 26, 2010
173
c81e7a2 @nvie Update the README to reflect the new subcommand structure.
authored Jan 28, 2010
174 * To list/start/finish feature branches, use:
78c73dc @nvie Add initial project outline and guidelines.
authored Jan 20, 2010
175
c81e7a2 @nvie Update the README to reflect the new subcommand structure.
authored Jan 27, 2010
176 git flow feature
177 git flow feature start <name> [<base>]
178 git flow feature finish <name>
78c73dc @nvie Add initial project outline and guidelines.
authored Jan 20, 2010
179
010252a @nvie Added an optional <base> argument to all start subactions.
authored Feb 4, 2010
180 For feature branches, the `<base>` arg must be a commit on `develop`.
c81e7a2 @nvie Update the README to reflect the new subcommand structure.
authored Jan 27, 2010
181
182 * To list/start/finish release branches, use:
78c73dc @nvie Add initial project outline and guidelines.
authored Jan 20, 2010
183
04839ae @nvie Forgot list command for hotfixes.
authored Jan 28, 2010
184 git flow release
010252a @nvie Added an optional <base> argument to all start subactions.
authored Feb 4, 2010
185 git flow release start <release> [<base>]
c81e7a2 @nvie Update the README to reflect the new subcommand structure.
authored Jan 27, 2010
186 git flow release finish <release>
78c73dc @nvie Add initial project outline and guidelines.
authored Jan 20, 2010
187
010252a @nvie Added an optional <base> argument to all start subactions.
authored Feb 4, 2010
188 For release branches, the `<base>` arg must be a commit on `develop`.
189
c81e7a2 @nvie Update the README to reflect the new subcommand structure.
authored Jan 27, 2010
190 * To list/start/finish hotfix branches, use:
78c73dc @nvie Add initial project outline and guidelines.
authored Jan 20, 2010
191
04839ae @nvie Forgot list command for hotfixes.
authored Jan 28, 2010
192 git flow hotfix
010252a @nvie Added an optional <base> argument to all start subactions.
authored Feb 4, 2010
193 git flow hotfix start <release> [<base>]
c81e7a2 @nvie Update the README to reflect the new subcommand structure.
authored Jan 27, 2010
194 git flow hotfix finish <release>
010252a @nvie Added an optional <base> argument to all start subactions.
authored Feb 4, 2010
195
196 For hotfix branches, the `<base>` arg must be a commit on `master`.
c81e7a2 @nvie Update the README to reflect the new subcommand structure.
authored Jan 27, 2010
197
198 * To list/start support branches, use:
78c73dc @nvie Add initial project outline and guidelines.
authored Jan 20, 2010
199
c81e7a2 @nvie Update the README to reflect the new subcommand structure.
authored Jan 27, 2010
200 git flow support
010252a @nvie Added an optional <base> argument to all start subactions.
authored Feb 4, 2010
201 git flow support start <release> <base>
202
203 For support branches, the `<base>` arg must be a commit on `master`.
78c73dc @nvie Add initial project outline and guidelines.
authored Jan 20, 2010
204
b33ea8a @nvie Added a Flattr button to the README file.
authored Aug 24, 2010
205
206 Showing your appreciation
207 =========================
208 A few people already requested it, so now it's here: a Flattr button.
209
210 Of course, the best way to show your appreciation for the original
211 [blog post](http://nvie.com/git-model) or the git-flow tool itself remains
212 contributing to the community. If you'd like to show your appreciation in
213 another way, however, consider Flattr'ing me:
214
215 [![Flattr this][2]][1]
216
217 [1]: http://flattr.com/thing/53771/git-flow
218 [2]: http://api.flattr.com/button/button-static-50x60.png
Something went wrong with that request. Please try again.