Improve documentation for "braiding" a single file

[Saragani]

We were using SVN and our solution have some files shared from other SVN repositories.
I was investigating solutions for Git for sharing "externals" just like with SVN, and Sub Modules was not giving the right solution as it would share the entire repository inside ours.
Other solutions using Sub Modules were creating a repository from the original ones, and deleting the irrelevant files, but it makes it impossible to merge any changes back to the original repo, and it also require regular merging from parent repo into forked "minimized" repo.

I've came across Braid, and I have found it useful. Unlike Sub Modules, it can take a specific sub directory from a repo and put it in my repo.
On some cases, I need just a single file from a directory (In my cause, I need 4 files from different sub directories of the same repo, where all of them should be placed on the same directory in my repo. One of the sub directories contains 100 files, while I need only 1 file).
Currently, I braid all 4 directories into 4 different directories, and I will have some kind of a exe that the developer need to run, which will update all "external" files, and then copy then to the relevant files.
It could be easier if I could do the same as I do for directories, but in this case, for files.

[mattmccutchen]

This should work if you run braid add with a --path option that refers to a single file, although it isn't well documented. Does it work for you? If so, we can use this issue to track improving the documentation.

[Saragani]

Will it work if I do? :
braid add --path dir1/dir2/file.ext https://bitbucket.org/someProject/project.git dir3/dir4
braid add --path dir5/dir6/file2.ext https://bitbucket.org/someProject/project.git dir3/dir4

Meaning multiple files from different paths saved to the same directory?
Should I also use the file name after dir3/dir4? (meaning dir3/dir4/file.ext)
(Because if not, then in the .braids.json both files will have the same JSON entry)

Thanks

[Saragani]

Great, it seem to work (Need file.ext after dir3/dir4 as well)

[mattmccutchen]

I'm glad it's working for you now. I want to reuse this issue to track the documentation improvements. (If you're not interested in following this, you can unsubscribe yourself from the issue now.) First, braid add --help should mention that braiding a single file is supported. Second, you raise a good point that it wasn't obvious that when a destination path is specified, Braid (unlike cp) never automatically appends the last component of the source path to the destination path, so the user needs to specify that explicitly if that's the result they want.