README.md
1gphoto-m4
2=========
3
4`gphoto-m4` is the gPhoto projects' collection of m4 macros for use
5with the autoconf/automake based build systems.
6
7It has been designed to be used in
8
9 * `gphoto2`
10 * `libgphoto2`
11 * `libgphoto2_port` (located in `libgphoto2/`)
12 * `gtkam`
13
14Some macros are re-used ones from `libexif`.
15
16Since the gPhoto project moved from SVN to git, we have not figured
17out yet how to properly include the `gphoto-m4` files into the
18respective software's `gphoto-m4/` subdirectory (either `git subtree`
19or `git submodule` come to mind).
20
21So for the time being, we manually update and synchronize the files.
22
23
24Use of `gphoto-m4` after the switch to git from SVN
25---------------------------------------------------
26
27Since the gPhoto project moved from SVN to git, we have not figured
28out yet how to properly include the `gphoto-m4` files into the
29respective software's `gphoto-m4/` subdirectory. The options are:
30
31 1. Manually update (and hopefully synchronize) the files.
32
33 Advantages:
34
35 * No special commands needed for users or developers.
36
37 Disadvantages:
38
39 * The manual work for the maintainers is exhausting and error
40 prone.
41
42 2. Use `git submodule`.
43
44 Advantages:
45
46 * Defined mechanism for syncing and updating the `gphoto-m4/*`
47 files.
48
49 Disadvantages:
50
51 * Requires special git commands from everybody (users,
52 developers, and maintainers) all the time (e.g. `git clone
53 --recursive` instead of `git clone`).
54
55 This is the showstopper for `git submodule`.
56
57 3. Use `git subtree`.
58
59 Advantages:
60
61 * Defined mechanism for syncing and updating the `gphoto-m4/*`
62 files.
63
64 * Requires no special git commands from users or developers.
65
66 * Not even people actually messing with the files in
67 `gphoto-m4/*` strictly need special commands.
68
69 Only the maintainers who do the syncing and updating of the
70 `gphoto-m4/*` files need the special commands.
71
72 Disadvantages:
73
74 * Requires special knowledge of special commands instead of
75 just copying files around. The concept is less complex than
76 copying files round, but it does require special commands.
77
78 * No rebasing possible across pulls to `gphoto-m4/`. Not really
79 necessary anyway, though.
80
81 * Pushes of changes to from, say, `gphoto2/gphoto-m4` to
82 upstream `gphoto-m4` create a lot of commit history noise in
83 the `gphoto-m4` repository by including the complete history
84 of the `gphoto2` repository.
85
86 Note this cannot be avoided by using `git subtree split`:
87 That is executed internally by `git subtree push`.
88
89 So it appears that using `git subtree push` will push all
90 projects' commit history into the `gphoto-m4` repo.
91
92 That is if not a showstopper, then at least very ugly.
93
94For the time being, we manually update and synchronize the files.
95
96
97Manually syncing and updating files
98-----------------------------------
99
100This section has not been written yet.
101
102
103Using `git submodule`
104---------------------
105
106This section has not been written yet.
107
108
109Using `git subtree`
110-------------------
111
112
113### Using `gphoto-m4` as git subtree ###
114
115This section describes how to use `gphoto-m4` when it has been set up
116as a `git subtree` (e.g. in `gphoto2` and `libgphoto2`).
117
118Add a remote for `gphoto-m4`:
119
120 git remote add origin-gphoto-m4 git@github.com:gphoto/gphoto-m4.git
121
122Pull changes to origin-gphoto-m4 into local `gphoto-m4`:
123
124 git subtree pull --prefix gphoto-m4 origin-gphoto-m4 master --squash
125
126Now we can push local changes to 'gphoto-m4/*' back to
127`origin-gphoto-m4` as follows:
128
129 git subtree push --prefix gphoto-m4 origin-gphoto-m4 master
130
131FIXME: Add more typical uses cases.
132
133
134### Setting up `gphoto-m4` as git subtree ###
135
136This section describes how we initially set up `gphoto-m4` as a git
137subtree for `gphoto2`. This is only required once by one person, then
138never needs to be done by anybody else ever again.
139
140 git subtree add --prefix gphoto-m4 origin-gphoto-m4 master --squash
141