e0a1f09313 · matheusbsbs/matheus-bagliano

@@ -81,12 +81,11 @@ merge::

81 changes into the latest <commit>. With '--squash',

82 creates only one commit that contains all the changes,

83 rather than merging in the entire history.

84 -

85 - If you use '--squash', the merge direction doesn't

86 - always have to be forward; you can use this command to

87 - go back in time from v2.5 to v2.4, for example. If your

88 - merge introduces a conflict, you can resolve it in the

89 - usual ways.

84 ++

85 +If you use '--squash', the merge direction doesn't always have to be

86 +forward; you can use this command to go back in time from v2.5 to v2.4,

87 +for example. If your merge introduces a conflict, you can resolve it in

88 +the usual ways.

89

90 pull::

91 Exactly like 'merge', but parallels 'git pull' in that

@@ -107,21 +106,19 @@ split::

106 contents of <prefix> at the root of the project instead

107 of in a subdirectory. Thus, the newly created history

108 is suitable for export as a separate git repository.

110 -

111 - After splitting successfully, a single commit id is

112 - printed to stdout. This corresponds to the HEAD of the

113 - newly created tree, which you can manipulate however you

114 - want.

115 -

116 - Repeated splits of exactly the same history are

117 - guaranteed to be identical (i.e. to produce the same

118 - commit ids). Because of this, if you add new commits

119 - and then re-split, the new commits will be attached as

120 - commits on top of the history you generated last time,

121 - so 'git merge' and friends will work as expected.

122 -

123 - Note that if you use '--squash' when you merge, you

124 - should usually not just '--rejoin' when you split.

109 ++

110 +After splitting successfully, a single commit id is printed to stdout.

111 +This corresponds to the HEAD of the newly created tree, which you can

112 +manipulate however you want.

113 ++

114 +Repeated splits of exactly the same history are guaranteed to be

115 +identical (i.e. to produce the same commit ids). Because of this, if

116 +you add new commits and then re-split, the new commits will be attached

117 +as commits on top of the history you generated last time, so 'git merge'

118 +and friends will work as expected.

119 ++

120 +Note that if you use '--squash' when you merge, you should usually not

121 +just '--rejoin' when you split.

122

123

124 OPTIONS

@@ -151,109 +148,96 @@ OPTIONS FOR add, merge, push, pull

148 --squash::

149 This option is only valid for add, merge, push and pull

150 commands.

154 -

155 - Instead of merging the entire history from the subtree

156 - project, produce only a single commit that contains all

157 - the differences you want to merge, and then merge that

158 - new commit into your project.

159 -

160 - Using this option helps to reduce log clutter. People

161 - rarely want to see every change that happened between

162 - v1.0 and v1.1 of the library they're using, since none of the

163 - interim versions were ever included in their application.

164 -

165 - Using '--squash' also helps avoid problems when the same

166 - subproject is included multiple times in the same

167 - project, or is removed and then re-added. In such a

168 - case, it doesn't make sense to combine the histories

169 - anyway, since it's unclear which part of the history

170 - belongs to which subtree.

171 -

172 - Furthermore, with '--squash', you can switch back and

173 - forth between different versions of a subtree, rather

174 - than strictly forward. 'git subtree merge --squash'

175 - always adjusts the subtree to match the exactly

176 - specified commit, even if getting to that commit would

177 - require undoing some changes that were added earlier.

178 -

179 - Whether or not you use '--squash', changes made in your

180 - local repository remain intact and can be later split

181 - and send upstream to the subproject.

151 ++

152 +Instead of merging the entire history from the subtree project, produce

153 +only a single commit that contains all the differences you want to

154 +merge, and then merge that new commit into your project.

155 ++

156 +Using this option helps to reduce log clutter. People rarely want to see

157 +every change that happened between v1.0 and v1.1 of the library they're

158 +using, since none of the interim versions were ever included in their

159 +application.

160 ++

161 +Using '--squash' also helps avoid problems when the same subproject is

162 +included multiple times in the same project, or is removed and then

163 +re-added. In such a case, it doesn't make sense to combine the

164 +histories anyway, since it's unclear which part of the history belongs

165 +to which subtree.

166 ++

167 +Furthermore, with '--squash', you can switch back and forth between

168 +different versions of a subtree, rather than strictly forward. 'git

169 +subtree merge --squash' always adjusts the subtree to match the exactly

170 +specified commit, even if getting to that commit would require undoing

171 +some changes that were added earlier.

172 ++

173 +Whether or not you use '--squash', changes made in your local repository

174 +remain intact and can be later split and send upstream to the

175 +subproject.

176

177

178 OPTIONS FOR split

179 -----------------

180 --annotate=<annotation>::

181 This option is only valid for the split command.

188 -

189 - When generating synthetic history, add <annotation> as a

190 - prefix to each commit message. Since we're creating new

191 - commits with the same commit message, but possibly

192 - different content, from the original commits, this can help

193 - to differentiate them and avoid confusion.

194 -

195 - Whenever you split, you need to use the same

196 - <annotation>, or else you don't have a guarantee that

197 - the new re-created history will be identical to the old

198 - one. That will prevent merging from working correctly.

199 - git subtree tries to make it work anyway, particularly

200 - if you use --rejoin, but it may not always be effective.

182 ++

183 +When generating synthetic history, add <annotation> as a prefix to each

184 +commit message. Since we're creating new commits with the same commit

185 +message, but possibly different content, from the original commits, this

186 +can help to differentiate them and avoid confusion.

187 ++

188 +Whenever you split, you need to use the same <annotation>, or else you

189 +don't have a guarantee that the new re-created history will be identical

190 +to the old one. That will prevent merging from working correctly. git

191 +subtree tries to make it work anyway, particularly if you use --rejoin,

192 +but it may not always be effective.

193

194 -b <branch>::

195 --branch=<branch>::

196 This option is only valid for the split command.

205 -

206 - After generating the synthetic history, create a new

207 - branch called <branch> that contains the new history.

208 - This is suitable for immediate pushing upstream.

209 - <branch> must not already exist.

197 ++

198 +After generating the synthetic history, create a new branch called

199 +<branch> that contains the new history. This is suitable for immediate

200 +pushing upstream. <branch> must not already exist.

201

202 --ignore-joins::

203 This option is only valid for the split command.

213 -

214 - If you use '--rejoin', git subtree attempts to optimize

215 - its history reconstruction to generate only the new

216 - commits since the last '--rejoin'. '--ignore-join'

217 - disables this behaviour, forcing it to regenerate the

218 - entire history. In a large project, this can take a

219 - long time.

204 ++

205 +If you use '--rejoin', git subtree attempts to optimize its history

206 +reconstruction to generate only the new commits since the last

207 +'--rejoin'. '--ignore-join' disables this behaviour, forcing it to

208 +regenerate the entire history. In a large project, this can take a long

209 +time.

210

211 --onto=<onto>::

212 This option is only valid for the split command.

223 -

224 - If your subtree was originally imported using something

225 - other than git subtree, its history may not match what

226 - git subtree is expecting. In that case, you can specify

227 - the commit id <onto> that corresponds to the first

228 - revision of the subproject's history that was imported

229 - into your project, and git subtree will attempt to build

230 - its history from there.

231 -

232 - If you used 'git subtree add', you should never need

233 - this option.

213 ++

214 +If your subtree was originally imported using something other than git

215 +subtree, its history may not match what git subtree is expecting. In

216 +that case, you can specify the commit id <onto> that corresponds to the

217 +first revision of the subproject's history that was imported into your

218 +project, and git subtree will attempt to build its history from there.

219 ++

220 +If you used 'git subtree add', you should never need this option.

221

222 --rejoin::

223 This option is only valid for the split command.

237 -

238 - After splitting, merge the newly created synthetic

239 - history back into your main project. That way, future

240 - splits can search only the part of history that has

241 - been added since the most recent --rejoin.

242 -

243 - If your split commits end up merged into the upstream

244 - subproject, and then you want to get the latest upstream

245 - version, this will allow git's merge algorithm to more

246 - intelligently avoid conflicts (since it knows these

247 - synthetic commits are already part of the upstream

248 - repository).

249 -

250 - Unfortunately, using this option results in 'git log'

251 - showing an extra copy of every new commit that was

252 - created (the original, and the synthetic one).

253 -

254 - If you do all your merges with '--squash', don't use

255 - '--rejoin' when you split, because you don't want the

256 - subproject's history to be part of your project anyway.

224 ++

225 +After splitting, merge the newly created synthetic history back into

226 +your main project. That way, future splits can search only the part of

227 +history that has been added since the most recent --rejoin.

228 ++

229 +If your split commits end up merged into the upstream subproject, and

230 +then you want to get the latest upstream version, this will allow git's

231 +merge algorithm to more intelligently avoid conflicts (since it knows

232 +these synthetic commits are already part of the upstream repository).

233 ++

234 +Unfortunately, using this option results in 'git log' showing an extra

235 +copy of every new commit that was created (the original, and the

236 +synthetic one).

237 ++

238 +If you do all your merges with '--squash', don't use '--rejoin' when you

239 +split, because you don't want the subproject's history to be part of

240 +your project anyway.

241

242

243 EXAMPLE 1. Add command

subtree: fix AsciiDoc list item continuation